@vectoriox/iox-ui 5.56.1 → 5.58.0

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

@@ -1,4 +1,5 @@
-import { COLOR_SCHEMES, DesignChoices, LinkType, resolveDesignChoices, setColorScheme } from '@vectoriox/iox-ui/design-core';
+import { AnimateId, COLOR_SCHEMES, DesignChoices, LinkType, resolveDesignChoices, setColorScheme } from '@vectoriox/iox-ui/design-core';
+import { SEO_DESCRIPTION_MAX, SEO_TITLE_MAX, SeoRawDoc } from '@vectoriox/iox-ui/seo-core';
 import { FormPresetDef, FormPresetField, formPresetById } from '@vectoriox/iox-ui/forms-core';
 import {
     ACCORDION_BIND_PROP, ACCORDION_CONTENT_LIMIT, ACCORDION_WORDS, accordionAnswerOf, accordionItems, accordionQuestionOf, AccordionRole,
@@ -8,12 +9,15 @@ import {
     TABS_TEXT_BIND_PROP, TABS_WORDS, BadgeTone, BADGE_TONES, buildSegmentedRecipe, CardWords, ITEM_OPEN_STATE, segmentedOptions,
 } from '@vectoriox/iox-ui/composite-core';
 
+import { EntranceMark, EntrancePart, planEntrances } from './entrances';
 import { NODE_BASELINES } from './node-baselines.generated';
-import { BindScope, CardBindTarget, PatternDirective, PatternNode, PatternOpens, PatternPlaceholder, PatternRecipe, SitePattern, patternById } from './patterns';
-import { assertStyleSlots, ComposeError, createSerializedNode, SerializedBinding, SerializedNode, setStyleProps } from './serialized-node';
 import {
-    ContentTypePlan, DataSourcePlan, FactKey, FACT_KEYS, GlobalSlot, PagePlan, PageSectionPlan, PlanDataSourceMode, PlanDataSourceType,
-    RelativeOp, SitePlan, SitePlanSource, SITE_FACT_LABELS, SiteBusiness,
+    BindScope, CardBindTarget, parsePatternPath, PatternDirective, PatternNode, PatternOpens, PatternPlaceholder, PatternRecipe, SitePattern, patternById,
+} from './patterns';
+import { assertStyleSlots, ComposeError, createSerializedNode, SerializedBinding, SerializedNode, setStyleProps, walkSerialized } from './serialized-node';
+import {
+    ContentRole, ContentTypePlan, DataSourcePlan, DEFAULT_SITE_LOCALE, FactKey, FACT_KEYS, GlobalSlot, isRtlLocale, PagePlan, PageSectionPlan, PlanDataSourceMode,
+    PlanDataSourceType, RelativeOp, roleField, SiteLocale, SitePlan, SitePlanSource, SITE_FACT_LABELS, SiteBusiness,
 } from './site-plan.model';
 import { assertValidSitePlan, nextSourceOf, routeParams } from './validate-site-plan';
 import { NavShape, planNavShape } from './nav-shape';
@@ -44,11 +48,14 @@ export enum PlaceholderKind {
     /** CC4b (Q37): a price — a FACT the customer could be held to. Free text the studio types ("₪ 1,200", "From $40",
      *  "On request"); its label shows meanwhile ("Monthly price"), never a number. No currency model. */
     Price = 'price',
+    /** L2 (`proof.stat-row`): a number the studio stands behind ("12 years", "300 clients") — a fact, its label shown
+     *  meanwhile ("Number"), never a number written for it. */
+    Stat = 'stat',
 }
 
-/** The placeholders a page cannot be published with unfilled (W4's gate): a fact, a price, the studio's own video.
- *  Copy and an empty image are the author's to rewrite, never blocking. */
-export const PUBLISH_BLOCKING_PLACEHOLDERS: ReadonlySet<PlaceholderKind> = new Set([PlaceholderKind.Fact, PlaceholderKind.Price, PlaceholderKind.Video]);
+/** The placeholders a page cannot be published with unfilled (W4's gate): a fact, a price, a number, the studio's own
+ *  video. Copy and an empty image are the author's to rewrite, never blocking. */
+export const PUBLISH_BLOCKING_PLACEHOLDERS: ReadonlySet<PlaceholderKind> = new Set([PlaceholderKind.Fact, PlaceholderKind.Price, PlaceholderKind.Stat, PlaceholderKind.Video]);
 
 /** True when a placeholder of `kind` blocks publishing until the studio fills it. */
 export function blocksPublish(kind: PlaceholderKind): boolean {
@@ -106,8 +113,13 @@ export interface ComposedPage {
     route: { path: string };
     isHome: boolean;
     status: 'draft';
+    /** The site's language (L0-2): the page's locale — the fonts it loads, the side its entrances slide from. */
+    locale: `${SiteLocale}`;
     /** DS3: every page the wizard creates follows the look (page-bg / text / font-body). */
     pageSettings: { designSystem: true };
+    /** M1-6c: the page's search-result words — written (a static page) or bound to the route item (a template page),
+     *  in the seo-core document shape the shared `resolveSeo` reads. */
+    seo: SeoRawDoc;
     layout: SerializedNode[];
 }
 
@@ -234,6 +246,9 @@ const create = (id: string, type: string, props: Record<string, unknown> = {}, e
 interface RepeaterScope {
     /** The alias a row's children bind (`repeaterItemAlias`: the iterate-path's last segment, else the source). */
     itemAlias: string;
+    /** The data source whose items the rows are (its content type's roles), or null when the rows are bare values (a
+     *  gallery's URLs). */
+    source: string | null;
 }
 
 interface Ctx {
@@ -258,6 +273,8 @@ interface Ctx {
     /** A section inserted from the palette (`composeSection`): a button to a page the studio lacks keeps its words,
      *  unlinked — the author links it — instead of being removed. */
     keepButtons?: boolean;
+    /** M1-6b: the pattern's entrance parts as stamped, for `planEntrances` once the pattern is whole. */
+    entrances?: Array<Omit<EntranceMark, 'index'>>;
 }
 
 interface ShownWhen {
@@ -298,28 +315,66 @@ function chooseText(pn: PatternNode, ctx: Ctx): TextChoice {
     const own = pn.text === undefined ? undefined : fillVariables(pn.text, ctx);
     if (pn.ph === PatternPlaceholder.Copy) return { value: own, placeholder: { kind: PlaceholderKind.Copy } };
     if (pn.ph === PatternPlaceholder.Price) return { value: own, placeholder: { kind: PlaceholderKind.Price } };
+    if (pn.ph === PatternPlaceholder.Stat) return { value: own, placeholder: { kind: PlaceholderKind.Stat } };
     return { value: own };
 }
 
-/** A `bind` / `alt` / `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('.');
+interface ScopedPath {
+    source: string;
+    path: string;
+}
+
+/** The binding source of a scope, and the data source whose content type its item is (for its roles). */
+function scopeOf(scope: string, path: string, repeater: RepeaterScope | null, ctx: Ctx, nodeId: string): { source: string; typeSource: string | null } {
     switch (scope) {
         case BindScope.Item:
             if (!repeater) throw new ComposeError(`${nodeId}: "${path}" outside a Repeater`);
-            return { source: repeater.itemAlias, path: sub || ITEM_VALUE_PATH };
+            return { source: repeater.itemAlias, typeSource: repeater.source };
         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 };
+            return { source: ctx.page.routeSource, typeSource: ctx.page.routeSource };
         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 };
+            return { source: ctx.nextAlias, typeSource: ctx.nextAlias };
         default:
             throw new ComposeError(`${nodeId}: unknown binding scope "${scope}"`);
     }
 }
 
+/**
+ * A `bind` / `alt` / `param` / `src` path → the binding source + path, in this node's scope. A ROLE (`item.@title`,
+ * L0-3) is the field of the item's content type that plays it; an optional role the type does not name (`@image?`)
+ * gives null — the part is left out. A required one it lacks is a plan the validator should have refused.
+ */
+function resolveScopedPath(path: string, repeater: RepeaterScope | null, ctx: Ctx, nodeId: string): ScopedPath | null {
+    const parsed = parsePatternPath(path);
+    const { source, typeSource } = scopeOf(parsed.scope, path, repeater, ctx, nodeId);
+    if (!parsed.role) return { source, path: parsed.field || ITEM_VALUE_PATH };
+    const field = roleField(typeSource ? contentTypeOfSource(typeSource, ctx.plan) : undefined, parsed.role);
+    if (field) return { source, path: field };
+    if (parsed.optional) return null;
+    throw new ComposeError(`${nodeId}: "${path}" — the item's content type names no ${parsed.role} field`);
+}
+
+function resolveScoped(path: string, repeater: RepeaterScope | null, ctx: Ctx, nodeId: string): ScopedPath {
+    const scoped = resolveScopedPath(path, repeater, ctx, nodeId);
+    if (!scoped) throw new ComposeError(`${nodeId}: "${path}" names an optional role where one is required`);
+    return scoped;
+}
+
+/** The page that shows ONE item of `scope`'s content type (the plan's template page for it), and the binding of its
+ *  route param — `detail: item | next` (L0-3). Null when the plan has no such page: the link is simply not made. */
+function detailLinkOf(scope: string, repeater: RepeaterScope | null, ctx: Ctx, nodeId: string): { route: string; param: string; binding: ScopedPath } | null {
+    const { typeSource } = scopeOf(scope, scope, repeater, ctx, nodeId);
+    const type = typeSource ? contentTypeOfSource(typeSource, ctx.plan) : undefined;
+    const page = type ? ctx.plan.pages.find(p => p.template === type.name && !!p.routeSource) : undefined;
+    const byRoute = page ? ctx.plan.dataSources.find(d => d.alias === page.routeSource) : undefined;
+    const filter = byRoute && byRoute.type === PlanDataSourceType.Cms ? byRoute.filterByRouteParam : undefined;
+    const [param] = page ? routeParams(page.route) : [];
+    if (!page || !filter || !param) return null;
+    return { route: page.route, param, binding: resolveScoped(`${scope}.${filter.field}`, repeater, ctx, nodeId) };
+}
+
 /** `page.<field>` on a node stamped for a navigation page: that page's own words, written in. */
 function stampedPageValue(path: string, ctx: Ctx, nodeId: string): string {
     const field = path.split('.').slice(1).join('.');
@@ -413,13 +468,12 @@ function reportDangling(fate: DanglingFate, pn: PatternNode, id: string, words:
     });
 }
 
-/** The alt binding of a bound Image: the pattern's `alt`, else the bound item's preview text field. */
-function altBinding(pn: PatternNode, repeater: RepeaterScope | null, ctx: Ctx, id: string): { source: string; path: string } {
+/** The alt binding of a bound Image: the pattern's `alt`, else the bound item's title role (W1.1, Q7 — every content
+ *  type names its title). */
+function altBinding(pn: PatternNode, repeater: RepeaterScope | null, ctx: Ctx, id: string): ScopedPath {
     if (pn.alt) return resolveScoped(pn.alt, repeater, ctx, id);
-    const bound = resolveScoped(pn.bind as string, repeater, ctx, id);
-    const field = contentTypeOfSource(bound.source, ctx.plan)?.previewTextField;
-    if (!field) throw new ComposeError(`${id}: a bound image needs an alt — the pattern names none and "${bound.source}" has no previewTextField`);
-    return { source: bound.source, path: field };
+    const scope = parsePatternPath(pn.bind as string).scope;
+    return resolveScoped(`${scope}.@${ContentRole.Title}`, repeater, ctx, id);
 }
 
 /** A preset Form's children — the forms-core preset's fields, submit and the WORDS of both state blocks. */
@@ -446,8 +500,10 @@ function composeForm(node: SerializedNode, pn: PatternNode, id: string, ctx: Ctx
         node.children = [...(node.children ?? []), ...FORM_STATE_BLOCKS.map((type, i) => create(`${id}-${(pn.c?.length ?? 0) + i}`, type))];
         return;
     }
-    const preset = formPresetById(pn.preset);
-    if (!preset) throw new ComposeError(`${id}: no form preset "${pn.preset}" in forms-core`);
+    // A section may give the pattern's form another preset (`form`: Practice's contact page asks to book).
+    const presetId = ctx.section?.form ?? pn.preset;
+    const preset = formPresetById(presetId);
+    if (!preset) throw new ComposeError(`${id}: no form preset "${presetId}" in forms-core`);
     if (pn.c?.length) throw new ComposeError(`${id}: a preset Form takes its fields from the preset, not the pattern`);
     setProp(node, 'name', preset.formName);
     setProp(node, 'formId', `${preset.id}-${stableHash(`${ctx.owner}/${id}`)}`);
@@ -476,9 +532,26 @@ function composeChildren(pn: PatternNode, id: string, repeater: RepeaterScope |
 
 /** One pattern node → one serialized node (and its subtree). `null` when the section leaves it out or a
  *  dangling link is removed. */
-function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null, ctx: Ctx): SerializedNode | null {
+/** A section re-points a linked slot to another page of the plan (`links`, validated): the node, with that route. */
+function withSectionLink(pn: PatternNode, ctx: Ctx): PatternNode {
+    const route = pn.slot ? ctx.section?.links?.[pn.slot] : undefined;
+    return route ? { ...pn, href: route } : pn;
+}
+
+/** M1-6b: a marked node joins the pattern's entrance parts (counted among its siblings once the pattern is whole). */
+function markEntrance(pn: PatternNode, nodeId: string, repeater: RepeaterScope | null, ctx: Ctx): void {
+    if (!pn.enter) return;
+    (ctx.entrances ??= []).push({ nodeId, part: pn.enter as EntrancePart, repeated: !!repeater, ...(pn.side ? { side: pn.side } : {}) });
+}
+
+function composeNode(given: PatternNode, id: string, repeater: RepeaterScope | null, ctx: Ctx): SerializedNode | null {
+    const pn = withSectionLink(given, ctx);
     if (pn.optional && ctx.section?.without?.includes(pn.optional)) return null;
     if (pn.recipe) return composeRecipe(pn, id, repeater, ctx);
+    // A part bound to a role its item's type does not have (`@meta?`) is left out (L0-3).
+    const bound = pn.bind && !isPageScope(pn.bind) ? resolveScopedPath(pn.bind, repeater, ctx, id) : undefined;
+    if (bound === null) return null;
+    const detail = pn.detail ? detailLinkOf(pn.detail, repeater, ctx, id) : null;
 
     const words = chooseText(pn, ctx);
     const fate = danglingFate(pn, ctx);
@@ -486,7 +559,9 @@ function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null
         reportDangling(fate, pn, id, words.value, ctx);
         return null;
     }
-    const type = fate === DanglingFate.Unlink ? UNLINKED_TYPE[pn.t] ?? pn.t : pn.t;
+    // A box that would link to its item's own page, where the plan has none, is the same box unlinked.
+    const unlinked = fate === DanglingFate.Unlink || (!!pn.detail && !detail);
+    const type = unlinked ? UNLINKED_TYPE[pn.t] ?? pn.t : pn.t;
 
     const props: Record<string, unknown> = {};
     if (pn.level) props['level'] = pn.level;
@@ -499,6 +574,7 @@ function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null
     // Props first: a Heading with no `es` wears its LEVEL's default style.
     const node = create(id, type, props, pn.es ?? null);
     if (pn.role) node.role = pn.role;
+    markEntrance(pn, id, repeater, ctx);
 
     // Words.
     if (words.placeholder) {
@@ -559,11 +635,15 @@ function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null
         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 (detail) {
+        writePageLink(node, detail.route);
+        addBinding(node, { prop: `routeParam:${detail.param}`, ...detail.binding });
+    }
     if (pn.bind) {
         const prop = BIND_PROP[type];
         if (!prop) throw new ComposeError(`${id}: ${type} has no bindable value`);
         if (isPageScope(pn.bind)) setProp(node, prop, stampedPageValue(pn.bind, ctx, id));
-        else addBinding(node, { prop, ...resolveScoped(pn.bind, repeater, ctx, id) });
+        else addBinding(node, { prop, ...(bound as ScopedPath) });
     }
     if (type === IMAGE && pn.bind && !isPageScope(pn.bind)) {
         setProp(node, 'src', '');
@@ -590,7 +670,8 @@ function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null
         }
         addBinding(node, binding);
         const lastSegment = binding.path.split('.').filter(Boolean).pop();
-        rowScope = { itemAlias: lastSegment || binding.source };
+        // Rows of a list source are its items (their type's roles); rows of an item's array are bare values.
+        rowScope = { itemAlias: lastSegment || binding.source, source: binding.path ? null : binding.source };
     }
 
     // Children.
@@ -640,12 +721,12 @@ function wireShownWhen(root: SerializedNode, entries: ReadonlyArray<ShownWhen>):
     }
 }
 
-/** A Card v2 `binds` key → the part it binds and that part's bound prop. */
-const CARD_BINDS: Readonly<Record<CardBindTarget, { role: CardRole; prop: string }>> = {
-    [CardBindTarget.Image]: { role: CardRole.Media, prop: 'src' },
-    [CardBindTarget.Eyebrow]: { role: CardRole.Eyebrow, prop: 'content' },
+/** A Card v2 `binds` key → the part it binds, that part's bound prop, and the optional part it is (the title is not). */
+const CARD_BINDS: Readonly<Record<CardBindTarget, { role: CardRole; prop: string; part?: CardPart }>> = {
+    [CardBindTarget.Image]: { role: CardRole.Media, prop: 'src', part: CardPart.Media },
+    [CardBindTarget.Eyebrow]: { role: CardRole.Eyebrow, prop: 'content', part: CardPart.Eyebrow },
     [CardBindTarget.Title]: { role: CardRole.Title, prop: 'content' },
-    [CardBindTarget.Text]: { role: CardRole.Text, prop: 'content' },
+    [CardBindTarget.Text]: { role: CardRole.Text, prop: 'content', part: CardPart.Text },
 };
 
 /**
@@ -670,10 +751,22 @@ function composeRecipe(pn: PatternNode, id: string, repeater: RepeaterScope | nu
     const tone = pn.badge as BadgeTone | undefined;
     if (tone && !BADGE_TONES.includes(tone)) throw new ComposeError(`${id}: a badge has no tone "${pn.badge}"`);
     for (const key of Object.keys(pn.words ?? {})) if (!CARD_WORD_KEYS.includes(key)) throw new ComposeError(`${id}: a card has no words "${key}"`);
+    // L0-3: each part binds a ROLE of the row's type; a part whose optional role the type lacks starts switched off.
+    const binds: Array<[CardBindTarget, ScopedPath, string]> = [];
+    const parts: Partial<Record<CardPart, boolean>> = { ...(pn.parts as Partial<Record<CardPart, boolean>> | undefined) };
+    for (const [key, path] of Object.entries(pn.binds ?? {})) {
+        const target = CARD_BINDS[key as CardBindTarget];
+        if (!target) throw new ComposeError(`${id}: a card cannot bind "${key}"`);
+        const scoped = resolveScopedPath(path, repeater, ctx, id);
+        if (scoped) binds.push([key as CardBindTarget, scoped, path]);
+        else if (target.part) parts[target.part] = false;
+        else throw new ComposeError(`${id}: a card's ${key} cannot be left out`);
+    }
     const card = buildCardRecipe(factory, {
-        layout, parts: pn.parts as Partial<Record<CardPart, boolean>>, words: pn.words as Partial<CardWords> | undefined, badgeTone: tone,
+        layout, parts, words: pn.words as Partial<CardWords> | undefined, badgeTone: tone,
         ...(pn.icon ? { badgeIcon: pn.icon } : {}),
     }) as SerializedNode;
+    markEntrance(pn, id, repeater, ctx);
     if (pn.scheme) {
         if (!COLOR_SCHEMES.some(c => c.id === pn.scheme)) throw new ComposeError(`${id}: no colour scheme "${pn.scheme}"`);
         setColorScheme(card, pn.scheme);
@@ -684,19 +777,27 @@ function composeRecipe(pn: PatternNode, id: string, repeater: RepeaterScope | nu
         content.children = [...(content.children ?? []), ...composeChildren(pn, id, repeater, ctx)];
     }
 
-    for (const [key, path] of Object.entries(pn.binds ?? {})) {
-        const target = CARD_BINDS[key as CardBindTarget];
-        if (!target) throw new ComposeError(`${id}: a card cannot bind "${key}"`);
+    for (const [key, scoped, path] of binds) {
+        const target = CARD_BINDS[key];
         const part = findByRole(card as CompositeNode, target.role) as SerializedNode | undefined;
         if (!part) throw new ComposeError(`${id}: "${key}" binds a part the card leaves out`);
         const node = target.role === CardRole.Media ? part.children?.find(c => c.type === IMAGE) : part;
         if (!node) throw new ComposeError(`${id}: the card's media holds no image`);
-        addBinding(node, { prop: target.prop, ...resolveScoped(path, repeater, ctx, id) });
+        addBinding(node, { prop: target.prop, ...scoped });
         if (node.type === IMAGE) addBinding(node, { prop: 'alt', ...altBinding({ ...pn, t: IMAGE, bind: path, alt: undefined }, repeater, ctx, id) });
     }
 
-    const fate = danglingFate({ ...pn, t: 'Heading' }, ctx);
+    // The whole card links to its item's own page through its title (`detail`) — or, by route, to a page (`href`).
     const title = findByRole(card as CompositeNode, CardRole.Title) as SerializedNode;
+    if (pn.detail) {
+        const detail = detailLinkOf(pn.detail, repeater, ctx, id);
+        if (detail) {
+            writePageLink(title, detail.route);
+            addBinding(title, { prop: `routeParam:${detail.param}`, ...detail.binding });
+        }
+        return card;
+    }
+    const fate = danglingFate({ ...pn, t: 'Heading' }, ctx);
     if (pn.href && !fate) writePageLink(title, pn.href);
     else if (fate) {
         if (fate === DanglingFate.Email) writeExternalLink(title, `${MAILTO}${ctx.email}`);
@@ -890,17 +991,81 @@ function wireOpeners(root: SerializedNode, openers: ReadonlyArray<string>): void
     visit(root);
 }
 
-function composePattern(pattern: SitePattern, id: string, ctx: Ctx): SerializedNode {
+/** How a composed section moves in (M1-6b): the look's How animated (or the section's own) on the page's direction. */
+interface SectionMotion {
+    level: AnimateId | string | null;
+    rtl: boolean;
+}
+
+function composePattern(pattern: SitePattern, id: string, ctx: Ctx, motion: SectionMotion | null = null): SerializedNode {
     if (pattern.node.each) throw new ComposeError(`${id}: a pattern's root cannot be stamped per page`);
-    const own: Ctx = { ...ctx, openers: [], shownWhen: [] };
+    const own: Ctx = { ...ctx, openers: [], shownWhen: [], entrances: [] };
     const node = composeNode(pattern.node, id, null, own);
     if (!node) throw new ComposeError(`${id}: a pattern's root cannot be optional or a link`);
     wireOpeners(node, own.openers ?? []);
     wireShownWhen(node, own.shownWhen ?? []);
+    if (motion && !pattern.global) stampEntrances(node, pattern.family, own.entrances ?? [], motion);
     node.label = pattern.label;
     return node;
 }
 
+/**
+ * M1-6b: the look's entrances on a composed section — `planEntrances` over the pattern's marked parts, each counted
+ * among the marked siblings of its part (static cards a literal delay apart), appended to the node's interactions
+ * (`origin: 'look'`, `viewportEnter`, once, on itself — a duplicated node needs no remap).
+ */
+function stampEntrances(root: SerializedNode, family: string, entrances: ReadonlyArray<Omit<EntranceMark, 'index'>>, motion: SectionMotion): void {
+    if (!entrances.length && !root.children?.length) return;
+    const parentOf = new Map<string, string>();
+    const nodes = new Map<string, SerializedNode>();
+    walkSerialized([root], (n, ancestors) => { nodes.set(n.id, n); if (ancestors.length) parentOf.set(n.id, ancestors[ancestors.length - 1].id); });
+    const seen = new Map<string, number>();
+    const marks: EntranceMark[] = entrances.map(e => {
+        const key = `${parentOf.get(e.nodeId) ?? ''}|${e.part}`;
+        const index = seen.get(key) ?? 0;
+        seen.set(key, index + 1);
+        return { ...e, index };
+    });
+    const stamps = planEntrances({ family, level: motion.level, marks, contentIds: (root.children ?? []).map(c => c.id), rtl: motion.rtl });
+    for (const { nodeId, interaction } of stamps) {
+        const node = nodes.get(nodeId);
+        if (node) node.interactions = [...node.interactions, interaction];
+    }
+}
+
+const SEO_JOIN = ' · ';
+const SEO_LINE = ' — ';
+
+/** Cut to `max` characters on a word boundary, with an ellipsis only when something was cut (seo-core's limits). */
+function fitSeo(text: string, max: number): string {
+    const clean = text.replace(/\s+/g, ' ').trim();
+    if (clean.length <= max) return clean;
+    const cut = clean.slice(0, max - 1);
+    const at = cut.lastIndexOf(' ');
+    return `${(at > max / 2 ? cut.slice(0, at) : cut).trimEnd()}…`;
+}
+
+/**
+ * A composed page's search-result words (M1-6c), in the seo-core shape `resolveSeo` reads — every page resolves a
+ * title and a description, and nothing is invented: the plan's own words when it writes them; else Home is the
+ * business (and its line), an inner page "<page> · <business>", described by the business's line or, without one,
+ * by the page, the business and the city it gave. A TEMPLATE page writes neither unless the plan does: the shared
+ * ladder's content rung reads its own bound heading and lead, so each item's page has its own title and line (the old
+ * one-title-for-every-template-page defect, seo-plan.md). Plain words only — a stored `{ binding }` value is refused by
+ * the CMS's page schema today (vectoriox/iox-cms#42).
+ */
+function composePageSeo(page: PagePlan, plan: SitePlan): SeoRawDoc {
+    const name = plan.business.name.trim();
+    const tagline = nonEmpty(plan.business.tagline) ? plan.business.tagline.trim() : '';
+    const city = nonEmpty(plan.business.facts?.city) ? plan.business.facts!.city!.trim() : '';
+    const perItem = !!page.routeSource;
+    const title = nonEmpty(page.seo?.title) ? page.seo!.title
+        : perItem ? undefined : fitSeo(page.isHome ? (tagline ? `${name}${SEO_LINE}${tagline}` : name) : `${page.name}${SEO_JOIN}${name}`, SEO_TITLE_MAX);
+    const description = nonEmpty(page.seo?.description) ? page.seo!.description
+        : perItem ? undefined : fitSeo(tagline || `${page.name}${SEO_LINE}${name}${city ? `, ${city}` : ''}.`, SEO_DESCRIPTION_MAX);
+    return { ...(title ? { title } : {}), ...(description ? { description } : {}) };
+}
+
 function composeDataSource(ds: DataSourcePlan): ComposedDataSource {
     const id = `ds-${ds.alias}`;
     if (ds.type === PlanDataSourceType.Cms) {
@@ -950,11 +1115,15 @@ export function composeSite(plan: SitePlan, context: ComposeContext): ComposedSi
     const email = nonEmpty(plan.business.facts?.email) ? plan.business.facts!.email!.trim() : null;
     const base = { plan, placeholders, issues, routes, year: context.year, email, navPage: null };
 
+    const design = resolveDesignChoices(clone(plan.design));
+    const locale = plan.locale ?? DEFAULT_SITE_LOCALE;
+    const rtl = isRtlLocale(locale);
     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 });
+            const motion: SectionMotion = { level: section.enter ?? design.animate ?? null, rtl };
+            return composePattern(pattern, `${page.key}-${i}`, { ...base, owner: page.key, page, section, nextAlias }, motion);
         });
         return {
             key: page.key,
@@ -962,7 +1131,9 @@ export function composeSite(plan: SitePlan, context: ComposeContext): ComposedSi
             route: { path: page.route },
             isHome: page.isHome === true,
             status: STATUS_DRAFT,
+            locale,
             pageSettings: { designSystem: true },
+            seo: composePageSeo(page, plan),
             layout,
         };
     });
