@vectoriox/iox-ui 5.25.0 → 5.27.0

package/src/design-core/flavor-tokens.ts

@@ -1,4 +1,5 @@
 import { deriveAccentTokens } from './brand';
+import { flavorColours, FlavorColours, preTintAccentGrounds } from './brand-neutrals';
 import { fontStackWithout, formatFontFamily } from './fonts';
 import { SPEC_AXES } from './flavor-spec.generated';
 import {
@@ -11,7 +12,8 @@ import {
  *
  * Layering, each step over the last (the boards' `tokenMap`, with the product's colour math):
  *   pack tokens → chosen font pair → shape · density · motion axes → pill-button rule →
- *   the author's own font roles → a seed ≠ the pack's own re-derives the accent quartet.
+ *   the author's own font roles → every COLOUR token from the brand seed and the background tint
+ *   (`flavorColours`, DS9: tinted neutrals, the accent quartet, the held contrast pairs).
  *
  * `mode` does not change rows — every row keeps its light value and its dark override; mode is
  * how the stylesheet is compiled.
@@ -91,13 +93,40 @@ export function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): D
         if (typeof family === 'string' && family.trim() !== '') set(role, userFontStack(family, byName.get(role)?.value), USER_TOKEN_SOURCE);
     }
 
+    setColours(byName, flavorColours(pack, { seed: choices.seed, tint: choices.tint ?? pack.defaults.tint }));
+
+    return rows;
+}
+
+/** Colour rows take their light value and the dark one only where it differs (the contract's own rule). */
+function setColours(byName: Map<string, DesignTokenRow>, colours: FlavorColours): void {
+    for (const [name, [light, dark]] of Object.entries(colours)) {
+        const row = byName.get(name);
+        if (!row) continue;
+        row.value = light;
+        if (dark !== undefined && dark !== light) row.values = { dark };
+        else delete row.values;
+    }
+}
+
+/**
+ * What the contract wrote for `choices` BEFORE DS9 — the baseline a studio that applied its look before
+ * the tint existed is judged against (`designBaseline`, `designTokenRepairs`): the look's own palette, the
+ * rows DS9 changed at their old values (`pack.legacy`), and a seed ≠ the pack's own re-deriving the accent
+ * set against `bg` alone, as `deriveAccentTokens` was called then. No held pairs, no tint.
+ */
+export function legacyFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): DesignTokenRow[] {
+    const rows = buildFlavorTokens(pack, { ...choices, seed: pack.seed, tint: 'neutral' });
+    const byName = new Map(rows.map(r => [r.name, r]));
+    for (const [name, old] of Object.entries(pack.legacy ?? {})) {
+        const row = byName.get(name);
+        if (!row) continue;
+        row.value = old.value;
+        if (old.dark !== undefined) row.values = { dark: old.dark };
+        else delete row.values;
+    }
     if (choices.seed && choices.seed.toLowerCase() !== pack.seed.toLowerCase()) {
-        const bg = byName.get('bg');
-        const inverseBg = byName.get('inverse-bg');
-        for (const accent of deriveAccentTokens(choices.seed, {
-            bg: bg?.value ?? '', bgDark: bg?.values?.dark,
-            inverseBg: inverseBg?.value, inverseBgDark: inverseBg?.values?.dark,
-        })) {
+        for (const accent of deriveAccentTokens(choices.seed, preTintAccentGrounds(pack.palette))) {
             const row = byName.get(accent.name);
             if (!row) continue;
             row.value = accent.value;
@@ -105,6 +134,5 @@ export function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): D
             else delete row.values;
         }
     }
-
     return rows;
 }

package/src/design-core/public-api.ts

@@ -18,6 +18,9 @@ export * from './adopt';
 export * from './node-classes';
 export * from './empty-image';
 export * from './brand';
+export * from './colour-eval';
+export * from './brand-neutrals';
+export * from './contrast-audit';
 export * from './flavor-tokens';
 export * from './flavor-seed';
 export * from './spring';

package/src/design-core/token-css.ts

@@ -121,7 +121,7 @@ export function tokensToDarkVarMap(tokens: ReadonlyArray<DesignTokenLike> | null
 }
 
 const TOKEN_REF = /var\(\s*--iox-([\w-]+)\s*(?:,([^()]*))?\)/g;
