Components, instances, overrides and slots

Any non-instance node with a truthy component is a component; its subtree (every node whose parent chain reaches it) is the component's content. An instance MAY also carry component — a derived component (e.g. a variant: Button/Ghost = an instance of Button/Primary with overrides, marked as a component). Paths into a derived component resolve through to the component it instantiates (§9.5).

A component MUST NOT contain, directly or through nested instances or derived components, an instance of itself (INSTANCE_CYCLE). This includes what an instance places inside its component: a set.of swap of a nested instance and an args value of an instance prop put the named component inside every component that holds the target (the instance's component and the component of each instance the path crosses), so naming one of those is a cycle too.

• of names a component: a local id, or alias:id for a library component. The target MUST exist and MUST be a component.
• An instance has only Placement fields at its top level (plus of, props, args, overrides, component). Every visual property of the component root (w, h, fill, opacity, visible, rotation, flipX, layout, …) MAY appear only inside props, never at the instance's top level (INSTANCE_VISUAL_FIELD). props MUST NOT contain Placement fields or component; applying props to the root MUST yield a valid node.
• args holds values for the component's declared props (§9.6).
• An instance has no children of its own: its subtree is the component's, plus instance-owned nodes (§9.4).

overrides maps an IdPath (§9.5) to exactly one of:

Overrides are explicitly tagged; their meaning never depends on which keys a value happens to contain.

Precedence (later wins): the component as authored → a derived component's own props/args/overrides → the instance's props (root) → the instance's args (declared props) → the instance's overrides. For nested instances, an outer instance's override of a deep path wins over the nested instance's own overrides. Overrides do not cascade to other instances of the same component.

To hide a descendant inside an instance, set visible: false; descendants of an instance cannot be deleted.

Slot content and replacement nodes live in the flat node table like any other node, so they diff, merge and sync the same way:

• parent = the instance id (a real Id), at = the IdPath of the descendant they attach to.
• A node whose parent is an instance MUST have at, and at MUST equal a key of that instance's overrides whose value is slot or replace (AT_WITHOUT_OVERRIDE). A node whose parent is not an instance MUST NOT have at.
• The override entry is only a marker: the child list's single source of truth is the set of nodes pointing at it.

An IdPath is resolved relative to a component C (for an override or at: the instance's component; for a declared prop target: the declaring component):

1. Split the path at /. For each segment, in order:
   1. The segment is looked up among the descendants of C (nodes whose parent chain reaches C, including instance-owned nodes inside C), in C's namespace: written as a bare Id when C is a node of this document, and as alias:Id when C belongs to the library imported as alias.
   2. If not found and C is a derived component (an instance), C is replaced by the component it instantiates and the lookup is repeated (derived components are transparent).
   3. If it is not the last segment, the found node MUST be an instance, and C becomes its component; the next segment crosses that instance boundary.
2. The node found for the last segment is the target. Any failure is OVERRIDE_PATH_UNRESOLVED.

So "ui:CardActns1/ui:BtnLabel01" crosses from a library card into a library button. Paths never use names, so renames cannot break them. In 1.0, a path segment that would enter a library imported by a library (rather than by this document) is not resolved by validators (reported as not checked).

component: { "props": { <name>: PropDef } } declares a typed prop API (used by the React exporter: typed props for declared props only; every other override is inlined).

target is an IdPath resolved from the declaring component (§9.5). A target equal to the declaring component's own id names the component root (through derived components, the base root); its args apply at the root with the precedence of args (above props). Only declared prop targets may name the root: override keys and at MUST NOT (OVERRIDE_PATH_UNRESOLVED; the root is overridden through props). default is informative for exporters (the generated prop's default); an instance without the arg renders the component as authored; enum props have no default. args keys MUST be declared props (ARG_UNKNOWN).

Enum targets (board 27 §8 a). targets[option] is a list of EnumTarget { target, field, value }: target is an IdPath resolved like a prop target (the declaring component's own id names the root), field is a property name of the target node, or <property>/<key> for one key of a struct property (layout/pad, layout/gap, style/size, style/weight, an instance's props/opacity) — the property keeps its other keys (an absent property starts empty). value MUST be valid for the field (checked as the property with that key replaced) and MAY be a binding. Every targets key MUST be an option (PROP_TARGET_INVALID), as are a target that does not resolve, a field the node lacks, or a target without field (and vice versa). Choosing an option on an instance applies the legacy target/field value first, then the option's targets in list order, all with the precedence of args; args apply in key order. Properties an option does not target keep the main's values. A file whose enum props use only target/field/options is unchanged; editors MAY rewrite such a prop as targets (one target per option) when it is edited.

Every PropDef MAY carry order (an Order key): component.props is a record, so canonical serialization sorts it by name; editors list declared props by (order, then name), an absent order counting as the empty string, and SHOULD write an order on every declaration they create. A derived component's redeclaration without order keeps the base declaration's position.

Derived components inherit the prop API. The declared props of a derived component are those of the component it instantiates (recursively), with its own component.props declarations merged over them by name. Inherited targets resolve through the derived component (§9.5), so an instance of Button/Ghost takes the same args as an instance of Button/Primary.

Readers expand an instance to its component's content as follows; @kimo/core-schema createExpandedView is the reference.

1. Composite ids. A node emitted from component content is addressed as <instance id>/<IdPath>, the IdPath being the node's path relative to the instance's component (§9.5) — exactly the key an override of that instance uses. Instance-owned nodes keep their own ids. Real ids never contain /.
2. Root. The expanded root is the base component root with props (and root-targeting args) applied; its placement fields (parent, at, order, x, y, position, locked, meta, name when the instance has one) are the instance's. Its theme is the component root's pins (base first, then each derived component's own pins) overwritten by the instance's pins, so a component authored under a pinned theme keeps it unless the instance pins otherwise.
3. Library content is read in the consumer's namespace: bindings, theme pin keys, of and slot.suggested values written inside library alias get the alias: prefix.
4. Theme of expanded nodes. The placement path of an expanded node runs through the expanded tree (instance → component content → slot frame → slot content), so pins inside component content apply to slot content placed in it.

The same rules apply to set.props and set.args of a set override on a nested instance: they are checked against that instance's effective component (the one named by set.of, if present) exactly like an instance's own props and args. Likewise an override key that crosses a nested instance continues in its effective component: when the holder swaps the nested instance (set.of on that path, else an instance prop arg targeting it), the remaining segments resolve in the swapped component, and keys that no longer resolve are OVERRIDE_PATH_UNRESOLVED.

5. Precedence of kinds across nesting levels. When an outer instance overrides a deep path with slot or replace, it replaces the nested instance's own slot / replace on that path; an outer set on a path the nested instance replaced targets a node that is not there and is not applied.
6. Size. Readers MAY bound the number of nodes one top-level expansion emits (the reference stops at 50 000 and reports INSTANCE_TOO_LARGE), since depth alone does not bound fan-out.