Resolves a surface's flat component dictionary into a tree of A2UICore.Resolution.Nodes.

Child references become nodes, collection templates become one node per item (each in its item's data scope), components that have not arrived yet become :pending placeholders that are replaced when their definition does, and a component referenced by one of its own descendants is cut with a :cyclic placeholder.

The resolver is plain data. It does not observe anything: after the surface changed, hand the new surface to update/2 and read what happened from the notifications it returns.

{resolver, notifications} = NodeResolver.new(surface)
surface = Surface.put_components(surface, components)
{resolver, notifications} = NodeResolver.update(resolver, surface)

Identity

A position is identified by the edge that leads to it (the parent position, the property, and the component and data path it points at). While the edge keeps leading to the same kind of node, the node keeps its ref; only its props change. A node is replaced — and the old one destroyed — when the component behind the edge appears, goes away or changes type, when a sibling ordinal shifts, or when its parent is destroyed.

Notifications

• {:node_created, ref} — a new position is mounted;
• {:node_updated, ref} — a node that was already mounted now has different props (reported once per update/2, whatever number of properties changed);
• {:node_destroyed, ref} — a mounted node is gone; reported once;

• {:error | :warning, payload} — a diagnostic (an unknown component type, a cyclic reference, a binding that does not resolve), reported when the condition appears and again only after it went away.

write/4 and invoke/5 are the interaction half: they say which path a write reaches and which events and calls an action produces, from the surface as it is now.

Agent functions

From v1.0 a function call that the surface's catalogs cannot run locally is the agent's (see Agent functions). The resolver keeps what it knows of those calls in agent_calls. When a property needs a call it has not seen, update/2 marks the call pending and reports {:agent_call, %{key: key, call: call}}: the renderer sends call to the agent and later hands the outcome to settle_agent_call/3, then calls update/2 again. Until then the property is nil and its node is busy. Settled calls are kept for the properties and actions that use them again; past 256 calls, the settled ones no property uses are forgotten.