@vectoriox/iox-ui 5.69.0 → 5.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.69.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/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;
+}

package/src/scene-core/scene.ts

@@ -0,0 +1,232 @@
+import { SceneRole } 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.
+ */
+
+export 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. */
+export type SceneKey = readonly [number, number | string];
+
+export 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). */
+export 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). */
+export interface SceneFrame {
+    transform?: string;
+    opacity?: string;
+    clipPath?: string;
+    backgroundColor?: string;
+    color?: string;
+}
+
+export 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. */
+export const SCENE_PHONE_MAX_WIDTH = 767;
+
+const DECIMALS = 10000;
+const round = (v: number): number => Math.round(v * DECIMALS) / DECIMALS;
+const clamp01 = (v: number): number => Math.min(1, Math.max(0, v));
+const smoothstep = (t: number): number => t * t * (3 - 2 * t);
+
+/** A colour a track may hold: a hex, an rgb()/hsl() literal, or a design token. Anything else could break out of the
+ *  inline style it lands in. */
+const COLOUR = /^(#[0-9a-f]{3,8}|(rgb|hsl)a?\([\d\s.,%/]+\)|var\(--iox-[\w-]+\))$/i;
+const COLOUR_PROPS: ReadonlySet<SceneProp> = new Set([SceneProp.Ground, SceneProp.Ink]);
+const ALL_PROPS: ReadonlySet<string> = new Set(Object.values(SceneProp));
+
+function validKey(key: unknown, colour: boolean): key is SceneKey {
+    if (!Array.isArray(key) || key.length !== 2) return false;
+    const [p, value] = key;
+    if (typeof p !== 'number' || !Number.isFinite(p) || p < 0 || p > 1) return false;
+    return colour ? typeof value === 'string' && COLOUR.test(value) : typeof value === 'number' && Number.isFinite(value);
+}
+
+/**
+ * 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.
+ */
+export function normalizeTracks(tracks: unknown): SceneTrack[] {
+    if (!Array.isArray(tracks)) return [];
+    const out: SceneTrack[] = [];
+    for (const track of tracks) {
+        const prop = (track as SceneTrack | null)?.prop;
+        if (!prop || !ALL_PROPS.has(prop) || !Array.isArray((track as SceneTrack).keys)) continue;
+        const keys = (track as SceneTrack).keys
+            .filter(key => validKey(key, COLOUR_PROPS.has(prop)))
+            .slice()
+            .sort((a, b) => a[0] - b[0]);
+        if (keys.length) out.push({ prop, keys });
+    }
+    return out;
+}
+
+/** The two keys around `p` and how far between them it eases. */
+function span(keys: ReadonlyArray<SceneKey>, p: number): { a: SceneKey; b: SceneKey; f: number } {
+    const at = clamp01(p);
+    if (at <= keys[0][0]) return { a: keys[0], b: keys[0], f: 0 };
+    for (let i = 1; i < keys.length; i++) {
+        if (at <= keys[i][0]) {
+            const a = keys[i - 1];
+            const b = keys[i];
+            const width = b[0] - a[0];
+            return { a, b, f: width > 0 ? smoothstep((at - a[0]) / width) : 1 };
+        }
+    }
+    const last = keys[keys.length - 1];
+    return { a: last, b: last, f: 0 };
+}
+
+/** A numeric track's value at progress `p`. */
+export function valueAt(keys: ReadonlyArray<SceneKey>, p: number): number {
+    if (!keys.length) return 0;
+    const { a, b, f } = span(keys, p);
+    const from = Number(a[1]);
+    return round(from + (Number(b[1]) - from) * f);
+}
+
+/**
+ * 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.
+ */
+export function colourAt(keys: ReadonlyArray<SceneKey>, p: number): string {
+    if (!keys.length) return '';
+    const { a, b, f } = span(keys, p);
+    if (f <= 0 || a === b) return String(a[1]);
+    if (f >= 1) return String(b[1]);
+    return `color-mix(in oklab, ${a[1]} ${round((1 - f) * 100)}%, ${b[1]})`;
+}
+
+export interface SceneFrameOptions {
+    /** -1 when the stage reads right-to-left: the inline axis mirrors. */
+    inlineSign?: 1 | -1;
+}
+
+/** What the tracks' transform-family properties rest at when a layer has no track for one. */
+const TRANSFORM_REST: Readonly<Partial<Record<SceneProp, number>>> = { [SceneProp.X]: 0, [SceneProp.Y]: 0, [SceneProp.Scale]: 1, [SceneProp.Rotate]: 0 };
+
+/**
+ * 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`).
+ */
+export function sceneFrame(tracks: ReadonlyArray<SceneTrack>, p: number, options: SceneFrameOptions = {}): SceneFrame {
+    const frame: SceneFrame = {};
+    const moves: Partial<Record<SceneProp, number>> = {};
+    for (const { prop, keys } of tracks) {
+        if (prop in TRANSFORM_REST) moves[prop] = valueAt(keys, p);
+        else if (prop === SceneProp.Opacity) frame.opacity = String(clamp01(valueAt(keys, p)));
+        else if (prop === SceneProp.Clip) frame.clipPath = `inset(${Math.min(50, Math.max(0, valueAt(keys, p)))}%)`;
+        else if (prop === SceneProp.Ground) frame.backgroundColor = colourAt(keys, p);
+        else if (prop === SceneProp.Ink) frame.color = colourAt(keys, p);
+    }
+    if (Object.keys(moves).length) {
+        const value = (prop: SceneProp): number => moves[prop] ?? TRANSFORM_REST[prop]!;
+        const x = round(value(SceneProp.X) * (options.inlineSign ?? 1));
+        frame.transform = `translate3d(${x}cqw, ${value(SceneProp.Y)}cqh, 0) rotate(${value(SceneProp.Rotate)}deg) scale(${value(SceneProp.Scale)})`;
+    }
+    return frame;
+}
+
+const CSS_NAME: Readonly<Record<keyof SceneFrame, string>> = {
+    transform: 'transform',
+    opacity: 'opacity',
+    clipPath: 'clip-path',
+    backgroundColor: 'background-color',
+    color: 'color',
+};
+
+/** A frame as kebab-case style declarations, for a string renderer. */
+export function sceneFrameDeclarations(frame: SceneFrame): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(frame)) if (value) out[CSS_NAME[key as keyof SceneFrame]] = value;
+    return out;
+}
+
+/** 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. */
+export function sceneNodeAttributes(node: SceneNodeSource | null | undefined): Record<string, string> {
+    const attrs: Record<string, string> = {};
+    if (node?.role === SceneRole.Scene) attrs[SceneAttribute.Root] = '';
+    const tracks = normalizeTracks(node?.sceneTracks);
+    const phone = normalizeTracks(node?.scenePhoneTracks);
+    if (tracks.length) attrs[SceneAttribute.Tracks] = JSON.stringify(tracks);
+    if (phone.length) attrs[SceneAttribute.PhoneTracks] = JSON.stringify(phone);
+    return attrs;
+}
+
+/** 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. */
+export function sceneFirstFrame(node: SceneNodeSource | null | undefined): SceneFrame {
+    return sceneFrame(normalizeTracks(node?.sceneTracks), 0);
+}
+
+/**
+ * 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.
+ */
+export function syncSceneAttributes(el: HTMLElement | null | undefined, node: SceneNodeSource | null | undefined): void {
+    if (!el?.setAttribute) return;
+    const attrs = sceneNodeAttributes(node);
+    for (const name of Object.values(SceneAttribute)) {
+        if (name in attrs) el.setAttribute(name, attrs[name]);
+        else el.removeAttribute(name);
+    }
+}
+
+/** Stamp a layer's first frame on its element (the component path, on the server too). */
+export function applySceneFirstFrame(el: HTMLElement | null | undefined, node: SceneNodeSource | null | undefined): void {
+    if (!el?.style) return;
+    for (const [name, value] of Object.entries(sceneFrameDeclarations(sceneFirstFrame(node)))) el.style.setProperty(name, value);
+}
+
+/**
+ * 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>`.
+ */
+export const SCENE_FLOW_RULES = `.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}`
+    + `[${SceneAttribute.Tracks}]{transform:none!important;opacity:1!important;clip-path:none!important}`;
+
+/** Under reduced motion the driver never starts, so the same rules hold for the whole visit. */
+export const SCENE_REDUCED_MOTION_CSS = `@media (prefers-reduced-motion: reduce){${SCENE_FLOW_RULES}}`;