@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/compose-reusable-components.d.ts

@@ -0,0 +1,504 @@
+/**
+ * @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.
+ */
+import type { AglynNodeSchema, NodeId, ReusableComponentIcon, ReusableComponentProp } from '../foundation';
+export * from './reusable-component-keys';
+export * from './reusable-prop-values';
+/**
+ * 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 declare function getInstanceStyleOverrides(node: {
+    componentId?: string;
+    styleOverrides?: unknown;
+} | undefined | null): Record<string, Record<string, unknown>>;
+/**
+ * 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 declare function getInstanceRootStyleOverride(node: {
+    componentId?: string;
+    styleOverrides?: unknown;
+} | undefined | null): Record<string, unknown> | undefined;
+/**
+ * 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 declare function getInstanceAttrOverrides(node: {
+    componentId?: string;
+    attrOverrides?: unknown;
+} | undefined | null): Record<string, Record<string, unknown>>;
+/** One styleable target inside an instance — see {@link listInstanceStyleTargets}. */
+export interface InstanceStyleTarget {
+    /** The `styleOverrides` key this target reads and writes. */
+    key: string;
+    /** The definition-internal node id it styles. */
+    componentInternalId: NodeId;
+    /** 0 for the component root, +1 per level down — the picker indents by it. */
+    depth: number;
+    /** The definition node's `componentId`, so a picker can label it. */
+    componentId?: string;
+    /** The definition node's own `name`, when the component author set one. */
+    name?: string;
+    /** True for the component root (the AGL-1306 target). */
+    isRoot: boolean;
+}
+/**
+ * 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 declare function listInstanceStyleTargets(definition: Pick<ReusableComponentTree<any>, 'rootId' | 'nodes'> | null | undefined): InstanceStyleTarget[];
+type NormalizedNodes<N extends AglynNodeSchema> = Record<NodeId, N>;
+/** Stored shape of a host-level reusable component definition's tree. */
+export interface ReusableComponentTree<N extends AglynNodeSchema = AglynNodeSchema> {
+    rootId: NodeId;
+    nodes: NormalizedNodes<N>;
+    /** Props this definition declares (AGL-1247); absent = unparameterised. */
+    props?: ReusableComponentProp[];
+    /**
+     * The definition's chosen icon (AGL-1193), carried so every editor surface
+     * that draws an instance can reach it without a second read. Nothing in
+     * the graft below touches it — an instance's icon is editor chrome, and
+     * the published page renders the definition's own nodes.
+     */
+    icon?: ReusableComponentIcon;
+}
+/**
+ * One kind of node that STANDS FOR a tree stored on another document, and
+ * where that tree comes from.
+ *
+ * A reusable-component instance was the first such node; a placed form is the
+ * second (`componentId: 'form'`, `props.formId` → `hosts/{hostId}/forms/{id}`,
+ * whose published `rootId`/`nodes` are the fields the page renders). They are
+ * one mechanism described twice, so they run through one expansion rather than
+ * two passes that would have to agree about id namespacing, depth bounding and
+ * cycle safety — and, more sharply, could not see each other: a form placed
+ * inside a shared component only exists after the component graft, and a
+ * reusable instance inside a form design only exists after the form graft.
+ * Passing both kinds to {@link composeReusableComponentNodes} expands each
+ * against the other, in either nesting order, within the same depth bound.
+ */
+export interface PlacementKind<N extends AglynNodeSchema = AglynNodeSchema> {
+    /** The `componentId` a node must carry to be expanded by this kind. */
+    componentId: string;
+    /** The prop naming the document whose tree is grafted. */
+    refProp: string;
+    /** Resolvable trees, keyed by the id `refProp` holds. */
+    definitionsById: Record<string, ReusableComponentTree<N> | undefined> | undefined;
+    /**
+     * Whether a resolved graft DISCARDS what the placement node already held.
+     *
+     * Off for reusable instances, which never hold anything: the editor refuses
+     * a drop into them (`flags.dropping: DISABLED`), so replacing the child list
+     * with the grafted root is the whole of what the graft has to do.
+     *
+     * On for placed forms, which do — a form node accepts fields, and every form
+     * on the site was built that way before the form entity existed. Those
+     * inline fields are the node's OWN content, so they cannot merely be
+     * unlinked: left in the map they would still be walked by every later
+     * compose stage, still ship in the page payload, and still answer to any
+     * scan that reads `formField` nodes out of a flat map. The subtree is
+     * dropped with the child list, exactly as `detachInstanceSubtree` drops what
+     * it replaces.
+     *
+     * ⚠️ This is the one thing here that can take content off a page that
+     * renders today, so it is deliberately gated on the graft RESOLVING: a
+     * placement whose document is missing, unpublished, or holds no design is
+     * left untouched, inline children and all. See
+     * {@link composeReusableComponentNodes}.
+     */
+    replacesAuthoredChildren?: boolean;
+}
+/**
+ * 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 declare function matchComponentPropToken(value: unknown): string | null;
+/** What feeds a grafted instance leaf — see {@link resolveInstanceLeafBinding}. */
+export interface InstanceLeafBinding {
+    /** The definition-internal node id the grafted leaf was copied from. */
+    componentInternalId: NodeId;
+    /**
+     * The declared prop whose value feeds the leaf's `contentProp`, or `null`
+     * when the leaf's content is the component's own (not prop-fed).
+     */
+    boundProp: string | 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 declare function resolveInstanceLeafBinding(graftedId: NodeId | null | undefined, instanceId: NodeId | null | undefined, definition: Pick<ReusableComponentTree, 'nodes' | 'props'> | null | undefined, contentProp?: string, rootId?: NodeId | null): InstanceLeafBinding | null;
+/**
+ * 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 declare function getInstanceEffectivePropText(instanceProps: unknown, declared: ReusableComponentProp[] | undefined | null, propName: string): string;
+/**
+ * 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 declare function resolveComponentPropTokens<N extends AglynNodeSchema = AglynNodeSchema>(nodes: NormalizedNodes<N>, declared: ReusableComponentProp[] | undefined | null, tokens: Record<string, string> | null | undefined, iconPaths?: Record<string, string> | null, values?: Record<string, unknown> | null): NormalizedNodes<N>;
+/**
+ * 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 declare function applyDeclaredProps<N extends AglynNodeSchema = AglynNodeSchema>(nodes: NormalizedNodes<N>, declared: ReusableComponentProp[] | undefined | null, values: Readonly<Record<string, unknown>> | null | undefined, rootId: NodeId): NormalizedNodes<N>;
+/**
+ * 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 declare function isNodeHiddenByDirective(props: unknown): boolean;
+/**
+ * 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 declare function pruneHiddenNodes<N extends AglynNodeSchema = AglynNodeSchema>(nodes: NormalizedNodes<N>, rootId: NodeId): NormalizedNodes<N>;
+/**
+ * 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 declare function composeReusableComponentNodes<N extends AglynNodeSchema = AglynNodeSchema>(nodes: NormalizedNodes<N>, definitionsById: Record<string, ReusableComponentTree<N> | undefined> | undefined, morePlacements?: readonly PlacementKind<N>[]): NormalizedNodes<N>;
+/**
+ * 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 declare function collectDescendantIds<N extends AglynNodeSchema>(nodes: NormalizedNodes<N>, rootId: NodeId): Set<NodeId>;
+/**
+ * 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 declare function detachInstanceSubtree<N extends AglynNodeSchema = AglynNodeSchema>(nodes: NormalizedNodes<N>, instanceId: NodeId, definition: Pick<ReusableComponentTree<N>, 'rootId' | 'nodes' | 'props'> | null | undefined, createId: () => NodeId): NormalizedNodes<N>;
+/**
+ * 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 declare function reusableComponentDefinitionFrom<N extends AglynNodeSchema = AglynNodeSchema>(nodes: NormalizedNodes<N>, rootId: NodeId): NormalizedNodes<N>;
+/**
+ * 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 declare function replaceSubtreeWithInstance<N extends AglynNodeSchema = AglynNodeSchema>(nodes: NormalizedNodes<N>, rootId: NodeId, definitionId: string, displayName?: string): NormalizedNodes<N>;
+/**
+ * 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 declare function resolveInstanceIconPath(node: {
+    componentId?: string;
+    props?: unknown;
+} | undefined | null, definitionsById: Record<string, {
+    icon?: ReusableComponentIcon;
+} | undefined> | undefined | null): string | 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 declare function nodesReferenceComponent(nodes: Record<string, AglynNodeSchema | undefined> | undefined | null, definitionId: string): boolean;
+/**
+ * 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 declare function collectReferencedComponentIds(nodes: Record<string, AglynNodeSchema | undefined> | undefined | null, definitionsById?: Record<string, {
+    nodes?: unknown;
+} | undefined> | undefined | null): Set<string>;
+export default composeReusableComponentNodes;