@kywi-software/core 0.10.0 → 0.12.0

package/dist/layout/component-refs.js

@@ -0,0 +1,848 @@
+/**
+ * component-refs.ts
+ * The pure layer under linked components (kywi-cms#147): finding the
+ * `componentId` links inside a layout document, diffing two documents' links,
+ * and materialising a link into an independent copy ("detach").
+ *
+ * Everything here is a pure function over plain layout data — no database, no
+ * React — so the instance index (`db/component-instance-queries.ts`), the
+ * detach-all endpoint, and the editor can all share one definition of "where
+ * are the links" and "what does detaching produce".
+ *
+ * Keep this module dependency-free beyond `./types.js`.
+ */
+import { validateLayoutSection, validateVariantContainer } from './types.js';
+/**
+ * Identity of a placement: the same component in the same node is one instance.
+ *
+ * The separator is US (unit separator, U+001F) — unusable inside a real id, so
+ * two different pairs can never collide on one key. It is deliberately NOT NUL:
+ * a NUL byte anywhere in the first 8 KiB makes git classify the whole source
+ * file as binary, which silently turns every diff and review of this file into
+ * "Bin 15229 bytes".
+ */
+export function componentRefKey(ref) {
+    return `${ref.componentId}${ref.nodeId}`;
+}
+function readComponentId(node) {
+    const value = node?.componentId;
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** Record a placement once — first occurrence, i.e. document order, wins. */
+function record(out, instance) {
+    const key = componentRefKey(instance);
+    if (!out.has(key))
+        out.set(key, instance);
+}
+function collectFromColumns(columns, out) {
+    for (const column of columns ?? []) {
+        for (const node of column.nodes ?? []) {
+            const componentId = readComponentId(node);
+            if (componentId) {
+                record(out, { componentId, nodeId: node.id, kind: 'module', node });
+            }
+        }
+    }
+}
+function collectFromSection(section, out) {
+    const componentId = readComponentId(section);
+    if (componentId) {
+        record(out, { componentId, nodeId: section.id, kind: 'section', node: section });
+        // A connected section renders its component's columns wholesale; the inline
+        // `columns` it still carries are only the fallback copy for an unresolvable
+        // link. Descending into them would count links the page never renders and
+        // double-count the ones the component definition owns — so stop here. What
+        // the definition contains is the component's business, not this page's.
+        return;
+    }
+    collectFromColumns(section.columns, out);
+}
+function collectFromRegionNode(node, out) {
+    if (node.type === 'section') {
+        collectFromSection(node, out);
+        return;
+    }
+    if (node.type === 'variantContainer') {
+        const componentId = readComponentId(node);
+        if (componentId) {
+            record(out, { componentId, nodeId: node.id, kind: 'variantContainer', node });
+            return; // same wholesale-resolution reasoning as a connected section
+        }
+        for (const section of node.defaultSections ?? [])
+            collectFromSection(section, out);
+        for (const variant of node.variants ?? []) {
+            for (const section of variant.sections ?? [])
+                collectFromSection(section, out);
+        }
+    }
+}
+function collectFromRegions(regions, out) {
+    for (const nodes of Object.values(regions ?? {})) {
+        for (const node of nodes ?? [])
+            collectFromRegionNode(node, out);
+    }
+}
+/**
+ * Every linked-component placement in a layout document, in document order,
+ * deduplicated by (componentId, nodeId).
+ *
+ * Page variants are walked because their regions really do render (the
+ * personalization pass swaps them in). A/B experiment variants are walked too,
+ * even though today's renderer never renders `abExperiments[]` regions — a link
+ * stored there is still a link the delete gate must see and detach-all must
+ * rewrite, otherwise deleting the component would leave a dangling id behind in
+ * data the renderer may well start honouring. Counting them can only ever
+ * over-report, never miss.
+ *
+ * Deduplication matters in both: a variant is often a near-copy of the default
+ * regions and may legitimately repeat a node id.
+ */
+export function collectComponentRefs(layout) {
+    return collectComponentInstances(layout).map(({ componentId, nodeId, kind }) => ({
+        componentId,
+        nodeId,
+        kind,
+    }));
+}
+/**
+ * {@link collectComponentRefs}, with the node each link sits on.
+ *
+ * THE traversal — `collectComponentRefs` is now a projection of this one, so
+ * "where are the links" and "what is in them" cannot drift apart. The nodes are
+ * the document's own objects, not copies: callers that intend to keep or rewrite
+ * one deep-copy it themselves (`detachedCopy` in the editor, jsonb serialisation
+ * on the server), exactly as they already did for the refs.
+ */
+export function collectComponentInstances(layout) {
+    const out = new Map();
+    if (!layout)
+        return [];
+    collectFromRegions(layout.regions, out);
+    for (const variant of layout.pageVariants ?? [])
+        collectFromRegions(variant.regions, out);
+    for (const experiment of layout.abExperiments ?? []) {
+        for (const variant of experiment.variants ?? [])
+            collectFromRegions(variant.regions, out);
+    }
+    return [...out.values()];
+}
+/**
+ * Which placements appeared and which disappeared between two documents.
+ *
+ * Identity is (componentId, nodeId), so moving a linked node to another column,
+ * region, or variant is not a change — but re-keying it (paste, duplicate) is a
+ * remove plus an add, which is exactly right: it is a different placement.
+ */
+export function diffComponentRefs(before, after) {
+    const beforeRefs = new Map(collectComponentRefs(before).map(r => [componentRefKey(r), r]));
+    const afterRefs = new Map(collectComponentRefs(after).map(r => [componentRefKey(r), r]));
+    const added = [];
+    const removed = [];
+    for (const [key, ref] of afterRefs)
+        if (!beforeRefs.has(key))
+            added.push(ref);
+    for (const [key, ref] of beforeRefs)
+        if (!afterRefs.has(key))
+            removed.push(ref);
+    return { added, removed };
+}
+// ── Re-keying a resolved definition ──────────────────────────────────────────
+/**
+ * Re-derive a resolved definition's ids from the id of the node it is rendered
+ * into, so the same component placed twice on a page never emits duplicate ids.
+ *
+ * This is the canonical implementation of the scheme the public renderer
+ * already applies to connected sections (`${localId}:${storedId}`), lifted out
+ * of `renderer.tsx` so the server-side detach produces *byte-identical* ids to
+ * what the page was already rendering — `renderer.tsx` imports this one.
+ */
+export function rekeyResolvedSection(resolved, localId) {
+    const scope = (storedId) => `${localId}:${storedId}`;
+    return {
+        ...resolved,
+        id: localId,
+        columns: (resolved.columns ?? []).map(col => ({
+            ...col,
+            id: scope(col.id),
+            nodes: (col.nodes ?? []).map(node => ({
+                ...node,
+                id: scope(node.id),
+                instanceId: scope(node.instanceId),
+            })),
+        })),
+    };
+}
+/**
+ * The variant-container equivalent of {@link rekeyResolvedSection}: the local
+ * container id is kept (stable keys, `data-*` hooks, style scoping) and every
+ * id underneath — variant arms and their sections' columns/modules — is
+ * re-derived from it.
+ *
+ * THE SCOPING SCHEME, and why the arm id is part of it:
+ *
+ *  - a Default-arm section becomes `${containerId}:${sectionId}`;
+ *  - a variant-arm section becomes `${containerId}:${armId}:${sectionId}`.
+ *
+ * A container's arms are near-copies of each other by construction — an A/B
+ * container is usually "the same section, two headlines" — so the same stored
+ * section id in the Default arm and in arm B is the NORMAL case, not a
+ * pathological one. Scoping both by the container id alone gave them (and every
+ * column/module beneath them) identical ids: duplicate React keys, a
+ * `[data-section-id]` responsive-style selector matching two sections, and a
+ * `data-instance-id` that no longer identifies one module. Folding the arm id in
+ * makes ids unique document-wide.
+ *
+ * These ids are a COMPATIBILITY SURFACE: detaching persists them into the page's
+ * stored layout, so changing the scheme re-keys previously detached containers.
+ * That is safe within a document (responsive selectors are re-derived from the
+ * same ids in the same save) but not for anything outside it that pinned a
+ * section id — analytics selectors, hand-written CSS. Changing it again means a
+ * migration, so it changes only for a bug of this class.
+ */
+export function rekeyResolvedVariantContainer(resolved, localId) {
+    const scope = (storedId) => `${localId}:${storedId}`;
+    const rekeySections = (sections, armScope) => (sections ?? []).map(section => rekeyResolvedSection(section, armScope(section.id)));
+    return {
+        ...resolved,
+        id: localId,
+        defaultSections: rekeySections(resolved.defaultSections, scope),
+        variants: (resolved.variants ?? []).map((variant) => ({
+            ...variant,
+            id: scope(variant.id),
+            sections: rekeySections(variant.sections, storedId => `${localId}:${variant.id}:${storedId}`),
+        })),
+    };
+}
+/**
+ * Is this a *clean* linked instance — one that carries no local content of its
+ * own and therefore renders its component's definition strictly (kywi-cms#147)?
+ *
+ * The connect flows write a node whose only prop is the `componentId` echo (see
+ * `buildConnectedModuleNode`) and whose style map is empty. Such a node has
+ * nothing to say about how it renders, so the definition speaks for it alone —
+ * which is what "strict link" means and what makes "edit the instance → save to
+ * all" coherent (there is no per-instance state to lose).
+ *
+ * A node with ANY other local prop, or any local style, is a LEGACY override
+ * node from before strict links (kywi-cms#46 allowed per-instance overrides) and
+ * keeps the old merge, so upgrading the engine never silently changes what an
+ * existing page renders. The distinction is deliberately structural rather than
+ * a stored flag: it needs no migration and it reads the same in the editor, the
+ * renderer and the detach path.
+ */
+export function isCleanComponentInstance(node) {
+    if (Object.keys(node.style ?? {}).length > 0)
+        return false;
+    return Object.keys(node.props ?? {}).every(key => key === 'componentId');
+}
+/**
+ * The props/style a connected module node renders with: the definition's alone
+ * for a clean instance, definition-then-node for a legacy override node (see
+ * {@link isCleanComponentInstance}).
+ *
+ * Note what the clean case drops: the `componentId` echo that
+ * `buildConnectedModuleNode` writes into `props`. It is a link marker, not
+ * content, and forwarding it to the module as a prop was only ever an artefact
+ * of the merge.
+ */
+export function resolveModulePlacement(node, resolved) {
+    if (isCleanComponentInstance(node)) {
+        return { props: { ...resolved.props }, style: { ...resolved.style } };
+    }
+    return {
+        props: { ...resolved.props, ...node.props },
+        style: { ...resolved.style, ...node.style },
+    };
+}
+function withoutComponentId(node) {
+    const { componentId: _dropped, ...rest } = node;
+    return rest;
+}
+/**
+ * Drop every `componentId` inside a resolved SECTION definition — the section
+ * itself and each module node in its columns.
+ *
+ * v1 refuses to store a definition that contains a link at all
+ * ({@link validateComponentDefinition}), so on any definition written through
+ * the API this is a no-op. It is here for the ones that aren't: a row created
+ * before the refusal, a hand-written INSERT, a restored dump.
+ *
+ * Stripping is the render-faithful choice, not a destructive one. A nested link
+ * is not resolved TODAY either — the host prefetch only fetches the links the
+ * document itself holds (a definition's interior is the component's business),
+ * so the renderer's resolver misses and the node renders its own inline props.
+ * Dropping the id produces exactly that, and it guarantees that neither detach
+ * nor pre-resolution can ever PROMOTE a dormant nested link into a live one by
+ * lifting it into a page where the next prefetch would find it.
+ */
+function stripLinksInSection(section) {
+    return withoutComponentId({
+        ...section,
+        columns: (section.columns ?? []).map(column => ({
+            ...column,
+            nodes: (column.nodes ?? []).map(node => withoutComponentId(node)),
+        })),
+    });
+}
+/** {@link stripLinksInSection} for every section a container holds. */
+function stripLinksInVariantContainer(container) {
+    return withoutComponentId({
+        ...container,
+        defaultSections: (container.defaultSections ?? []).map(stripLinksInSection),
+        variants: (container.variants ?? []).map((variant) => ({
+            ...variant,
+            sections: (variant.sections ?? []).map(stripLinksInSection),
+        })),
+    });
+}
+/**
+ * What a connected section renders: the resolved definition, re-keyed off the
+ * placement's own id. The placement's inline `columns`/`style` are only the
+ * fallback copy for an unresolvable link, so nothing of the placement survives
+ * but its id — v1 sections are an all-or-nothing reference.
+ *
+ * Every link inside the result is dropped ({@link stripLinksInSection}),
+ * including one on the definition's own root. The renderer stamps
+ * `data-component-id` from the PLACEMENT, so a definition cannot smuggle a
+ * second link in through here.
+ */
+export function applySectionPlacement(resolved, placement) {
+    return stripLinksInSection(rekeyResolvedSection(resolved, placement.id));
+}
+/**
+ * The variant-container counterpart of {@link applySectionPlacement}, with one
+ * addition: the placement's own experiment binding wins over the definition's.
+ *
+ * `experimentId`/`winnerId` identify THIS page's experiment run — which
+ * experiment the arms report to and which arm has been locked in as the winner —
+ * not the saved component's. Everything selection-related therefore reads off
+ * the returned container: the arms come from the definition, the experiment they
+ * belong to comes from the placement. A placement that names neither inherits
+ * the definition's, so a component saved with its experiment binding intact
+ * keeps working when placed as-is.
+ */
+export function applyVariantContainerPlacement(resolved, placement) {
+    const materialised = rekeyResolvedVariantContainer(resolved, placement.id);
+    return stripLinksInVariantContainer({
+        ...materialised,
+        ...(placement.experimentId !== undefined ? { experimentId: placement.experimentId } : {}),
+        ...(placement.winnerId !== undefined ? { winnerId: placement.winnerId } : {}),
+    });
+}
+// ── Un-applying a placement (the inverse) ────────────────────────────────────
+//
+// THE PAIR THAT MAKES "UPDATE ALL" NON-DESTRUCTIVE (kywi-cms#147 T4 review, C1).
+//
+// A linked section/container placement stores an inline fallback copy, and the
+// editor edits THAT copy. Turning an edited copy back into a definition therefore
+// has to undo whatever `apply*Placement` did on the way in — otherwise the
+// placement's scoping travels into the definition, and every later refresh scopes
+// it again (`P:P:col`, `P:P:P:col`, …). So `apply` and `unapply` are written as an
+// explicit pair, with a round-trip test pinning `unapply(apply(D, P)) ≡ D`.
+//
+// What `unapply` cannot restore, and why that is fine: `apply` also STRIPS links
+// inside the definition ({@link stripLinksInSection}). v1 refuses to store a
+// definition that contains a link at all, so on every definition written through
+// the API stripping is a no-op and there is nothing to restore.
+/** Remove one `${scope}:` prefix, if this id carries it. */
+function unscope(id, scope) {
+    const prefix = `${scope}:`;
+    return id.startsWith(prefix) ? id.slice(prefix.length) : id;
+}
+/**
+ * The inverse of {@link rekeyResolvedSection}: strip the scope that section's own
+ * id imposed on its columns and modules, and give the result `rootId`.
+ *
+ * The scope is read off `resolved.id` rather than passed in, because that is
+ * exactly what `rekeyResolvedSection` used as the `localId` — for a top-level
+ * placement the placement's id, for a container's arm section the arm-scoped id it
+ * was rekeyed to. Ids that do NOT carry the prefix are left alone: a module the
+ * author ADDED to a linked instance has a freshly generated id and no scope, and
+ * must keep it.
+ */
+export function unrekeyResolvedSection(resolved, rootId) {
+    const scope = resolved.id;
+    return {
+        ...resolved,
+        id: rootId,
+        columns: (resolved.columns ?? []).map(col => ({
+            ...col,
+            id: unscope(col.id, scope),
+            nodes: (col.nodes ?? []).map(node => ({
+                ...node,
+                id: unscope(node.id, scope),
+                instanceId: unscope(node.instanceId, scope),
+            })),
+        })),
+    };
+}
+/**
+ * What this placement would be as a DEFINITION: the inverse of
+ * {@link applySectionPlacement}.
+ *
+ * `definitionId` is the id the stored definition already carries, so a definition
+ * rewritten from a placement keeps its own root id rather than adopting the
+ * page's. Nothing reads a section definition's root id (the placement's always
+ * wins at render — see `applySectionPlacement`), but keeping it stable means two
+ * successive update-alls produce byte-identical rows.
+ */
+export function unapplySectionPlacement(placement, definitionId) {
+    return withoutComponentId(unrekeyResolvedSection(placement, definitionId ?? placement.id));
+}
+/**
+ * The container counterpart of {@link unapplySectionPlacement}, mirroring
+ * {@link rekeyResolvedVariantContainer}'s arm-aware scheme in reverse:
+ * `${containerId}:${armId}:${sectionId}` unwinds one level at a time.
+ *
+ * The placement's `experimentId`/`winnerId` are DROPPED, not inverted: they are
+ * this page's experiment run, and `applyVariantContainerPlacement` lets them win
+ * over the definition's precisely so a component never carries one page's run.
+ * Restoring the definition's own binding is the caller's business (it holds the
+ * stored row); this returns a container with no binding at all.
+ */
+export function unapplyVariantContainerPlacement(placement, definitionId) {
+    const scope = placement.id;
+    const { experimentId: _thisPagesRun, winnerId: _thisPagesWinner, ...rest } = placement;
+    return withoutComponentId({
+        ...rest,
+        id: definitionId ?? placement.id,
+        defaultSections: (placement.defaultSections ?? []).map(section => unrekeyResolvedSection(section, unscope(section.id, scope))),
+        variants: (placement.variants ?? []).map((variant) => {
+            const armId = unscope(variant.id, scope);
+            return {
+                ...variant,
+                id: armId,
+                sections: (variant.sections ?? []).map(section => unrekeyResolvedSection(section, unscope(section.id, `${scope}:${armId}`))),
+            };
+        }),
+    });
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Is this stored `definition` a legal one for a component of this type?
+ *
+ * A component definition is not just a blob: detaching materialises it straight
+ * into a page's layout, so a definition that a layout could never hold is a
+ * loaded gun. A section definition whose columns don't sum to 12, for instance,
+ * gets copied into every page that links the component the moment anyone
+ * detaches — and every subsequent layout save of those pages is then rejected by
+ * the very same rule, leaving them un-editable with no way back through the UI.
+ *
+ * So the rules here are deliberately the *same* rules the layout write path
+ * applies, reached through the same functions:
+ *  - `module`   → a resolvable `moduleType`, plus `props`/`style` object maps
+ *                 (the shape `ComponentResolver` and `detachModuleNode` read);
+ *  - `section`  → {@link validateLayoutSection};
+ *  - `variantContainer` → {@link validateVariantContainer}.
+ *
+ * Called on component create and on every definition-bearing update, which is
+ * the only pair of doors a definition can come in through.
+ */
+export function validateComponentDefinition(component) {
+    const { type, definition } = component;
+    if (type === 'module') {
+        // Without a moduleType the renderer resolves this component to nothing —
+        // every instance would silently render its own (usually empty) props. It is
+        // not a usable component, so it is not a creatable one.
+        if (!component.moduleType) {
+            return { success: false, error: "A 'module' component requires a moduleType" };
+        }
+        if (!isPlainObject(definition)) {
+            return { success: false, error: "A 'module' definition must be an object with props/style" };
+        }
+        if (definition['props'] !== undefined && !isPlainObject(definition['props'])) {
+            return { success: false, error: "A 'module' definition's props must be an object" };
+        }
+        const style = definition['style'];
+        if (style !== undefined) {
+            if (!isPlainObject(style)) {
+                return { success: false, error: "A 'module' definition's style must be an object" };
+            }
+            for (const [key, value] of Object.entries(style)) {
+                if (typeof value !== 'string') {
+                    return { success: false, error: `A 'module' definition's style.${key} must be a string` };
+                }
+            }
+        }
+        return { success: true };
+    }
+    if (type === 'section') {
+        const result = validateLayoutSection(definition);
+        if (!result.success)
+            return { success: false, error: result.error };
+        return rejectNestedComponentLinks(result.data);
+    }
+    if (type === 'variantContainer') {
+        const result = validateVariantContainer(definition);
+        if (!result.success)
+            return { success: false, error: result.error };
+        return rejectNestedComponentLinks(result.data);
+    }
+    return { success: false, error: `Unknown component type '${type}'` };
+}
+/**
+ * v1 REFUSAL: a component definition may not itself contain a link to another
+ * component (kywi-cms#147).
+ *
+ * A depth-2 link is not a small extra case, it is a different feature. The whole
+ * engine rests on "what a placement renders IS what detaching bakes in"
+ * (`applySectionPlacement` is called by the renderer and by the detach path
+ * alike). A nested link breaks that equality: the host prefetch only fetches the
+ * links the DOCUMENT holds, so an inner link renders its inline fallback while
+ * the delete gate, the instance index and the usage counts — all of which read
+ * `collectComponentRefs`, which deliberately stops at a connected node — never
+ * see it at all. A component could then be deleted while a page still renders
+ * it, one level down.
+ *
+ * Refusing at the only two doors a definition can come in through (component
+ * POST/PUT) makes the whole class impossible, INCLUDING cycles: a cycle needs at
+ * least one component whose definition names another component, so if no stored
+ * definition may name any component, no cycle can be constructed — not a
+ * self-reference, not a mutual pair, not a longer ring. There is no depth limit
+ * to tune and no cycle detector to get wrong.
+ *
+ * The flows that WANT nesting materialise instead of linking: "save as
+ * component" flattens any links inside the selection before storing it, so the
+ * definition is a self-contained copy. Belt and braces, the placement helpers
+ * strip any link they find in a definition anyway ({@link stripLinksInSection}),
+ * so a row that predates this rule still cannot promote one.
+ */
+function rejectNestedComponentLinks(definition) {
+    const refs = collectComponentRefs({ regions: { definition: [definition] } });
+    const nested = refs[0];
+    if (!nested)
+        return { success: true };
+    return {
+        success: false,
+        error: `A component definition may not link to another component: ` +
+            `node '${nested.nodeId}' links to component '${nested.componentId}'. ` +
+            `Materialise (detach) it before saving this component.`,
+    };
+}
+/**
+ * Project a `kywi_components` row into a {@link ComponentDetachSource}.
+ * Takes the structural shape rather than the row type so it stays usable from
+ * the editor (which holds the same fields over the wire).
+ */
+export function componentDetachSource(component) {
+    if (!component)
+        return { kind: 'unresolvable' };
+    const def = (component.definition ?? {});
+    if (component.type === 'module') {
+        // A module component with no `moduleType` is unresolvable, not "resolvable
+        // with the node's own type". The renderer's resolver returns null for such
+        // a row, so the page renders the node's OWN props and never merges the
+        // definition's — materialising them here would bake in content no visitor
+        // ever saw. Unresolvable makes detach drop the link and leave the node
+        // exactly as it renders today.
+        if (!component.moduleType)
+            return { kind: 'unresolvable' };
+        return {
+            kind: 'module',
+            moduleType: component.moduleType,
+            props: (def['props'] ?? {}),
+            style: (def['style'] ?? {}),
+        };
+    }
+    if (component.type === 'section') {
+        if (def['type'] !== 'section')
+            return { kind: 'unresolvable' };
+        return { kind: 'section', section: def };
+    }
+    if (component.type === 'variantContainer') {
+        if (def['type'] !== 'variantContainer')
+            return { kind: 'unresolvable' };
+        return { kind: 'variantContainer', container: def };
+    }
+    return { kind: 'unresolvable' };
+}
+function applyLink(materialised, original, link) {
+    const componentId = original.componentId;
+    if (link === 'drop' || !componentId)
+        return withoutComponentId(materialised);
+    return { ...materialised, componentId };
+}
+/**
+ * Materialise a connected module node: the definition's props/style baked in,
+ * the module's `type` set to the component's `moduleType`.
+ *
+ * What it renders through the link is decided by {@link resolveModulePlacement}
+ * — the same call the renderer makes — so what the page rendered before is
+ * exactly what it renders after. Ids are preserved: this is the same placement,
+ * not a new one.
+ */
+export function materializeModuleNode(node, source, link = 'drop') {
+    if (source.kind !== 'module')
+        return applyLink(node, node, link);
+    return applyLink({ ...node, type: source.moduleType, ...resolveModulePlacement(node, source) }, node, link);
+}
+/**
+ * Materialise a connected section: exactly what the renderer draws for this
+ * placement ({@link applySectionPlacement}). An unresolvable source degrades to
+ * keeping the section's own inline fallback copy — again matching what the
+ * renderer shows.
+ */
+export function materializeSectionNode(section, source, link = 'drop') {
+    if (source.kind !== 'section')
+        return applyLink(section, section, link);
+    return applyLink(applySectionPlacement(source.section, section), section, link);
+}
+/** The variant-container equivalent of {@link materializeSectionNode}. */
+export function materializeVariantContainerNode(container, source, link = 'drop') {
+    if (source.kind !== 'variantContainer')
+        return applyLink(container, container, link);
+    return applyLink(applyVariantContainerPlacement(source.container, container), container, link);
+}
+/** Materialise a connected module node into an INDEPENDENT one (link dropped). */
+export function detachModuleNode(node, source) {
+    return materializeModuleNode(node, source, 'drop');
+}
+/** Materialise a connected section into an INDEPENDENT one (link dropped). */
+export function detachSectionNode(section, source) {
+    return materializeSectionNode(section, source, 'drop');
+}
+/** Materialise a connected container into an INDEPENDENT one (link dropped). */
+export function detachVariantContainerNode(container, source) {
+    return materializeVariantContainerNode(container, source, 'drop');
+}
+/**
+ * THE traversal for "visit every linked placement in a document".
+ *
+ * It knows the two rules that make a placement a placement, and it knows them
+ * once: a connected section/container resolves WHOLESALE, so its inline
+ * columns/arms are fallback copy the renderer never shows and must not be
+ * descended into; and links live in page variants and A/B experiment regions as
+ * well as the default regions.
+ *
+ * Both whole-document rewrites — detach ({@link detachComponentFromLayout}) and
+ * pre-resolution ({@link resolveComponentPlacements}) — run through here, so
+ * neither can develop its own idea of where the links are. It mirrors
+ * {@link collectComponentRefs}, which answers the same question read-only.
+ */
+function mapLinkedPlacements(layout, mapper) {
+    let changed = 0;
+    const mapSection = (section) => {
+        const sectionLink = readComponentId(section);
+        if (sectionLink) {
+            // A connected section's inline columns are fallback copy the renderer
+            // never shows, so nothing below it is a placement of this page's.
+            if (!mapper.matches(sectionLink, 'section'))
+                return section;
+            changed++;
+            return mapper.section(section, sectionLink);
+        }
+        let columnsChanged = false;
+        const columns = (section.columns ?? []).map(col => {
+            let nodesChanged = false;
+            const nodes = (col.nodes ?? []).map(node => {
+                const link = readComponentId(node);
+                if (!link || !mapper.matches(link, 'module'))
+                    return node;
+                changed++;
+                nodesChanged = true;
+                return mapper.module(node, link);
+            });
+            if (!nodesChanged)
+                return col;
+            columnsChanged = true;
+            return { ...col, nodes };
+        });
+        return columnsChanged ? { ...section, columns } : section;
+    };
+    const mapRegionNode = (node) => {
+        if (node.type === 'section')
+            return mapSection(node);
+        if (node.type !== 'variantContainer')
+            return node;
+        const containerLink = readComponentId(node);
+        if (containerLink) {
+            if (!mapper.matches(containerLink, 'variantContainer'))
+                return node;
+            changed++;
+            return mapper.variantContainer(node, containerLink);
+        }
+        return {
+            ...node,
+            defaultSections: (node.defaultSections ?? []).map(mapSection),
+            variants: (node.variants ?? []).map(variant => ({
+                ...variant,
+                sections: (variant.sections ?? []).map(mapSection),
+            })),
+        };
+    };
+    const mapRegions = (regions) => Object.fromEntries(Object.entries(regions ?? {}).map(([name, nodes]) => [name, (nodes ?? []).map(mapRegionNode)]));
+    const next = {
+        ...layout,
+        regions: mapRegions(layout.regions),
+        ...(layout.pageVariants
+            ? { pageVariants: layout.pageVariants.map(v => ({ ...v, regions: mapRegions(v.regions) })) }
+            : {}),
+        ...(layout.abExperiments
+            ? {
+                abExperiments: layout.abExperiments.map(exp => ({
+                    ...exp,
+                    variants: exp.variants.map(v => ({ ...v, regions: mapRegions(v.regions) })),
+                })),
+            }
+            : {}),
+    };
+    return changed === 0 ? { layout, changed: 0 } : { layout: next, changed };
+}
+export function rewriteComponentInstances(layout, rewrite) {
+    const { layout: next } = mapLinkedPlacements(layout, {
+        matches: (_componentId, kind) => rewrite[kind] !== undefined,
+        module: (node, componentId) => rewrite.module?.(node, { componentId, nodeId: node.id, kind: 'module' }) ?? node,
+        section: (section, componentId) => rewrite.section?.(section, { componentId, nodeId: section.id, kind: 'section' }) ?? section,
+        variantContainer: (container, componentId) => rewrite.variantContainer?.(container, {
+            componentId,
+            nodeId: container.id,
+            kind: 'variantContainer',
+        }) ?? container,
+    });
+    return next;
+}
+/**
+ * Replace every placement of `componentId` in a layout document with an
+ * independent copy of the component's definition. Returns a new document; the
+ * input is not mutated. `detached` is 0 when the document held no link, in
+ * which case `layout` is the input document unchanged.
+ */
+export function detachComponentFromLayout(layout, componentId, source) {
+    const { layout: next, changed } = mapLinkedPlacements(layout, {
+        matches: id => id === componentId,
+        module: node => materializeModuleNode(node, source, 'drop'),
+        section: section => materializeSectionNode(section, source, 'drop'),
+        variantContainer: container => materializeVariantContainerNode(container, source, 'drop'),
+    });
+    return { layout: next, detached: changed };
+}
+/**
+ * Resolve every connected placement in a layout document AHEAD of rendering,
+ * producing a document that already contains what each placement draws.
+ *
+ * WHY THIS EXISTS. The renderer's resolver props (`componentResolver` and
+ * friends) are FUNCTIONS, and `renderer.tsx` is a `'use client'` module. A host
+ * that resolves components in an async Server Component — which is every real
+ * host, because resolution is a database read — cannot pass them: React's flight
+ * serializer rejects a function prop with "Functions cannot be passed directly
+ * to Client Components", and the page 500s. That was true of module components
+ * (kywi-cms#46) and section components (#69) from the day they shipped; nothing
+ * caught it because no database in the wild had a `componentId` in a layout, and
+ * every test rendered through `renderToString` with no RSC boundary in sight.
+ *
+ * So resolution moves to where the data already is: the server, before render.
+ * The host fetches the definitions it needs, calls this, and hands `KywiLayout`
+ * a plain serializable document. No functions cross the boundary.
+ *
+ * WHAT IT PRODUCES. Materialisation is the same code detaching uses, with the
+ * link KEPT rather than dropped — pre-resolution ≡ detach output ≡ what the
+ * renderer was supposed to show. Keeping the link is what preserves everything
+ * built on it: `data-component-id` in the public DOM, the editor's
+ * linked-instance affordance, and the fact that saving the page writes a link
+ * back rather than a baked-in copy.
+ *
+ * Selection is unaffected and needs no ordering care: a pre-resolved variant
+ * container is an ordinary container holding the component's arms, so audience
+ * matching and A/B assignment run on it exactly as on an inline one — which is
+ * also why a pre-resolved page ships the same bytes to the visitor that a native
+ * one does (all arms in the document), no more and no less.
+ *
+ * The operation is idempotent: every placement is re-materialised from the
+ * DEFINITION, not from whatever the node currently holds, so running it twice
+ * (or on a document that already came back from the editor) yields the same
+ * document.
+ *
+ * ⚠ A PRE-RESOLVED DOCUMENT IS A RENDER ARTEFACT — NEVER FEED IT TO AN EDITOR.
+ * Saving one would write the definition's props into every placement, and a
+ * clean instance (props empty but for the `componentId` echo) would come back as
+ * a LEGACY override node: still linked, but no longer following its component.
+ * Hosts must hand the editor / front-edit overlay the STORED layout, which is
+ * what both of Kywi's own hosts do — the same rule feed and nav hydration
+ * already live by.
+ */
+export function resolveComponentPlacements(layout, lookup) {
+    if (!layout)
+        return { regions: {} };
+    const sourceOf = (componentId, kind) => {
+        const source = lookup(componentId);
+        if (!source || source.kind !== kind)
+            return null;
+        return source;
+    };
+    const { layout: next } = mapLinkedPlacements(layout, {
+        matches: (componentId, kind) => sourceOf(componentId, kind) !== null,
+        module: (node, id) => materializeModuleNode(node, sourceOf(id, 'module'), 'keep'),
+        section: (section, id) => materializeSectionNode(section, sourceOf(id, 'section'), 'keep'),
+        variantContainer: (container, id) => materializeVariantContainerNode(container, sourceOf(id, 'variantContainer'), 'keep'),
+    });
+    return next;
+}
+// ── Editor-side copy refresh ─────────────────────────────────────────────────
+/**
+ * Bring a document's linked SECTION and CONTAINER fallback copies back in line
+ * with the definitions they point at (kywi-cms#147 T4 review, C1).
+ *
+ * THE BUG THIS EXISTS FOR. A linked section/container stores an inline copy of its
+ * definition, and the editor edits that copy — nothing refreshed it when the
+ * definition changed elsewhere. "Save and update all instances" then built the new
+ * definition out of the page's subtree, so an update-all from a page whose copy was
+ * stale REVERTED every newer edit of that component, everywhere, published pages
+ * included, without saying a word. Two placements on one page were enough: update
+ * from the first, then from the second, and the first edit was gone.
+ *
+ * So the copy is refreshed BEFORE it can be edited, which makes the baseline the
+ * definition and makes update-all a true inverse by construction (see
+ * {@link unapplySectionPlacement}). It is also simply what the editor should be
+ * showing: the stale copy was on screen.
+ *
+ * WHAT IT DELIBERATELY DOES NOT TOUCH. Module placements. A clean module instance
+ * carries no copy to refresh (the rail reads what it renders through the library),
+ * and materialising one would bake the definition's props onto the node — turning a
+ * clean instance into a LEGACY override that no longer follows its component, which
+ * is precisely the hazard behind "⚠ a pre-resolved document must never reach an
+ * editor" on {@link resolveComponentPlacements}. Nothing here writes a node an
+ * editor may not save: refreshing a section/container's fallback copy is the same
+ * write the connect flows make.
+ *
+ * ONE CONSEQUENCE TO KNOW ABOUT: IDS. A refreshed copy is the definition re-keyed
+ * off the placement (`${placementId}:${definitionId}` — {@link rekeyResolvedSection}),
+ * which is what the RENDERER already emits for that placement, so the editor and the
+ * public DOM now agree. But a copy stored before this existed carries the ids its
+ * clone was given, so the first save after upgrading re-writes the ids inside every
+ * linked section/container placement. Nothing inside Kywi minds — responsive style
+ * selectors and `data-*` hooks are all re-derived from the same document in the same
+ * pass, and the placement's OWN id (the one the instance index and usage counts are
+ * keyed on) never changes — but this is the compatibility surface documented at
+ * {@link rekeyResolvedVariantContainer}, so hand-written CSS or an analytics selector
+ * pinned to an id INSIDE a linked instance sees a new value. That is the cost of the
+ * editor and the renderer finally holding the same document; the alternative, keeping
+ * the stored ids by matching two trees positionally, cannot survive an edit that
+ * restructured one of them.
+ *
+ * Returns the INPUT document when nothing changed, so a caller can dispatch only
+ * on a real difference and never manufacture dirty state out of a no-op.
+ */
+export function refreshComponentCopies(layout, lookup) {
+    const sourceOf = (componentId, kind) => {
+        const source = lookup(componentId);
+        if (!source || source.kind !== kind)
+            return null;
+        return source;
+    };
+    const { layout: next } = mapLinkedPlacements(layout, {
+        // Modules are left alone on purpose — see the note above.
+        matches: (componentId, kind) => kind !== 'module' && sourceOf(componentId, kind) !== null,
+        module: node => node,
+        section: (section, id) => materializeSectionNode(section, sourceOf(id, 'section'), 'keep'),
+        variantContainer: (container, id) => materializeVariantContainerNode(container, sourceOf(id, 'variantContainer'), 'keep'),
+    });
+    if (next === layout)
+        return layout;
+    // `mapLinkedPlacements` counts placements it VISITED, not ones it altered, so a
+    // document whose copies were already current comes back as a fresh object with
+    // identical content. Callers key dirty-state on identity, so compare the content.
+    return JSON.stringify(next) === JSON.stringify(layout) ? layout : next;
+}
+//# sourceMappingURL=component-refs.js.map