@m0saic/templates 0.2.0

package/dist/m0saic/dsl-tutorial/v1/pipeline/buildSteps.js

@@ -0,0 +1,443 @@
+"use strict";
+/**
+ * ============================================================================
+ * dsl-tutorial — Step[] pipeline (CHARACTER-LEVEL parse model)
+ * ============================================================================
+ *
+ * The m0 DSL is parsed one CHARACTER at a time, and EVERY significant character
+ * is a real step that transforms the geometry cursor (X/Y/W/H) or emits a frame:
+ *
+ *   digit  `2`      — read a split count (no geometry change yet)
+ *   open   `(` `[`  — split the cursor into N children; cursor → first child
+ *                     (so W halves on a `(` 2-split, H divides on a `[` 3-split)
+ *   comma  `,`      — advance to the next sibling; cursor X (col) or Y (row) moves
+ *   leaf   `1` `F`  — EMIT a frame at the cursor (paints; no geometry change)
+ *   close  `)` `]`  — pop the split; cursor RESTORES to the parent region
+ *   pass   `0` `>`  — a passthrough slot (donates space; no paint)
+ *   null   `-`      — a reserved-but-empty slot
+ *   overlay`{` `}`  — change the overlay LAYER depth (Z); cursor unchanged
+ *
+ * Step 0 (before the first character) is the unparsed canvas — the root's own
+ * full rect. The cursor RECTS are pulled from the real parse tree (exact, so
+ * weighted/passthrough layouts are honest), keyed by source span; the character
+ * walk only drives the ORDER + which op each character performs.
+ *
+ * `Z` is the OVERLAY nesting depth (inside `{}`), NOT a logical/stack index —
+ * for a flat layout it stays 0 the whole walk.
+ *
+ * Pure function of (m0, width, height): same inputs → byte-identical `Step[]`.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countTokens = countTokens;
+exports.buildSteps = buildSteps;
+const dsl_1 = require("@m0saic/dsl");
+/** Count significant lexical tokens: each maximal digit-run is one token. */
+function countTokens(m0) {
+    let n = 0;
+    for (let i = 0; i < m0.length;) {
+        const ch = m0[i];
+        if (ch >= "0" && ch <= "9") {
+            n++;
+            i++;
+            while (i < m0.length && m0[i] >= "0" && m0[i] <= "9")
+                i++;
+            continue;
+        }
+        if ("()[]{},-F>".includes(ch))
+            n++;
+        i++;
+    }
+    return n;
+}
+/** Significant-symbol index (1-based) at a source offset — for the parse banner. */
+function symbolIndexAt(m0, offset) {
+    if (offset <= 0)
+        return 1;
+    return Math.max(1, countTokens(m0.slice(0, Math.min(offset, m0.length))));
+}
+const ZERO_RECT = { x: 0, y: 0, width: 0, height: 0 };
+const isDigit = (c) => c >= "0" && c <= "9";
+const rectOf = (f) => ({ x: f.x, y: f.y, width: f.width, height: f.height });
+const spanStart = (f) => (f.meta.span ? f.meta.span.start : 0);
+/** Interior divider fractions (0..1 of the region extent) between sorted children. */
+function dividersOf(node, children) {
+    const axis = node.axis;
+    if (!axis)
+        return [];
+    const origin = axis === "col" ? node.x : node.y;
+    const extent = axis === "col" ? node.width : node.height;
+    if (!(extent > 0))
+        return [];
+    const out = [];
+    for (let c = 0; c < children.length - 1; c++) {
+        const edge = axis === "col" ? children[c].x + children[c].width : children[c].y + children[c].height;
+        const frac = (edge - origin) / extent;
+        if (frac > 0.001 && frac < 0.999)
+            out.push(frac);
+    }
+    return out;
+}
+/** Build the ordered, character-level Step[] for an m0 layout at a canvas size. */
+function buildSteps(m0, width, height, _opts) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const s = String(m0);
+    const result = (0, dsl_1.parseM0StringComplete)(s, width, height, { trace: true });
+    if (!result.ok) {
+        throw new Error(`dsl-tutorial: m0 parse failed — ${(_b = (_a = result.error) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : "unknown"}`);
+    }
+    const editor = result.ir.editorFrames;
+    const nodeCount = editor.length;
+    const tokenCount = countTokens(s);
+    // R / C are the hidden engine state, computed from geometry in the walk below:
+    //  · R = the split's quantization remainder — leftover px when a region doesn't
+    //    divide evenly across its children (the resolved tiles absorb it, so it's
+    //    invisible in X/Y/W/H). Exact for uniform splits (the tutorial's main case).
+    //  · C = the passthrough carry — px a `0`/`>` donates forward, claimed by the
+    //    next tile.
+    const remainderOf = (node, count) => {
+        if (count <= 0 || !node.axis)
+            return 0;
+        const r = rectOf(node);
+        const ext = Math.round(node.axis === "col" ? r.width : r.height);
+        return ext % count;
+    };
+    // Index the parse tree by span start (split-node lookup) and parent (children).
+    const nodeBySpanStart = new Map();
+    const childrenByParent = new Map();
+    let root;
+    for (const f of editor) {
+        if (f.meta.span)
+            nodeBySpanStart.set(f.meta.span.start, f);
+        const p = f.meta.parentStableKey;
+        if (p) {
+            const list = (_c = childrenByParent.get(p)) !== null && _c !== void 0 ? _c : [];
+            list.push(f);
+            childrenByParent.set(p, list);
+        }
+        else if (!root) {
+            root = f;
+        }
+    }
+    // A child is an OVERLAY layer (not a split cell) when its own stableKey segment
+    // starts with `ov` (e.g. `r/ov1c0` for `…{F}`). Overlay children must NOT count
+    // toward split ARITY (`3(F,F,F){F}` is a 3-split, N=3 — the overlay is a Z layer,
+    // not a 4th column). They're still emitted as leaves via the post-`)` walk, so
+    // excluding them here only corrects the arity — never drops the overlay tile.
+    const isOverlayChild = (f) => {
+        var _a;
+        const k = (_a = f.meta.stableKey) !== null && _a !== void 0 ? _a : "";
+        return k.slice(k.lastIndexOf("/") + 1).startsWith("ov");
+    };
+    const sortedChildrenOf = (key) => {
+        var _a;
+        return ((_a = childrenByParent.get(key)) !== null && _a !== void 0 ? _a : [])
+            .filter((f) => !isOverlayChild(f))
+            .slice()
+            .sort((a, b) => spanStart(a) - spanStart(b));
+    };
+    // Classify each digit char: part of a split COUNT (followed by `(`/`[`) vs a
+    // leaf `1`. `countRunStart[i]` = where the count run begins (for split lookup).
+    const n = s.length;
+    const isCount = new Array(n).fill(false);
+    const countRunStart = new Array(n).fill(-1);
+    for (let i = 0; i < n;) {
+        if (isDigit(s[i])) {
+            let e = i;
+            while (e < n && isDigit(s[e]))
+                e++;
+            const next = e < n ? s[e] : "";
+            if (next === "(" || next === "[") {
+                for (let k = i; k < e; k++) {
+                    isCount[k] = true;
+                    countRunStart[k] = i;
+                }
+            }
+            i = e;
+        }
+        else
+            i++;
+    }
+    // ── Character walk ──
+    const rootRect = root ? rectOf(root) : ZERO_RECT;
+    const stack = [];
+    let cursor = rootRect;
+    let overlayDepth = 0;
+    let leafIdx = 0;
+    let prevRect = rootRect;
+    let prevZ = 0;
+    let prevN = 0;
+    let prevR = 0;
+    let prevC = 0;
+    // Arity / remainder of each split currently open (parallel to `stack`), so a
+    // count-read step shows that split's values and inner steps show the enclosing
+    // split's. `carryPx` is the running passthrough carry (donated px in flight).
+    // Each open split tracks its RUNNING remainder (`rem`, decremented as children
+    // claim leftover px), the floor extent (`floor`), and its axis — so R counts
+    // DOWN tile-by-tile instead of snapping to 0 at the split close.
+    const countStack = [];
+    const remainderStack = [];
+    let carryPx = 0;
+    /** Floor extent of a k-way split of `node` along its axis (px each child gets
+     *  before the remainder is sprinkled on). */
+    const floorOf = (node, count) => {
+        if (count <= 0 || !node.axis)
+            return 0;
+        const r = rectOf(node);
+        const ext = Math.round(node.axis === "col" ? r.width : r.height);
+        return Math.floor(ext / count);
+    };
+    /** The child currently under `cursor` claims its share of the enclosing split's
+     *  remainder: extra = cursorExtent − floor − (carry it absorbs). Decrements the
+     *  open split's running `rem` and returns the px claimed (0 if it sits on the
+     *  floor). Geometry-driven, so it's correct whichever children the engine fattened
+     *  — and the `carryAbsorbed` term keeps a passthrough donation from masquerading
+     *  as remainder. */
+    const claimRemainder = (carryAbsorbed) => {
+        const top = remainderStack[remainderStack.length - 1];
+        if (!top || top.rem <= 0)
+            return 0;
+        const childExt = Math.round(top.axis === "col" ? cursor.width : cursor.height);
+        const extra = childExt - top.floor - carryAbsorbed;
+        if (extra <= 0)
+            return 0;
+        const take = Math.min(extra, top.rem);
+        top.rem -= take;
+        return take;
+    };
+    const acc = {};
+    let prevAccSnapshot = {};
+    const diff = (before, after) => ({ before, after });
+    const steps = [];
+    for (let i = 0; i < n; i++) {
+        const ch = s[i];
+        if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r")
+            continue;
+        let eventType = "count";
+        let kind = "frame";
+        let stableKey = "";
+        let leafIndex;
+        let split;
+        let splitRegion;
+        let narration = "";
+        let readCount = null;
+        let readRemainder = null;
+        let readAxis;
+        let remainderClaim = 0;
+        let carryAbsorbed = 0;
+        if (isDigit(ch) && isCount[i]) {
+            eventType = "count";
+            const node = nodeBySpanStart.get(countRunStart[i]);
+            kind = (_d = node === null || node === void 0 ? void 0 : node.kind) !== null && _d !== void 0 ? _d : "group";
+            stableKey = (_e = node === null || node === void 0 ? void 0 : node.meta.stableKey) !== null && _e !== void 0 ? _e : "";
+            if (node === null || node === void 0 ? void 0 : node.axis) {
+                const kids = sortedChildrenOf(node.meta.stableKey).length;
+                readCount = kids;
+                readRemainder = remainderOf(node, kids);
+                readAxis = node.axis;
+                if (node.axis === "col")
+                    acc["grid.cols"] = kids;
+                else
+                    acc["grid.rows"] = kids;
+                narration = `Read split count — ${kids} ${node.axis === "col" ? "columns" : "rows"}.`;
+            }
+            else {
+                narration = "Read split count.";
+            }
+        }
+        else if (ch === "(" || ch === "[") {
+            eventType = "enter";
+            const cs = i > 0 && isCount[i - 1] ? countRunStart[i - 1] : i;
+            const node = nodeBySpanStart.get(cs);
+            const axis = (_f = node === null || node === void 0 ? void 0 : node.axis) !== null && _f !== void 0 ? _f : (ch === "(" ? "col" : "row");
+            if (node) {
+                const children = sortedChildrenOf(node.meta.stableKey);
+                stack.push({ node, children, idx: 0 });
+                countStack.push(children.length);
+                remainderStack.push({
+                    rem: remainderOf(node, children.length),
+                    floor: floorOf(node, children.length),
+                    axis,
+                });
+                if (children[0])
+                    cursor = rectOf(children[0]);
+                splitRegion = rectOf(node);
+                split = { axis, dividers: dividersOf(node, children) };
+                kind = node.kind;
+                stableKey = node.meta.stableKey;
+                narration = `Split into ${children.length} ${axis === "col" ? "columns" : "rows"}.`;
+            }
+        }
+        else if (ch === ")" || ch === "]") {
+            eventType = "exit";
+            const top = stack.pop();
+            countStack.pop();
+            const closed = remainderStack.pop();
+            if (top) {
+                cursor = rectOf(top.node);
+                kind = top.node.kind;
+                stableKey = top.node.meta.stableKey;
+            }
+            // Safety net: any remainder px not itemized to a leaf (e.g. absorbed by a
+            // nested split-child) is accounted for here so R never lingers past close.
+            const leftover = (_g = closed === null || closed === void 0 ? void 0 : closed.rem) !== null && _g !== void 0 ? _g : 0;
+            narration =
+                leftover > 0
+                    ? `Close split — ${leftover} remainder px absorbed by nested regions, restore the parent.`
+                    : "Close split — restore the parent region.";
+        }
+        else if (ch === ",") {
+            eventType = "sibling";
+            const top = stack[stack.length - 1];
+            if (top) {
+                top.idx++;
+                const c = top.children[top.idx];
+                if (c) {
+                    cursor = rectOf(c);
+                    kind = c.kind;
+                    stableKey = c.meta.stableKey;
+                }
+            }
+            narration = "Advance to the next sibling.";
+        }
+        else if (ch === "F" || (ch === "1" && !isCount[i])) {
+            eventType = "emitLeaf";
+            const top = stack[stack.length - 1];
+            const c = top ? top.children[top.idx] : undefined;
+            if (c) {
+                cursor = rectOf(c);
+                stableKey = c.meta.stableKey;
+            }
+            leafIndex = leafIdx++;
+            kind = "frame";
+            acc["tile.index"] = leafIndex;
+            acc["tile.w"] = cursor.width;
+            acc["tile.h"] = cursor.height;
+            // This tile claims any donated passthrough space in flight (C → 0) and its
+            // share of the split's quantization remainder (R counts down). Order matters:
+            // the carry it absorbs is netted out so a donation isn't miscounted as a
+            // remainder px.
+            carryAbsorbed = carryPx;
+            remainderClaim = claimRemainder(carryAbsorbed);
+            carryPx = 0;
+            narration =
+                `Emit tile ${leafIndex + 1} — ${cursor.width}×${cursor.height} at (${cursor.x}, ${cursor.y}).` +
+                    (carryAbsorbed > 0 ? ` Absorbs ${carryAbsorbed}px donated by a passthrough.` : "") +
+                    (remainderClaim > 0
+                        ? ` Claims ${remainderClaim} leftover remainder px (one of the fat tiles).`
+                        : "");
+        }
+        else if (ch === "0" || ch === ">") {
+            eventType = "passthrough";
+            const top = stack[stack.length - 1];
+            const c = top ? top.children[top.idx] : undefined;
+            if (c) {
+                cursor = rectOf(c);
+                stableKey = c.meta.stableKey;
+            }
+            kind = "passthrough";
+            // The parse tree's rect for a passthrough is CUMULATIVE: in a run of `>`s each
+            // one already holds every donation in flight before it, so its extent IS the
+            // carry — not an increment. (Adding it re-counted the run: the brand M's
+            // 136-column rows reported a 146,300px carry on a 1,920px canvas, and tiles
+            // "absorbing" 80,311px — 2026-09-05.) The carry already in flight is netted
+            // out of the remainder claim for the same reason: only THIS slot's own fat
+            // (remainder) px count, else they'd be claimed again by the receiving tile.
+            const carryBefore = carryPx;
+            remainderClaim = claimRemainder(carryBefore);
+            const cumulative = top ? (top.node.axis === "col" ? cursor.width : cursor.height) : 0;
+            const donated = Math.max(0, cumulative - carryBefore);
+            carryPx = Math.max(carryBefore, cumulative);
+            narration = `Passthrough — donate ${donated}px forward (carry now ${carryPx}px), claimed by the next tile.`;
+        }
+        else if (ch === "-") {
+            eventType = "null";
+            const top = stack[stack.length - 1];
+            const c = top ? top.children[top.idx] : undefined;
+            if (c) {
+                cursor = rectOf(c);
+                stableKey = c.meta.stableKey;
+            }
+            kind = "null";
+            remainderClaim = claimRemainder(0);
+            narration =
+                "Null slot — reserve space, paint nothing." +
+                    (remainderClaim > 0 ? ` (holds ${remainderClaim} remainder px)` : "");
+        }
+        else if (ch === "{") {
+            eventType = "overlay";
+            overlayDepth++;
+            kind = "group";
+            narration = `Open overlay layer ${overlayDepth}.`;
+        }
+        else if (ch === "}") {
+            eventType = "overlay";
+            overlayDepth = Math.max(0, overlayDepth - 1);
+            kind = "group";
+            narration = "Close overlay layer.";
+        }
+        else {
+            continue; // unknown punctuation — not a step
+        }
+        const z = overlayDepth;
+        // N = arity of the split in focus. A count-read step shows the count it just
+        // read (before the split is pushed); inner steps show the enclosing split's
+        // size; root (no split open) is 0.
+        const currentN = readCount != null ? readCount : countStack.length ? countStack[countStack.length - 1] : 0;
+        // Axis the arity refers to: the count just read, else the enclosing split's.
+        const axisInFocus = readAxis !== null && readAxis !== void 0 ? readAxis : (stack.length ? stack[stack.length - 1].node.axis : undefined);
+        // R mirrors N: a count-read shows that split's remainder; inner steps show the
+        // enclosing split's; root shows 0. C is the running passthrough carry balance.
+        const currentR = readRemainder != null
+            ? readRemainder
+            : remainderStack.length
+                ? remainderStack[remainderStack.length - 1].rem
+                : 0;
+        const currentC = carryPx;
+        const fields = {
+            X: diff(prevRect.x, cursor.x),
+            Y: diff(prevRect.y, cursor.y),
+            W: diff(prevRect.width, cursor.width),
+            H: diff(prevRect.height, cursor.height),
+            Z: diff(prevZ, z),
+            N: diff(prevN, currentN),
+            R: diff(prevR, currentR),
+            C: diff(prevC, currentC),
+        };
+        const accumulator = {};
+        for (const k of Object.keys(acc)) {
+            const before = k in prevAccSnapshot ? prevAccSnapshot[k] : null;
+            accumulator[k] = diff(before, acc[k]);
+        }
+        steps.push({
+            index: steps.length + 1,
+            total: 0, // filled after the walk
+            eventType,
+            charIndex: i,
+            kind,
+            stableKey,
+            leafIndex,
+            span: { start: i, end: i + 1 },
+            rect: { x: cursor.x, y: cursor.y, width: cursor.width, height: cursor.height },
+            fields,
+            accumulator,
+            narration,
+            tokenIndex: symbolIndexAt(s, i),
+            split,
+            splitRegion,
+            remainderClaim: remainderClaim > 0 ? remainderClaim : undefined,
+            carryAbsorbed: carryAbsorbed > 0 ? carryAbsorbed : undefined,
+            axisInFocus,
+        });
+        prevRect = cursor;
+        prevZ = z;
+        prevN = currentN;
+        prevR = currentR;
+        prevC = currentC;
+        prevAccSnapshot = { ...acc };
+    }
+    const total = steps.length;
+    for (const st of steps)
+        st.total = total;
+    return { m0: s, steps, tokenCount, nodeCount };
+}