@@ -984,7 +1155,7 @@ export function composeSite(plan: SitePlan, context: ComposeContext): ComposedSi
     return {
         source: clone(plan.source),
         business: clone(plan.business),
-        design: resolveDesignChoices(clone(plan.design)),
+        design,
         schemas: clone(plan.contentTypes) as ContentTypePlan[],
         items: Object.fromEntries(plan.contentTypes.map(t => [t.name, composeItems(t)])),
         dataSources: plan.dataSources.map(composeDataSource),

package/src/generation-core/entrances.ts

@@ -1,9 +1,11 @@
-import { AnimateId, SPEC_AXES } from '@vectoriox/iox-ui/design-core';
+import { AnimateId, EntranceParam, SPEC_AXES, staggerDelay } from '@vectoriox/iox-ui/design-core';
 
 /**
  * How animated (AI plan rev 3.1 §3p) — the ONE reading of the contract's `axes.animations` (what each level
  * moves, how) and `axes.animationFamilies` (which parts a section family lets move). The pieces every stamper
- * shares: the Design step's business specimen (H4-4) today, `planEntrances` in the composer (M1-6b) next. Pure.
+ * shares: the Design step's business specimen (H4-4) and `planEntrances`, which the composer runs per section (M1-6b).
+ * When an entrance plays — a static item's literal delay, a Repeater row's share — is design-core's `staggerDelay` /
+ * `entranceDelay`, which both interaction runtimes read too. Pure.
  *
  * A level with `content` moves a section's content together, once; otherwise it names parts (heading, items,
  * media…) and each part enters on its own, items one after another. Navigation, footers and globals are a family
@@ -52,7 +54,7 @@ export interface EntranceAction {
     delay: number;
     easing: typeof ENTRANCE_EASING;
     once: true;
-    params?: { distance: number };
+    params?: { distance?: number; stagger?: number; cap?: number };
 }
 
 export interface EntranceInteraction {
@@ -84,23 +86,42 @@ export function sectionEntrances(level: AnimateId | string | null | undefined, f
     return { content: null, parts };
 }
 
-/** The literal delay of the `index`-th item: `stagger` ms each, the last `cap` waiting no longer than the one before. */
-export function staggerDelay(spec: EntranceSpec, index = 0): number {
-    if (!spec.stagger) return 0;
-    const cap = Math.max(1, spec.cap ?? 1);
-    return Math.min(Math.max(0, index), cap - 1) * spec.stagger;
+/** Which side of its row a picture sits on (`rowMedia`): an end-side picture enters from the end. */
+export enum EntranceSide {
+    Start = 'start',
+    End = 'end',
 }
 
-/** The action a node plays: the spec's type (mirrored on a right-to-left page), its distance and its delay. */
-export function entranceAction(spec: EntranceSpec, opts: { index?: number; rtl?: boolean } = {}): EntranceAction {
+export interface EntranceActionOptions {
+    /** The item's place among the items that enter together (a literal delay, `staggerDelay`). */
+    index?: number;
+    /** A right-to-left page: what slides comes from the mirrored side. */
+    rtl?: boolean;
+    /** A row picture's side (default end — the side the spec's own type enters from). */
+    side?: EntranceSide | `${EntranceSide}`;
+    /** The node is a Repeater's template: its rows take their share at runtime (`entranceDelay`), so the stagger is
+     *  carried as params and nothing is written into the delay. */
+    repeated?: boolean;
+}
+
+/** The action a node plays: the spec's type (mirrored for a start-side picture and on a right-to-left page — both
+ *  together cancel out), its distance, and its delay (or, for a Repeater's rows, the stagger the runtime adds). */
+export function entranceAction(spec: EntranceSpec, opts: EntranceActionOptions = {}): EntranceAction {
+    const mirrored = (opts.side === EntranceSide.Start) !== !!opts.rtl;
+    const params: Record<string, number> = {};
+    if (spec.distance) params[EntranceParam.Distance] = spec.distance;
+    if (opts.repeated && spec.stagger) {
+        params[EntranceParam.Stagger] = spec.stagger;
+        params[EntranceParam.Cap] = spec.cap ?? 1;
+    }
     return {
-        type: opts.rtl && spec.mirror ? spec.mirror : spec.type,
+        type: mirrored && spec.mirror ? spec.mirror : spec.type,
         target: 'self',
         duration: spec.duration,
-        delay: staggerDelay(spec, opts.index),
+        delay: opts.repeated ? 0 : staggerDelay(spec, opts.index),
         easing: ENTRANCE_EASING,
         once: true,
-        ...(spec.distance ? { params: { distance: spec.distance } } : {}),
+        ...(Object.keys(params).length ? { params } : {}),
     };
 }
 
@@ -108,3 +129,51 @@ export function entranceAction(spec: EntranceSpec, opts: { index?: number; rtl?:
 export function entranceInteraction(nodeId: string, action: EntranceAction): EntranceInteraction {
     return { id: `${nodeId}-enter`, trigger: ENTRANCE_TRIGGER, actions: [action], origin: ENTRANCE_ORIGIN_LOOK };
 }
+
+/** A node a pattern marks as an entrance part (`enter`), as the composer stamped it. */
+export interface EntranceMark {
+    nodeId: string;
+    part: EntrancePart | `${EntrancePart}`;
+    /** Its place among the marks of the same part under the same parent — what a static item's delay is counted by. */
+    index: number;
+    /** A Repeater's template (its rows share the node). */
+    repeated: boolean;
+    side?: EntranceSide | `${EntranceSide}`;
+}
+
+export interface EntranceStamp {
+    nodeId: string;
+    interaction: EntranceInteraction;
+}
+
+export interface PlanEntrancesInput {
+    /** The section's family (contract `animationFamilies`). */
+    family: string;
+    /** How animated — the look's, or the section's own (`PageSectionPlan.enter`). */
+    level: AnimateId | string | null | undefined;
+    /** The section's marked parts, in document order. */
+    marks: ReadonlyArray<EntranceMark>;
+    /** The section's own children: what a level that moves the CONTENT fades when the pattern marks no content node. */
+    contentIds: ReadonlyArray<string>;
+    rtl?: boolean;
+}
+
+/**
+ * The entrances a composed section gets (AI plan §3p, M1-6b): a level that moves the CONTENT fades the pattern's
+ * `content` marks — else every child of the section — together, once; otherwise each marked part its family allows
+ * enters on its own (static items a literal delay apart, a Repeater's rows by the runtime), a row picture from its side.
+ * Nothing for a header or footer family, Still, or an unknown level. Pure.
+ */
+export function planEntrances(input: PlanEntrancesInput): EntranceStamp[] {
+    const plan = sectionEntrances(input.level, input.family);
+    const stamp = (nodeId: string, spec: EntranceSpec, opts: EntranceActionOptions): EntranceStamp =>
+        ({ nodeId, interaction: entranceInteraction(nodeId, entranceAction(spec, { ...opts, rtl: input.rtl })) });
+    if (plan.content) {
+        const marked = input.marks.filter(m => m.part === EntrancePart.Content).map(m => m.nodeId);
+        return (marked.length ? marked : input.contentIds).map(id => stamp(id, plan.content!, {}));
+    }
+    return input.marks.flatMap(m => {
+        const spec = m.part === EntrancePart.Content ? undefined : plan.parts[m.part as EntrancePart];
+        return spec ? [stamp(m.nodeId, spec, { index: m.index, repeated: m.repeated, side: m.side })] : [];
+    });
+}