-const PLACEHOLDER = /\{\{\s*([\w-]+)\s*\}\}/g;
+const PLACEHOLDER = /\{\{\s*(~?)([\w-]+)\s*\}\}/g;
 
 /** A compiled colour mode — the contract's modes minus `auto`, which is a compile CHOICE, not values. */
 export type ResolvedMode = Exclude<DesignMode, 'auto'>;
@@ -163,6 +163,26 @@ export function resolveTokenValues(
     return out;
 }
 
+/**
+ * Every token's value INSIDE a section wearing `schemeId`, in one mode — what CSS computes there: the
+ * scheme's overrides (`{{token}}` / `{{~token}}` placeholders substituted from the root), every other
+ * row as declared, and `var()` references resolved within the section (the §3c re-declaration rule
+ * makes that the section's own resolution). `default` (or an unknown id) is the root.
+ */
+export function resolveSchemeTokenValues(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    mode: ResolvedMode,
+    schemeId: string,
+): Record<string, string> {
+    const rows = usableTokens(tokens);
+    const set = schemeId === DEFAULT_SCHEME ? undefined : (SPEC_SCHEMES as Readonly<Record<string, { set: Readonly<Record<string, string>> }>>)[schemeId]?.set;
+    if (!set) return resolveTokenValues(rows, mode);
+    const root = resolveTokenValues(rows, mode);
+    const other = resolveTokenValues(rows, mode === DARK ? LIGHT : DARK);
+    const overrides = new Map(schemeEntries(set, root, other));
+    return resolveTokenValues(rows.map(t => ({ name: t.name, value: overrides.get(t.name) ?? modeValue(t, mode) })), LIGHT);
+}
+
 /**
  * `value` with every `var(--iox-…)` replaced by that token's resolved root value in `mode` — what
  * the Style panel's Detach writes, so the node keeps exactly what it showed as a literal. An unknown
@@ -178,20 +198,25 @@ export function resolveTokenReferences(
         resolved[name] ?? (fallback !== undefined ? fallback.trim() : ref));
 }
 
-/** A scheme value with its `{{token}}` placeholders replaced by resolved root values — or null
- *  when a placeholder names a token the set does not have (the declaration is then omitted). */
-function substitute(template: string, resolved: Readonly<Record<string, string>>): string | null {
+type ResolvedValues = Readonly<Record<string, string>>;
+
+/** A scheme value with its placeholders replaced — `{{token}}` by the root's resolved value in this
+ *  mode, `{{~token}}` by its value in the OTHER mode (an inverse section is the other mode's ground,
+ *  DS9) — or null when a placeholder names a token the set does not have (the declaration is then
+ *  omitted). */
+function substitute(template: string, resolved: ResolvedValues, opposite: ResolvedValues): string | null {
     let missing = false;
-    const value = template.replace(PLACEHOLDER, (_, name: string) => {
-        if (!(name in resolved)) missing = true;
-        return resolved[name] ?? '';
+    const value = template.replace(PLACEHOLDER, (_, tilde: string, name: string) => {
+        const from = tilde ? opposite : resolved;
+        if (!(name in from)) missing = true;
+        return from[name] ?? '';
     });
     return missing ? null : value;
 }
 
-const schemeEntries = (set: Readonly<Record<string, string>>, resolved: Readonly<Record<string, string>>) =>
+const schemeEntries = (set: Readonly<Record<string, string>>, resolved: ResolvedValues, opposite: ResolvedValues) =>
     Object.entries(set)
-        .map(([name, template]): [string, string | null] => [name, substitute(template, resolved)])
+        .map(([name, template]): [string, string | null] => [name, substitute(template, resolved, opposite)])
         .filter((e): e is [string, string] => e[1] !== null);
 
 const hasPlaceholder = (value: string) => value.includes('{{');
@@ -209,12 +234,17 @@ const hasPlaceholder = (value: string) => value.includes('{{');
  *   and CSS makes both invalid. The contract writes `{{accent}}` instead — the token's ROOT value,
  *   resolved here at compile time (and again from dark values for the dark twin).
  */
-export function compileSchemeCss(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, scope?: string): string {
+export function compileSchemeCss(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    scope?: string,
+    opposite?: ResolvedValues,
+): string {
     const rows = usableTokens(tokens);
     if (!rows.length) return '';
     const resolved = resolveTokenValues(rows, LIGHT);
+    const other = opposite ?? resolveTokenValues(rows, DARK);
     return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
-        ...schemeEntries(set, resolved),
+        ...schemeEntries(set, resolved, other),
         ...rows.filter(t => !(t.name in set) && t.value.includes(REFERENCE))
             .map((t): [string, string] => [t.name, t.value]),
     ])).filter(Boolean).join('\n');
@@ -231,9 +261,9 @@ function darkSchemeRules(rows: ReadonlyArray<DesignTokenLike>, scope: string | u
     });
     return nonDefaultSchemes().map(([id, set]) => {
         const swapped = Object.fromEntries(Object.entries(set).filter(([, v]) => hasPlaceholder(v)));
-        const lightSwap = new Map(schemeEntries(swapped, light));
+        const lightSwap = new Map(schemeEntries(swapped, light, dark));
         return rule(schemeSelector(id, scope), [
-            ...schemeEntries(swapped, dark).filter(([name, value]) => lightSwap.get(name) !== value),
+            ...schemeEntries(swapped, dark, light).filter(([name, value]) => lightSwap.get(name) !== value),
             ...redeclared.filter(t => !(t.name in set)).map((t): [string, string] => [t.name, darkOf(t) as string]),
         ], '  ');
     });
@@ -249,15 +279,18 @@ export function compileTokenCssBlocks(
     tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
     opts: TokenCssOptions = {},
 ): TokenCssBlocks {
-    const rows = rowsForMode(usableTokens(tokens), opts.mode);
+    const all = usableTokens(tokens);
+    const rows = rowsForMode(all, opts.mode);
     const root = opts.scope ?? ROOT;
+    // A forced mode flattens the rows to ONE mode; a `{{~token}}` still reads the other mode's value.
+    const opposite = resolveTokenValues(all, opts.mode === DARK ? LIGHT : DARK);
     const present = new Set(rows.map(t => t.name));
     const unset: Array<[string, string]> = opts.isolate
         ? [...specTokenNames()].filter(name => !present.has(name)).map((name): [string, string] => [name, 'initial'])
         : [];
     const base = [
         rule(root, [...unset, ...rows.map((t): [string, string] => [t.name, t.value])]),
-        compileSchemeCss(rows, opts.scope),
+        compileSchemeCss(rows, opts.scope, opposite),
         ...ACCESSIBILITY_MEDIA.map(({ query, overrides }) =>
             media(query, [rule(root, presentOverrides(rows, overrides, false), '  ')])),
     ].filter(Boolean).join('\n');

package/src/generation-core/compose-site.ts

@@ -0,0 +1,474 @@
+import { DesignChoices, resolveDesignChoices } from '@vectoriox/iox-ui/design-core';
+
+import { NODE_BASELINES } from './node-baselines.generated';
+import { BindScope, PatternDirective, PatternNode, PatternPlaceholder, SitePattern, patternById } from './patterns';
+import { assertStyleSlots, createSerializedNode, SerializedBinding, SerializedNode, setStyleProps, ComposeError, walkSerialized } from './serialized-node';
+import {
+    ContentTypePlan, DataSourcePlan, FactKey, FACT_KEYS, GlobalSlot, PagePlan, PageSectionPlan, PlanDataSourceMode, PlanDataSourceType,
+    RelativeOp, SitePlan, SitePlanSource, SITE_FACT_LABELS, SiteBusiness,
+} from './site-plan.model';
+import { assertValidSitePlan, NAV_PAGES_ALIAS, nextSourceOf, routeParams } from './validate-site-plan';
+
+/**
+ * THE composer — a Site Plan in, ordinary IOX data out (design-system plan §6b, W1). Deterministic and
+ * pure: the same plan composes to byte-identical output, with no clock, no randomness and no transport.
+ * The wizard and the AI agent both end here; W2's site-build service writes what it returns.
+ *
+ * Every node is created the way the builder creates one (`createSerializedNode`): the type's full
+ * constructor defaults, then ONE element style, then the pattern's layout. So a composed page is what
+ * an author would have built by hand from the palette — the builder reloads it and saves it unchanged,
+ * and the engine renders it with nothing to resolve. Never a colour, size or font a pattern did not
+ * name; never a fact the customer did not give (blank → a placeholder carrying the fact's label).
+ */
+
+export enum PlaceholderKind {
+    /** A FACT the customer did not give (email, phone, city): publish-blocking. */
+    Fact = 'fact',
+    /** The pattern's own words, for the author to rewrite. */
+    Copy = 'copy',
+    /** An image slot with no image: the empty-image placeholder (DS3). */
+    Image = 'image',
+}
+
+export interface ComposedPlaceholder {
+    nodeId: string;
+    /** The page key, or the global slot (`header` / `footer`), the node lives in. */
+    owner: string;
+    kind: PlaceholderKind;
+    fact?: FactKey;
+    slot?: string;
+    /** What the node shows meanwhile: the fact's label, the pattern's copy, or '' for an image. */
+    text: string;
+}
+
+export enum ComposeIssueCode {
+    /** A slot the plan and the business left empty and the pattern gives no words for — the node keeps
+     *  its type's default text. */
+    UnfilledSlot = 'unfilled-slot',
+    /** A pattern links to a route the plan has no page for (an optional page was left out). */
+    DanglingLink = 'dangling-link',
+}
+
+export interface ComposeIssue {
+    code: ComposeIssueCode;
+    nodeId: string;
+    owner: string;
+    detail: string;
+}
+
+export interface ComposedPage {
+    key: string;
+    name: string;
+    route: { path: string };
+    isHome: boolean;
+    status: 'draft';
+    /** DS3: every page the wizard creates follows the look (page-bg / text / font-body). */
+    pageSettings: { designSystem: true };
+    layout: SerializedNode[];
+}
+
+export interface ComposedDataSource {
+    id: string;
+    alias: string;
+    type: string;
+    mode: string;
+    request: Record<string, unknown>;
+}
+
+export type ComposedItem = Record<string, unknown> & { isPublished: boolean; isSample: boolean };
+
+export interface ComposedRoute {
+    key: string;
+    path: string;
+    isHome: boolean;
+}
+
+export interface ComposedSite {
+    source: SitePlanSource;
+    business: SiteBusiness;
+    /** The look, completed against its pack (`resolveDesignChoices`) — what the build applies. */
+    design: DesignChoices;
+    /** The content types to create, as the plan states them. */
+    schemas: ContentTypePlan[];
+    /** Sample items per content type. `{sampleImage:k}` values name a bundled sample image the build resolves. */
+    items: Record<string, ComposedItem[]>;
+    /** Merged by alias into the org data-source library. */
+    dataSources: ComposedDataSource[];
+    pages: ComposedPage[];
+    /** Header + footer: root nodes carry `isGlobal` and `globalPosition`. */
+    globals: SerializedNode[];
+    routes: ComposedRoute[];
+    placeholders: ComposedPlaceholder[];
+    issues: ComposeIssue[];
+}
+
+/** `{sampleImage:k}` — a bundled abstract sample image, never a stock photo (plan §6b). */
+export const SAMPLE_IMAGE_REF = /^\{sampleImage:(\d+)\}$/;
+const SAMPLE_IMAGE_TEMPLATE = /\{sampleImage:n(?:\+(\d+))?\}/g;
+const ITEM_NUMBER = /\{n\}/g;
+
+export function sampleImageRef(index: number): string {
+    return `{sampleImage:${index}}`;
+}
+
+/** The 1-based index a `{sampleImage:k}` value names, or null. */
+export function parseSampleImageRef(value: unknown): number | null {
+    const m = typeof value === 'string' ? SAMPLE_IMAGE_REF.exec(value) : null;
+    return m ? Number(m[1]) : null;
+}
+
+/** The prop a pattern's `text` / slot / fact fills, per type. */
+const TEXT_PROP: Readonly<Record<string, string>> = {
+    Heading: 'content',
+    Text: 'content',
+    Link: 'label',
+    SubmitButton: 'label',
+};
+/** The prop a pattern's `bind` binds, per type. */
+const BIND_PROP: Readonly<Record<string, string>> = {
+    Heading: 'content',
+    Text: 'content',
+    Link: 'label',
+    Image: 'src',
+};
+/** Types whose `href` is a website page (`linkType: page` + `pageRoute`). */
+const PAGE_LINK_TYPES: ReadonlySet<string> = new Set(['Link', 'LinkedContainer']);
+const BUTTON_BLOCK = 'ButtonBlock';
+const FORM = 'Form';
+const FORM_STATE_BLOCKS = ['FormSuccess', 'FormError'];
+const LINK_TYPE_PAGE = 'page';
+const ANCHOR_TAG = 'a';
+const LABEL_TAG = 'span';
+const TEXT = 'Text';
+/** A button's label reads the button's type and ink (the consent preset's labels, `consent-preset.ts`). */
+const BUTTON_LABEL_INHERITS = { fontSize: 'inherit', fontWeight: 'inherit', color: 'inherit' };
+const ITEM_VALUE_PATH = '$';
+const STATUS_DRAFT = 'draft';
+
+const clone = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
+
+/** 32-bit FNV-1a, base 36 — a short stable id fragment. */
+function stableHash(text: string): string {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(36).padStart(7, '0').slice(-6);
+}
+
+/** A page route as a base-relative href — the engine's `resolvePageHref` form (`/contact` → `contact`,
+ *  `/` → `./`), so a link stays inside the org's `<base href>`. */
+export function baseRelativeHref(route: string): string {
+    const path = route.replace(/\/{2,}/g, '/').replace(/^\/+/, '').replace(/\/+$/, '');
+    return path || './';
+}
+
+interface RepeaterScope {
+    /** The alias a row's children bind (`repeaterItemAlias`: the iterate-path's last segment, else the source). */
+    itemAlias: string;
+}
+
+interface Ctx {
+    owner: string;
+    page: PagePlan | null;
+    section: PageSectionPlan | null;
+    plan: SitePlan;
+    /** `next.*` → this alias. */
+    nextAlias: string | null;
+    placeholders: ComposedPlaceholder[];
+    issues: ComposeIssue[];
+    routes: ReadonlySet<string>;
+}
+
+function nonEmpty(v: unknown): v is string {
+    return typeof v === 'string' && v.trim() !== '';
+}
+
+interface TextChoice {
+    value?: string;
+    placeholder?: { kind: PlaceholderKind; fact?: FactKey };
+}
+
+/** Where a node's words come from: the plan's slot → the business → the customer's fact → the pattern's
+ *  own text. A missing fact shows its label and is a placeholder; nothing is ever made up. */
+function chooseText(pn: PatternNode, ctx: Ctx): TextChoice {
+    const fact = pn.ph && (FACT_KEYS as ReadonlyArray<string>).includes(pn.ph) ? pn.ph as FactKey : null;
+    const slotValue = pn.slot ? ctx.section?.slots?.[pn.slot] : undefined;
+    if (nonEmpty(slotValue)) return { value: slotValue };
+    if (pn.fromBusiness) {
+        const v = (ctx.plan.business as unknown as Record<string, unknown>)[pn.fromBusiness];
+        if (nonEmpty(v)) return { value: v };
+    }
+    if (fact) {
+        const given = ctx.plan.business.facts?.[fact];
+        return nonEmpty(given) ? { value: given } : { value: SITE_FACT_LABELS[fact], placeholder: { kind: PlaceholderKind.Fact, fact } };
+    }
+    if (pn.ph === PatternPlaceholder.Copy) return { value: pn.text, placeholder: { kind: PlaceholderKind.Copy } };
+    return { value: pn.text };
+}
+
+/** A `bind` / `param` / `src` path → the binding source + path, in this node's scope. */
+function resolveScoped(path: string, repeater: RepeaterScope | null, ctx: Ctx, nodeId: string): { source: string; path: string } {
+    const [scope, ...rest] = path.split('.');
+    const sub = rest.join('.');
+    switch (scope) {
+        case BindScope.Item:
+        case BindScope.Page:
+            if (!repeater) throw new ComposeError(`${nodeId}: "${path}" outside a Repeater`);
+            return { source: repeater.itemAlias, path: sub || ITEM_VALUE_PATH };
+        case BindScope.Route:
+            if (!ctx.page?.routeSource) throw new ComposeError(`${nodeId}: "${path}" on a page with no routeSource`);
+            return { source: ctx.page.routeSource, path: sub || ITEM_VALUE_PATH };
+        case BindScope.Next:
+            if (!ctx.nextAlias) throw new ComposeError(`${nodeId}: "${path}" with no next-sibling source`);
+            return { source: ctx.nextAlias, path: sub || ITEM_VALUE_PATH };
+        default:
+            throw new ComposeError(`${nodeId}: unknown binding scope "${scope}"`);
+    }
+}
+
+function addBinding(node: SerializedNode, binding: SerializedBinding): void {
+    const declared = NODE_BASELINES[node.type]?.traits ?? [];
+    if (!declared.includes(binding.prop) && !binding.prop.startsWith('routeParam:')) {
+        throw new ComposeError(`${node.type} has no trait "${binding.prop}" to bind`);
+    }
+    node.bindings.push(binding);
+}
+
+function assertTraits(type: string, names: ReadonlyArray<string>): void {
+    const declared = NODE_BASELINES[type]?.traits ?? [];
+    for (const name of names) if (!declared.includes(name)) throw new ComposeError(`${type} has no trait "${name}"`);
+}
+
+function setProp(node: SerializedNode, name: string, value: unknown): void {
+    assertTraits(node.type, [name]);
+    node.props[name] = value;
+}
+
+/** One pattern node → one serialized node (and its subtree). `null` when the section leaves it out. */
+function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null, ctx: Ctx): SerializedNode | null {
+    if (pn.optional && ctx.section?.without?.includes(pn.optional)) return null;
+
+    const props: Record<string, unknown> = {};
+    if (pn.level) props['level'] = pn.level;
+    if (pn.tag) props['htmlTag'] = pn.tag;
+    if (pn.scheme) props['colorScheme'] = pn.scheme;
+    if (pn.control) props['control'] = pn.control;
+    if (pn.label) props['label'] = pn.label;
+    if (pn.required !== undefined) props['required'] = pn.required;
+    assertTraits(pn.t, Object.keys(props));
+    // Props first: a Heading with no `es` wears its LEVEL's default style.
+    const node = createSerializedNode(id, pn.t, props, pn.es ?? null);
+
+    // Words.
+    const words = chooseText(pn, ctx);
+    if (words.placeholder) {
+        const shown = words.value ?? String(NODE_BASELINES[pn.t]?.props[TEXT_PROP[pn.t]] ?? '');
+        ctx.placeholders.push({ nodeId: id, owner: ctx.owner, kind: words.placeholder.kind, ...(words.placeholder.fact ? { fact: words.placeholder.fact } : {}), ...(pn.slot ? { slot: pn.slot } : {}), text: shown });
+    } else if (words.value === undefined && (pn.slot || pn.fromBusiness)) {
+        ctx.issues.push({ code: ComposeIssueCode.UnfilledSlot, nodeId: id, owner: ctx.owner, detail: `no value for ${pn.slot ? `slot "${pn.slot}"` : `business "${pn.fromBusiness}"`} — keeps the ${pn.t} default` });
+    }
+    if (words.value !== undefined) {
+        if (pn.t === BUTTON_BLOCK) {
+            const label = createSerializedNode(`${id}-label`, TEXT, { content: words.value, tag: LABEL_TAG });
+            setStyleProps(label, BUTTON_LABEL_INHERITS);
+            node.children = [label];
+        } else {
+            const prop = TEXT_PROP[pn.t];
+            if (!prop) throw new ComposeError(`${id}: ${pn.t} cannot hold text`);
+            setProp(node, prop, words.value);
+        }
+    }
+
+    // Images.
+    if (pn.ph === PatternPlaceholder.Image) {
+        setProp(node, 'src', '');
+        ctx.placeholders.push({ nodeId: id, owner: ctx.owner, kind: PlaceholderKind.Image, text: '' });
+    }
+    if (pn.aspect) setStyleProps(node, { aspectRatio: pn.aspect });
+
+    // Links.
+    if (pn.href) {
+        if (pn.href === PatternDirective.PageRoute) {
+            setProp(node, 'linkType', LINK_TYPE_PAGE);
+            addBinding(node, { prop: 'pageRoute', ...resolveScoped(`${BindScope.Page}.route`, repeater, ctx, id) });
+        } else {
+            if (!ctx.routes.has(pn.href)) ctx.issues.push({ code: ComposeIssueCode.DanglingLink, nodeId: id, owner: ctx.owner, detail: `links to ${pn.href}, which the plan has no page for` });
+            if (PAGE_LINK_TYPES.has(pn.t)) {
+                setProp(node, 'linkType', LINK_TYPE_PAGE);
+                setProp(node, 'pageRoute', pn.href);
+            } else if (pn.t === BUTTON_BLOCK) {
+                setProp(node, 'tag', ANCHOR_TAG);
+                setProp(node, 'href', baseRelativeHref(pn.href));
+            } else {
+                throw new ComposeError(`${id}: ${pn.t} cannot link`);
+            }
+        }
+    }
+    if (pn.param) {
+        const names = pn.href ? routeParams(pn.href) : [];
+        if (names.length !== 1) throw new ComposeError(`${id}: "param" needs an href with one :param`);
+        addBinding(node, { prop: `routeParam:${names[0]}`, ...resolveScoped(pn.param, repeater, ctx, id) });
+    }
+    if (pn.bind) {
+        const prop = BIND_PROP[pn.t];
+        if (!prop) throw new ComposeError(`${id}: ${pn.t} has no bindable value`);
+        addBinding(node, { prop, ...resolveScoped(pn.bind, repeater, ctx, id) });
+    }
+
+    // Layout.
+    if (pn.lay) setStyleProps(node, pn.lay);
+    if (pn.resp) {
+        for (const layer of Object.values(pn.resp)) assertStyleSlots(node.type, Object.keys(layer));
+        node.responsive = Object.fromEntries(Object.entries(pn.resp).map(([bp, styleProps]) => [bp, { styleProps: { ...styleProps } }]));
+    }
+
+    // A Repeater's rows.
+    let rowScope = repeater;
+    if (pn.src) {
+        let binding: SerializedBinding;
+        if (pn.src === PatternDirective.Binding) {
+            if (!ctx.section?.binding) throw new ComposeError(`${id}: "$binding" with no section binding`);
+            binding = { prop: 'source', source: ctx.section.binding, path: '' };
+        } else if (pn.src === PatternDirective.NavPages) {
+            binding = { prop: 'source', source: NAV_PAGES_ALIAS, path: '' };
+        } else {
+            const scoped = resolveScoped(pn.src, repeater, ctx, id);
+            binding = { prop: 'source', source: scoped.source, path: scoped.path === ITEM_VALUE_PATH ? '' : scoped.path };
+        }
+        addBinding(node, binding);
+        const lastSegment = binding.path.split('.').filter(Boolean).pop();
+        rowScope = { itemAlias: lastSegment || binding.source };
+    }
+
+    // Children.
+    const children = (pn.c ?? [])
+        .map((child, i) => composeNode(child, `${id}-${i}`, rowScope, ctx))
+        .filter((c): c is SerializedNode => !!c);
+    if (pn.c?.length) {
+        if (!node.children) throw new ComposeError(`${id}: ${pn.t} holds no children`);
+        node.children = [...node.children, ...children];
+    }
+
+    // A Form: its stable id, and both state blocks — never optional (forms plan D7).
+    if (pn.t === FORM) {
+        if (pn.preset) setProp(node, 'formId', `${pn.preset}-${stableHash(`${ctx.owner}/${id}`)}`);
+        node.children = [
+            ...(node.children ?? []),
+            ...FORM_STATE_BLOCKS.map((type, i) => createSerializedNode(`${id}-${(pn.c?.length ?? 0) + i}`, type)),
+        ];
+    }
+    return node;
+}
+
+function composePattern(pattern: SitePattern, id: string, ctx: Ctx): SerializedNode {
+    const node = composeNode(pattern.node, id, null, ctx);
+    if (!node) throw new ComposeError(`${id}: a pattern's root cannot be optional`);
+    node.label = pattern.label;
+    return node;
+}
+
+function composeDataSource(ds: DataSourcePlan): ComposedDataSource {
+    const id = `ds-${ds.alias}`;
+    if (ds.type === PlanDataSourceType.Cms) {
+        const cms: Record<string, unknown> = { contentType: ds.contentType };
+        if (ds.limit !== undefined) cms['limit'] = ds.limit;
+        if (ds.filterByRouteParam) cms['filterByRouteParam'] = { ...ds.filterByRouteParam };
+        return { id, alias: ds.alias, type: PlanDataSourceType.Cms, mode: ds.mode, request: { cms } };
+    }
+    const pick = ds.op === RelativeOp.SiblingsNext ? 'next' : 'prev';
+    return {
+        id, alias: ds.alias, type: PlanDataSourceType.Relative, mode: PlanDataSourceMode.Single,
+        request: { relative: { kind: 'siblings', from: ds.within, subjectFrom: ds.of, pick } },
+    };
+}
+
+function navPagesSource(plan: SitePlan): ComposedDataSource {
+    return {
+        id: `ds-${NAV_PAGES_ALIAS}`, alias: NAV_PAGES_ALIAS, type: 'static', mode: PlanDataSourceMode.Query,
+        request: { data: plan.pages.filter(p => p.inNav).map(p => ({ name: p.name, route: p.route })) },
+    };
+}
+
+function expandSeedValue(value: unknown, n: number): unknown {
+    if (Array.isArray(value)) return value.map(v => expandSeedValue(v, n));
+    if (typeof value !== 'string') return value;
+    return value
+        .replace(ITEM_NUMBER, String(n))
+        .replace(SAMPLE_IMAGE_TEMPLATE, (_m, plus?: string) => sampleImageRef(n + (plus ? Number(plus) : 0)));
+}
+
+function composeItems(type: ContentTypePlan): ComposedItem[] {
+    const seed = type.seed;
+    if (!seed) return [];
+    const items: ComposedItem[] = [];
+    for (let n = 1; n <= seed.count; n++) {
+        const item: Record<string, unknown> = {};
+        for (const field of type.fields) if (field.name in seed) item[field.name] = expandSeedValue(seed[field.name], n);
+        items.push({ ...item, isPublished: seed.isPublished, isSample: seed.sample });
+    }
+    return items;
+}
+
+/** True when a composed tree iterates the navigation's pages. */
+function bindsAlias(trees: ReadonlyArray<ReadonlyArray<SerializedNode>>, alias: string): boolean {
+    let found = false;
+    for (const tree of trees) walkSerialized(tree, node => { if (node.bindings.some(b => b.source === alias)) found = true; });
+    return found;
+}
+
+/**
+ * Compose a Site Plan. Throws `SitePlanError` (every issue) when the plan does not validate — the
+ * composer never repairs a plan.
+ */
+export function composeSite(plan: SitePlan): ComposedSite {
+    assertValidSitePlan(plan);
+    const placeholders: ComposedPlaceholder[] = [];
+    const issues: ComposeIssue[] = [];
+    const routes = new Set(plan.pages.map(p => p.route));
+    const relatives = new Map(plan.dataSources.map(d => [d.alias, d.type === PlanDataSourceType.Relative ? { type: d.type, of: d.of, op: d.op } : { type: d.type }]));
+    const base = { plan, placeholders, issues, routes };
+
+    const pages: ComposedPage[] = plan.pages.map(page => {
+        const nextAlias = page.routeSource ? nextSourceOf(relatives, page.routeSource) : null;
+        const layout = page.sections.map((section, i) => {
+            const pattern = patternById(section.pattern) as SitePattern;
+            return composePattern(pattern, `${page.key}-${i}`, { ...base, owner: page.key, page, section, nextAlias });
+        });
+        return {
+            key: page.key,
+            name: page.name,
+            route: { path: page.route },
+            isHome: page.isHome === true,
+            status: STATUS_DRAFT,
+            pageSettings: { designSystem: true },
+            layout,
+        };
+    });
+
+    const globals = Object.values(GlobalSlot).map(slot => {
+        const pattern = patternById(plan.globals[slot]) as SitePattern;
+        const node = composePattern(pattern, slot, { ...base, owner: slot, page: null, section: null, nextAlias: null });
+        node.isGlobal = true;
+        node.globalPosition = pattern.global;
+        return node;
+    });
+
+    const dataSources = plan.dataSources.map(composeDataSource);
+    if (bindsAlias([...pages.map(p => p.layout), globals], NAV_PAGES_ALIAS)) dataSources.push(navPagesSource(plan));
+
+    return {
+        source: clone(plan.source),
+        business: clone(plan.business),
+        design: resolveDesignChoices(clone(plan.design)),
+        schemas: clone(plan.contentTypes) as ContentTypePlan[],
+        items: Object.fromEntries(plan.contentTypes.map(t => [t.name, composeItems(t)])),
+        dataSources,
+        pages,
+        globals,
+        routes: plan.pages.map(p => ({ key: p.key, path: p.route, isHome: p.isHome === true })),
+        placeholders,
+        issues,
+    };
+}