package/dist/m0saic/dsl-tutorial/v1/pipeline/camera.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ============================================================================
+ * dsl-tutorial — canvas camera (follow the active tile)
+ * ============================================================================
+ *
+ * Turns the deterministic Step[] timeline into an `effects.camera` for the
+ * canvas panel: a fixed zoom plus an eased `focusX`/`focusY` that pans to
+ * center each tile as the geometry walk reaches it.
+ *
+ * The camera is ONE scale+crop on the finished canvas video (applied by the
+ * engine via {@link MosaicCamera}), so it is depth-independent — it follows the
+ * active tile identically whether the layout has 4 tiles or 400, which is the
+ * whole point of "panning the canvas" for large layouts.
+ *
+ * All motion is a single ffmpeg expression over global `t` (smoothstep between
+ * per-tile keyframes), so it stays frame-synced with the reveal + highlight.
+ * ============================================================================
+ */
+import type { Step } from "./buildSteps";
+import type { Timing } from "./timing";
+export type CameraSpec = {
+    zoom: number | string;
+    focusX: string;
+    focusY: string;
+};
+/**
+ * Pick the canvas zoom from LEGIBILITY, per the rule: if every tile already
+ * renders its number + dims well at fit-to-panel, don't zoom (return 1).
+ * Otherwise zoom just enough that the SMALLEST tile reaches a legible on-screen
+ * size — the minimum zoom, which keeps the most tiles visible while the walk
+ * pans across them.
+ *
+ * @param cellW/cellH  the canvas panel's pixel size (tiles are laid out within it).
+ */
+export declare function autoCanvasZoom(steps: Step[], parseW: number, parseH: number, cellW: number, cellH: number): number;
+/**
+ * Smoothstep piecewise interpolation through (t, v) keyframes → ffmpeg expr.
+ * Holds the first value before the first keyframe and the last value after the
+ * last, easing (ease-in-out) between adjacent keyframes.
+ *
+ * Emitted as a FLAT SUM of disjoint window-gated segments — NOT a nested
+ * if-else chain. ffmpeg's expression parser has a ~100 recursion budget and a
+ * nested chain consumes one level per keyframe, so a dense walk (10×10 = 100
+ * leaves) makes `crop` fail at config ("Missing ')' or too many args" →
+ * Invalid argument). The gates partition the timeline (`lt` head, half-open
+ * `gte·lt` segments, `gte` tail), so exactly one term is nonzero at any `t`.
+ * The engine rebalances the long `+` chain into a tree (applyCamera →
+ * rebalanceAdditiveChains), keeping parse depth O(log n).
+ */
+export declare function focusExpr(keys: {
+    t: number;
+    v: number;
+}[]): string;
+/**
+ * Build a follow-the-active-tile camera from the leaf steps, or `undefined` when
+ * `zoom ≤ 1` (no zoom → the canvas stays fit-to-panel, the M1a behavior).
+ *
+ * Keyframes are placed at each leaf's active-window CENTER so the camera is
+ * settled on the tile while its highlight is brightest, easing between.
+ *
+ * @param parseW/parseH  the dimensions the Step rects were parsed at (camera
+ *   focus is a fraction, so only the ratio matters — must match `buildSteps`).
+ */
+export declare function buildCanvasCamera(steps: Step[], timing: Timing, parseW: number, parseH: number, zoom: number): CameraSpec | undefined;

