@kywi-software/core 0.13.0 → 0.15.0

package/dist/layout/component-refs.d.ts

@@ -11,8 +11,8 @@
  *
  * Keep this module dependency-free beyond `./types.js`.
  */
-import type { LayoutDocument, LayoutSection, ModuleNode, VariantContainer } from './types.js';
-export type ComponentRefKind = 'module' | 'section' | 'variantContainer';
+import type { LayoutDocument, LayoutSection, ModuleNode, ModuleVariantContainer, VariantContainer } from './types.js';
+export type ComponentRefKind = 'module' | 'section' | 'variantContainer' | 'moduleVariantContainer';
 /** One placement of a linked component inside a layout document. */
 export interface ComponentRef {
     componentId: string;
@@ -46,6 +46,11 @@ export type ComponentInstance = {
     nodeId: string;
     kind: 'variantContainer';
     node: VariantContainer;
+} | {
+    componentId: string;
+    nodeId: string;
+    kind: 'moduleVariantContainer';
+    node: ModuleVariantContainer;
 };
 /**
  * Identity of a placement: the same component in the same node is one instance.
@@ -103,6 +108,14 @@ export declare function diffComponentRefs(before: LayoutDocument | null | undefi
  * 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.
+ *
+ * KNOWN, ACCEPTED RISK (kywi-cms#77): the `:` delimiter is not reserved. An
+ * API-authored node id that happens to start with `<scope>:` could fool the
+ * `unrekey`/`unscope` heuristics. A charset ban was tried and rejected because
+ * `validateLayoutDocument` must accept the engine's own rekeyed documents
+ * (they round-trip through the editor and PUT /layout). Owner decision
+ * 2026-08-26: document rather than redesign the scope key; revisit only if a
+ * real collision is observed.
  */
 export declare function rekeyResolvedSection(resolved: LayoutSection, localId: string): LayoutSection;
 /**
@@ -133,6 +146,31 @@ export declare function rekeyResolvedSection(resolved: LayoutSection, localId: s
  * migration, so it changes only for a bug of this class.
  */
 export declare function rekeyResolvedVariantContainer(resolved: VariantContainer, localId: string): VariantContainer;
+/**
+ * The MODULE-level container's {@link rekeyResolvedVariantContainer}
+ * (kywi-cms#170): the local container id is kept and everything underneath —
+ * arm ids, the Default arm's module, each variant arm's module — is re-derived
+ * from it.
+ *
+ * The arm id is folded in for exactly the reason it is one level up: a
+ * container's arms are near-copies by construction ("the same hero, two
+ * headlines"), so the same stored module id appearing in the Default arm and in
+ * arm B is the NORMAL case. Scoping both by the container id alone would give
+ * them one id, one `data-instance-id`, and one React key.
+ *
+ *  - a Default-arm module becomes `${containerId}:${moduleId}`;
+ *  - a variant-arm module becomes `${containerId}:${armId}:${moduleId}`;
+ *  - the arm itself becomes `${containerId}:${armId}`.
+ *
+ * `instanceId` is scoped with the same key as `id`: it is what the front-edit
+ * overlay and the analytics DOM address a rendered module by, so two placements
+ * sharing one would be two nodes the editor cannot tell apart.
+ *
+ * Same COMPATIBILITY SURFACE caveat as the section-level scheme: detaching
+ * persists these ids into the page's stored layout, so changing the scheme
+ * re-keys previously detached containers.
+ */
+export declare function rekeyResolvedModuleVariantContainer(resolved: ModuleVariantContainer, localId: string): ModuleVariantContainer;
 /** A resolved module component, in the shape the renderer's resolver returns. */
 export interface ResolvedModuleDefinition {
     moduleType: string;
@@ -196,6 +234,21 @@ export declare function applySectionPlacement(resolved: LayoutSection, placement
  * keeps working when placed as-is.
  */
 export declare function applyVariantContainerPlacement(resolved: VariantContainer, placement: Pick<VariantContainer, 'id' | 'experimentId' | 'winnerId'>): VariantContainer;
+/**
+ * The MODULE-level counterpart of {@link applyVariantContainerPlacement}
+ * (kywi-cms#170), rule for rule: the definition's arms, re-keyed off the
+ * placement's id, with the PLACEMENT's experiment binding winning over the
+ * definition's.
+ *
+ * The binding rule is the same one and it is here for the same reason —
+ * `experimentId`/`winnerId` say which run THIS page's arms report to and which
+ * arm has been locked in, which is a fact about the page, not about the shared
+ * component. A placement naming neither inherits the definition's, so a
+ * container saved with its binding intact keeps working when placed as-is; the
+ * editor mints a fresh one per placement precisely so that inheritance is never
+ * what a real placement relies on.
+ */
+export declare function applyModuleVariantContainerPlacement(resolved: ModuleVariantContainer, placement: Pick<ModuleVariantContainer, 'id' | 'experimentId' | 'winnerId'>): ModuleVariantContainer;
 /**
  * The inverse of {@link rekeyResolvedSection}: strip the scope that section's own
  * id imposed on its columns and modules, and give the result `rootId`.
@@ -208,6 +261,17 @@ export declare function applyVariantContainerPlacement(resolved: VariantContaine
  * must keep it.
  */
 export declare function unrekeyResolvedSection(resolved: LayoutSection, rootId: string): LayoutSection;
+/**
+ * The inverse of {@link rekeyResolvedModuleVariantContainer}: unwind the scope
+ * the container's own id imposed on its arms and their modules, and give the
+ * result `rootId`.
+ *
+ * `${containerId}:${armId}:${moduleId}` unwinds one level at a time, exactly as
+ * {@link unapplyVariantContainerPlacement} unwinds the section-level scheme. Ids
+ * that do NOT carry the prefix are left alone — a module the author swapped into
+ * an arm has a freshly generated id and no scope, and must keep it.
+ */
+export declare function unrekeyResolvedModuleVariantContainer(resolved: ModuleVariantContainer, rootId: string): ModuleVariantContainer;
 /**
  * What this placement would be as a DEFINITION: the inverse of
  * {@link applySectionPlacement}.
@@ -231,6 +295,18 @@ export declare function unapplySectionPlacement(placement: LayoutSection, defini
  * stored row); this returns a container with no binding at all.
  */
 export declare function unapplyVariantContainerPlacement(placement: VariantContainer, definitionId?: string | null | undefined): VariantContainer;
+/**
+ * The MODULE-level counterpart of {@link unapplyVariantContainerPlacement}
+ * (kywi-cms#170) — what this placement would be as a DEFINITION, and the exact
+ * inverse of {@link applyModuleVariantContainerPlacement}.
+ *
+ * The placement's `experimentId`/`winnerId` are DROPPED rather than inverted,
+ * for the reason its section-level twin drops them: they are this page's run of
+ * the experiment, and letting them travel into the definition is how one page's
+ * A/B test would enrol every other page placing the component. Restoring the
+ * definition's own binding is the caller's business — it holds the stored row.
+ */
+export declare function unapplyModuleVariantContainerPlacement(placement: ModuleVariantContainer, definitionId?: string | null | undefined): ModuleVariantContainer;
 /**
  * A component's stored definition, projected into the shape detaching needs.
  * `unresolvable` covers a component row whose definition doesn't match its
@@ -248,6 +324,9 @@ export type ComponentDetachSource = {
 } | {
     kind: 'variantContainer';
     container: VariantContainer;
+} | {
+    kind: 'moduleVariantContainer';
+    container: ModuleVariantContainer;
 } | {
     kind: 'unresolvable';
 };
@@ -325,12 +404,20 @@ export declare function materializeModuleNode(node: ModuleNode, source: Componen
 export declare function materializeSectionNode(section: LayoutSection, source: ComponentDetachSource, link?: LinkDisposition): LayoutSection;
 /** The variant-container equivalent of {@link materializeSectionNode}. */
 export declare function materializeVariantContainerNode(container: VariantContainer, source: ComponentDetachSource, link?: LinkDisposition): VariantContainer;
+/**
+ * The MODULE-level container equivalent (kywi-cms#170), delegating to
+ * {@link applyModuleVariantContainerPlacement} so what the renderer draws, what
+ * detaching bakes in and what pre-resolution ships are one function's output.
+ */
+export declare function materializeModuleVariantContainerNode(container: ModuleVariantContainer, source: ComponentDetachSource, link?: LinkDisposition): ModuleVariantContainer;
 /** Materialise a connected module node into an INDEPENDENT one (link dropped). */
 export declare function detachModuleNode(node: ModuleNode, source: ComponentDetachSource): ModuleNode;
 /** Materialise a connected section into an INDEPENDENT one (link dropped). */
 export declare function detachSectionNode(section: LayoutSection, source: ComponentDetachSource): LayoutSection;
 /** Materialise a connected container into an INDEPENDENT one (link dropped). */
 export declare function detachVariantContainerNode(container: VariantContainer, source: ComponentDetachSource): VariantContainer;
+/** {@link detachVariantContainerNode} for a MODULE-level container (kywi-cms#170). */
+export declare function detachModuleVariantContainerNode(container: ModuleVariantContainer, source: ComponentDetachSource): ModuleVariantContainer;
 /**
  * Rewrite linked placements anywhere in a document, one kind at a time.
  *
@@ -350,6 +437,7 @@ export interface ComponentInstanceRewrite {
     module?: (node: ModuleNode, ref: ComponentRef) => ModuleNode;
     section?: (section: LayoutSection, ref: ComponentRef) => LayoutSection;
     variantContainer?: (container: VariantContainer, ref: ComponentRef) => VariantContainer;
+    moduleVariantContainer?: (container: ModuleVariantContainer, ref: ComponentRef) => ModuleVariantContainer;
 }
 export declare function rewriteComponentInstances(layout: LayoutDocument, rewrite: ComponentInstanceRewrite): LayoutDocument;
 export interface DetachResult {

package/dist/layout/component-refs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-refs.d.ts","sourceRoot":"","sources":["../../src/layout/component-refs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"component-refs.d.ts","sourceRoot":"","sources":["../../src/layout/component-refs.ts"],"names":[],"mappings":"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"}

package/dist/layout/component-refs.js

@@ -11,7 +11,7 @@
  *
  * Keep this module dependency-free beyond `./types.js`.
  */
-import { columnModules, mapColumnNode, validateLayoutSection, validateVariantContainer } from './types.js';
+import { columnModules, isModuleVariantContainer, mapColumnNode, validateLayoutSection, validateModuleVariantContainer, validateVariantContainer, } from './types.js';
 /**
  * Identity of a placement: the same component in the same node is one instance.
  *
@@ -36,14 +36,42 @@ function record(out, instance) {
 }
 function collectFromColumns(columns, out) {
     for (const column of columns ?? []) {
-        for (const node of columnModules(column)) {
-            const componentId = readComponentId(node);
-            if (componentId) {
-                record(out, { componentId, nodeId: node.id, kind: 'module', node });
+        for (const node of column.nodes ?? []) {
+            // A LINKED module-level container resolves WHOLESALE (kywi-cms#170), so
+            // stop here rather than descending through `columnModules` — the same rule
+            // `collectFromSection` applies one level up, and for the same two reasons:
+            // an arm module's grandfathered `componentId` is a link this page never
+            // renders (the placement helpers strip it), and counting it would
+            // double-count what the component definition owns.
+            //
+            // Arms are never independently linkable in the first place (#170 D1), so
+            // what this skips is only ever a grandfathered link or one written straight
+            // over the API — never a placement the editor could mint.
+            if (isModuleVariantContainer(node)) {
+                const containerLink = readComponentId(node);
+                if (containerLink) {
+                    record(out, {
+                        componentId: containerLink,
+                        nodeId: node.id,
+                        kind: 'moduleVariantContainer',
+                        node,
+                    });
+                    continue;
+                }
+            }
+            for (const module of mapColumnNodeToModules(node)) {
+                const componentId = readComponentId(module);
+                if (componentId) {
+                    record(out, { componentId, nodeId: module.id, kind: 'module', node: module });
+                }
             }
         }
     }
 }
+/** Every ModuleNode one column node holds — `columnModules` for a single node. */
+function mapColumnNodeToModules(node) {
+    return columnModules({ id: '', width: 12, nodes: [node] });
+}
 function collectFromSection(section, out) {
     const componentId = readComponentId(section);
     if (componentId) {
@@ -155,6 +183,14 @@ export function diffComponentRefs(before, after) {
  * 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.
+ *
+ * KNOWN, ACCEPTED RISK (kywi-cms#77): the `:` delimiter is not reserved. An
+ * API-authored node id that happens to start with `<scope>:` could fool the
+ * `unrekey`/`unscope` heuristics. A charset ban was tried and rejected because
+ * `validateLayoutDocument` must accept the engine's own rekeyed documents
+ * (they round-trip through the editor and PUT /layout). Owner decision
+ * 2026-08-26: document rather than redesign the scope key; revisit only if a
+ * real collision is observed.
  */
 export function rekeyResolvedSection(resolved, localId) {
     const scope = (storedId) => `${localId}:${storedId}`;
@@ -164,10 +200,33 @@ export function rekeyResolvedSection(resolved, localId) {
         columns: (resolved.columns ?? []).map(col => ({
             ...col,
             id: scope(col.id),
-            nodes: (col.nodes ?? []).map(node => mapColumnNode(node, m => ({ ...m, id: scope(m.id), instanceId: scope(m.instanceId) }))),
+            nodes: (col.nodes ?? []).map(node => rekeyColumnNode(node, scope)),
         })),
     };
 }
+/**
+ * Re-key one column node under a section's scope.
+ *
+ * A plain module is just its two ids. A MODULE-LEVEL variant container is a
+ * subtree with an identity of its own — the container id the renderer stamps as
+ * `data-module-variant-container-id`, and arm ids the selector matches on — so it
+ * goes through {@link rekeyResolvedModuleVariantContainer} rather than through
+ * `mapColumnNode`, which deliberately touches only the modules and leaves the
+ * container's identity alone (kywi-cms#170).
+ *
+ * WHY THAT MATTERS NOW. Until #170 a section definition could not hold a
+ * promoted module at all, so `mapColumnNode` was enough. It can now, and a
+ * section component placed twice would otherwise emit two containers with the
+ * same id and the same arm ids — the exact duplicate-id class
+ * {@link rekeyResolvedVariantContainer} folds the arm id in to avoid, one level
+ * further down.
+ */
+function rekeyColumnNode(node, scope) {
+    if (isModuleVariantContainer(node)) {
+        return rekeyResolvedModuleVariantContainer(node, scope(node.id));
+    }
+    return mapColumnNode(node, m => ({ ...m, id: scope(m.id), instanceId: scope(m.instanceId) }));
+}
 /**
  * The variant-container equivalent of {@link rekeyResolvedSection}: the local
  * container id is kept (stable keys, `data-*` hooks, style scoping) and every
@@ -209,6 +268,47 @@ export function rekeyResolvedVariantContainer(resolved, localId) {
         })),
     };
 }
+/**
+ * The MODULE-level container's {@link rekeyResolvedVariantContainer}
+ * (kywi-cms#170): the local container id is kept and everything underneath —
+ * arm ids, the Default arm's module, each variant arm's module — is re-derived
+ * from it.
+ *
+ * The arm id is folded in for exactly the reason it is one level up: a
+ * container's arms are near-copies by construction ("the same hero, two
+ * headlines"), so the same stored module id appearing in the Default arm and in
+ * arm B is the NORMAL case. Scoping both by the container id alone would give
+ * them one id, one `data-instance-id`, and one React key.
+ *
+ *  - a Default-arm module becomes `${containerId}:${moduleId}`;
+ *  - a variant-arm module becomes `${containerId}:${armId}:${moduleId}`;
+ *  - the arm itself becomes `${containerId}:${armId}`.
+ *
+ * `instanceId` is scoped with the same key as `id`: it is what the front-edit
+ * overlay and the analytics DOM address a rendered module by, so two placements
+ * sharing one would be two nodes the editor cannot tell apart.
+ *
+ * Same COMPATIBILITY SURFACE caveat as the section-level scheme: detaching
+ * persists these ids into the page's stored layout, so changing the scheme
+ * re-keys previously detached containers.
+ */
+export function rekeyResolvedModuleVariantContainer(resolved, localId) {
+    const rekeyModule = (module, armScope) => ({
+        ...module,
+        id: armScope(module.id),
+        instanceId: armScope(module.instanceId),
+    });
+    return {
+        ...resolved,
+        id: localId,
+        defaultModule: rekeyModule(resolved.defaultModule, storedId => `${localId}:${storedId}`),
+        variants: (resolved.variants ?? []).map((variant) => ({
+            ...variant,
+            id: `${localId}:${variant.id}`,
+            module: rekeyModule(variant.module, 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)?
@@ -276,7 +376,32 @@ function stripLinksInSection(section) {
         ...section,
         columns: (section.columns ?? []).map(column => ({
             ...column,
-            nodes: (column.nodes ?? []).map(node => mapColumnNode(node, withoutComponentId)),
+            nodes: (column.nodes ?? []).map(stripLinksInColumnNode),
+        })),
+    });
+}
+/**
+ * {@link stripLinksInSection} for one column node — the modules, and since
+ * kywi-cms#170 a module-level container's OWN link as well.
+ *
+ * `mapColumnNode` reaches the arm modules but never the container itself, so
+ * before this a linked container buried in a section definition would have
+ * survived the strip and been promoted into a live link the moment the
+ * definition was materialised into a page. That is precisely the promotion
+ * {@link stripLinksInSection}'s docstring says can never happen.
+ */
+function stripLinksInColumnNode(node) {
+    const stripped = mapColumnNode(node, withoutComponentId);
+    return isModuleVariantContainer(stripped) ? withoutComponentId(stripped) : stripped;
+}
+/** {@link stripLinksInColumnNode}, for a module container resolved on its own. */
+function stripLinksInModuleVariantContainer(container) {
+    return withoutComponentId({
+        ...container,
+        defaultModule: withoutComponentId(container.defaultModule),
+        variants: (container.variants ?? []).map((variant) => ({
+            ...variant,
+            module: withoutComponentId(variant.module),
         })),
     });
 }
@@ -325,6 +450,28 @@ export function applyVariantContainerPlacement(resolved, placement) {
         ...(placement.winnerId !== undefined ? { winnerId: placement.winnerId } : {}),
     });
 }
+/**
+ * The MODULE-level counterpart of {@link applyVariantContainerPlacement}
+ * (kywi-cms#170), rule for rule: the definition's arms, re-keyed off the
+ * placement's id, with the PLACEMENT's experiment binding winning over the
+ * definition's.
+ *
+ * The binding rule is the same one and it is here for the same reason —
+ * `experimentId`/`winnerId` say which run THIS page's arms report to and which
+ * arm has been locked in, which is a fact about the page, not about the shared
+ * component. A placement naming neither inherits the definition's, so a
+ * container saved with its binding intact keeps working when placed as-is; the
+ * editor mints a fresh one per placement precisely so that inheritance is never
+ * what a real placement relies on.
+ */
+export function applyModuleVariantContainerPlacement(resolved, placement) {
+    const materialised = rekeyResolvedModuleVariantContainer(resolved, placement.id);
+    return stripLinksInModuleVariantContainer({
+        ...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).
@@ -364,10 +511,52 @@ export function unrekeyResolvedSection(resolved, rootId) {
         columns: (resolved.columns ?? []).map(col => ({
             ...col,
             id: unscope(col.id, scope),
-            nodes: (col.nodes ?? []).map(node => mapColumnNode(node, m => ({ ...m, id: unscope(m.id, scope), instanceId: unscope(m.instanceId, scope) }))),
+            nodes: (col.nodes ?? []).map(node => unrekeyColumnNode(node, scope)),
         })),
     };
 }
+/** The inverse of {@link rekeyColumnNode}, undoing one section-level scope. */
+function unrekeyColumnNode(node, scope) {
+    if (isModuleVariantContainer(node)) {
+        return unrekeyResolvedModuleVariantContainer(node, unscope(node.id, scope));
+    }
+    return mapColumnNode(node, m => ({
+        ...m,
+        id: unscope(m.id, scope),
+        instanceId: unscope(m.instanceId, scope),
+    }));
+}
+/**
+ * The inverse of {@link rekeyResolvedModuleVariantContainer}: unwind the scope
+ * the container's own id imposed on its arms and their modules, and give the
+ * result `rootId`.
+ *
+ * `${containerId}:${armId}:${moduleId}` unwinds one level at a time, exactly as
+ * {@link unapplyVariantContainerPlacement} unwinds the section-level scheme. Ids
+ * that do NOT carry the prefix are left alone — a module the author swapped into
+ * an arm has a freshly generated id and no scope, and must keep it.
+ */
+export function unrekeyResolvedModuleVariantContainer(resolved, rootId) {
+    const scope = resolved.id;
+    const unscopeModule = (module, armScope) => ({
+        ...module,
+        id: unscope(module.id, armScope),
+        instanceId: unscope(module.instanceId, armScope),
+    });
+    return {
+        ...resolved,
+        id: rootId,
+        defaultModule: unscopeModule(resolved.defaultModule, scope),
+        variants: (resolved.variants ?? []).map((variant) => {
+            const armId = unscope(variant.id, scope);
+            return {
+                ...variant,
+                id: armId,
+                module: unscopeModule(variant.module, `${scope}:${armId}`),
+            };
+        }),
+    };
+}
 /**
  * What this placement would be as a DEFINITION: the inverse of
  * {@link applySectionPlacement}.
@@ -409,6 +598,21 @@ export function unapplyVariantContainerPlacement(placement, definitionId) {
         }),
     });
 }
+/**
+ * The MODULE-level counterpart of {@link unapplyVariantContainerPlacement}
+ * (kywi-cms#170) — what this placement would be as a DEFINITION, and the exact
+ * inverse of {@link applyModuleVariantContainerPlacement}.
+ *
+ * The placement's `experimentId`/`winnerId` are DROPPED rather than inverted,
+ * for the reason its section-level twin drops them: they are this page's run of
+ * the experiment, and letting them travel into the definition is how one page's
+ * A/B test would enrol every other page placing the component. Restoring the
+ * definition's own binding is the caller's business — it holds the stored row.
+ */
+export function unapplyModuleVariantContainerPlacement(placement, definitionId) {
+    const { experimentId: _thisPagesRun, winnerId: _thisPagesWinner, ...rest } = placement;
+    return withoutComponentId(unrekeyResolvedModuleVariantContainer(rest, definitionId ?? placement.id));
+}
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -472,6 +676,18 @@ export function validateComponentDefinition(component) {
             return { success: false, error: result.error };
         return rejectNestedComponentLinks(result.data);
     }
+    if (type === 'moduleVariantContainer') {
+        const result = validateModuleVariantContainer(definition);
+        if (!result.success)
+            return { success: false, error: result.error };
+        // Wrapped in the shape a module container really lives in, because that is
+        // the shape every walker downstream knows how to read: a one-column section
+        // holding it. The wrapper is thrown away — only the verdict is kept — but it
+        // is what makes the ADMIN-ONLY arm-module walk and the nested-link refusal
+        // reach a promoted module's arms through exactly the same code that reaches
+        // a plain module beside it (kywi-cms#170).
+        return rejectNestedComponentLinks(wrapModuleVariantContainer(result.data));
+    }
     return { success: false, error: `Unknown component type '${type}'` };
 }
 /**
@@ -501,6 +717,19 @@ export function validateComponentDefinition(component) {
  * strip any link they find in a definition anyway ({@link stripLinksInSection}),
  * so a row that predates this rule still cannot promote one.
  */
+/**
+ * A module-level container as the one-column section it lives inside, so the
+ * document-shaped walkers can read it (kywi-cms#170). Ids are synthetic and
+ * discarded with the wrapper; the container keeps its own.
+ */
+function wrapModuleVariantContainer(container) {
+    return {
+        id: `${container.id}-definition-section`,
+        type: 'section',
+        style: {},
+        columns: [{ id: `${container.id}-definition-column`, width: 12, nodes: [container] }],
+    };
+}
 function rejectNestedComponentLinks(definition) {
     const refs = collectComponentRefs({ regions: { definition: [definition] } });
     const nested = refs[0];
@@ -548,6 +777,14 @@ export function componentDetachSource(component) {
             return { kind: 'unresolvable' };
         return { kind: 'variantContainer', container: def };
     }
+    if (component.type === 'moduleVariantContainer') {
+        if (def['type'] !== 'moduleVariantContainer')
+            return { kind: 'unresolvable' };
+        return {
+            kind: 'moduleVariantContainer',
+            container: def,
+        };
+    }
     return { kind: 'unresolvable' };
 }
 function applyLink(materialised, original, link) {
@@ -587,6 +824,16 @@ export function materializeVariantContainerNode(container, source, link = 'drop'
         return applyLink(container, container, link);
     return applyLink(applyVariantContainerPlacement(source.container, container), container, link);
 }
+/**
+ * The MODULE-level container equivalent (kywi-cms#170), delegating to
+ * {@link applyModuleVariantContainerPlacement} so what the renderer draws, what
+ * detaching bakes in and what pre-resolution ships are one function's output.
+ */
+export function materializeModuleVariantContainerNode(container, source, link = 'drop') {
+    if (source.kind !== 'moduleVariantContainer')
+        return applyLink(container, container, link);
+    return applyLink(applyModuleVariantContainerPlacement(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');
@@ -599,6 +846,10 @@ export function detachSectionNode(section, source) {
 export function detachVariantContainerNode(container, source) {
     return materializeVariantContainerNode(container, source, 'drop');
 }
+/** {@link detachVariantContainerNode} for a MODULE-level container (kywi-cms#170). */
+export function detachModuleVariantContainerNode(container, source) {
+    return materializeModuleVariantContainerNode(container, source, 'drop');
+}
 /**
  * THE traversal for "visit every linked placement in a document".
  *
@@ -628,14 +879,29 @@ function mapLinkedPlacements(layout, mapper) {
         let columnsChanged = false;
         const columns = (section.columns ?? []).map(col => {
             let nodesChanged = false;
-            const nodes = (col.nodes ?? []).map(node => mapColumnNode(node, m => {
-                const link = readComponentId(m);
-                if (!link || !mapper.matches(link, 'module'))
-                    return m;
-                changed++;
-                nodesChanged = true;
-                return mapper.module(m, link);
-            }));
+            const nodes = (col.nodes ?? []).map(node => {
+                // A LINKED module-level container resolves wholesale, so its inline arms
+                // are fallback copy and nothing inside them is a placement of this
+                // page's — the same rule a linked section gets, one level down
+                // (kywi-cms#170). Descending would rewrite an arm module's grandfathered
+                // link that the page never renders.
+                const containerLink = isModuleVariantContainer(node) ? readComponentId(node) : undefined;
+                if (containerLink) {
+                    if (!mapper.matches(containerLink, 'moduleVariantContainer'))
+                        return node;
+                    changed++;
+                    nodesChanged = true;
+                    return mapper.moduleVariantContainer(node, containerLink);
+                }
+                return mapColumnNode(node, m => {
+                    const link = readComponentId(m);
+                    if (!link || !mapper.matches(link, 'module'))
+                        return m;
+                    changed++;
+                    nodesChanged = true;
+                    return mapper.module(m, link);
+                });
+            });
             if (!nodesChanged)
                 return col;
             columnsChanged = true;
@@ -692,6 +958,11 @@ export function rewriteComponentInstances(layout, rewrite) {
             nodeId: container.id,
             kind: 'variantContainer',
         }) ?? container,
+        moduleVariantContainer: (container, componentId) => rewrite.moduleVariantContainer?.(container, {
+            componentId,
+            nodeId: container.id,
+            kind: 'moduleVariantContainer',
+        }) ?? container,
     });
     return next;
 }
@@ -707,6 +978,7 @@ export function detachComponentFromLayout(layout, componentId, source) {
         module: node => materializeModuleNode(node, source, 'drop'),
         section: section => materializeSectionNode(section, source, 'drop'),
         variantContainer: container => materializeVariantContainerNode(container, source, 'drop'),
+        moduleVariantContainer: container => materializeModuleVariantContainerNode(container, source, 'drop'),
     });
     return { layout: next, detached: changed };
 }
@@ -768,6 +1040,7 @@ export function resolveComponentPlacements(layout, lookup) {
         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'),
+        moduleVariantContainer: (container, id) => materializeModuleVariantContainerNode(container, sourceOf(id, 'moduleVariantContainer'), 'keep'),
     });
     return next;
 }
@@ -829,6 +1102,10 @@ export function refreshComponentCopies(layout, lookup) {
         module: node => node,
         section: (section, id) => materializeSectionNode(section, sourceOf(id, 'section'), 'keep'),
         variantContainer: (container, id) => materializeVariantContainerNode(container, sourceOf(id, 'variantContainer'), 'keep'),
+        // A module-level container carries a fallback copy just as its section-level
+        // sibling does, so it is refreshed for the same reason (kywi-cms#170) — the
+        // `kind !== 'module'` predicate above already picks it up.
+        moduleVariantContainer: (container, id) => materializeModuleVariantContainerNode(container, sourceOf(id, 'moduleVariantContainer'), 'keep'),
     });
     if (next === layout)
         return layout;