@vectoriox/iox-ui 5.57.0 → 5.58.1

package/src/generation-core/patterns.ts

@@ -1,4 +1,5 @@
-import { SPEC_SITE_PATTERNS } from './site-spec.generated';
+import type { EntrancePart, EntranceSide } from './entrances';
+import { SPEC_SITE_COPY_LENGTHS, SPEC_SITE_DENSITY_COPY, SPEC_SITE_LIBRARY, SPEC_SITE_PATTERNS } from './site-spec.generated';
 
 /**
  * The pattern library (contract `site.patterns`): structure and element styles only — never a colour,
@@ -28,6 +29,11 @@ import { SPEC_SITE_PATTERNS } from './site-spec.generated';
  * label) · on a card recipe: `words` (title / text / badge), `badge` (the badge's tone) and `icon` (its glyph), `scheme`
  * (the Brand card), and `c` — nodes joining its Content column · `icon` an Icon's glyph · `layer` the node's name in the
  * layer tree.
+ *
+ * The library (AI plan L0-2 · L0-3 · M1-6b): `max` a slot's budget in characters (at the standard copy length) ·
+ * `@<role>` in a binding path = the bound type's field for that role (`item.@title`; `?` = left out when the type has
+ * no such role) · `detail` = a link to the page showing that scope's item (`item`, `next`) · `enter` = the entrance
+ * part this node is (`side` = where a row's picture sits) · `ph: 'stat'` a number the studio types.
  */
 export interface PatternNode {
     readonly t: string;
@@ -76,8 +82,18 @@ export interface PatternNode {
     readonly icon?: string;
     /** CC4b: the node's name in the layer tree (`Price · Monthly`). */
     readonly layer?: string;
+    /** L0-2: a slot's budget in characters at the standard copy length. */
+    readonly max?: number;
+    /** M1-6b: the entrance part this node is — what the look's How animated may move. */
+    readonly enter?: `${EntrancePart}`;
+    /** M1-6b: the side a row's picture sits on (`rowMedia` slides in from it). */
+    readonly side?: `${EntranceSide}`;
+    /** L0-3: a link to the page that shows this scope's item (the plan's template page of its type). */
+    readonly detail?: `${BindScope.Item}` | `${BindScope.Next}`;
 }
 
+
+
 /** The composite-core recipes a pattern may stamp (`recipe`). */
 export enum PatternRecipe {
     Card = 'card',
@@ -116,6 +132,8 @@ export enum PatternGlobalPosition {
 export interface SitePattern {
     readonly family: string;
     readonly label: string;
+    /** The one sentence the model reads when it chooses the pattern (L0-2). */
+    readonly intent: string;
     /** Set on a header/footer pattern: it renders on every page, before or after the page. */
     readonly global?: `${PatternGlobalPosition}`;
     /** A navigation pattern's phone shape (CC1): `planNavShape` adds it after the pattern is stamped. */
@@ -133,6 +151,8 @@ export enum PatternPlaceholder {
     Video = 'video',
     /** CC4b (Q37): a price the studio types — free text, publish-blocking, its label shown meanwhile, never a number. */
     Price = 'price',
+    /** L2 (`proof.stat-row`): a number the studio stands behind — publish-blocking, its label shown, never a number. */
+    Stat = 'stat',
 }
 
 /** CC3: what an `opens` node opens. */
@@ -202,28 +222,120 @@ export function patternTakesBinding(pattern: SitePattern): boolean {
 }
 
 const IMAGE_TYPE = 'Image';
+const ROLE_MARK = '@';
+const OPTIONAL_MARK = '?';
 
-/** The scopes whose ITEM a pattern's bound Images take their alt text from (an Image that names no `alt`
- *  of its own): `item` (the row of a `$binding` Repeater — the section's list), `route` or `next`. Each
- *  needs a content type with a `previewTextField` (W1.1, Q7). */
-export function altSourceScopes(pattern: SitePattern): Set<string> {
-    const scopes = new Set<string>();
-    const visit = (n: PatternNode) => {
-        if (n.t === IMAGE_TYPE && n.bind && n.alt === undefined) scopes.add(n.bind.split('.')[0]);
-        // A Card v2's bound image takes its alt from the same item.
-        const cardImage = n.recipe === PatternRecipe.Card ? n.binds?.[CardBindTarget.Image] : undefined;
-        if (cardImage) scopes.add(cardImage.split('.')[0]);
-        for (const child of n.c ?? []) visit(child);
+/** A binding path read apart: its scope (`item`, `route`, `next`, `page`), and — when it names a ROLE (`@title`) — the
+ *  role and whether the part may go without it (`@image?`); else the plain field path after the scope. */
+export interface PatternPath {
+    scope: string;
+    role?: string;
+    optional: boolean;
+    field: string;
+}
+
+export function parsePatternPath(path: string): PatternPath {
+    const [scope, ...rest] = path.split('.');
+    const tail = rest.join('.');
+    if (!tail.startsWith(ROLE_MARK)) return { scope, optional: false, field: tail };
+    const optional = tail.endsWith(OPTIONAL_MARK);
+    return { scope, role: tail.slice(ROLE_MARK.length, optional ? -OPTIONAL_MARK.length : undefined), optional, field: '' };
+}
+
+/** A role a pattern reads from the item of `scope` (`item` = the section's list, `route`, `next`) — and whether the
+ *  pattern can do without it. A bound image that names no `alt` of its own reads the item's title (W1.1, Q7). */
+export interface PatternRoleNeed {
+    scope: string;
+    role: string;
+    optional: boolean;
+}
+
+export function patternRoleNeeds(pattern: SitePattern): PatternRoleNeed[] {
+    const out: PatternRoleNeed[] = [];
+    const add = (path: string | undefined) => {
+        if (!path) return;
+        const p = parsePatternPath(path);
+        if (p.role) out.push({ scope: p.scope, role: p.role, optional: p.optional });
     };
-    visit(pattern.node);
-    return scopes;
+    for (const n of patternNodes(pattern)) {
+        for (const path of [...nodeBindPaths(n), n.src]) add(path);
+        if (n.t === IMAGE_TYPE && n.bind && n.alt === undefined && !parsePatternPath(n.bind).optional) {
+            out.push({ scope: parsePatternPath(n.bind).scope, role: 'title', optional: false });
+        }
+    }
+    return out;
+}
+
+/** Every slot's budget in characters at the standard copy length (L0-2). */
+export function patternSlotBudgets(pattern: SitePattern): Record<string, number> {
+    const out: Record<string, number> = {};
+    for (const n of patternNodes(pattern)) if (n.slot && typeof n.max === 'number') out[n.slot] = n.max;
+    return out;
+}
+
+/** The copy length a density writes at (contract `site.densityCopy`) and its multiplier (`site.copyLengths`). */
+export function copyLengthOf(density: string | null | undefined): number {
+    const length = (SPEC_SITE_DENSITY_COPY as Readonly<Record<string, string>>)[density ?? ''] ?? 'standard';
+    return (SPEC_SITE_COPY_LENGTHS as Readonly<Record<string, number>>)[length] ?? 1;
+}
+
+/** A slot's budget under the look's density (M1-6c): its `max` × the density's copy length, whole characters. */
+export function slotBudget(pattern: SitePattern, slot: string, density?: string | null): number | null {
+    const max = patternSlotBudgets(pattern)[slot];
+    return max === undefined ? null : Math.round(max * copyLengthOf(density));
+}
+
+/** The slots whose node links somewhere (a button, a link): what a section's `links` may re-point. */
+export function patternLinkSlots(pattern: SitePattern): string[] {
+    return [...new Set(patternNodes(pattern).filter(n => n.slot && n.href && !n.href.startsWith('$')).map(n => n.slot as string))];
+}
+
+/** True when the pattern holds a Form a section's `form` may give another preset. */
+export function patternHasForm(pattern: SitePattern): boolean {
+    return patternNodes(pattern).some(n => !!n.preset);
+}
+
+/** The library's 31 sections (contract `site.library`), each with whether it is composed. */
+export const SITE_LIBRARY: ReadonlyArray<{ readonly id: string; readonly family: string; readonly composed: boolean }> = SPEC_SITE_LIBRARY;
+
+/** One pattern as the model reads it (L0-2): what it is for, what it may write and how long, and what it binds. */
+export interface PatternManifestEntry {
+    id: string;
+    family: string;
+    label: string;
+    intent: string;
+    /** Header (`before`) or footer (`after`): a `globals` choice, never a page section. */
+    global?: string;
+    /** Each slot the plan may fill and its budget under the density. */
+    slots: Record<string, number>;
+    /** The slots a section's `links` may re-point. */
+    links: string[];
+    /** It iterates a list source (`binding`): required, optional, or none. */
+    binding: 'required' | 'optional' | 'none';
+    /** The roles it reads from the bound or route item (optional ones marked `?`). */
+    roles: string[];
+    optionalParts: string[];
+    form: boolean;
+}
+
+/** The composed library as the model reads it — every pattern, its budgets under `density` (M1-3's manifest). */
+export function patternManifest(density?: string | null): PatternManifestEntry[] {
+    return Object.entries(SITE_PATTERNS).map(([id, p]) => ({
+        id, family: p.family, label: p.label, intent: p.intent, ...(p.global ? { global: p.global } : {}),
+        slots: Object.fromEntries(Object.keys(patternSlotBudgets(p)).map(slot => [slot, slotBudget(p, slot, density) as number])),
+        links: patternLinkSlots(p),
+        binding: patternNeedsBinding(p) ? 'required' : patternTakesBinding(p) ? 'optional' : 'none',
+        roles: [...new Set(patternRoleNeeds(p).map(r => `${r.scope}.@${r.role}${r.optional ? OPTIONAL_MARK : ''}`))],
+        optionalParts: patternOptionalParts(p),
+        form: patternHasForm(p),
+    }));
 }
 
 /** The bind scopes a pattern reads (`route`, `next`, …) — what its page must provide. */
 export function patternScopes(pattern: SitePattern): Set<string> {
     const scopes = new Set<string>();
     for (const n of patternNodes(pattern)) {
-        for (const path of [...nodeBindPaths(n), n.alt, n.param, n.src]) {
+        for (const path of [...nodeBindPaths(n), n.alt, n.param, n.src, n.detail]) {
             if (path && !path.startsWith('$')) scopes.add(path.split('.')[0]);
         }
     }

package/src/generation-core/plan-words.ts

@@ -54,8 +54,9 @@ export function writtenTexts(plan: SitePlan): WrittenText[] {
 }
 
 const HEBREW = /[֐-׿]/;
-/** Hebrew joins up to two one-letter words (and, the, in, to, from, that, as) to the next: "והטוב" holds "טוב". */
-const HEBREW_PREFIXES = '[והבלמשכ]{0,2}';
+/** Hebrew joins up to two one-letter words (and, the, in, to, from, that, as) to the next: "והטוב" holds "טוב". The
+ *  ONE rule — the intake's keyword match (harness-core) uses it too. */
+export const HEBREW_PREFIXES = '[והבלמשכ]{0,2}';
 const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 const normalise = (s: string) => s.normalize('NFKC').toLowerCase();
 

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

@@ -1,7 +1,7 @@
 /**
  * @vectoriox/iox-ui/generation-core — the shared, FRAMEWORK-FREE site-plan core (design-system plan
- * §6b, W1): the Site Plan shape + its validator, the pattern library and the Studio template (both
- * generated 1:1 from iox-ai-guidance `flavor-spec.v1.json`), and `composeSite` — a plan in, the
+ * §6b, W1): the Site Plan shape + its validator, the pattern library, the page types and the three structures (Studio ·
+ * Practice · Place — all generated 1:1 from iox-ai-guidance `flavor-spec.v1.json`), and `composeSite` — a plan in, the
  * schemas, sample items, data sources, pages, routes and header/footer globals out, as serialized
  * layout JSON. The website wizard (W2–W4) and the AI agent drive the SAME composer.
  * Pure: no transport, no clock, no randomness. Consumed by iox-cms (the server-side site build), the
@@ -24,6 +24,7 @@ export * from './compose-site';
 export * from './nav-shape';
 export * from './entrances';
 export * from './plan-data';
+export * from './showcase';
 export * from './site-build-run';
 export * from './ai-run';
 export * from './site-plan-schema';

package/src/generation-core/showcase.ts

@@ -0,0 +1,81 @@
+import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
+
+import { BindScope, patternNeedsBinding, PatternGlobalPosition, patternScopes, SITE_PATTERNS } from './patterns';
+import { GlobalSlot, PagePlan, PageSectionPlan, SiteBusiness, SiteLocale, SitePlan, SitePlanSourceKind, SITE_PLAN_VERSION } from './site-plan.model';
+import { STUDIO_TEMPLATE } from './templates';
+
+/**
+ * THE LIBRARY ON SHOW — every composed pattern, stamped by the real composer onto ordinary pages (one page per family,
+ * the item page holding the patterns that read a route item), over the Studio's content and sources. One plan per
+ * header × footer pairing so every global variant is composed too. What the render-parity e2e, the specs and any
+ * gallery of the library compose — ONE definition, never a hand-picked list that forgets the newest pattern. Pure.
+ */
+
+export interface ShowcaseInput {
+    business: SiteBusiness;
+    design: DesignChoices;
+    locale?: `${SiteLocale}`;
+}
+
+const ITEM_ROUTE = '/work/:slug';
+const LIST_SOURCE = 'projects';
+
+const routeOf = (family: string) => `/${family}`;
+/** A page key: the family — never a global slot's name (`header` would share the site header's ids). */
+const keyOf = (family: string) => ((Object.values(GlobalSlot) as string[]).includes(family) ? `${family}-page` : family);
+
+function sectionFor(id: string): PageSectionPlan {
+    return patternNeedsBinding(SITE_PATTERNS[id]) ? { pattern: id, binding: LIST_SOURCE } : { pattern: id };
+}
+
+/** True when the pattern reads the route item (its page must be the item page). */
+function readsRouteItem(id: string): boolean {
+    const scopes = patternScopes(SITE_PATTERNS[id]);
+    return scopes.has(BindScope.Route) || scopes.has(BindScope.Next);
+}
+
+/** The showcase's pages: Home (the heroes), one page per other family in library order, and the item page. */
+export function showcasePages(): PagePlan[] {
+    const byFamily = new Map<string, string[]>();
+    const onItemPage: string[] = [];
+    for (const [id, p] of Object.entries(SITE_PATTERNS)) {
+        if (p.global) continue;
+        if (readsRouteItem(id)) { onItemPage.push(id); continue; }
+        byFamily.set(p.family, [...(byFamily.get(p.family) ?? []), id]);
+    }
+    const heroes = byFamily.get('hero') ?? [];
+    byFamily.delete('hero');
+    const home: PagePlan = { key: 'home', name: 'Home', route: '/', isHome: true, inNav: false, sections: heroes.map(sectionFor) };
+    const families = [...byFamily.entries()].map(([family, ids]): PagePlan => ({
+        key: keyOf(family), name: family.charAt(0).toUpperCase() + family.slice(1), route: routeOf(family), inNav: true, sections: ids.map(sectionFor),
+    }));
+    const item: PagePlan = {
+        key: 'item', name: 'Item', route: ITEM_ROUTE, inNav: false, template: STUDIO_TEMPLATE.contentTypes[0].name, routeSource: 'project',
+        sections: onItemPage.map(sectionFor),
+    };
+    return [home, ...families, item];
+}
+
+/** Every header and footer pattern, in contract order. */
+export function showcaseGlobals(): { headers: string[]; footers: string[] } {
+    const of = (position: `${PatternGlobalPosition}`) => Object.entries(SITE_PATTERNS).filter(([, p]) => p.global === position).map(([id]) => id);
+    return { headers: of(PatternGlobalPosition.Before), footers: of(PatternGlobalPosition.After) };
+}
+
+/** The showcase as Site Plans — as many as it takes for every header and every footer to be composed once. */
+export function showcasePlans(input: ShowcaseInput): SitePlan[] {
+    const { headers, footers } = showcaseGlobals();
+    const count = Math.max(headers.length, footers.length, 1);
+    const pages = showcasePages();
+    return Array.from({ length: count }, (_, i): SitePlan => ({
+        version: SITE_PLAN_VERSION,
+        source: { kind: SitePlanSourceKind.Template, templateId: 'showcase', templateVersion: 1 },
+        business: JSON.parse(JSON.stringify(input.business)),
+        ...(input.locale ? { locale: input.locale } : {}),
+        design: JSON.parse(JSON.stringify(input.design)),
+        contentTypes: JSON.parse(JSON.stringify(STUDIO_TEMPLATE.contentTypes)),
+        dataSources: JSON.parse(JSON.stringify(STUDIO_TEMPLATE.dataSources)),
+        pages: JSON.parse(JSON.stringify(pages)),
+        globals: { [GlobalSlot.Header]: headers[i % headers.length], [GlobalSlot.Footer]: footers[i % footers.length] } as SitePlan['globals'],
+    }));
+}

package/src/generation-core/site-plan-schema.ts

@@ -1,11 +1,15 @@
-import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
+import { ANIMATE_IDS, DesignChoices } from '@vectoriox/iox-ui/design-core';
+import { FORM_PRESETS } from '@vectoriox/iox-ui/forms-core';
 
 import {
     jsonAnyOf, jsonBoolean, jsonClosedObject, jsonInteger, jsonListOf, jsonOneOf, JsonSchema, jsonShapedObject, jsonText,
 } from './json-schema';
-import { patternOptionalParts, patternSlots, patternTakesBinding, PatternGlobalPosition, SITE_PATTERNS, SitePattern } from './patterns';
 import {
-    FACT_KEYS, GlobalSlot, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SitePlan, SitePlanSource, SitePlanSourceKind, SITE_PLAN_VERSION,
+    patternHasForm, patternLinkSlots, patternOptionalParts, patternSlots, patternTakesBinding, PatternGlobalPosition, SITE_PATTERNS, SitePattern,
+} from './patterns';
+import {
+    FACT_KEYS, GlobalSlot, PAGE_ARCHETYPES, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SitePlan, SitePlanSource, SitePlanSourceKind, SITE_LOCALES,
+    SITE_PLAN_VERSION,
 } from './site-plan.model';
 import { SPEC_SITE_PLAN_SHAPE } from './site-spec.generated';
 import { isPlainObject, PlainObject, ShapeEntry } from './shape-check';
@@ -88,8 +92,10 @@ export function contentTypeJsonSchema(): JsonSchema {
     const values = jsonListOf(jsonClosedObject({ [SitePlanWireKey.SeedField]: jsonText(), [SitePlanWireKey.SeedValue]: value }, [SitePlanWireKey.SeedField, SitePlanWireKey.SeedValue]));
     const seed = jsonShapedObject(SHAPE['seed'], { count: jsonInteger(), sample: jsonBoolean(), isPublished: jsonBoolean() }, 'seed',
         { key: SitePlanWireKey.SeedValues, schema: values });
+    const roleKeys = Object.keys(SHAPE['roles']).map(k => k.replace(/\?$/, ''));
+    const roles = jsonShapedObject(SHAPE['roles'], Object.fromEntries(roleKeys.map(k => [k, jsonText()])), 'roles');
     return jsonShapedObject(SHAPE['contentType'], {
-        name: jsonText(), label: jsonText(), previewTextField: jsonText(), previewImageField: jsonText(), fields: jsonListOf(fieldJsonSchema()), seed,
+        name: jsonText(), label: jsonText(), roles, fields: jsonListOf(fieldJsonSchema()), seed,
     }, 'contentType');
 }
 
@@ -114,20 +120,25 @@ export function sectionPatternIds(): string[] {
 /** A key a pattern has nothing for: only `{}` (or leaving it out) — the decoder drops it. */
 const NOTHING = (): JsonSchema => jsonClosedObject({}, []);
 
-/** One section branch: this pattern's id, its declared slots (a list), its optional parts, a binding when it takes one. */
+/** One section branch: this pattern's id, its declared slots (a list), the slots it may re-point (`links`, closed per
+ *  pattern), its optional parts, a binding when it takes one, a form preset when it holds a form, its own entrance. */
 function sectionBranch(id: string, pattern: SitePattern): JsonSchema {
     const slots = patternSlots(pattern);
     const parts = patternOptionalParts(pattern);
+    const linkSlots = patternLinkSlots(pattern);
     const slotList = slots.length
         ? jsonListOf(jsonClosedObject({ [SitePlanWireKey.SlotName]: jsonOneOf(slots), [SitePlanWireKey.SlotText]: jsonText() }, [SitePlanWireKey.SlotName, SitePlanWireKey.SlotText]))
         : NOTHING();
     const branch = jsonShapedObject(SHAPE['section'], {
         pattern: one(id),
         slots: slotList,
+        links: linkSlots.length ? jsonClosedObject(Object.fromEntries(linkSlots.map(slot => [slot, jsonText()])), []) : NOTHING(),
         binding: patternTakesBinding(pattern) ? jsonText() : NOTHING(),
         without: parts.length ? jsonListOf(jsonOneOf(parts)) : NOTHING(),
+        form: patternHasForm(pattern) ? jsonOneOf(FORM_PRESETS.map(p => p.id)) : NOTHING(),
+        enter: jsonOneOf(ANIMATE_IDS),
     }, 'section');
-    return { ...branch, description: `${id}: ${pattern.label}` };
+    return { ...branch, description: `${id}: ${pattern.intent}` };
 }
 
 /** A page section: one branch per pattern. */
@@ -137,9 +148,10 @@ export function sectionJsonSchema(): JsonSchema {
 
 /** A page. */
 export function pageJsonSchema(): JsonSchema {
+    const seo = jsonShapedObject(SHAPE['pageSeo'], { title: jsonText(), description: jsonText() }, 'pageSeo');
     return jsonShapedObject(SHAPE['page'], {
         key: jsonText(), name: jsonText(), route: jsonText(), isHome: jsonBoolean(), required: jsonBoolean(), inNav: jsonBoolean(),
-        template: jsonText(), routeSource: jsonText(), sections: jsonListOf(sectionJsonSchema()),
+        archetype: jsonOneOf(Object.keys(PAGE_ARCHETYPES)), template: jsonText(), routeSource: jsonText(), seo, sections: jsonListOf(sectionJsonSchema()),
     }, 'page');
 }
 
@@ -155,6 +167,7 @@ export function sitePlanJsonSchema(pin: SitePlanSchemaPin): JsonSchema {
         version: one(SITE_PLAN_VERSION),
         source: sourceSchema(pin.source),
         business: businessSchema(),
+        locale: jsonOneOf(Object.keys(SITE_LOCALES)),
         design: pinnedDesign(pin.design),
         contentTypes: jsonListOf(contentTypeJsonSchema()),
         dataSources: jsonListOf(dataSourceJsonSchema()),
@@ -182,7 +195,7 @@ function slotsFromWire(slots: unknown): unknown {
 export function sectionFromWire(section: unknown): unknown {
     if (!isPlainObject(section)) return section;
     const out: PlainObject = { ...section };
-    for (const key of ['slots', 'binding', 'without']) if (isEmptyObject(out[key])) delete out[key];
+    for (const key of ['slots', 'links', 'binding', 'without', 'form']) if (isEmptyObject(out[key])) delete out[key];
     if ('slots' in out) out['slots'] = slotsFromWire(out['slots']);
     return out;
 }

package/src/generation-core/site-plan.model.ts

@@ -1,6 +1,6 @@
-import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
+import type { AnimateId, DesignChoices } from '@vectoriox/iox-ui/design-core';
 
-import { SPEC_SITE_FACTS } from './site-spec.generated';
+import { SPEC_SITE_ARCHETYPES, SPEC_SITE_FACTS, SPEC_SITE_LOCALES, SPEC_SITE_REQUIRED_ROLES, SPEC_SITE_ROLES } from './site-spec.generated';
 
 /**
  * The Site Plan (contract `site.planShape`, `SPEC_SITE_PLAN_SHAPE`: every key typed and explained, and the
@@ -49,15 +49,42 @@ export interface ContentSeedPlan {
     readonly [field: string]: unknown;
 }
 
+/** The part a field plays (contract `site.roles`, AI plan L0-3): what a pattern binds instead of a field name, so one
+ *  card grid shows projects, services or a menu. `title` is required on every type. */
+export enum ContentRole {
+    Title = 'title',
+    Summary = 'summary',
+    Image = 'image',
+    Meta = 'meta',
+    Date = 'date',
+    Gallery = 'gallery',
+}
+
+/** What each role means, verbatim from the contract — what the model reads. */
+export const CONTENT_ROLE_MEANINGS: Readonly<Record<`${ContentRole}`, string>> = SPEC_SITE_ROLES;
+export const REQUIRED_CONTENT_ROLES: ReadonlyArray<`${ContentRole}`> = SPEC_SITE_REQUIRED_ROLES;
+
+/** Which field plays each role (a field name of the type). */
+export type ContentRoles = Readonly<{ title: string } & Partial<Record<Exclude<`${ContentRole}`, 'title'>, string>>>;
+
 export interface ContentTypePlan {
     readonly name: string;
     readonly label: string;
-    readonly previewTextField?: string;
-    readonly previewImageField?: string;
+    readonly roles: ContentRoles;
     readonly fields: ReadonlyArray<ContentFieldPlan>;
     readonly seed?: ContentSeedPlan;
 }
 
+/** The CMS schema's preview fields of a content type — its title and image roles (the CMS's own names for them). */
+export function contentTypePreviewFields(type: Pick<ContentTypePlan, 'roles'>): { previewTextField: string; previewImageField?: string } {
+    return { previewTextField: type.roles.title, ...(type.roles.image ? { previewImageField: type.roles.image } : {}) };
+}
+
+/** The field playing `role` in `type`, or undefined. */
+export function roleField(type: Pick<ContentTypePlan, 'roles'> | null | undefined, role: string): string | undefined {
+    return (type?.roles as Readonly<Record<string, string>> | undefined)?.[role];
+}
+
 export enum PlanDataSourceType {
     Cms = 'cms',
     Relative = 'relative',
@@ -98,12 +125,38 @@ export type DataSourcePlan = CmsDataSourcePlan | RelativeDataSourcePlan;
 export interface PageSectionPlan {
     readonly pattern: string;
     readonly slots?: Readonly<Record<string, string>>;
+    /** A linked slot (a button, a link) re-pointed to another page route of the plan. */
+    readonly links?: Readonly<Record<string, string>>;
     /** The list source alias a pattern's `$binding` repeater iterates. */
     readonly binding?: string;
     /** Optional pattern parts (`optional: <id>`) to leave out. */
     readonly without?: ReadonlyArray<string>;
+    /** A forms-core preset for the pattern's form, instead of the pattern's own. */
+    readonly form?: string;
+    /** How this section moves in, instead of the look's How animated (M1-6b; M2's "make the hero calmer"). */
+    readonly enter?: AnimateId;
+}
+
+/** A page's search-result words, when the plan writes them (each within the seo-core limits). */
+export interface PageSeoPlan {
+    readonly title?: string;
+    readonly description?: string;
 }
 
+/** The kinds of page a plan is made of (contract `site.archetypes`, L0-2). */
+export type PageArchetypeId = keyof typeof SPEC_SITE_ARCHETYPES;
+export interface PageArchetypeSlot {
+    readonly label: string;
+    readonly families: ReadonlyArray<string>;
+    readonly required: boolean;
+}
+export interface PageArchetype {
+    readonly label: string;
+    readonly intent: string;
+    readonly slots: ReadonlyArray<PageArchetypeSlot>;
+}
+export const PAGE_ARCHETYPES: Readonly<Record<string, PageArchetype>> = SPEC_SITE_ARCHETYPES;
+
 export interface PagePlan {
     readonly key: string;
     readonly name: string;
@@ -117,6 +170,9 @@ export interface PagePlan {
     readonly template?: string;
     /** The single source bound to the route item (`route.*`). */
     readonly routeSource?: string;
+    /** The kind of page (`PAGE_ARCHETYPES`): its sections fill the type's required slots from the families it allows. */
+    readonly archetype?: PageArchetypeId;
+    readonly seo?: PageSeoPlan;
     readonly sections: ReadonlyArray<PageSectionPlan>;
 }
 
@@ -125,10 +181,25 @@ export enum GlobalSlot {
     Footer = 'footer',
 }
 
+/** The site's language (contract `site.locales`): every page's locale, and its direction. */
+export enum SiteLocale {
+    En = 'en',
+    He = 'he',
+}
+export const DEFAULT_SITE_LOCALE = SiteLocale.En;
+export const SITE_LOCALES: Readonly<Record<`${SiteLocale}`, { label: string; dir: 'ltr' | 'rtl' }>> = SPEC_SITE_LOCALES;
+
+/** True when `locale` reads right to left. */
+export function isRtlLocale(locale: string | null | undefined): boolean {
+    return (SITE_LOCALES as Readonly<Record<string, { dir: string }>>)[locale ?? '']?.dir === 'rtl';
+}
+
 export interface SitePlan {
     readonly version: typeof SITE_PLAN_VERSION;
     readonly source: SitePlanSource;
     readonly business: SiteBusiness;
+    /** The site's language — absent = English. */
+    readonly locale?: `${SiteLocale}`;
     readonly design: Readonly<DesignChoices>;
     readonly contentTypes: ReadonlyArray<ContentTypePlan>;
     readonly dataSources: ReadonlyArray<DataSourcePlan>;