@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/compose-reusable-components.js

@@ -0,0 +1,1366 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ // By path: the naming rule alone, without the icon catalog's loader beside it.
+import { iconPathPropName } from "@aglyn/shared-data-mdi/utils/icon-path-prop-name";
+import { reusablePropValueClass } from "../foundation/definitions/property-kinds.js";
+import { COMPONENT_NODE_ID_PREFIX, COMPONENT_PROP_TOKEN_PREFIX, INSTANCE_CARRIED_NODE_FIELDS, INSTANCE_CARRIED_PROPS, NODE_HIDE_IF_PROP, NODE_HIDE_UNLESS_PROP, REUSABLE_INSTANCE_COMPONENT_ID, REUSABLE_INSTANCE_PROP_VALUES_KEY, STYLE_OVERRIDES_ROOT_KEY } from "./reusable-component-keys.js";
+import { REPEAT_DIRECTIVE_PROPS, REPEAT_SELF_PROP, repeatKey, withoutRepeatDirective } from "./expand-repeatables.js";
+import { mergeNodeSx } from "./merge-node-sx.js";
+import { hasUrlScheme, isSafeNodeUrl, NODE_URL_PROPS } from "./node-url-policy.js";
+import { readInstanceIconValue, readYesNoValue, resolveReusablePropValues } from "./reusable-prop-values.js";
+import { resolveNamedTokens } from "./resolve-named-tokens.js";
+export * from "./reusable-component-keys.js";
+export * from "./reusable-prop-values.js";
+const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value) && Object.keys(value).length > 0;
+/**
+ * Space-separated class lists joined in order, each name once, or `undefined`
+ * when no list holds a name. A value that is not a string contributes nothing.
+ */ function joinClassNames(...lists) {
+    const names = lists.filter((list)=>typeof list === 'string').flatMap((list)=>list.split(/\s+/)).filter(Boolean);
+    return names.length ? [
+        ...new Set(names)
+    ].join(' ') : undefined;
+}
+/**
+ * Every per-instance style override an instance node carries, keyed the way
+ * it is stored (AGL-1332): {@link STYLE_OVERRIDES_ROOT_KEY} for the
+ * component root, and a DEFINITION-internal node id for each overridden
+ * leaf. Empty for a node that is not an instance or carries none.
+ *
+ * Keyed on the definition's own id, never the grafted `cmp__…` id: the
+ * graft id is DERIVED from the instance id, so keying on it would break the
+ * moment a subtree was duplicated or an instance re-keyed, and two
+ * instances of one component could not share the same authoring vocabulary.
+ * Entries that are not a non-empty plain object are dropped here rather
+ * than at each call site — a `null`, a string, or a cleared `{}` must read
+ * as "no override" identically in the graft, in detach and in the panel.
+ *
+ * Deliberately here rather than in a render surface: this file owns what
+ * an instance node looks like, and the graft below is the ONE place the
+ * overrides are applied — canvas, Preview and tenant SSR all call
+ * {@link composeReusableComponentNodes}, so they cannot disagree about
+ * what an override means.
+ */ export function getInstanceStyleOverrides(node) {
+    if ((node == null ? void 0 : node.componentId) !== REUSABLE_INSTANCE_COMPONENT_ID) return {};
+    const overrides = node == null ? void 0 : node.styleOverrides;
+    if (!isStyleRecord(overrides)) return {};
+    const clean = {};
+    for (const [key, value] of Object.entries(overrides)){
+        if (key && isStyleRecord(value)) clean[key] = value;
+    }
+    return clean;
+}
+/**
+ * The sx-shaped ROOT style override carried by an instance node, or
+ * `undefined` when the node is not an instance or carries none — the
+ * AGL-1306 half of {@link getInstanceStyleOverrides}.
+ */ export function getInstanceRootStyleOverride(node) {
+    return getInstanceStyleOverrides(node)[STYLE_OVERRIDES_ROOT_KEY];
+}
+/**
+ * The `{ sx }` patch one definition node takes from an instance's
+ * overrides, or `undefined` when none applies (AGL-1332).
+ *
+ * Two layers, coarse first: the root slice when this node IS the
+ * definition root, then the node's own definition-id slice. Both go
+ * through `mergeNodeSx`, so a per-leaf override gets exactly the cascade
+ * semantics the root one already had — a `{ md: … }` slice keeps the
+ * base's narrower widths, an `@scheme dark` slice merges key-by-key, and
+ * a plain property replaces only the leaf it names.
+ *
+ * A key naming a node the definition no longer has is simply never
+ * consulted: this runs per definition node, so a component edited after
+ * the override was written degrades to the component's own styling rather
+ * than throwing on a page nobody has opened since.
+ *
+ * Returned as a patch object rather than a value so the caller can spread
+ * nothing at all — writing `sx: undefined` onto a node that never had one
+ * would materialize the key on every grafted leaf.
+ */ function instanceSxPatch(baseSx, overrides, defId, rootId) {
+    // The root is addressed by the constant, so a definition node whose id
+    // merely happens to BE `root` without being the root gets nothing from
+    // the root slice — the alternative is styling an arbitrary leaf from the
+    // panel's root target.
+    const rootSlice = defId === rootId ? overrides[STYLE_OVERRIDES_ROOT_KEY] : undefined;
+    const leafSlice = defId === STYLE_OVERRIDES_ROOT_KEY ? undefined : overrides[defId];
+    if (!rootSlice && !leafSlice) return undefined;
+    let sx = baseSx;
+    if (rootSlice) sx = mergeNodeSx(sx, rootSlice);
+    if (leafSlice) sx = mergeNodeSx(sx, leafSlice);
+    return {
+        sx
+    };
+}
+/**
+ * Props on a grafted definition node that an instance override must never
+ * address (AGL-1899).
+ *
+ * `sx` has its own override layer one field up, and honouring it here would
+ * leave two writers racing for one rendered value with no rule to say which
+ * wins — the Styles panel would show an instance as clean while the
+ * Attributes panel silently repainted it.
+ */ const ATTR_OVERRIDE_REFUSED_PROPS = new Set([
+    'sx'
+]);
+/**
+ * Every per-instance ATTRIBUTE override an instance node carries, keyed the
+ * way {@link getInstanceStyleOverrides} keys styles — `root` for the
+ * definition root, a definition-internal node id for anything else
+ * (AGL-1899).
+ *
+ * Refused props are dropped HERE rather than at the write site, so a slice
+ * that reached storage before a refusal existed (or by any path that did not
+ * go through the panel) still cannot take effect.
+ */ export function getInstanceAttrOverrides(node) {
+    if ((node == null ? void 0 : node.componentId) !== REUSABLE_INSTANCE_COMPONENT_ID) return {};
+    const overrides = node == null ? void 0 : node.attrOverrides;
+    if (!isStyleRecord(overrides)) return {};
+    const clean = {};
+    for (const [key, value] of Object.entries(overrides)){
+        if (!key || !isStyleRecord(value)) continue;
+        const slice = {};
+        for (const [prop, propValue] of Object.entries(value)){
+            if (ATTR_OVERRIDE_REFUSED_PROPS.has(prop)) continue;
+            slice[prop] = propValue;
+        }
+        if (Object.keys(slice).length > 0) clean[key] = slice;
+    }
+    return clean;
+}
+/**
+ * The `{ props }` patch one definition node takes from an instance's
+ * attribute overrides, or `undefined` when none applies (AGL-1899).
+ *
+ * Layered coarse-first exactly like {@link instanceSxPatch} — the root slice
+ * when this node IS the definition root, then the node's own id slice — so
+ * the two override kinds stay one authoring model rather than two.
+ *
+ * The merge is one level deep, replacing only the props each slice NAMES.
+ * That keeps a component free to add a prop later and still have every
+ * existing instance pick up the new default, and it is deliberately not the
+ * cascade `mergeNodeSx` performs: an sx object's nested records are
+ * selectors (`@scheme dark`, breakpoints) that genuinely compose, while a
+ * prop value is one value. Deep-merging two prop objects that merely look
+ * alike would hand the renderer a third thing neither the component nor the
+ * page asked for.
+ */ function instancePropsPatch(baseProps, overrides, defId, rootId) {
+    const rootSlice = defId === rootId ? overrides[STYLE_OVERRIDES_ROOT_KEY] : undefined;
+    const leafSlice = defId === STYLE_OVERRIDES_ROOT_KEY ? undefined : overrides[defId];
+    if (!rootSlice && !leafSlice) return undefined;
+    return {
+        props: _extends({}, baseProps != null ? baseProps : {}, rootSlice != null ? rootSlice : {}, leafSlice != null ? leafSlice : {})
+    };
+}
+/**
+ * The styleable targets inside one component definition, in tree order
+ * (root first, then depth-first through each node's `nodes`) — what the
+ * Styles panel offers when a component instance is selected (AGL-1332).
+ *
+ * Beside the graft on purpose: the panel must write the SAME keys the
+ * graft reads, and a second walker that disagreed would offer authors
+ * targets no renderer consults. Cycle-safe and unreachable-safe: a node
+ * the root cannot reach is not offered, because the graft would never
+ * render it either.
+ */ export function listInstanceStyleTargets(definition) {
+    const rootId = definition == null ? void 0 : definition.rootId;
+    const nodes = definition == null ? void 0 : definition.nodes;
+    if (!rootId || !(nodes == null ? void 0 : nodes[rootId])) return [];
+    const targets = [];
+    const seen = new Set();
+    const walk = (id, depth)=>{
+        const node = nodes[id];
+        // `seen` is what bounds the walk: a definition that referenced an
+        // ancestor would otherwise recurse until the stack gave out.
+        if (!node || seen.has(id)) return;
+        seen.add(id);
+        const isRoot = id === rootId;
+        targets.push({
+            key: isRoot ? STYLE_OVERRIDES_ROOT_KEY : id,
+            componentInternalId: id,
+            depth,
+            componentId: node.componentId,
+            name: node.name,
+            isRoot
+        });
+        const children = node.nodes;
+        if (!Array.isArray(children)) return;
+        for (const childId of children){
+            if (typeof childId === 'string') walk(childId, depth + 1);
+        }
+    };
+    walk(rootId, 0);
+    return targets;
+}
+/**
+ * Definitions may nest instances of other definitions; expansion runs in
+ * passes capped here so a self-referencing definition can't recurse forever.
+ */ const MAX_COMPONENT_DEPTH = 5;
+function instancePrefix(instanceId) {
+    return `${COMPONENT_NODE_ID_PREFIX}${instanceId}__`;
+}
+/**
+ * The declared-prop name a stored value references when it is EXACTLY one
+ * `{{prop.<name>}}` token (whitespace inside the braces tolerated, matching
+ * `resolveNamedTokens`' grammar), else `null`.
+ *
+ * Exact-match on purpose: a value that merely CONTAINS a token
+ * (`"Hi {{prop.name}}!"`) is only partially prop-fed, so an inline edit of
+ * the rendered text could not be decomposed back into a prop value — those
+ * leaves stay component-owned (AGL-1304).
+ */ export function matchComponentPropToken(value) {
+    if (typeof value !== 'string') return null;
+    const match = /^\s*\{\{\s*prop\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}\s*$/.exec(value);
+    return match ? match[1] : null;
+}
+/**
+ * Maps a grafted node id back to its component-internal source and the
+ * declared prop (if any) feeding one of its content props (AGL-1304).
+ *
+ * The graft's provenance is its id scheme — `cmp__{instanceId}__{defId}`
+ * (see {@link composeReusableComponentNodes}) — and this is the ONE reader
+ * of that scheme, deliberately beside the writer: the canvas double-click
+ * hit-test uses it today, and AGL-1306 phase 2 (inner-node style overrides)
+ * and AGL-1303 phase 3 (in-place focus mode) need the same inverse mapping.
+ *
+ * Returns `null` when the id was not grafted from THIS instance, or when
+ * the internal id is unknown to the definition — which includes leaves of a
+ * NESTED instance's graft (prefixes stack per pass), whose props are fed by
+ * the outer definition's own instance node, not by this one.
+ *
+ * `boundProp` is non-null only when the definition node's `contentProp`
+ * (default `children`; pass `src` for image leaves) is exactly one
+ * `{{prop.*}}` token naming a DECLARED prop — an undeclared token never
+ * substitutes, so an override written for it would silently do nothing.
+ *
+ * Pure: no canvas, no DOM, inputs never mutated.
+ */ export function resolveInstanceLeafBinding(graftedId, instanceId, definition, contentProp = 'children', rootId) {
+    var _ref;
+    var _definition_nodes, _defNode_props;
+    if (!graftedId || !instanceId) return null;
+    const prefix = instancePrefix(instanceId);
+    // The definition's ROOT carries the instance's own id, not a prefixed one
+    // — the two are one element (AGL-2521). Without this the root is the one
+    // leaf the double-click cannot reach, so a component whose root IS its text
+    // stops being inline-editable through its placements.
+    if (graftedId === instanceId) {
+        var _ref1;
+        const rootInternalId = rootId != null ? rootId : Object.keys((_ref1 = definition == null ? void 0 : definition.nodes) != null ? _ref1 : {}).find((id)=>{
+            var _definition_nodes_id, _definition_nodes;
+            return !(definition == null ? void 0 : (_definition_nodes = definition.nodes) == null ? void 0 : (_definition_nodes_id = _definition_nodes[id]) == null ? void 0 : _definition_nodes_id.parentId);
+        });
+        if (!rootInternalId) return null;
+        return resolveInstanceLeafBinding(`${prefix}${rootInternalId}`, instanceId, definition, contentProp);
+    }
+    if (!graftedId.startsWith(prefix)) return null;
+    const componentInternalId = graftedId.slice(prefix.length);
+    if (!componentInternalId) return null;
+    const defNode = definition == null ? void 0 : (_definition_nodes = definition.nodes) == null ? void 0 : _definition_nodes[componentInternalId];
+    if (!defNode) return null;
+    const raw = (_defNode_props = defNode.props) == null ? void 0 : _defNode_props[contentProp];
+    const name = matchComponentPropToken(raw);
+    const declared = name != null && ((_ref = definition == null ? void 0 : definition.props) != null ? _ref : []).some((prop)=>(prop == null ? void 0 : prop.name) === name);
+    return {
+        componentInternalId,
+        boundProp: declared ? name : null
+    };
+}
+/** An instance's own values, keyed by declared prop name (AGL-1247). */ function instancePropValues(instanceProps) {
+    const values = instanceProps == null ? void 0 : instanceProps[REUSABLE_INSTANCE_PROP_VALUES_KEY];
+    return values && typeof values === 'object' && !Array.isArray(values) ? values : undefined;
+}
+/**
+ * The text an instance currently renders for a declared prop: its override
+ * when set, else the prop's `defaultValue`, else `''`. `''` counts as unset,
+ * as it does in the graft — clearing an override restores the component's own
+ * copy, so the inline editor and the graft agree about what the author is
+ * looking at.
+ */ export function getInstanceEffectivePropText(instanceProps, declared, propName) {
+    var _resolveReusablePropValues_tokens_;
+    return (_resolveReusablePropValues_tokens_ = resolveReusablePropValues(declared, instancePropValues(instanceProps)).tokens[`${COMPONENT_PROP_TOKEN_PREFIX}${propName}`]) != null ? _resolveReusablePropValues_tokens_ : '';
+}
+/** A value a field bound to a property has nothing to receive from. */ function isNothingToGive(value) {
+    return value === undefined || value === null || value === '' || Array.isArray(value) && value.length === 0 || matchComponentPropToken(value) != null;
+}
+/** A copy a field can own: a list is copied, so no two fields share one. */ function ownValue(value) {
+    return Array.isArray(value) ? [
+        ...value
+    ] : value;
+}
+/**
+ * What a field bound to exactly one property token receives, by the value
+ * class of that property — or `undefined` to remove the prop.
+ *
+ * `known` is the property's value when the caller resolved one, and
+ * `substituted` the text its token became; a caller that resolved nothing
+ * (a component editor drawing raw tokens) is read from the text alone.
+ */ function typedBindingValue(valueClass, known, substituted) {
+    const value = known ? known.value : substituted;
+    switch(valueClass){
+        case 'boolean':
+            return readYesNoValue(value) === true;
+        case 'number':
+            {
+                if (isNothingToGive(value)) return undefined;
+                if (typeof value === 'number') return value;
+                const numeric = Number(value);
+                return Number.isFinite(numeric) ? numeric : substituted;
+            }
+        case 'icon':
+            var _ref;
+            var _readInstanceIconValue;
+            return isNothingToGive(value) ? undefined : (_ref = (_readInstanceIconValue = readInstanceIconValue(value)) == null ? void 0 : _readInstanceIconValue.iconId) != null ? _ref : undefined;
+        default:
+            return isNothingToGive(value) ? undefined : ownValue(value);
+    }
+}
+/**
+ * The declared-prop substitution for a set of nodes, with each binding handed
+ * to the element as the value its property's kind holds (AGL-2871, AGL-2893).
+ *
+ * The substitution itself is textual — every token becomes text and
+ * `resolveNamedTokens` splices it into string props. That is right for copy
+ * and wrong for the fields that do not hold copy. So a prop whose stored value
+ * is EXACTLY one token naming a declared prop is finished by that prop's value
+ * class (`reusablePropValueClass`):
+ *
+ * - `boolean` (Yes / no, a single Checkbox) — a real `true` or `false`, read
+ *   through {@link readYesNoValue}, because an element reading `lightbox`
+ *   takes the string `'false'` for a yes. Nothing to read is a no.
+ * - `number` (Number, Slider) — a real number when the value is one, because an
+ *   element passing `size` to MUI turns `'32'` into `font-size: 32`, which no
+ *   browser applies. Nothing set is removed; text that is not a number is left
+ *   as it was authored.
+ * - `icon` — the picked icon's id, with its path written into the field's
+ *   companion (`iconId` → `iconPath`, the rule `iconPathPropName` states)
+ *   from `iconPaths`. The path is what a published page draws, since it never
+ *   loads the icon catalog; and it is written or removed on every pass,
+ *   because a path left over from the component's own icon would be drawn in
+ *   place of the page's. Nothing picked removes both.
+ * - `value` (every other kind: a Choice, a Color, a Size, a Date, a list of
+ *   answers, an entity) — the value exactly as the property holds it, from
+ *   `values`, so a list stays a list and a theme multiple stays a number.
+ *   Nothing set is removed, so the element keeps its own default: a
+ *   dropdown's empty value is not one of its options, and an element handed
+ *   `variant: ''` draws neither the component's variant nor its own.
+ * - `text` (Text, Long text, Image, Link) — the substituted text.
+ *
+ * "Nothing chosen" includes a binding still holding its token after
+ * substitution — a component editor drawing a prop that has no default —
+ * which is then drawn exactly as a page that sets nothing renders it.
+ *
+ * The same finishing reaches a nested placement: a component placed inside
+ * this definition, whose own `propValues` hand one of this definition's
+ * properties on by its exact token, receives the value typed — a list, a
+ * number, an icon with its path — and nothing at all where there is nothing to
+ * give, so its own default applies.
+ *
+ * Exact match only, for the reason {@link matchComponentPropToken} gives: a
+ * value that merely contains a token is text with a value inside it, and it
+ * stays text. An undeclared name is never typed either — it never substitutes,
+ * so there is no value to read.
+ *
+ * Top-level props only, and never an element's text content (`children`). The
+ * binding a panel field offers writes that field's own prop; a token nested in
+ * an item list is content the component spelled out, and text is text
+ * whatever kind of property fills it — so both keep the textual treatment.
+ *
+ * An `href` or `src` a token fed is then held to the address rule — see
+ * {@link holdPropFedAddresses}.
+ *
+ * Inputs are never mutated, and a map with no typed binding and no refused
+ * address comes back exactly as the substitution left it.
+ */ export function resolveComponentPropTokens(nodes, declared, tokens, iconPaths, values) {
+    const substituted = resolveNamedTokens(nodes, tokens);
+    const typedProps = new Map();
+    for (const prop of declared != null ? declared : []){
+        if (!(prop == null ? void 0 : prop.name)) continue;
+        const valueClass = reusablePropValueClass(prop);
+        if (valueClass !== 'text') typedProps.set(prop.name, valueClass);
+    }
+    if (!typedProps.size) return holdPropFedAddresses(nodes, substituted);
+    const knownValue = (name)=>values ? {
+            value: values[name]
+        } : undefined;
+    let typed;
+    for (const [id, node] of Object.entries(nodes != null ? nodes : {})){
+        const raw = node == null ? void 0 : node.props;
+        if (!raw || typeof raw !== 'object') continue;
+        let props;
+        const own = ()=>{
+            var _substituted_id;
+            return props = props != null ? props : _extends({}, (_substituted_id = substituted[id]) == null ? void 0 : _substituted_id.props);
+        };
+        for (const [key, value] of Object.entries(raw)){
+            if (key === 'children') continue;
+            const name = matchComponentPropToken(value);
+            const valueClass = name ? typedProps.get(name) : undefined;
+            if (!name || !valueClass) continue;
+            const next = own();
+            const finished = typedBindingValue(valueClass, knownValue(name), next[key]);
+            if (finished === undefined) delete next[key];
+            else next[key] = finished;
+            if (valueClass !== 'icon') continue;
+            const pathKey = iconPathPropName(key);
+            if (pathKey === key) continue;
+            const path = finished === undefined ? undefined : iconPaths == null ? void 0 : iconPaths[name];
+            if (path) next[pathKey] = path;
+            else delete next[pathKey];
+        }
+        const nested = (node == null ? void 0 : node.componentId) === REUSABLE_INSTANCE_COMPONENT_ID ? instancePropValues(raw) : undefined;
+        if (nested) {
+            let forwarded;
+            for (const [key, value] of Object.entries(nested)){
+                const name = matchComponentPropToken(value);
+                const valueClass = name ? typedProps.get(name) : undefined;
+                if (!name || !valueClass) continue;
+                forwarded = forwarded != null ? forwarded : _extends({}, instancePropValues(own()));
+                const known = knownValue(name);
+                const given = known ? known.value : forwarded[key];
+                if (isNothingToGive(given)) {
+                    delete forwarded[key];
+                    continue;
+                }
+                if (valueClass === 'icon') {
+                    const icon = readInstanceIconValue(given);
+                    const path = iconPaths == null ? void 0 : iconPaths[name];
+                    forwarded[key] = icon ? _extends({}, icon, path && !icon.iconPath ? {
+                        iconPath: path
+                    } : {}) : undefined;
+                    if (!forwarded[key]) delete forwarded[key];
+                    continue;
+                }
+                forwarded[key] = typedBindingValue(valueClass, {
+                    value: given
+                }, given);
+            }
+            if (forwarded) own()[REUSABLE_INSTANCE_PROP_VALUES_KEY] = forwarded;
+        }
+        if (!props) continue;
+        typed = typed != null ? typed : _extends({}, substituted);
+        typed[id] = _extends({}, substituted[id], {
+            props
+        });
+    }
+    return holdPropFedAddresses(nodes, typed != null ? typed : substituted);
+}
+/** A `{{prop.*}}` token's opening, escaped for a pattern. */ const PROP_TOKEN_SOURCE = `\\{\\{\\s*${COMPONENT_PROP_TOKEN_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`;
+/** Where a `{{prop.*}}` token opens, anywhere inside a value. */ const PROP_TOKEN_OPENING = new RegExp(PROP_TOKEN_SOURCE);
+/**
+ * The bindings that open a value and that a later compose stage resolves — a
+ * host token, a site variable — but not a property token, which this stage
+ * resolves or never will.
+ */ const LATER_BINDINGS_OPENING = new RegExp(`^(?:\\{\\{(?!${PROP_TOKEN_SOURCE.slice('\\{\\{'.length)})[^{}]*\\}\\}\\s*)+`);
+/**
+ * Whether a property-fed value may stay in an address prop once the
+ * substitution has made it.
+ *
+ * The address rule, with the site's own references admitted — a screen or
+ * collection link, a media-library pick — since this is the site that resolves
+ * them. One exception: a value that opens with a binding a later stage
+ * resolves (`{{host.url}}/about`) has no scheme until then, so the binding is
+ * left to supply one and what follows it is judged as though the binding came
+ * to nothing — which is what an unknown host token does — so a scheme cannot
+ * be smuggled in behind it.
+ */ function isRenderableAddress(prop, value) {
+    if (typeof value !== 'string') return false;
+    const address = value.trim();
+    if (isSafeNodeUrl(prop, address, {
+        siteReferences: true
+    })) return true;
+    const opening = LATER_BINDINGS_OPENING.exec(address);
+    if (!opening) return false;
+    const rest = address.slice(opening[0].length);
+    return rest === '' || isSafeNodeUrl(prop, rest, {
+        siteReferences: true
+    }) || !hasUrlScheme(rest);
+}
+/**
+ * `resolved` with every `href` and `src` that a `{{prop.*}}` token fed held to
+ * the address rule, and removed where it fails it (AGL-2933).
+ *
+ * A published node's own address is held to that rule when it is published,
+ * and a property's default when its declaration is — but a property's value
+ * is set by whichever page places the component, or screen inside the layout,
+ * long after either, and this is where it becomes the prop an element spreads
+ * onto the DOM. Canvas, Preview, detach and the tenant all arrive here, so a
+ * `javascript:` or `data:` value set on a property reaches none of them.
+ *
+ * It judges the whole value the substitution made (see
+ * {@link isRenderableAddress}), so a token behind a literal scheme
+ * (`https://example.com/{{prop.path}}`) stays a path on that site, and two
+ * values that spell a scheme between them are refused together. A value still
+ * holding its property token — an undeclared name, or the component editor's
+ * raw-token view — is no address either, and a linking element reads it as
+ * none.
+ *
+ * Only the prop goes: a button with no address is still a button. `raw` is
+ * the map before substitution, which is what says a token fed the value;
+ * neither map is mutated.
+ */ function holdPropFedAddresses(raw, resolved) {
+    let held;
+    for (const [id, node] of Object.entries(raw != null ? raw : {})){
+        const authored = node == null ? void 0 : node.props;
+        if (!authored || typeof authored !== 'object') continue;
+        let props;
+        for (const key of NODE_URL_PROPS){
+            var _this, _resolved_id, _resolved_id1;
+            const source = authored[key];
+            if (typeof source !== 'string' || !PROP_TOKEN_OPENING.test(source)) continue;
+            const current = (_this = props != null ? props : (_resolved_id = resolved[id]) == null ? void 0 : _resolved_id.props) == null ? void 0 : _this[key];
+            if (current === undefined || isRenderableAddress(key, current)) continue;
+            props = props != null ? props : _extends({}, (_resolved_id1 = resolved[id]) == null ? void 0 : _resolved_id1.props);
+            delete props[key];
+        }
+        if (!props) continue;
+        held = held != null ? held : _extends({}, resolved);
+        held[id] = _extends({}, resolved[id], {
+            props
+        });
+    }
+    return held != null ? held : resolved;
+}
+/**
+ * A definition's declared props resolved over a set of its nodes for one page,
+ * then the parts that page hides pruned (AGL-1314) — the single sequence the
+ * component graft, detach and a composed layout all run.
+ *
+ * `values` is the page's own map, and `rootId` the node the prune never
+ * removes. Visibility directives are evaluated on the result, never before:
+ * they read `{{prop.*}}` like everything else, so pruning ahead of
+ * substitution would see a token instead of the value and hide whatever the
+ * definition merely MENTIONED.
+ */ export function applyDeclaredProps(nodes, declared, values, rootId) {
+    const resolved = resolveReusablePropValues(declared, values);
+    return pruneHiddenNodes(resolveComponentPropTokens(nodes, declared, resolved.tokens, resolved.iconPaths, resolved.values), rootId);
+}
+/**
+ * Whether a node's props ask for it to be dropped (AGL-1314) — see
+ * {@link NODE_HIDE_IF_PROP} and {@link NODE_HIDE_UNLESS_PROP}.
+ *
+ * Evaluated on SUBSTITUTED props, so callers must run this after the
+ * declared-prop tokens have resolved; against a raw definition node every
+ * directive is still a token and reads as "no opinion" by design, which is
+ * what keeps the component editor showing the parts a page will hide.
+ */ export function isNodeHiddenByDirective(props) {
+    if (!props || typeof props !== 'object' || Array.isArray(props)) return false;
+    const bag = props;
+    if (readYesNoValue(bag[NODE_HIDE_IF_PROP]) === true) return true;
+    return readYesNoValue(bag[NODE_HIDE_UNLESS_PROP]) === false;
+}
+function hasVisibilityDirective(props) {
+    if (!props || typeof props !== 'object' || Array.isArray(props)) return false;
+    const bag = props;
+    return NODE_HIDE_IF_PROP in bag || NODE_HIDE_UNLESS_PROP in bag;
+}
+/**
+ * The node minus its visibility directives — they are compose-time
+ * instructions, and `Leaf` spreads whatever survives onto the component,
+ * so leaving them would put `hideif="…"` on the DOM of every node that
+ * declared one and stayed.
+ */ function withoutVisibilityDirectives(node) {
+    if (!hasVisibilityDirective(node == null ? void 0 : node.props)) return node;
+    const props = _extends({}, node.props);
+    delete props[NODE_HIDE_IF_PROP];
+    delete props[NODE_HIDE_UNLESS_PROP];
+    return _extends({}, node, {
+        props: props
+    });
+}
+/**
+ * Drops every node under `rootId` whose props ask to be hidden, along with
+ * its whole subtree and its entry in its parent's child list, and strips
+ * the directives off everything that survives (AGL-1314).
+ *
+ * Structural rather than a `display: none`: an instance can already hide a
+ * leaf with a per-leaf style override (AGL-1332), but that still ships the
+ * markup, still fetches the image, still leaves the grid column, and still
+ * leaves the control in the tab order. "This page has no mockup" is a
+ * statement about the tree, so it is made in the tree.
+ *
+ * `rootId` itself is never dropped. The graft below wires the instance
+ * node's single child to the definition root by id, so a self-hiding root
+ * would leave a dangling reference; a component that should not appear at
+ * all is a decision for the page that placed it, not for the definition.
+ *
+ * Returns the input unchanged when no node carries a directive, so the
+ * overwhelmingly common case costs one scan and allocates nothing.
+ */ export function pruneHiddenNodes(nodes, rootId) {
+    if (!nodes) return nodes;
+    let sawDirective = false;
+    for (const node of Object.values(nodes)){
+        if (hasVisibilityDirective(node == null ? void 0 : node.props)) {
+            sawDirective = true;
+            break;
+        }
+    }
+    if (!sawDirective) return nodes;
+    const hidden = new Set();
+    const seen = new Set();
+    const walk = (id)=>{
+        const node = nodes[id];
+        // `seen` bounds the walk: a definition that referenced an ancestor
+        // would otherwise recurse until the stack gave out.
+        if (!node || seen.has(id)) return;
+        seen.add(id);
+        const children = Array.isArray(node.nodes) ? node.nodes : [];
+        for (const childId of children){
+            var _nodes_childId;
+            if (typeof childId !== 'string' || !nodes[childId]) continue;
+            if (isNodeHiddenByDirective((_nodes_childId = nodes[childId]) == null ? void 0 : _nodes_childId.props)) {
+                hidden.add(childId);
+                for (const descendant of collectDescendantIds(nodes, childId)){
+                    hidden.add(descendant);
+                }
+                continue;
+            }
+            walk(childId);
+        }
+    };
+    walk(rootId);
+    const next = {};
+    for (const [id, node] of Object.entries(nodes)){
+        if (hidden.has(id)) continue;
+        const kept = withoutVisibilityDirectives(node);
+        const children = Array.isArray(kept == null ? void 0 : kept.nodes) ? kept.nodes : null;
+        const survivors = children && children.some((childId)=>hidden.has(childId)) ? children.filter((childId)=>!hidden.has(childId)) : null;
+        next[id] = survivors ? _extends({}, kept, {
+            nodes: survivors
+        }) : kept;
+    }
+    return next;
+}
+/**
+ * Expands reusable-component instance nodes (componentId
+ * {@link REUSABLE_INSTANCE_COMPONENT_ID}, `props.refId` → definition id) by
+ * grafting the referenced definition's subtree under each instance:
+ *
+ * - Grafted node ids are namespaced per instance (`cmp__{instanceId}__…`).
+ * - The instance node keeps its identity (selection/attributes target) and
+ *   gains the grafted root as its only child.
+ * - Unresolvable refIds leave the instance untouched — a deleted definition
+ *   must never take a published screen down.
+ * - Definitions may contain instances of other definitions; expansion
+ *   repeats up to {@link MAX_COMPONENT_DEPTH} passes, which also bounds
+ *   accidental self-reference.
+ * - A definition's declared props (AGL-1247) resolve per instance as the
+ *   subtree is grafted: `{{prop.name}}` tokens take that instance's
+ *   override, falling back to the prop's default. This is what lets one
+ *   hero serve eleven pages instead of being copied onto each.
+ * - A grafted node asking to be hidden ({@link NODE_HIDE_IF_PROP} /
+ *   {@link NODE_HIDE_UNLESS_PROP}, AGL-1314) is pruned with its subtree —
+ *   which is how one hero renders with a mockup on `/product` and without
+ *   one on `/press`.
+ * - Inputs are never mutated.
+ *
+ * `morePlacements` adds further node kinds that stand for a stored tree — a
+ * placed form is the second one ({@link PlacementKind}) — expanded in the same
+ * passes as instances, so the two nest inside each other in either order.
+ *
+ * ⛔ **A placement is expanded only when its tree RESOLVES**, meaning the
+ * document is in the map AND carries a `rootId` its `nodes` actually hold. An
+ * unresolvable one is left exactly as authored. That is what makes the
+ * child-replacing kind safe to introduce on a live site: a form bound to an
+ * entity that has never been published still renders the fields drawn on the
+ * page, and the graft can only ever swap a page's copy of a form for the
+ * entity's own.
+ */ export function composeReusableComponentNodes(nodes, definitionsById, morePlacements) {
+    const placements = [
+        {
+            componentId: REUSABLE_INSTANCE_COMPONENT_ID,
+            refProp: 'refId',
+            definitionsById
+        },
+        ...morePlacements != null ? morePlacements : []
+    ].filter((placement)=>placement.definitionsById);
+    if (!placements.length) return nodes;
+    /**
+   * The kind and tree this node stands for, or `undefined` when it stands for
+   * nothing resolvable.
+   *
+   * The `nodes[rootId]` check is the resolution rule stated once: a document
+   * whose root is not among its own nodes has no design to graft, and wiring
+   * the placement's only child to an id nothing holds would blank it on the
+   * page while reading, downstream, as already expanded.
+   */ const resolvePlacement = (node)=>{
+        for (const placement of placements){
+            var _node_props, _placement_definitionsById, _definition_nodes;
+            if ((node == null ? void 0 : node.componentId) !== placement.componentId) continue;
+            const refId = (_node_props = node.props) == null ? void 0 : _node_props[placement.refProp];
+            if (typeof refId !== 'string' || !refId) continue;
+            const definition = (_placement_definitionsById = placement.definitionsById) == null ? void 0 : _placement_definitionsById[refId];
+            if (!(definition == null ? void 0 : definition.rootId) || !((_definition_nodes = definition.nodes) == null ? void 0 : _definition_nodes[definition.rootId])) continue;
+            return {
+                placement,
+                definition
+            };
+        }
+        return undefined;
+    };
+    /** Expanded by an earlier pass — its children already carry its prefix. */ const alreadyGrafted = (id, node)=>{
+        const childIds = Array.isArray(node.nodes) ? node.nodes : [];
+        return childIds.some((childId)=>typeof childId === 'string' && childId.startsWith(instancePrefix(id)));
+    };
+    let composed = nodes;
+    /*
+   * WHAT A RESOLVED FORM REPLACES, DROPPED BEFORE ANYTHING IS GRAFTED.
+   *
+   * Ahead of the passes rather than inside them so the drop is decided against
+   * the authored tree alone. Inside a pass it would race the expansions
+   * running beside it: an inline field that was itself a component instance
+   * could be grafted in the same pass that discards it, and its grafted
+   * subtree — keyed off ids this walk never sees — would survive its own
+   * parent as unreachable nodes on a published page.
+   */ const doomed = new Set();
+    const emptied = [];
+    for (const [id, node] of Object.entries(nodes)){
+        var _resolvePlacement;
+        if (!node || !((_resolvePlacement = resolvePlacement(node)) == null ? void 0 : _resolvePlacement.placement.replacesAuthoredChildren)) {
+            continue;
+        }
+        if (alreadyGrafted(id, node)) continue;
+        const descendants = collectDescendantIds(nodes, id);
+        if (!descendants.size) continue;
+        for (const descendantId of descendants)doomed.add(descendantId);
+        emptied.push(id);
+    }
+    if (doomed.size) {
+        const pruned = {};
+        for (const [id, node] of Object.entries(nodes)){
+            if (!doomed.has(id)) pruned[id] = node;
+        }
+        for (const id of emptied){
+            // A replaced form nested in another replaced form's authored children is
+            // gone with it, so there is nothing left here to empty.
+            if (pruned[id]) pruned[id] = _extends({}, pruned[id], {
+                nodes: []
+            });
+        }
+        composed = pruned;
+    }
+    /**
+   * Which definition each graft brought in, keyed by the id prefix its nodes
+   * carry — the ancestry a node cannot expand into again.
+   *
+   * `alreadyGrafted` bounds an instance against ITSELF: once a node's children
+   * carry its prefix, that node is done. It cannot see the other shape, where
+   * a definition's own subtree contains a FRESH instance naming the same
+   * definition. Each pass mints a new instance id, so that node looks new to
+   * every check there was, and the graft ran again on its own output until
+   * {@link MAX_COMPONENT_DEPTH} stopped it.
+   *
+   * A depth cap is the right backstop for a reusable component, where
+   * self-reference is an authoring mistake. It is the wrong bound for a FORM:
+   * `checkFormContract` REQUIRES a form design's tree to contain a `form` node
+   * naming that same form, so a placed form does not merely risk grafting into
+   * itself — it always does, to the cap, every render. Six nested `<form>`
+   * elements is invalid HTML, so the server parser drops the inner ones and
+   * the client tree then disagrees with the server tree, which is a hydration
+   * failure on a public page.
+   *
+   * Keyed by prefix because the prefix chain IS the ancestry: a node grafted
+   * inside instance X has an id beginning with X's prefix, and one nested two
+   * deep begins with both. Testing `startsWith` against a definition already
+   * open above therefore asks exactly the right question — "is this the same
+   * definition, inside its own expansion?" — while leaving a genuinely
+   * different form placed inside a form free to expand.
+   */ const graftedAncestry = [];
+    /**
+   * The definition id a node points at, and the placement that claims it.
+   *
+   * Scoped to placements that REPLACE authored children. That is what a form
+   * does and what a reusable-component instance does not, and the difference
+   * is the whole reason this guard is narrow: for a component, a definition
+   * naming itself is an authoring mistake whose documented behaviour is a
+   * depth-bounded expansion, and collapsing it here would change a semantic
+   * this fix has no business touching. For a placement that replaces children,
+   * the instance and the definition's root denote the same thing.
+   */ const replacingRefOf = (node)=>{
+        for (const placement of placements){
+            var _node_props;
+            if (!placement.replacesAuthoredChildren) continue;
+            // `componentId` sits on the NODE and the ref on its props, matching
+            // `resolvePlacement` exactly — a predicate that drifted from that one
+            // would not fail loudly, it would simply never match and leave the guard
+            // switched off.
+            if ((node == null ? void 0 : node.componentId) !== placement.componentId) continue;
+            const refId = (_node_props = node.props) == null ? void 0 : _node_props[placement.refProp];
+            if (typeof refId === 'string' && refId) return {
+                refId,
+                placement
+            };
+        }
+        return null;
+    };
+    /** Just the id, for the two call sites that do not need the placement. */ const refIdOf = (node)=>{
+        var _ref;
+        var _replacingRefOf;
+        return (_ref = (_replacingRefOf = replacingRefOf(node)) == null ? void 0 : _replacingRefOf.refId) != null ? _ref : null;
+    };
+    /**
+   * Is this node an instance of a definition already open above it?
+   *
+   * Left completely untouched when so — not pruned, not emptied. An unexpanded
+   * form node renders its own authored children, which is the same thing an
+   * unresolvable ref does, and matches the rule that a missing definition must
+   * never take a published page down.
+   */ const withinOwnExpansion = (id, node)=>{
+        const refId = refIdOf(node);
+        if (!refId) return false;
+        return graftedAncestry.some((entry)=>entry.refId === refId && id.startsWith(entry.prefix));
+    };
+    for(let depth = 0; depth < MAX_COMPONENT_DEPTH; depth++){
+        const pending = Object.entries(composed).filter(([id, node])=>Boolean(resolvePlacement(node)) && !alreadyGrafted(id, node) && !withinOwnExpansion(id, node));
+        if (!pending.length) break;
+        const next = _extends({}, composed);
+        for (const [instanceId, instanceNode] of pending){
+            const definition = resolvePlacement(instanceNode).definition;
+            const prefix = instancePrefix(instanceId);
+            // Recorded BEFORE the subtree is written, so the nodes this graft is
+            // about to produce are already inside its ancestry when the next pass
+            // considers them.
+            const grafting = refIdOf(instanceNode);
+            if (grafting) graftedAncestry.push({
+                prefix,
+                refId: grafting
+            });
+            const prefixId = (id)=>`${prefix}${id}`;
+            // Style overrides (AGL-1306 root, AGL-1332 per leaf): merged over
+            // each definition node's own sx as this instance's copy is grafted —
+            // per-instance scope exists only here, exactly like the declared-prop
+            // substitution below. Merging into the graft (rather than a renderer
+            // patch) is what gives canvas/Preview/tenant parity for free, and
+            // reading the definition's CURRENT nodes each pass is why an override
+            // can never pin the instance to an old component version.
+            //
+            // Per-leaf is not a nicety: a component's text leaves usually set
+            // their OWN colour, so a root-level `color` never reaches them and an
+            // instance given a white background renders white-on-white (AGL-1318).
+            const styleOverrides = getInstanceStyleOverrides(instanceNode);
+            // Attribute overrides (AGL-1899) ride the same graft for the same
+            // reason: this is the one point where per-instance scope exists, so
+            // merging here is what makes canvas, Preview and tenant SSR agree
+            // without any of them knowing an override happened.
+            //
+            // Applied to the props BEFORE `resolveNamedTokens` below, which is
+            // what lets an override be written in `{{prop.*}}`/`{{var:id}}` and
+            // still resolve, and what makes an override on a bound prop beat the
+            // component's own binding — the more specific placement wins.
+            const attrOverrides = getInstanceAttrOverrides(instanceNode);
+            const grafted = {};
+            for (const [defId, defNode] of Object.entries(definition.nodes)){
+                var _defNode_$id, _instanceSxPatch, _instancePropsPatch;
+                if (!defNode) continue;
+                grafted[prefixId(defId)] = _extends({}, defNode, {
+                    $id: prefixId((_defNode_$id = defNode.$id) != null ? _defNode_$id : defId),
+                    parentId: defId === definition.rootId ? instanceId : defNode.parentId != null ? prefixId(defNode.parentId) : defNode.parentId
+                }, Array.isArray(defNode.nodes) && {
+                    nodes: defNode.nodes.map((childId)=>typeof childId === 'string' ? prefixId(childId) : childId)
+                }, (_instanceSxPatch = instanceSxPatch(defNode.sx, styleOverrides, defId, definition.rootId)) != null ? _instanceSxPatch : {}, (_instancePropsPatch = instancePropsPatch(defNode.props, attrOverrides, defId, definition.rootId)) != null ? _instancePropsPatch : {});
+            }
+            // Declared props (AGL-1247) substitute HERE, on this instance's copy
+            // of the subtree — the only point in the pipeline where per-instance
+            // scope exists, since after the merge every grafted node is just
+            // another entry in one flat map.
+            //
+            // The value lands in a real string prop and compose runs graft →
+            // repeatables → `resolveNodesBindings`, so a `{{var:id}}` typed into
+            // an override still resolves downstream for free. A field bound to a
+            // prop that is not text is finished by that prop's kind instead — see
+            // `resolveComponentPropTokens` — and the parts this page hides are
+            // pruned from the result (`applyDeclaredProps`).
+            Object.assign(next, applyDeclaredProps(grafted, definition.props, instancePropValues(instanceNode.props), prefixId(definition.rootId)));
+            /*
+       * A definition whose ROOT names the definition itself is grafted
+       * UNWRAPPED — its root's children attach to the instance, and the
+       * duplicate root is dropped.
+       *
+       * Bounding the recursion above stops the runaway, but one graft of a
+       * self-naming design still produces two of the same element nested: the
+       * placed node, and the design's root inside it. For a form that is a
+       * `<form>` inside a `<form>`, which is invalid HTML — the server parser
+       * drops the inner one, the client keeps it, and the two trees disagree.
+       * Six of them or two, the page still fails to hydrate.
+       *
+       * Unwrapping is not a special case bolted on for forms: the instance and
+       * the definition's root denote THE SAME THING here, and rendering both
+       * was always the duplicate. `checkFormContract` is what makes a form
+       * design always take this shape, so for forms this branch is the normal
+       * path rather than the exception.
+       *
+       * The instance keeps its own props: it is the node the page authored,
+       * carrying the id everything else resolves against.
+       */ const graftedRootId = prefixId(definition.rootId);
+            const definitionRoot = definition.nodes[definition.rootId];
+            const rootNamesItself = Boolean(grafting) && refIdOf(definitionRoot) === grafting;
+            const graftedRoot = next[graftedRootId];
+            if (rootNamesItself && graftedRoot) {
+                const adopted = Array.isArray(graftedRoot.nodes) ? graftedRoot.nodes : [];
+                for (const childId of adopted){
+                    if (next[childId]) {
+                        next[childId] = _extends({}, next[childId], {
+                            parentId: instanceId
+                        });
+                    }
+                }
+                delete next[graftedRootId];
+                next[instanceId] = _extends({}, instanceNode, {
+                    nodes: adopted
+                });
+            } else if (graftedRoot) {
+                var _graftedRoot_props, _instanceNode_props;
+                /*
+         * THE INSTANCE AND THE DEFINITION'S ROOT ARE ONE ELEMENT (AGL-2521).
+         *
+         * The graft used to keep both — the instance as a container with the
+         * definition's root inside it — so every placement published a `div`
+         * the author never drew. On `aglyn.com` that was four of them on the
+         * home page, one per placement, each sitting between a landmark and
+         * its parent and breaking any direct-child selector the layout wrote.
+         *
+         * So the root TAKES THE INSTANCE'S PLACE: same id, same parent, same
+         * slot in the parent's child list. Its own grafted id disappears and
+         * its children keep theirs, which is what leaves the `cmp__{instance}
+         * __{defId}` scheme — and everything reading it, from per-leaf
+         * overrides to {@link resolveInstanceLeafBinding} — untouched.
+         *
+         * Keeping the INSTANCE'S id rather than the root's is the half that
+         * matters: interactions, animations and analytics are all keyed to the
+         * node the page authored, and a swap to the prefixed id would silently
+         * drop every one of them.
+         *
+         * What the instance contributed as an element comes with it. Its `sx`
+         * merges OVER the root's, because a placement styling its component is
+         * the more specific of the two. Its universal directives — hide,
+         * animate — move across for the same reason: they were authored
+         * against "this placement", which is now this element. What stays
+         * behind is the bookkeeping that only ever addressed the wrapper:
+         * `refId`, `name`, the declared-prop values and the override slices,
+         * all of them already consumed by the graft above.
+         */ /*
+         * Interactions come from BOTH nodes, root's first.
+         *
+         * They are keyed to the element by node id, and after the merge one
+         * element answers to two authors: the component, which wrote the
+         * choreography its internals rely on, and the placement, which wrote
+         * whatever this page wants on top. Keeping only one side silently
+         * drops the other's — and because the instance keeps its own id, the
+         * side that would go missing is the page's, on the very node whose id
+         * it is.
+         *
+         * Root's run first for the reason the host actions do in
+         * `getClientAutomations`: the more general enrolls before the more
+         * specific, which is the order a page is read in.
+         *
+         * `interactions` is declared on `NodeSchema`, one layer above the
+         * `AglynNodeSchema` this function is generic over, so both are read
+         * off the node rather than through the type.
+         */ const interactionsOf = (node)=>{
+                    const value = node == null ? void 0 : node.interactions;
+                    return Array.isArray(value) ? value : [];
+                };
+                const mergedInteractions = [
+                    ...interactionsOf(graftedRoot),
+                    ...interactionsOf(instanceNode)
+                ];
+                const carried = {};
+                for (const key of INSTANCE_CARRIED_PROPS){
+                    var _instanceNode_props1;
+                    const value = (_instanceNode_props1 = instanceNode.props) == null ? void 0 : _instanceNode_props1[key];
+                    if (value !== undefined) carried[key] = value;
+                }
+                /*
+         * A placement's repeat moves across too, and the element repeats
+         * ITSELF (AGL-3111).
+         *
+         * It is the other universal directive authored against "this
+         * placement": the page asked for one copy of the component per record.
+         * After the merge that component is an element whose children are the
+         * component's own, which would read as the item template, so the scope
+         * is stated rather than left to the child list. The placement's repeat
+         * replaces one on the component's root rather than mixing with it —
+         * repeats do not nest, and a filter meant for the root's rows applied
+         * to the placement's would be neither author's.
+         */ const repeatsPlacement = repeatKey(instanceNode) !== '';
+                if (repeatsPlacement) {
+                    for (const key of REPEAT_DIRECTIVE_PROPS){
+                        var _instanceNode_props2;
+                        const value = (_instanceNode_props2 = instanceNode.props) == null ? void 0 : _instanceNode_props2[key];
+                        if (value !== undefined) carried[key] = value;
+                    }
+                    carried[REPEAT_SELF_PROP] = true;
+                }
+                const rootProps = repeatsPlacement ? withoutRepeatDirective(graftedRoot).props : graftedRoot.props;
+                /*
+         * Classes from BOTH nodes, the component root's first.
+         *
+         * A class names the element for the site's stylesheet and for the
+         * runtime: ⋮ ▸ Start hidden writes `aglyn-hidden` into the placement's
+         * `props.className`, and the show/hide steps toggle that class on the
+         * element answering to the placement's id, which after the merge is
+         * this one. Keeping either list alone drops the other author's names,
+         * so the two are joined, each name once, in `props` and on the node.
+         */ const propsClassName = joinClassNames((_graftedRoot_props = graftedRoot.props) == null ? void 0 : _graftedRoot_props['className'], (_instanceNode_props = instanceNode.props) == null ? void 0 : _instanceNode_props['className']);
+                if (propsClassName) carried['className'] = propsClassName;
+                const nodeClassName = joinClassNames(graftedRoot.className, instanceNode.className);
+                // The override slices and the reference are DOCUMENT state living on
+                // the node beside `sx`, not props — the renderer never spreads them at
+                // an element — so they ride along rather than being consumed and
+                // dropped. A composed map that is saved back must still carry what the
+                // author set on this placement (AGL-1306/AGL-1899), and a re-compose
+                // is a no-op because the merged node no longer answers to
+                // `reusableInstance`.
+                const documentState = {};
+                for (const key of INSTANCE_CARRIED_NODE_FIELDS){
+                    const value = instanceNode[key];
+                    if (value !== undefined) documentState[key] = value;
+                }
+                const mergedSx = mergeNodeSx(graftedRoot.sx, instanceNode.sx);
+                const merged = _extends({}, graftedRoot, {
+                    $id: instanceId,
+                    parentId: instanceNode.parentId
+                }, documentState, mergedSx === undefined ? {} : {
+                    sx: mergedSx
+                }, rootProps !== undefined || Object.keys(carried).length ? {
+                    props: _extends({}, rootProps, carried)
+                } : {}, nodeClassName ? {
+                    className: nodeClassName
+                } : {}, mergedInteractions.length ? {
+                    interactions: mergedInteractions
+                } : {}, instanceNode.hidden ? {
+                    hidden: true
+                } : {});
+                for (const childId of Array.isArray(merged.nodes) ? merged.nodes : []){
+                    if (next[childId]) {
+                        next[childId] = _extends({}, next[childId], {
+                            parentId: instanceId
+                        });
+                    }
+                }
+                delete next[graftedRootId];
+                next[instanceId] = merged;
+            } else {
+                /*
+         * The root was pruned by its own visibility directive, so there is
+         * nothing to take the instance's place. The instance stays as an empty
+         * container rather than vanishing: its own hide directive has not been
+         * evaluated yet, and removing a node the later passes still expect to
+         * walk would strand its parent's child list.
+         */ next[instanceId] = _extends({}, instanceNode, {
+                    nodes: []
+                });
+            }
+        }
+        composed = next;
+    }
+    return composed;
+}
+/**
+ * Ids of every descendant of `rootId` reachable through `nodes` arrays —
+ * the root itself excluded, unknown and repeated ids skipped, so a cycle
+ * cannot hang the walk.
+ *
+ * Child lists are the only edges followed, never `parentId`. That is the
+ * published renderer's own reach from the document root, which is why
+ * `pageVideoObjects` asks this which Video nodes a page draws (AGL-2957).
+ */ export function collectDescendantIds(nodes, rootId) {
+    const found = new Set();
+    const root = nodes == null ? void 0 : nodes[rootId];
+    const queue = Array.isArray(root == null ? void 0 : root.nodes) ? [
+        ...root.nodes
+    ] : [];
+    while(queue.length){
+        var _nodes_id;
+        const id = queue.shift();
+        if (found.has(id) || id === rootId || !nodes[id]) continue;
+        found.add(id);
+        const children = (_nodes_id = nodes[id]) == null ? void 0 : _nodes_id.nodes;
+        if (Array.isArray(children)) queue.push(...children);
+    }
+    return found;
+}
+/**
+ * Materializes the instance at `instanceId` into a plain, freely editable
+ * copy of what it was RENDERING (AGL-1314) — what "Detach from component"
+ * does, and the inverse of {@link replaceSubtreeWithInstance}.
+ *
+ * Deliberately here, beside the graft, because "what the instance rendered"
+ * is a question only {@link composeReusableComponentNodes} can answer. The
+ * console used to copy `definition.nodes` verbatim, which is the whole bug:
+ * the definition's leaves hold `{{prop.headline}}` TOKENS, not text, so a
+ * detached hero rendered its own markers and the author's copy was gone.
+ * A second, simpler materializer will always drift from the renderer —
+ * so this one runs the renderer's own steps:
+ *
+ * - Declared props (AGL-1247) resolve through {@link applyDeclaredProps},
+ *   exactly as the graft does: the instance's override, else the
+ *   definition's default. Every string prop is walked,
+ *   so an image's `src` bakes to the bound media for free — the token is
+ *   substituted by name, not by which prop happens to hold it.
+ * - The style overrides (AGL-1306 root, AGL-1332 per leaf) merge over the
+ *   matching definition node's own sx, so the copy keeps the look the page
+ *   was showing rather than snapping back to the component's base styling.
+ *   Every node is patched, not just the root: an instance re-coloured to a
+ *   white band with black copy must detach as a white band with black copy.
+ * - Ids are FRESH (`createId`), never the `cmp__…` graft namespace: a
+ *   detached copy is an ordinary subtree, and leaving graft ids behind
+ *   would collide the next time an instance of the same definition
+ *   expanded here. Only the root keeps the instance's id, so the parent's
+ *   child list, the undo stack and the selection all stay valid.
+ * - Anything hanging under the instance (a pre-grafted layout-chrome
+ *   subtree, AGL-1218) is dropped with it; the copy replaces the whole
+ *   thing.
+ *
+ * A missing instance, a node that is not an instance, or a definition
+ * without a resolvable root returns `nodes` UNCHANGED — detach must never
+ * be the thing that empties a screen. Inputs are never mutated.
+ */ export function detachInstanceSubtree(nodes, instanceId, definition, createId) {
+    var _definition_nodes;
+    const instanceNode = nodes == null ? void 0 : nodes[instanceId];
+    if ((instanceNode == null ? void 0 : instanceNode.componentId) !== REUSABLE_INSTANCE_COMPONENT_ID) {
+        return nodes;
+    }
+    const rootId = definition == null ? void 0 : definition.rootId;
+    if (!rootId || !(definition == null ? void 0 : (_definition_nodes = definition.nodes) == null ? void 0 : _definition_nodes[rootId])) return nodes;
+    // Fresh ids for everything but the root, which inherits the instance's.
+    // `createId` is injected so this stays pure (and specs stay readable);
+    // the loop re-rolls rather than trusting uniqueness, because a collision
+    // here would silently overwrite an unrelated node on the page.
+    const taken = new Set(Object.keys(nodes));
+    const idMap = {
+        [rootId]: instanceId
+    };
+    for (const defId of Object.keys(definition.nodes)){
+        if (idMap[defId] != null) continue;
+        let fresh = createId();
+        for(let attempt = 0; (!fresh || taken.has(fresh)) && attempt < 10; attempt++){
+            fresh = createId();
+        }
+        taken.add(fresh);
+        idMap[defId] = fresh;
+    }
+    const styleOverrides = getInstanceStyleOverrides(instanceNode);
+    const attrOverrides = getInstanceAttrOverrides(instanceNode);
+    const copied = {};
+    for (const [defId, defNode] of Object.entries(definition.nodes)){
+        var _instanceNode_parentId, _idMap_defNode_parentId, _defNode_parentId, _instanceSxPatch, _instancePropsPatch;
+        if (!defNode) continue;
+        const newId = idMap[defId];
+        copied[newId] = _extends({}, defNode, {
+            $id: newId,
+            parentId: defId === rootId ? (_instanceNode_parentId = instanceNode.parentId) != null ? _instanceNode_parentId : null : defNode.parentId != null ? (_idMap_defNode_parentId = idMap[defNode.parentId]) != null ? _idMap_defNode_parentId : null : (_defNode_parentId = defNode.parentId) != null ? _defNode_parentId : null
+        }, Array.isArray(defNode.nodes) && {
+            nodes: defNode.nodes.map((childId)=>{
+                var _idMap_childId;
+                return typeof childId === 'string' ? (_idMap_childId = idMap[childId]) != null ? _idMap_childId : childId : childId;
+            })
+        }, (_instanceSxPatch = instanceSxPatch(defNode.sx, styleOverrides, defId, rootId)) != null ? _instanceSxPatch : {}, (_instancePropsPatch = instancePropsPatch(defNode.props, attrOverrides, defId, rootId)) != null ? _instancePropsPatch : {});
+    }
+    const doomed = collectDescendantIds(nodes, instanceId);
+    const next = {};
+    for (const [id, node] of Object.entries(nodes)){
+        if (id === instanceId || doomed.has(id)) continue;
+        next[id] = node;
+    }
+    // Detach must materialize what the instance was RENDERING, so the parts
+    // this page hid (AGL-1314) are absent from the copy too — a detached hero
+    // that grew its mockup back is the same class of bug as one that rendered
+    // `{{prop.headline}}`.
+    return Object.assign(next, applyDeclaredProps(copied, definition.props, instancePropValues(instanceNode.props), instanceId));
+}
+/**
+ * The definition a subtree becomes when it is promoted (AGL-2908): the
+ * element at `rootId` and everything under it, as a component document's own
+ * `nodes` map.
+ *
+ * The other half of "Save as reusable component", beside
+ * {@link replaceSubtreeWithInstance}: this one says what the new document
+ * holds, that one says what the promoting document keeps. Both are here so
+ * neither can drift from what the graft expects to read back.
+ *
+ * - The promoted root's `parentId` is dropped. In its old document it hung
+ *   from a section; in its own it IS the document, and a definition whose
+ *   root still points at a parent it no longer has grafts nothing.
+ * - Editor-only fields go: `componentSchema` is the palette's own object and
+ *   `resolvedProps` is a render of the props beside them, so storing either
+ *   writes a snapshot of the editor into a document the renderer reads.
+ * - Unknown `rootId` gives an empty map, and the input is never mutated.
+ *
+ * Child lists are the only edges followed, so an element the subtree does not
+ * reach is not carried along even if it claims the root as its parent.
+ */ export function reusableComponentDefinitionFrom(nodes, rootId) {
+    const root = nodes == null ? void 0 : nodes[rootId];
+    if (!root) return {};
+    const definition = {};
+    for (const id of [
+        rootId,
+        ...collectDescendantIds(nodes, rootId)
+    ]){
+        const node = nodes[id];
+        if (!node) continue;
+        const { componentSchema: _schema, resolvedProps: _resolved } = node, stored = _object_without_properties_loose(node, [
+            "componentSchema",
+            "resolvedProps"
+        ]);
+        definition[id] = id === rootId ? _extends({}, stored, {
+            parentId: null
+        }) : stored;
+    }
+    return definition;
+}
+/**
+ * Replaces the subtree rooted at `rootId` with an instance of `definitionId`
+ * (AGL-1193) — what "Save as reusable component" does to the tree it was
+ * promoted from.
+ *
+ * Without this the promoting document keeps an inline *copy*: the one place
+ * guaranteed never to track the component it created, silently. Deliberately
+ * in this file so the swap and {@link composeReusableComponentNodes} cannot
+ * drift about what an instance node looks like.
+ *
+ * - The instance keeps the promoted root's `$id` and `parentId`, so the
+ *   parent's child list, the undo stack and the current selection all stay
+ *   valid — the mirror of the detach path, which reuses the instance id.
+ * - Every descendant is dropped; its content now lives in the definition.
+ * - `displayName` rides along as a prop purely so the editor placeholder can
+ *   name what it stands for (definitions are not grafted into the canvas).
+ * - Unknown `rootId` is a no-op, and the input is never mutated.
+ */ export function replaceSubtreeWithInstance(nodes, rootId, definitionId, displayName) {
+    var _root_parentId;
+    const root = nodes == null ? void 0 : nodes[rootId];
+    if (!root || !definitionId) return nodes;
+    // Descendants only — the root is replaced, not removed.
+    const doomed = collectDescendantIds(nodes, rootId);
+    const next = {};
+    for (const [id, node] of Object.entries(nodes)){
+        if (!doomed.has(id)) next[id] = node;
+    }
+    next[rootId] = {
+        $id: rootId,
+        parentId: (_root_parentId = root.parentId) != null ? _root_parentId : null,
+        componentId: REUSABLE_INSTANCE_COMPONENT_ID,
+        pluginId: 'mui',
+        props: _extends({
+            refId: definitionId
+        }, displayName && {
+            name: displayName
+        }),
+        nodes: []
+    };
+    return next;
+}
+/**
+ * The icon path an instance node should be drawn with (AGL-1193), or
+ * `undefined` when the node is not an instance, its definition is unknown,
+ * or that definition chose no icon — every one of which means "fall back to
+ * the component schema's own glyph".
+ *
+ * The visual half of `getNodeLabelShort`: an instance stands for one
+ * specific component, so a hierarchy of promoted sections drawn with one
+ * repeated package glyph tells the author nothing. Unlike the label, the
+ * icon is NOT denormalized onto the instance — it is read live off the
+ * definition, so changing a component's icon updates every instance already
+ * placed instead of only the ones inserted afterwards.
+ *
+ * Deliberately here rather than in the canvas manager: this file owns what
+ * an instance node looks like, and a second reader that disagreed would draw
+ * definition icons on nodes the graft does not treat as instances.
+ *
+ * Returns only the stored `iconPath`. Resolving `iconId` would need the
+ * ~2.9 MB icon catalog, which render surfaces never load — and the lookup
+ * that "helpfully" substitutes a default is what made every icon a "help"
+ * glyph in AGL-1212.
+ */ export function resolveInstanceIconPath(node, definitionsById) {
+    var _node_props, _definitionsById_refId_icon, _definitionsById_refId;
+    if (!node || !definitionsById) return undefined;
+    if (node.componentId !== REUSABLE_INSTANCE_COMPONENT_ID) return undefined;
+    const refId = (_node_props = node.props) == null ? void 0 : _node_props.refId;
+    if (typeof refId !== 'string' || !refId) return undefined;
+    return ((_definitionsById_refId = definitionsById[refId]) == null ? void 0 : (_definitionsById_refId_icon = _definitionsById_refId.icon) == null ? void 0 : _definitionsById_refId_icon.iconPath) || undefined;
+}
+/**
+ * Whether a node map contains an instance of `definitionId` (AGL-703).
+ *
+ * The inverse of the graft above, and deliberately in the same file: a
+ * "Used by" card that disagreed with {@link composeReusableComponentNodes}
+ * about what counts as a reference would report "used nowhere" for
+ * something the renderer does expand, which is an invitation to delete it.
+ *
+ * Scans ONLY direct instances. Callers wanting transitive usage must scan
+ * definitions too — a definition may nest instances of other definitions,
+ * so "used by no screen" does not mean "used by nothing".
+ */ export function nodesReferenceComponent(nodes, definitionId) {
+    if (!nodes || !definitionId) return false;
+    return Object.values(nodes).some((node)=>{
+        var _node_props;
+        return (node == null ? void 0 : node.componentId) === REUSABLE_INSTANCE_COMPONENT_ID && ((_node_props = node.props) == null ? void 0 : _node_props.refId) === definitionId;
+    });
+}
+/**
+ * Every definition id a node map renders, DIRECTLY or through another
+ * definition (AGL-1898).
+ *
+ * {@link nodesReferenceComponent} answers the same question for one id and
+ * scans direct instances only — its own doc says a caller wanting transitive
+ * usage "must scan definitions too". This is that scan, kept beside the
+ * graft for the same reason: a caller that disagreed with
+ * {@link composeReusableComponentNodes} about what a document references
+ * would be wrong about exactly the nested case the canvas draws.
+ *
+ * Why it exists here rather than at a call site. A screen's canvas re-grafts
+ * when the host's definitions map changes, which is the whole of AGL-1898's
+ * phase-2 transport — but that map changes whenever ANY component in the
+ * host is published, most of them not on this page. Deciding whether a
+ * change is this document's business needs the transitive set, because the
+ * usual shared component is reached through a nav or a card rather than
+ * placed on the screen itself.
+ *
+ * - Unresolvable ids are INCLUDED. A screen referencing a definition that is
+ *   unpublished, deleted, or simply not in the map yet still references it;
+ *   a caller filtering to "what can expand" can intersect with its own map,
+ *   whereas an id dropped here cannot be recovered.
+ * - Cycles terminate: an id already collected is never re-walked, which
+ *   bounds a self-referencing definition the same way
+ *   {@link MAX_COMPONENT_DEPTH} bounds the graft.
+ * - Traversal is over the definition's stored `nodes`, NOT a composed tree,
+ *   so it costs nothing and cannot be thrown off by grafted ids.
+ */ export function collectReferencedComponentIds(nodes, definitionsById) {
+    const found = new Set();
+    const directRefIds = (source)=>{
+        const ids = [];
+        for (const node of Object.values(source != null ? source : {})){
+            var _node_props;
+            if ((node == null ? void 0 : node.componentId) !== REUSABLE_INSTANCE_COMPONENT_ID) continue;
+            const refId = (_node_props = node.props) == null ? void 0 : _node_props.refId;
+            if (typeof refId === 'string' && refId) ids.push(refId);
+        }
+        return ids;
+    };
+    const queue = directRefIds(nodes);
+    while(queue.length){
+        const refId = queue.shift();
+        if (found.has(refId)) continue;
+        found.add(refId);
+        const definition = definitionsById == null ? void 0 : definitionsById[refId];
+        if (!(definition == null ? void 0 : definition.nodes)) continue;
+        queue.push(...directRefIds(definition.nodes));
+    }
+    return found;
+}
+export default composeReusableComponentNodes;
+
+//# sourceMappingURL=compose-reusable-components.js.map