@vectoriox/iox-ui 5.68.0 → 5.70.0

package/generation-core/index.d.ts

@@ -69,6 +69,7 @@ declare const SPEC_SITE_PLAN_SHAPE: {
         readonly count: "integer ≥ 0";
         readonly sample: "boolean — items are flagged isSample";
         readonly isPublished: "boolean";
+        readonly "perItem?": "per field, one string per sample: real content that wins over the template";
         readonly "[field]?": "the field's value — strings are templates: {n} = the item's 1-based number, {sampleImage:n} / {sampleImage:n+k} = a bundled sample image";
     };
     readonly cmsDataSource: {
@@ -4371,6 +4372,8 @@ interface ContentSeedPlan {
     readonly count: number;
     readonly sample: boolean;
     readonly isPublished: boolean;
+    /** Per field, one value per sample: real content where the items are about a subject anyone can know. Wins over the field's template. */
+    readonly perItem?: Readonly<Record<string, ReadonlyArray<string>>>;
     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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.68.0",
+  "version": "5.70.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -55,6 +55,10 @@
       "types": "./media-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-media-core.mjs"
     },
+    "./scene-core": {
+      "types": "./scene-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-scene-core.mjs"
+    },
     "./seo-core": {
       "types": "./seo-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-seo-core.mjs"

package/scene-core/index.d.ts

@@ -0,0 +1,193 @@
+import { CompositeNode, CompositeNodeFactory } from '@vectoriox/iox-ui/composite-core';
+
+/**
+ * A Scene's data and maths (premium-sites plan §5b). A Scene is a recipe of ordinary nodes — a tall Section, a pinned
+ * stage inside it, ordinary nodes as layers — so every word stays real, bound and translatable, and all three render
+ * paths already draw it. What moves a layer is its OWN `sceneTracks`, never a list on the root naming layer ids: a clone
+ * copies them with the layer, a delete takes them with it, and there is no id to remap.
+ *
+ * The vocabulary is closed. Every property is one the compositor can run without layout (CLS stays 0): a saved value
+ * outside it is dropped when read, so a page document can never write CSS through a track.
+ */
+declare enum SceneProp {
+    /** Along the inline axis, in % of the stage's width. Positive runs toward the inline END (mirrored in RTL). */
+    X = "x",
+    /** Down, in % of the stage's height. */
+    Y = "y",
+    Scale = "scale",
+    /** Degrees. */
+    Rotate = "rotate",
+    /** 0–1. */
+    Opacity = "opacity",
+    /** Inset from every side, in % of the layer (0 = whole, 50 = gone). */
+    Clip = "clip",
+    /** The layer's background colour. */
+    Ground = "ground",
+    /** The layer's text colour. */
+    Ink = "ink"
+}
+/** One key: at progress `[0]` (0–1) the property holds `[1]`: a number, or a colour for Ground and Ink. */
+type SceneKey = readonly [number, number | string];
+interface SceneTrack {
+    prop: SceneProp;
+    /** Ascending by progress. Between two keys the value eases (smoothstep); outside them it holds the nearest. */
+    keys: ReadonlyArray<SceneKey>;
+}
+/** What a node carries (both a builder node and a saved one). */
+interface SceneNodeSource {
+    role?: string | null;
+    /** How this layer moves, from the wide layout down to the phone's. */
+    sceneTracks?: ReadonlyArray<SceneTrack> | null;
+    /** How it moves at phone width instead (`SCENE_PHONE_MAX_WIDTH`). Absent = the same tracks. */
+    scenePhoneTracks?: ReadonlyArray<SceneTrack> | null;
+}
+/** A frame as inline-style properties (camelCase, as `CSSStyleDeclaration` and `Object.assign` take them). */
+interface SceneFrame {
+    transform?: string;
+    opacity?: string;
+    clipPath?: string;
+    backgroundColor?: string;
+    color?: string;
+}
+declare enum SceneAttribute {
+    Root = "data-iox-scene",
+    Tracks = "data-iox-tracks",
+    PhoneTracks = "data-iox-tracks-phone"
+}
+/** At or under this stage width a layer plays its phone tracks. The `mobile` breakpoint's width. */
+declare const SCENE_PHONE_MAX_WIDTH = 767;
+/**
+ * The tracks a saved value really holds: unknown properties, bad keys and colours that are not colours are dropped,
+ * keys sorted by progress, a track left with no key dropped. Never throws on what a page document holds.
+ */
+declare function normalizeTracks(tracks: unknown): SceneTrack[];
+/** A numeric track's value at progress `p`. */
+declare function valueAt(keys: ReadonlyArray<SceneKey>, p: number): number;
+/**
+ * A colour track's value at progress `p`. Mixed by the browser, never computed here, so a design token stays a live
+ * reference (a re-theme reaches a Scene, as it reaches every saved page) and the path is perceptual.
+ */
+declare function colourAt(keys: ReadonlyArray<SceneKey>, p: number): string;
+interface SceneFrameOptions {
+    /** -1 when the stage reads right-to-left: the inline axis mirrors. */
+    inlineSign?: 1 | -1;
+}
+/**
+ * A layer's frame at progress `p`. Lengths are container-query units, so one frame is right at any width, under any
+ * canvas zoom, on the server and with no measuring: the stage is the size container (`iox-design.css`).
+ */
+declare function sceneFrame(tracks: ReadonlyArray<SceneTrack>, p: number, options?: SceneFrameOptions): SceneFrame;
+/** A frame as kebab-case style declarations, for a string renderer. */
+declare function sceneFrameDeclarations(frame: SceneFrame): Record<string, string>;
+/** The attributes a node's own element carries — the same decision in all three render paths. The runtime reads them,
+ *  so it needs no node tree and is the same on every path. Empty for any node that is no part of a Scene. */
+declare function sceneNodeAttributes(node: SceneNodeSource | null | undefined): Record<string, string>;
+/** The frame a layer ships in from the server: where it stands before anyone has scrolled. Without it the page would
+ *  paint every layer at once, and then jump when the script arrives. */
+declare function sceneFirstFrame(node: SceneNodeSource | null | undefined): SceneFrame;
+/**
+ * Make an element carry its node's Scene attributes: the live sync on the canvas and the component path's stamp.
+ * Removes stale ones, touches nothing else.
+ */
+declare function syncSceneAttributes(el: HTMLElement | null | undefined, node: SceneNodeSource | null | undefined): void;
+/** Stamp a layer's first frame on its element (the component path, on the server too). */
+declare function applySceneFirstFrame(el: HTMLElement | null | undefined, node: SceneNodeSource | null | undefined): void;
+/**
+ * Where nothing will drive it (reduced motion, no script) a Scene is ordinary content: it flows, every layer in its
+ * place and in its own look, every word readable. `!important` because it must beat a node's compiled height and
+ * position, and the inline first frame. The engine wraps it in a reduced-motion query and in `<noscript>`.
+ */
+declare const SCENE_FLOW_RULES: string;
+/** Under reduced motion the driver never starts, so the same rules hold for the whole visit. */
+declare const SCENE_REDUCED_MOTION_CSS = "@media (prefers-reduced-motion: reduce){.iox-role-scene{height:auto!important}.iox-role-scene-stage{position:relative!important;top:auto!important;height:auto!important;overflow:visible!important;container-type:normal!important}[data-iox-tracks]{transform:none!important;opacity:1!important;clip-path:none!important}}";
+
+/**
+ * The SCENE recipe: ordinary nodes, no new type, so all three render paths and every panel already know it.
+ *
+ *   Section    role scene         height = how long it plays (× the viewport)
+ *   └─ Container  role scene.stage   pinned, one viewport tall, clips its layers, the size container for their lengths
+ *       ├─ Heading                   a layer with its own tracks
+ *       └─ Text                      a layer with its own tracks
+ *
+ * How long it plays IS the root's height, so it follows the width system the way every other size does. The stage is a
+ * track-carrying layer too: its Ground is the colour the whole Scene moves through.
+ */
+type SceneLayerNode = CompositeNode & SceneNodeSource;
+interface SceneWords {
+    title: string;
+    line: string;
+}
+/** Generic words a fresh Scene starts with: the author's to replace. */
+declare const SCENE_WORDS: Readonly<SceneWords>;
+/** How long a fresh Scene plays: 4 viewports wide, 3 on a phone (a thumb travels less). */
+declare const SCENE_LENGTH = "400vh";
+declare const SCENE_PHONE_LENGTH = "300vh";
+/** Small viewport height: a phone's toolbar never pushes the stage's bottom out of sight. */
+declare const SCENE_STAGE_HEIGHT = "100svh";
+/** A fresh Scene: it already moves, so the author sees what the thing is before touching it. */
+declare function buildSceneRecipe(create: CompositeNodeFactory, words?: Partial<SceneWords>): SceneLayerNode;
+
+/**
+ * The ONE scroll loop (premium-sites plan §5b, SC0). Every Scene on a page reads one progress value from it, on the
+ * canvas and on the live site alike. It reads where the root is and nothing else, so it has one code path: under the
+ * canvas's zoom the same rectangle divides by the same zoom, and the answer is the same at any scale.
+ *
+ * - The value is DAMPED: the scroll stops and the page settles a moment later. This is much of the prototype's weight,
+ *   and why this is not a CSS scroll timeline, which cannot do it.
+ * - The live site pins with `position: sticky`, on the compositor. The canvas cannot (its page never scrolls itself,
+ *   its Lenis scrolls a wrapper around a zoomed frame), so `pin` holds the stage there with `translate` instead.
+ *   `translate`, not `transform`: a Stage may carry tracks of its own.
+ * - It sleeps. No frame is asked for unless something moved, so a page holding a settled Scene costs nothing.
+ * - Reads come first in a frame and writes after, and a write only ever touches compositor properties.
+ */
+declare const SCENE_DAMPING = 9;
+/** One frame of the damping: frame-rate independent, so 60 Hz and 120 Hz settle in the same time. */
+declare function dampToward(current: number, target: number, seconds: number, rate?: number): number;
+/** Where a root stands: scrolled `local` page px into its `travel`. `zoom` undoes the canvas's scale. */
+declare function sceneScrollState(rootTop: number, originTop: number, zoom: number, travel: number): {
+    local: number;
+    progress: number;
+};
+interface ScrollDriverOptions {
+    /** Hold the stage with `translate` (the canvas). The live site's stage is sticky and needs nothing. */
+    pin?: boolean;
+    /** The element a root scrolls under, when that is not the window (the canvas's frame, Preview's page). */
+    originOf?: (root: HTMLElement) => HTMLElement | null;
+    /** Follow what changes inside a root: tracks edited, layers added (the canvas). */
+    observe?: boolean;
+    damping?: number;
+    /** The window, for a test. */
+    host?: Window;
+}
+declare class ScrollDriver {
+    private readonly options;
+    private readonly scenes;
+    private readonly host;
+    private readonly resize;
+    private frame;
+    private lastTime;
+    private readonly wakeUp;
+    constructor(options?: ScrollDriverOptions);
+    /** Drive a Scene's root. Idempotent: adding a root again re-reads it. */
+    add(root: HTMLElement): void;
+    remove(root: HTMLElement): void;
+    /** The damped progress a root's layers stand at. */
+    progressOf(root: HTMLElement): number | null;
+    /** Something moved that no scroll or resize announces (the canvas's zoom). */
+    wake(): void;
+    destroy(): void;
+    /** Read a root's stage and layers from its DOM: its own Scene's only, never a nested one's. */
+    private reread;
+    private readLayer;
+    private remeasureAll;
+    private measure;
+    private readonly tick;
+    private read;
+    private write;
+}
+/** A page's Scenes, driven by one driver; null when it holds none, or when the visitor asked for less motion (the
+ *  page's own CSS then lets each Scene flow). The live site's door. */
+declare function attachScenes(container: HTMLElement, options?: ScrollDriverOptions): ScrollDriver | null;
+
+export { SCENE_DAMPING, SCENE_FLOW_RULES, SCENE_LENGTH, SCENE_PHONE_LENGTH, SCENE_PHONE_MAX_WIDTH, SCENE_REDUCED_MOTION_CSS, SCENE_STAGE_HEIGHT, SCENE_WORDS, SceneAttribute, SceneProp, ScrollDriver, applySceneFirstFrame, attachScenes, buildSceneRecipe, colourAt, dampToward, normalizeTracks, sceneFirstFrame, sceneFrame, sceneFrameDeclarations, sceneNodeAttributes, sceneScrollState, syncSceneAttributes, valueAt };
+export type { SceneFrame, SceneFrameOptions, SceneKey, SceneLayerNode, SceneNodeSource, SceneTrack, SceneWords, ScrollDriverOptions };

package/scene-core/package.json

@@ -0,0 +1,3 @@
+{
+  "module": "../fesm2022/vectoriox-iox-ui-scene-core.mjs"
+}

package/src/composite-core/composite-kinds.ts

@@ -66,6 +66,15 @@ export enum SegmentedRole {
     Badge = 'segmented.badge',
 }
 
+/**
+ * A SCENE (premium-sites plan §5b): a stage held still while the page scrolls past it. The stage is the root's only
+ * part; everything inside the stage is an ordinary node. Its maths and its runtime are `@vectoriox/iox-ui/scene-core`.
+ */
+export enum SceneRole {
+    Scene = 'scene',
+    Stage = 'scene.stage',
+}
+
 interface RoleLike { role?: string | null }
 
 /** The roles each open/close kind plays in the shared runtime. */

package/src/composite-core/structure.ts

@@ -1,4 +1,4 @@
-import { AccordionRole, DisclosureRole, SegmentedRole, TabsRole } from './composite-kinds';
+import { AccordionRole, DisclosureRole, SceneRole, SegmentedRole, TabsRole } from './composite-kinds';
 import { CardPart, CardRole } from './card';
 import { SLIDER_TYPE, SliderRole } from './slider';
 
@@ -56,6 +56,9 @@ export const COMPOSITE_ROLE_SPECS: Readonly<Record<string, CompositeRoleSpec>> =
     [SegmentedRole.Segmented]: { parent: null, accepts: [SegmentedRole.Option] },
     [SegmentedRole.Option]: { parent: SegmentedRole.Segmented, pinned: true },
     [SegmentedRole.Badge]: { parent: SegmentedRole.Option, pinned: true },
+    // A Scene always keeps its stage: everything it pins and clips lives there.
+    [SceneRole.Scene]: { parent: null },
+    [SceneRole.Stage]: { parent: SceneRole.Scene, locked: true },
     // CC3 — a Slider's controls are its own direct children (Swiper is handed them). The pause control stays while
     // Autoplay is on (WCAG 2.2.2): the Autoplay switch removes it, never Delete. The arrows and the dots follow
     // their switches and may be deleted.

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

@@ -1109,7 +1109,8 @@ function composeItems(type: ContentTypePlan, fillEmpty: boolean): ComposedItem[]
         for (const field of type.fields) {
             const given = seed[field.name];
             const empty = !(field.name in seed) || given === '' || (Array.isArray(given) && !given.length);
-            const value = empty && fillEmpty ? defaultSeed(type, field) : given;
+            const own = seed.perItem?.[field.name]?.[n - 1];
+            const value = own || (empty && fillEmpty ? defaultSeed(type, field) : given);
             if (value !== undefined) item[field.name] = expandSeedValue(value, n);
         }
         items.push({ ...item, isPublished: seed.isPublished, isSample: seed.sample });

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

@@ -130,6 +130,7 @@ const WIRE_KEYS: Readonly<Record<`${PlanWireEntry}`, Readonly<Record<string, Wir
     seedValue: {
         field: { refs: ['seed.[field]'], text: 'string — a field of the type' },
         value: { refs: ['seed.[field]'], text: `string | string[] — ${describeShapeKey(PLAN_SHAPE['seed'], '[field]')} (a list for an array field)` },
+        each: { refs: ['seed.perItem'], text: 'string[] — one value per sample, in order, when each sample has its own content', none: '[]' },
     },
     dataSource: {
         alias: { refs: ['cmsDataSource.alias', 'relativeDataSource.alias'] },
@@ -284,7 +285,7 @@ const shapedAs = (entry: `${PlanWireEntry}`, options: WireOptions, properties: R
 };
 
 export function wireContentTypeJsonSchema(options: WireOptions = {}): JsonSchema {
-    const value = shaped(PlanWireEntry.SeedValue, { field: jsonText(), value: jsonAnyOf([jsonText(), jsonListOf(jsonText())]) });
+    const value = shaped(PlanWireEntry.SeedValue, { field: jsonText(), value: jsonAnyOf([jsonText(), jsonListOf(jsonText())]), each: jsonListOf(jsonText()) });
     return shapedAs(PlanWireEntry.ContentType, options, {
         name: jsonText(),
         label: jsonText(),
@@ -412,8 +413,16 @@ export function expandWireContentType(wire: unknown, options: WireOptions = {}):
     if (!isPlainObject(seed)) return seed === undefined ? out : { ...out, seed };
     const { values, ...fixed } = seed;
     if (fixed['count'] === 0 && emptyList(values)) return out;
-    const map = listToMap(values ?? [], 'field', 'value');
-    return { ...out, seed: isPlainObject(map) ? { ...fixed, ...map } : { ...fixed, values } };
+    const perItem: Record<string, unknown> = {};
+    const plain = Array.isArray(values) ? values.map(row => {
+        if (!isPlainObject(row)) return row;
+        const { each, ...rest } = row;
+        if (Array.isArray(each) && each.length) perItem[String(rest['field'])] = each;
+        return rest;
+    }) : values;
+    const map = listToMap(plain ?? [], 'field', 'value');
+    const items = Object.keys(perItem).length ? { perItem } : {};
+    return { ...out, seed: isPlainObject(map) ? { ...fixed, ...items, ...map } : { ...fixed, values } };
 }
 
 export function expandWireDataSource(wire: unknown): DataSourcePlan | unknown {
@@ -501,10 +510,10 @@ export function fieldToWire(field: ContentFieldPlan): PlainObject {
 export function contentTypeToWire(type: ContentTypePlan, options: WireOptions = {}): PlainObject {
     const played = type.roles as Readonly<Record<string, string | undefined>>;
     const roles = ROLE_KEYS.filter(role => played[role]).map(role => ({ role, field: played[role] }));
-    const { count = 0, sample = false, isPublished = false, ...values } = type.seed ?? {};
+    const { count = 0, sample = false, isPublished = false, perItem = {}, ...values } = type.seed ?? {};
     return {
         name: type.name, label: type.label, roles, ...(options.children === false ? {} : { fields: type.fields.map(fieldToWire) }),
-        seed: { count, sample, isPublished, values: mapToList(values, 'field', 'value') },
+        seed: { count, sample, isPublished, values: mapToList(values, 'field', 'value').map(row => ({ ...row, each: perItem[String(row['field'])] ?? [] })) },
     };
 }
 

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

@@ -45,7 +45,9 @@ export function writtenTexts(plan: SitePlan): WrittenText[] {
     });
     plan.contentTypes?.forEach((type, t) => {
         add(`contentTypes[${t}].label`, type.label);
-        for (const [field, value] of Object.entries(type.seed ?? {})) {
+        const { perItem, ...seed }: Record<string, unknown> & { perItem?: Readonly<Record<string, ReadonlyArray<string>>> } = type.seed ?? {};
+        for (const [field, list] of Object.entries(perItem ?? {})) list.forEach((v, k) => add(`contentTypes[${t}].seed.perItem.${field}[${k}]`, v));
+        for (const [field, value] of Object.entries(seed)) {
             const values = Array.isArray(value) ? value : [value];
             values.forEach((v, k) => add(`contentTypes[${t}].seed.${field}${Array.isArray(value) ? `[${k}]` : ''}`, v));
         }

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

@@ -79,6 +79,8 @@ export interface ContentSeedPlan {
     readonly count: number;
     readonly sample: boolean;
     readonly isPublished: boolean;
+    /** Per field, one value per sample: real content where the items are about a subject anyone can know. Wins over the field's template. */
+    readonly perItem?: Readonly<Record<string, ReadonlyArray<string>>>;
     readonly [field: string]: unknown;
 }
 

package/src/generation-core/site-spec.generated.ts

@@ -69,6 +69,7 @@ export const SPEC_SITE_PLAN_SHAPE = {
     "count": "integer ≥ 0",
     "sample": "boolean — items are flagged isSample",
     "isPublished": "boolean",
+    "perItem?": "per field, one string per sample: real content that wins over the template",
     "[field]?": "the field's value — strings are templates: {n} = the item's 1-based number, {sampleImage:n} / {sampleImage:n+k} = a bundled sample image"
   },
   "cmsDataSource": {

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

@@ -103,6 +103,7 @@ const ROLE_KEYS = shapeKeys(SHAPE['roles']);
 const PAGE_SEO_KEYS = shapeKeys(SHAPE['pageSeo']);
 const ARRAY_TYPE = 'array';
 const FIELD_KEYS = shapeKeys(SHAPE['field']);
+const SLUG_FIELD = 'slug';
 const SEED_FIXED_KEYS = shapeKeys(SHAPE['seed']);
 const CMS_SOURCE_KEYS = shapeKeys(SHAPE['cmsDataSource']);
 const RELATIVE_SOURCE_KEYS = shapeKeys(SHAPE['relativeDataSource']);
@@ -226,6 +227,16 @@ function validateContentTypes(c: Collector, list: unknown[]): Map<string, Conten
             else {
                 if (!Number.isInteger(seed['count']) || (seed['count'] as number) < 0) c.add(SitePlanIssueCode.Shape, `${path}.seed.count`, 'must be a whole number');
                 for (const key of ['sample', 'isPublished']) if (typeof seed[key] !== 'boolean') c.add(SitePlanIssueCode.Shape, `${path}.seed.${key}`, 'must be a boolean');
+                const perItem = seed['perItem'];
+                if (perItem !== undefined) {
+                    if (!isObject(perItem)) c.add(SitePlanIssueCode.Shape, `${path}.seed.perItem`, 'must be an object');
+                    else for (const [field, list] of Object.entries(perItem)) {
+                        const at = `${path}.seed.perItem.${field}`;
+                        if (!fieldSet.has(field)) c.add(SitePlanIssueCode.UnknownField, at, `"${field}" is not a field of ${name}`);
+                        else if (!Array.isArray(list) || list.length !== seed['count'] || list.some(v => typeof v !== 'string')) c.add(SitePlanIssueCode.Shape, at, `must be ${String(seed['count'])} strings, one per sample`);
+                        else if (field === SLUG_FIELD && new Set(list).size !== list.length) c.add(SitePlanIssueCode.Shape, at, 'each sample needs its own slug');
+                    }
+                }
                 for (const key of Object.keys(seed)) {
                     if (!SEED_FIXED_KEYS.includes(key) && !fieldSet.has(key)) c.add(SitePlanIssueCode.UnknownField, `${path}.seed.${key}`, `"${key}" is not a field of ${name}`);
                 }

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

@@ -0,0 +1,9 @@
+/**
+ * @vectoriox/iox-ui/scene-core — a Scene: a stage that holds still while the page scrolls past it, its layers moving on
+ * ONE progress value (premium-sites plan §5b). FRAMEWORK-FREE: the builder canvas, both engine paths and (from SC6) the
+ * composer read the same tracks, frames and recipe; the driver is DOM-only and is the ONE scroll loop.
+ * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig paths.
+ */
+export * from './scene';
+export * from './scene-recipe';
+export * from './scroll-driver';

package/src/scene-core/scene-recipe.ts

@@ -0,0 +1,100 @@
+import { CompositeNode, CompositeNodeFactory, makeCompositePart, NO_ELEMENT_STYLE, SceneRole, writeLayerStyles, writeStyles } from '@vectoriox/iox-ui/composite-core';
+
+import { SceneNodeSource, SceneProp, SceneTrack } from './scene';
+
+/**
+ * The SCENE recipe: ordinary nodes, no new type, so all three render paths and every panel already know it.
+ *
+ *   Section    role scene         height = how long it plays (× the viewport)
+ *   └─ Container  role scene.stage   pinned, one viewport tall, clips its layers, the size container for their lengths
+ *       ├─ Heading                   a layer with its own tracks
+ *       └─ Text                      a layer with its own tracks
+ *
+ * How long it plays IS the root's height, so it follows the width system the way every other size does. The stage is a
+ * track-carrying layer too: its Ground is the colour the whole Scene moves through.
+ */
+
+export type SceneLayerNode = CompositeNode & SceneNodeSource;
+
+export interface SceneWords {
+    title: string;
+    line: string;
+}
+
+/** Generic words a fresh Scene starts with: the author's to replace. */
+export const SCENE_WORDS: Readonly<SceneWords> = {
+    title: 'One idea, held still',
+    line: 'The page keeps moving. This stays until you have read it.',
+};
+
+/** How long a fresh Scene plays: 4 viewports wide, 3 on a phone (a thumb travels less). */
+export const SCENE_LENGTH = '400vh';
+export const SCENE_PHONE_LENGTH = '300vh';
+/** Small viewport height: a phone's toolbar never pushes the stage's bottom out of sight. */
+export const SCENE_STAGE_HEIGHT = '100svh';
+const PHONE_BREAKPOINT = 'mobile';
+
+enum Type {
+    Section = 'Section',
+    Container = 'Container',
+    Heading = 'Heading',
+    Text = 'Text',
+}
+
+const ROOT_LAYOUT: Readonly<Record<string, string>> = {
+    position: 'relative',
+    display: 'block',
+    width: '100%',
+    height: SCENE_LENGTH,
+};
+
+const STAGE_LAYOUT: Readonly<Record<string, string>> = {
+    position: 'sticky',
+    top: '0px',
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: '100%',
+    height: SCENE_STAGE_HEIGHT,
+    overflow: 'hidden',
+};
+
+const TITLE_TRACKS: ReadonlyArray<SceneTrack> = [
+    { prop: SceneProp.Opacity, keys: [[0, 0], [0.2, 1], [0.75, 1], [1, 0]] },
+    { prop: SceneProp.Y, keys: [[0, 8], [0.2, 0], [1, -6]] },
+    { prop: SceneProp.Scale, keys: [[0, 0.96], [0.6, 1], [1, 1.04]] },
+];
+
+const LINE_TRACKS: ReadonlyArray<SceneTrack> = [
+    { prop: SceneProp.Opacity, keys: [[0.25, 0], [0.45, 1], [0.8, 1], [1, 0]] },
+    { prop: SceneProp.Y, keys: [[0.25, 6], [0.45, 0], [1, -4]] },
+];
+
+const STAGE_TRACKS: ReadonlyArray<SceneTrack> = [
+    { prop: SceneProp.Ground, keys: [[0, 'var(--iox-surface-2)'], [0.6, 'var(--iox-page-bg)']] },
+];
+
+const copyTracks = (tracks: ReadonlyArray<SceneTrack>): SceneTrack[] => tracks.map(t => ({ prop: t.prop, keys: t.keys.map(k => [k[0], k[1]] as const) }));
+
+/** A fresh Scene: it already moves, so the author sees what the thing is before touching it. */
+export function buildSceneRecipe(create: CompositeNodeFactory, words: Partial<SceneWords> = {}): SceneLayerNode {
+    const text = { ...SCENE_WORDS, ...words };
+    const root = makeCompositePart(create, { key: 'root', type: Type.Section, elementStyle: NO_ELEMENT_STYLE }, SceneRole.Scene, 'Scene', ROOT_LAYOUT) as SceneLayerNode;
+    writeLayerStyles(root, PHONE_BREAKPOINT, { height: SCENE_PHONE_LENGTH });
+
+    const stage = makeCompositePart(create, { key: 'stage', type: Type.Container, elementStyle: NO_ELEMENT_STYLE }, SceneRole.Stage, 'Stage', STAGE_LAYOUT) as SceneLayerNode;
+    stage.sceneTracks = copyTracks(STAGE_TRACKS);
+
+    const title = makeCompositePart(create, { key: 'title', type: Type.Heading, props: { text: text.title, tag: 'h2' } }, null, 'Title') as SceneLayerNode;
+    title.sceneTracks = copyTracks(TITLE_TRACKS);
+    writeStyles(title, { textAlign: 'center' });
+
+    const line = makeCompositePart(create, { key: 'line', type: Type.Text, props: { text: text.line } }, null, 'Line') as SceneLayerNode;
+    line.sceneTracks = copyTracks(LINE_TRACKS);
+    writeStyles(line, { textAlign: 'center' });
+
+    stage.children = [title, line];
+    root.children = [stage];
+    return root;
+}