package/dist/m0saic/dsl-tutorial/v1/pipeline/camera.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * ============================================================================
+ * dsl-tutorial — canvas camera (follow the active tile)
+ * ============================================================================
+ *
+ * Turns the deterministic Step[] timeline into an `effects.camera` for the
+ * canvas panel: a fixed zoom plus an eased `focusX`/`focusY` that pans to
+ * center each tile as the geometry walk reaches it.
+ *
+ * The camera is ONE scale+crop on the finished canvas video (applied by the
+ * engine via {@link MosaicCamera}), so it is depth-independent — it follows the
+ * active tile identically whether the layout has 4 tiles or 400, which is the
+ * whole point of "panning the canvas" for large layouts.
+ *
+ * All motion is a single ffmpeg expression over global `t` (smoothstep between
+ * per-tile keyframes), so it stays frame-synced with the reveal + highlight.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoCanvasZoom = autoCanvasZoom;
+exports.focusExpr = focusExpr;
+exports.buildCanvasCamera = buildCanvasCamera;
+/** Min on-screen tile dimension (px) for its number + dims to paint legibly. */
+const LEGIBLE_TILE_PX = 104;
+/** Don't bother zooming for a sliver of legibility gain. */
+const MIN_WORTH_ZOOM = 1.05;
+/** Cap auto-zoom so even a pathologically dense layout keeps some context. */
+const MAX_AUTO_ZOOM = 4;
+/**
+ * Pick the canvas zoom from LEGIBILITY, per the rule: if every tile already
+ * renders its number + dims well at fit-to-panel, don't zoom (return 1).
+ * Otherwise zoom just enough that the SMALLEST tile reaches a legible on-screen
+ * size — the minimum zoom, which keeps the most tiles visible while the walk
+ * pans across them.
+ *
+ * @param cellW/cellH  the canvas panel's pixel size (tiles are laid out within it).
+ */
+function autoCanvasZoom(steps, parseW, parseH, cellW, cellH) {
+    if (parseW <= 0 || parseH <= 0 || cellW <= 0 || cellH <= 0)
+        return 1;
+    const leaves = steps.filter((s) => s.eventType === "emitLeaf");
+    if (leaves.length === 0)
+        return 1;
+    let minTilePx = Infinity;
+    let maxTileW = 0;
+    let maxTileH = 0;
+    for (const s of leaves) {
+        const pxW = (s.rect.width / parseW) * cellW;
+        const pxH = (s.rect.height / parseH) * cellH;
+        minTilePx = Math.min(minTilePx, pxW, pxH);
+        maxTileW = Math.max(maxTileW, s.rect.width);
+        maxTileH = Math.max(maxTileH, s.rect.height);
+    }
+    if (!(minTilePx > 0))
+        return 1;
+    // Never zoom past what FITS the biggest tile. At zoom z the viewport shows
+    // parseW/z × parseH/z of the canvas, so a tile wider/taller than that is
+    // clipped — and the walk to its side (e.g. passthroughs feeding a full-width
+    // hero) falls off-screen. Capping the legibility zoom to `fitZoom` keeps every
+    // tile fully on-screen; a full-bleed tile (maxTile == canvas) pins zoom to 1.
+    const fitZoom = Math.min(maxTileW > 0 ? parseW / maxTileW : Infinity, maxTileH > 0 ? parseH / maxTileH : Infinity);
+    const z = Math.min(LEGIBLE_TILE_PX / minTilePx, fitZoom);
+    if (z < MIN_WORTH_ZOOM)
+        return 1; // tiles already fit legibly (or a full-bleed tile) → no zoom
+    return Math.min(MAX_AUTO_ZOOM, z);
+}
+/**
+ * The `focus` value (0..1) that CENTERS a tile-center fraction `f` (0..1) in a
+ * `zoom`× crop window, clamped so the window never leaves the canvas.
+ *
+ * The camera crop window's center sits at fraction
+ *   ((zoom-1)/zoom)·focus + 1/(2·zoom)
+ * of the source; solving "= f" for focus gives the expression below. A tile at
+ * the very edge can't be perfectly centered without showing past the canvas, so
+ * the result is clamped to [0,1] (the camera bumps against the edge instead).
+ */
+function centerFocus(f, zoom) {
+    const v = (f * zoom - 0.5) / (zoom - 1);
+    return Math.max(0, Math.min(1, v));
+}
+/**
+ * Smoothstep piecewise interpolation through (t, v) keyframes → ffmpeg expr.
+ * Holds the first value before the first keyframe and the last value after the
+ * last, easing (ease-in-out) between adjacent keyframes.
+ *
+ * Emitted as a FLAT SUM of disjoint window-gated segments — NOT a nested
+ * if-else chain. ffmpeg's expression parser has a ~100 recursion budget and a
+ * nested chain consumes one level per keyframe, so a dense walk (10×10 = 100
+ * leaves) makes `crop` fail at config ("Missing ')' or too many args" →
+ * Invalid argument). The gates partition the timeline (`lt` head, half-open
+ * `gte·lt` segments, `gte` tail), so exactly one term is nonzero at any `t`.
+ * The engine rebalances the long `+` chain into a tree (applyCamera →
+ * rebalanceAdditiveChains), keeping parse depth O(log n).
+ */
+function focusExpr(keys) {
+    const f = (n) => n.toFixed(5);
+    if (keys.length === 0)
+        return "0.5";
+    if (keys.length === 1)
+        return f(keys[0].v);
+    const terms = [];
+    terms.push(`lt(t,${f(keys[0].t)})*(${f(keys[0].v)})`); // hold first value
+    for (let i = 0; i < keys.length - 1; i++) {
+        const a = keys[i];
+        const b = keys[i + 1];
+        const dur = Math.max(1e-4, b.t - a.t);
+        const p = `min(1,max(0,(t-${f(a.t)})/${f(dur)}))`;
+        const sp = `(${p})*(${p})*(3-2*(${p}))`; // smoothstep
+        const lerp = `(${f(a.v)}+(${f(b.v)}-${f(a.v)})*${sp})`;
+        terms.push(`(gte(t,${f(a.t)})*lt(t,${f(b.t)}))*${lerp}`);
+    }
+    terms.push(`gte(t,${f(keys[keys.length - 1].t)})*(${f(keys[keys.length - 1].v)})`); // hold last
+    return terms.join("+");
+}
+/**
+ * Build a follow-the-active-tile camera from the leaf steps, or `undefined` when
+ * `zoom ≤ 1` (no zoom → the canvas stays fit-to-panel, the M1a behavior).
+ *
+ * Keyframes are placed at each leaf's active-window CENTER so the camera is
+ * settled on the tile while its highlight is brightest, easing between.
+ *
+ * @param parseW/parseH  the dimensions the Step rects were parsed at (camera
+ *   focus is a fraction, so only the ratio matters — must match `buildSteps`).
+ */
+function buildCanvasCamera(steps, timing, parseW, parseH, zoom) {
+    if (!(zoom > 1) || parseW <= 0 || parseH <= 0)
+        return undefined;
+    // Keyframe on tiles AND passthroughs so the camera FOLLOWS the walk through the
+    // donating `>` slots too — otherwise it pre-centers on the next EMITTED tile and
+    // the passthroughs (to the side of a wide absorber) walk by off-screen.
+    const leaves = steps
+        .filter((s) => s.eventType === "emitLeaf" || s.eventType === "passthrough")
+        .sort((a, b) => a.index - b.index);
+    if (leaves.length === 0)
+        return undefined;
+    const xs = [];
+    const ys = [];
+    let lastSettle = 0;
+    for (const s of leaves) {
+        const t = timing.stepStartSec(s.index) + timing.stepDurSec / 2;
+        const fx = (s.rect.x + s.rect.width / 2) / parseW;
+        const fy = (s.rect.y + s.rect.height / 2) / parseH;
+        xs.push({ t, v: centerFocus(fx, zoom) });
+        ys.push({ t, v: centerFocus(fy, zoom) });
+        lastSettle = t;
+    }
+    // FINAL pull-back: once the last tile has painted, ease zoom → 1 and focus →
+    // center over the tail so the whole layout is revealed at the end. The engine
+    // scale is rounded to EVEN every frame (applyCamera), so the per-frame `crop`
+    // reinitialises cleanly as the (animated) zoom shrinks. At zoom 1 the crop offset
+    // resolves to 0 → the full frame.
+    const endT = timing.durationMs / 1000;
+    const revealLast = timing.stepStartSec(leaves[leaves.length - 1].index); // last tile appears
+    const settleOut = Math.min(lastSettle + timing.stepDurSec / 2, endT);
+    // End on a deliberate HOLD of the full layout: ease to full view (zoom 1,
+    // centered) by `zoomEndT`, then hold it to `endT`. Target ~`HOLD_TARGET`s of
+    // hold and fit it into the tail after the last tile — the pull-back never
+    // begins before the last tile is on screen (`revealLast`), so the hold is as
+    // long as the tail allows. The walk's closing exit steps happen under the
+    // (already-moving) pull-back, which is why the hold can outlast a short trail.
+    const HOLD_TARGET = 2.0;
+    const outStart = Math.max(revealLast, Math.min(settleOut, endT - HOLD_TARGET - 0.6));
+    const zoomEndT = Math.min(endT, Math.max(outStart + 0.3, endT - HOLD_TARGET));
+    if (endT > outStart + 1e-3) {
+        xs.push({ t: outStart, v: xs[xs.length - 1].v }); // hold the last focus, then…
+        ys.push({ t: outStart, v: ys[ys.length - 1].v });
+        xs.push({ t: zoomEndT, v: 0.5 }); // …pan to center by zoomEndT; focusExpr then
+        ys.push({ t: zoomEndT, v: 0.5 }); //    tail-HOLDS center (0.5) from zoomEndT → endT
+    }
+    // Zoom holds at `zoom` through the walk, eases to 1 by `zoomEndT`, then the last
+    // keyframe's value (1) tail-holds through the end hold. No tail → hold `zoom`.
+    const zoomExpr = endT > outStart + 1e-3
+        ? focusExpr([{ t: outStart, v: zoom }, { t: zoomEndT, v: 1 }])
+        : focusExpr([{ t: outStart, v: zoom }]);
+    return { zoom: zoomExpr, focusX: focusExpr(xs), focusY: focusExpr(ys) };
+}