@m0saic/templates 0.2.0

package/dist/m0saic/media/scroll_wall/v1/geometry.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Scroll Wall v1 — lattice geometry.
+ *
+ * The wall's motion (`motion.ts`) subtracts a `baseX` computed BEFORE
+ * placement, so every rect is placed with `drift: "exact"` — any drift would
+ * desync every clip. Locking exact makes the precision floor
+ * `gcd(all edges, canvas)`, which collapses to 1 on an unquantized gap and
+ * explodes the m0 (measured up to ~24k chars at 997×720 in the step-0
+ * prototype). Hence the lattice: every geometry number is picked on a
+ * DIVISOR of the canvas dimension (`q | canvasW`, `qy | canvasH`), then
+ * locked exact. On a prime-ish canvas the quantum falls to 1 — the geometry
+ * stays correct (warning-only, surfaced via the geometry-contract floors
+ * under `debugGeometry`), it just costs precision.
+ *
+ * Deriving `pitch` from the CANVAS (never from the asset aspect) also avoids
+ * the hard throw in `placeOptimizedRects` when `r.x + r.w > rootW`.
+ *
+ * The two axes are deliberately factored as SCROLL axis vs CROSS axis (not
+ * x vs y) so a vertical-scroll v2 can reuse both helpers unchanged.
+ */
+/** Scroll-axis lattice: the tile comb the clips travel along. */
+export type ScrollAxisLattice = {
+    /** Lattice quantum — the largest divisor of `axisLen` that is ≤ the requested gap. */
+    q: number;
+    /** Achieved inter-tile gap (a `q`-multiple, ≥ 1 — see the seam note below). */
+    gapPx: number;
+    /** Tile pitch = cell + gap. Divides the strip period. */
+    pitch: number;
+    /** Painted cell size along the scroll axis (`pitch - gapPx`). */
+    cellPx: number;
+    /** DSL footprints across the canvas: distinct `baseX` slots the tiles cycle through. */
+    slots: number;
+    /** K = min tiles covering the axis (`ceil(axisLen / pitch)`). */
+    coverCount: number;
+    /** Minimum slot count for gap-free coverage at every t (= K + 1). */
+    minSlotCount: number;
+};
+/** Cross-axis bands: uniform rows (or columns for a vertical v2). */
+export type CrossAxisBands = {
+    /** Lattice quantum — the largest divisor of `axisLen` ≤ the requested gap. */
+    q: number;
+    /** Achieved inter-band gap (a `q`-multiple). */
+    gapPx: number;
+    /** Uniform band size (a `q`-multiple). */
+    bandPx: number;
+    /** Band start offsets, one per band, ascending. */
+    bandStarts: number[];
+    /** Slack before the first band (≥ the snapped margin; a `q`-multiple). */
+    leadPx: number;
+    /** Slack after the last band. */
+    trailPx: number;
+};
+/** The template-facing bundle, in the plan's vocabulary. */
+export type ScrollWallGeometry = {
+    canvasW: number;
+    canvasH: number;
+    rows: number;
+    visibleCount: number;
+    /** X lattice quantum (`q | canvasW`). */
+    q: number;
+    /** Y lattice quantum (`qy | canvasH`). */
+    qy: number;
+    gapX: number;
+    gapY: number;
+    pitch: number;
+    cellW: number;
+    slots: number;
+    /** K. */
+    coverCount: number;
+    /** K + 1 — the slot-count floor. */
+    minSlotCount: number;
+    rowH: number;
+    /** Top y of each row, ascending. */
+    rowYs: number[];
+    topPad: number;
+    bottomPad: number;
+};
+export type ScrollWallGeometryResult = {
+    ok: true;
+    geometry: ScrollWallGeometry;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The floor below which a tile stops being a tile.
+ *
+ * The look knobs thin themselves to fit (see `scrollAxisLattice` /
+ * `crossAxisBands`), which means the geometry no longer runs out of room — it
+ * runs out of MEANING first: 12 visible tiles across a 100px axis is arithmetic
+ * that succeeds and a wall nobody can watch. So the honest failure moved here.
+ * On the scroll axis it is soft — the template's `fitVisibleCount` walks the
+ * tile count down until the tiles clear it. On the cross axis it is hard:
+ * `rows` is the caller's ask, not a look knob, so 4 rows on a 180px canvas is
+ * told it is 4 rows on a 180px canvas.
+ */
+export declare const MIN_TILE_PX = 24;
+/** Largest divisor of `n` that is ≤ `cap` (cap clamped to ≥ 1, so always ≥ 1). */
+export declare function largestDivisorAtMost(n: number, cap: number): number;
+/**
+ * Scroll-axis lattice. The seam: the wrap hands a tile off at
+ * `absX = -pitch`, where it spans `[-pitch, -gapPx)` — fully off-screen with
+ * `gapPx` px of slack. That requires `gapPx ≥ 1`, so a truly flush zero-gap
+ * wall is not supported (the requested gap has a floor of 1, which snaps up
+ * to `q` px).
+ */
+export declare function scrollAxisLattice(axisLen: number, visibleCount: number, requestedGapPx: number): ScrollAxisLattice | {
+    error: string;
+};
+/**
+ * Cross-axis uniform bands, cumulative-boundary style (screencap-grid v2's
+ * `computeGridTileRects` sibling) on its own quantum `q | axisLen`. The
+ * requested margin snaps to the NEAREST lattice point, then down to whatever
+ * still leaves every band a pixel; band size is the largest
+ * `q`-multiple fitting `bands` uniform bands + gaps inside it; the remaining
+ * slack (a `q`-multiple by construction, since `q | axisLen` and every used
+ * span is a `q`-multiple) splits lead/trail with the lead floored to the
+ * lattice — so every band edge stays a `q`-multiple.
+ */
+export declare function crossAxisBands(axisLen: number, bands: number, requestedGapPx: number, requestedMarginPx: number): CrossAxisBands | {
+    error: string;
+};
+/** The full wall geometry (horizontal scroll: x = scroll axis, y = cross axis). */
+export declare function computeScrollWallGeometry(args: {
+    canvasW: number;
+    canvasH: number;
+    visibleCount: number;
+    rows: number;
+    gapPx: number;
+    marginPx: number;
+}): ScrollWallGeometryResult;

package/dist/m0saic/media/scroll_wall/v1/geometry.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Scroll Wall v1 — lattice geometry.
+ *
+ * The wall's motion (`motion.ts`) subtracts a `baseX` computed BEFORE
+ * placement, so every rect is placed with `drift: "exact"` — any drift would
+ * desync every clip. Locking exact makes the precision floor
+ * `gcd(all edges, canvas)`, which collapses to 1 on an unquantized gap and
+ * explodes the m0 (measured up to ~24k chars at 997×720 in the step-0
+ * prototype). Hence the lattice: every geometry number is picked on a
+ * DIVISOR of the canvas dimension (`q | canvasW`, `qy | canvasH`), then
+ * locked exact. On a prime-ish canvas the quantum falls to 1 — the geometry
+ * stays correct (warning-only, surfaced via the geometry-contract floors
+ * under `debugGeometry`), it just costs precision.
+ *
+ * Deriving `pitch` from the CANVAS (never from the asset aspect) also avoids
+ * the hard throw in `placeOptimizedRects` when `r.x + r.w > rootW`.
+ *
+ * The two axes are deliberately factored as SCROLL axis vs CROSS axis (not
+ * x vs y) so a vertical-scroll v2 can reuse both helpers unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_TILE_PX = void 0;
+exports.largestDivisorAtMost = largestDivisorAtMost;
+exports.scrollAxisLattice = scrollAxisLattice;
+exports.crossAxisBands = crossAxisBands;
+exports.computeScrollWallGeometry = computeScrollWallGeometry;
+/**
+ * The floor below which a tile stops being a tile.
+ *
+ * The look knobs thin themselves to fit (see `scrollAxisLattice` /
+ * `crossAxisBands`), which means the geometry no longer runs out of room — it
+ * runs out of MEANING first: 12 visible tiles across a 100px axis is arithmetic
+ * that succeeds and a wall nobody can watch. So the honest failure moved here.
+ * On the scroll axis it is soft — the template's `fitVisibleCount` walks the
+ * tile count down until the tiles clear it. On the cross axis it is hard:
+ * `rows` is the caller's ask, not a look knob, so 4 rows on a 180px canvas is
+ * told it is 4 rows on a 180px canvas.
+ */
+exports.MIN_TILE_PX = 24;
+/** Largest divisor of `n` that is ≤ `cap` (cap clamped to ≥ 1, so always ≥ 1). */
+function largestDivisorAtMost(n, cap) {
+    const c = Math.max(1, Math.min(Math.floor(cap), n));
+    for (let d = c; d >= 2; d--) {
+        if (n % d === 0)
+            return d;
+    }
+    return 1;
+}
+/**
+ * Scroll-axis lattice. The seam: the wrap hands a tile off at
+ * `absX = -pitch`, where it spans `[-pitch, -gapPx)` — fully off-screen with
+ * `gapPx` px of slack. That requires `gapPx ≥ 1`, so a truly flush zero-gap
+ * wall is not supported (the requested gap has a floor of 1, which snaps up
+ * to `q` px).
+ */
+function scrollAxisLattice(axisLen, visibleCount, requestedGapPx) {
+    // Bound the gap BEFORE it picks the quantum. `q` is the largest divisor of
+    // the axis that fits the gap, so an over-large gap on a short axis chooses a
+    // quantum near the whole canvas (96px asked of 320px picks q=80) and then
+    // every geometry number has to be a multiple of it — which is what actually
+    // makes those canvases infeasible, not the gap itself. Halving the per-tile
+    // share first keeps the lattice fine enough to lay the wall out.
+    const gapCeiling = Math.max(1, Math.floor(axisLen / (2 * Math.max(1, visibleCount))));
+    const q = largestDivisorAtMost(axisLen, Math.min(Math.max(1, requestedGapPx), gapCeiling));
+    const pitch = q * Math.floor(axisLen / (visibleCount * q));
+    // The gap is a LOOK knob and a SEPARATOR: it never takes more than half the
+    // pitch, so a gap wider than the tiles it separates thins to the widest
+    // lattice multiple that leaves the tile the larger half, instead of refusing
+    // the wall. (Thinning only to "the cell survives" would hand back 1px tiles
+    // on a hostile canvas — a render, but not a wall.) What stays an error is a
+    // pitch too small for even one quantum of gap; the template's
+    // `fitVisibleCount` answers that by asking for fewer, bigger tiles.
+    const maxGapQ = Math.floor(pitch / (2 * q));
+    const gapPx = q * Math.max(1, Math.min(Math.floor(Math.max(1, requestedGapPx) / q), maxGapQ));
+    const cellPx = pitch - gapPx;
+    if (cellPx < exports.MIN_TILE_PX) {
+        return {
+            error: `axis ${axisLen}px cannot fit ${visibleCount} visible tile(s) with a ${gapPx}px gap ` +
+                `(tile would be ${cellPx}px, under the ${exports.MIN_TILE_PX}px floor).`,
+        };
+    }
+    const slots = Math.floor((axisLen - cellPx) / pitch) + 1;
+    const coverCount = Math.ceil(axisLen / pitch);
+    return {
+        q,
+        gapPx,
+        pitch,
+        cellPx,
+        slots,
+        coverCount,
+        minSlotCount: coverCount + 1,
+    };
+}
+/**
+ * Cross-axis uniform bands, cumulative-boundary style (screencap-grid v2's
+ * `computeGridTileRects` sibling) on its own quantum `q | axisLen`. The
+ * requested margin snaps to the NEAREST lattice point, then down to whatever
+ * still leaves every band a pixel; band size is the largest
+ * `q`-multiple fitting `bands` uniform bands + gaps inside it; the remaining
+ * slack (a `q`-multiple by construction, since `q | axisLen` and every used
+ * span is a `q`-multiple) splits lead/trail with the lead floored to the
+ * lattice — so every band edge stays a `q`-multiple.
+ */
+function crossAxisBands(axisLen, bands, requestedGapPx, requestedMarginPx) {
+    // Same pre-bound as the scroll axis: an over-large row gap would otherwise
+    // pick a quantum near half the canvas and leave no room for the bands.
+    const gapCeiling = Math.max(1, Math.floor(axisLen / (2 * Math.max(1, bands))));
+    const askedGapPx = Math.min(Math.max(1, requestedGapPx), gapCeiling);
+    const q = largestDivisorAtMost(axisLen, askedGapPx);
+    const gapPx = bands > 1 ? q * Math.max(1, Math.floor(askedGapPx / q)) : 0;
+    // The margin is a LOOK knob under the same rule as the gap: the two margins
+    // together never take more than half the axis, so 200px of margin on a 360px
+    // canvas thins to fit instead of refusing the wall — a slider at its stop is
+    // not an error. What survives as an error is the ask no margin rescues: more
+    // bands than the axis has room for.
+    const roomForBands = Math.max(bands * q, Math.floor(axisLen / 2));
+    const maxMarginQ = Math.max(0, Math.floor((axisLen - (bands - 1) * gapPx - roomForBands) / (2 * q)));
+    const marginPx = q * Math.min(Math.round(Math.max(0, requestedMarginPx) / q), maxMarginQ);
+    const avail = axisLen - 2 * marginPx - (bands - 1) * gapPx;
+    const bandPx = q * Math.floor(avail / (bands * q));
+    if (bandPx < exports.MIN_TILE_PX) {
+        return {
+            error: `axis ${axisLen}px cannot fit ${bands} band(s) with a ${gapPx}px gap ` +
+                `(band would be ${bandPx}px, under the ${exports.MIN_TILE_PX}px floor).`,
+        };
+    }
+    const used = bands * bandPx + (bands - 1) * gapPx;
+    const slack = axisLen - used; // ≡ 0 (mod q), ≥ 2·marginPx
+    // Floored to the lattice; ≥ marginPx because marginPx is a q-multiple and
+    // slack ≥ 2·marginPx.
+    const leadPx = q * Math.floor(slack / (2 * q));
+    const bandStarts = Array.from({ length: bands }, (_, r) => leadPx + r * (bandPx + gapPx));
+    return { q, gapPx, bandPx, bandStarts, leadPx, trailPx: axisLen - (leadPx + used) };
+}
+/** The full wall geometry (horizontal scroll: x = scroll axis, y = cross axis). */
+function computeScrollWallGeometry(args) {
+    const { canvasW, canvasH, visibleCount, rows, gapPx, marginPx } = args;
+    if (!Number.isInteger(canvasW) || canvasW < 1 || !Number.isInteger(canvasH) || canvasH < 1) {
+        return { ok: false, error: `canvas ${canvasW}x${canvasH} is not a positive integer size.` };
+    }
+    const x = scrollAxisLattice(canvasW, visibleCount, gapPx);
+    if ("error" in x) {
+        return { ok: false, error: `Canvas too small for visibleCount=${visibleCount}: ${x.error}` };
+    }
+    const y = crossAxisBands(canvasH, rows, gapPx, marginPx);
+    if ("error" in y) {
+        return { ok: false, error: `Canvas too small for rows=${rows}: ${y.error}` };
+    }
+    return {
+        ok: true,
+        geometry: {
+            canvasW,
+            canvasH,
+            rows,
+            visibleCount,
+            q: x.q,
+            qy: y.q,
+            gapX: x.gapPx,
+            gapY: y.gapPx,
+            pitch: x.pitch,
+            cellW: x.cellPx,
+            slots: x.slots,
+            coverCount: x.coverCount,
+            minSlotCount: x.minSlotCount,
+            rowH: y.bandPx,
+            rowYs: y.bandStarts,
+            topPad: y.leadPx,
+            bottomPad: y.trailPx,
+        },
+    };
+}

package/dist/m0saic/media/scroll_wall/v1/index.d.ts

@@ -0,0 +1 @@
+export { ScrollWallV1, type ScrollWallProps } from "./scroll-wall";

package/dist/m0saic/media/scroll_wall/v1/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScrollWallV1 = void 0;
+var scroll_wall_1 = require("./scroll-wall");
+Object.defineProperty(exports, "ScrollWallV1", { enumerable: true, get: function () { return scroll_wall_1.ScrollWallV1; } });

package/dist/m0saic/media/scroll_wall/v1/motion.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Scroll Wall v1 — the per-tile `overlay.xExpr` motion algebra.
+ *
+ * `overlay.xExpr` is an OFFSET added to the cell's DSL x (the engine emits
+ * `x='(baseX)+(xExpr)'`), so each tile's expression carries its phase plus
+ * the shared scroll, and the absolute position collapses to
+ *
+ *   absX_i(t) = mod(C_i ± v·t, P) - pitch        (floor-mod, range [-pitch, P-pitch))
+ *
+ * Why each piece exists:
+ *
+ * - **`-pitch` (the origin shift) is load-bearing.** ffmpeg's `mod` returns
+ *   `[0, P)`, so without it a clip could never leave the LEFT edge — it would
+ *   land flush at `x = 0`, fully visible, and teleport once per period.
+ *   Shifting by `pitch` (not `cellW`) puts the wrap handoff `gapX` px past
+ *   fully-off-screen.
+ * - **The bias costs nothing.** For left-moving rows it folds into the integer
+ *   literal `C_i`, making the mod argument provably ≥ 0 for every rendered t —
+ *   the emitted string shape is identical and the template is correct under
+ *   either mod convention (ffmpeg's is floor-mod; verified on the pinned
+ *   toolchain: mod(-30,100)=70).
+ * - **All-integer constants, no `w`/`W`.** Baking pixels avoids any dependence
+ *   on the engine's macro-substitution order.
+ *
+ * The emitted shape is ~5 additive terms, far under the ~99-term expression
+ * parse cliff, so no `rebalanceAdditiveChains` call is needed. If you ever add
+ * terms here, import it from `@m0saic/platform/ffexpr` and wrap the result
+ * (precedent: `meta/camera-debug/v1`).
+ *
+ * "Seamless" means POSITION-CONTINUOUS across the loop point, not
+ * frame-identical: the last rendered frame sits at `(N-1)/fps`, one frame
+ * BEFORE the period closes, so `frame[0]` and `frame[N-1]` differ by exactly
+ * `v/fps` px — correct, and the loop plays through with no jump. Assert
+ * `absX(0) == absX(N/fps)`; never assert frame equality. Clip CONTENT runs on
+ * the global clock and does not loop with the positions.
+ */
+/** Everything shared by all tiles of one row. */
+export type ScrollMotionParams = {
+    /** DSL footprints across the canvas — `baseX_i = (i mod slots) * pitch`. */
+    slots: number;
+    /** Tile pitch (px). */
+    pitch: number;
+    /** Strip period `P = slotCount * pitch` (px). */
+    period: number;
+    /** Row phase in `[0, pitch)` (px) — see {@link rowPhasePx}. */
+    phasePx: number;
+    /** -1 = leftward travel, +1 = rightward. */
+    sign: -1 | 1;
+    /** Exact scroll velocity (px/sec) — see {@link resolveSpeedPxPerSec}. */
+    pxPerSec: number;
+    /** Render duration (sec) — sizes the left-direction non-negativity bias. */
+    durationSec: number;
+};
+/** Floor-mod (result in `[0, b)` for `b > 0`) — ffmpeg's `mod` convention. */
+export declare function floorMod(a: number, b: number): number;
+/**
+ * Resolve the exact scroll velocity in px/sec.
+ *
+ * In `"cycles"` mode the velocity comes from the FRAME COUNT, not the wall
+ * duration: frames sit at `t = k/fps`, so the strip must travel `cycles·P`
+ * over `N = round(durationMs/1000 · fps)` frames — `v = cycles·P·fps/N`.
+ * (Identical to `cycles·P/durationSec` when `durationMs·fps/1000` is whole;
+ * correct when it isn't.) Whole-number `cycles` values loop seamlessly.
+ *
+ * `snapVelocityToFrameGrid` rounds to an integer px/frame, killing the ±1px
+ * truncation jitter at the cost of exact seamlessness — default off.
+ */
+export declare function resolveSpeedPxPerSec(args: {
+    speedMode: "cycles" | "pxPerSec";
+    cycles: number;
+    pxPerSec: number;
+    period: number;
+    fps: number;
+    durationMs: number;
+    snapVelocityToFrameGrid: boolean;
+}): number;
+/** Per-row travel direction: base sign from `direction`, flipped on odd rows when alternating. */
+export declare function rowDirectionSign(direction: "left" | "right", row: number, alternateRowDirection: boolean): -1 | 1;
+/**
+ * Per-row phase in `[0, pitch)`. `rowOffsetFrac` is a fraction of PITCH, not
+ * of the period — a phase of `k·pitch` merely relabels which clip sits where
+ * (positions are pitch-multiples mod P), so only a sub-pitch phase actually
+ * breaks vertical column alignment.
+ */
+export declare function rowPhasePx(rowOffsetFrac: number, row: number, pitch: number): number;
+/**
+ * The emitted `overlay.xExpr` for tile `i` — one shape for both directions:
+ * `mod(C±v*t,P)-SUB` with `SUB_i = pitch + (i mod slots)·pitch` (the engine
+ * adds `baseX_i = (i mod slots)·pitch` back, collapsing to `mod(...) - pitch`).
+ */
+export declare function buildScrollXExpr(p: ScrollMotionParams, tileIndex: number): string;
+/**
+ * Independent floor-mod reference model for tile `i`'s ABSOLUTE x at time
+ * `t` (i.e. after the engine adds `baseX_i`). Tests prove string ≡ model
+ * without rendering.
+ */
+export declare function scrollAbsX(p: ScrollMotionParams, tileIndex: number, t: number): number;
+/** The parsed pieces of one emitted expression. */
+export type ParsedScrollXExpr = {
+    c: number;
+    sign: -1 | 1;
+    pxPerSec: number;
+    period: number;
+    sub: number;
+};
+/** Parse the one expression shape this template emits. Throws on any other. */
+export declare function parseScrollXExpr(expr: string): ParsedScrollXExpr;
+/**
+ * Evaluate an emitted expression at time `t` exactly as ffmpeg's overlay
+ * evaluator would (floor-mod) — this is the OFFSET the engine adds to the
+ * cell's `baseX`. `evalScrollXExpr(expr, t) + baseX` must equal
+ * {@link scrollAbsX} for the same tile.
+ */
+export declare function evalScrollXExpr(expr: string, t: number): number;

package/dist/m0saic/media/scroll_wall/v1/motion.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * Scroll Wall v1 — the per-tile `overlay.xExpr` motion algebra.
+ *
+ * `overlay.xExpr` is an OFFSET added to the cell's DSL x (the engine emits
+ * `x='(baseX)+(xExpr)'`), so each tile's expression carries its phase plus
+ * the shared scroll, and the absolute position collapses to
+ *
+ *   absX_i(t) = mod(C_i ± v·t, P) - pitch        (floor-mod, range [-pitch, P-pitch))
+ *
+ * Why each piece exists:
+ *
+ * - **`-pitch` (the origin shift) is load-bearing.** ffmpeg's `mod` returns
+ *   `[0, P)`, so without it a clip could never leave the LEFT edge — it would
+ *   land flush at `x = 0`, fully visible, and teleport once per period.
+ *   Shifting by `pitch` (not `cellW`) puts the wrap handoff `gapX` px past
+ *   fully-off-screen.
+ * - **The bias costs nothing.** For left-moving rows it folds into the integer
+ *   literal `C_i`, making the mod argument provably ≥ 0 for every rendered t —
+ *   the emitted string shape is identical and the template is correct under
+ *   either mod convention (ffmpeg's is floor-mod; verified on the pinned
+ *   toolchain: mod(-30,100)=70).
+ * - **All-integer constants, no `w`/`W`.** Baking pixels avoids any dependence
+ *   on the engine's macro-substitution order.
+ *
+ * The emitted shape is ~5 additive terms, far under the ~99-term expression
+ * parse cliff, so no `rebalanceAdditiveChains` call is needed. If you ever add
+ * terms here, import it from `@m0saic/platform/ffexpr` and wrap the result
+ * (precedent: `meta/camera-debug/v1`).
+ *
+ * "Seamless" means POSITION-CONTINUOUS across the loop point, not
+ * frame-identical: the last rendered frame sits at `(N-1)/fps`, one frame
+ * BEFORE the period closes, so `frame[0]` and `frame[N-1]` differ by exactly
+ * `v/fps` px — correct, and the loop plays through with no jump. Assert
+ * `absX(0) == absX(N/fps)`; never assert frame equality. Clip CONTENT runs on
+ * the global clock and does not loop with the positions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.floorMod = floorMod;
+exports.resolveSpeedPxPerSec = resolveSpeedPxPerSec;
+exports.rowDirectionSign = rowDirectionSign;
+exports.rowPhasePx = rowPhasePx;
+exports.buildScrollXExpr = buildScrollXExpr;
+exports.scrollAbsX = scrollAbsX;
+exports.parseScrollXExpr = parseScrollXExpr;
+exports.evalScrollXExpr = evalScrollXExpr;
+/** Floor-mod (result in `[0, b)` for `b > 0`) — ffmpeg's `mod` convention. */
+function floorMod(a, b) {
+    return ((a % b) + b) % b;
+}
+/**
+ * Resolve the exact scroll velocity in px/sec.
+ *
+ * In `"cycles"` mode the velocity comes from the FRAME COUNT, not the wall
+ * duration: frames sit at `t = k/fps`, so the strip must travel `cycles·P`
+ * over `N = round(durationMs/1000 · fps)` frames — `v = cycles·P·fps/N`.
+ * (Identical to `cycles·P/durationSec` when `durationMs·fps/1000` is whole;
+ * correct when it isn't.) Whole-number `cycles` values loop seamlessly.
+ *
+ * `snapVelocityToFrameGrid` rounds to an integer px/frame, killing the ±1px
+ * truncation jitter at the cost of exact seamlessness — default off.
+ */
+function resolveSpeedPxPerSec(args) {
+    const { speedMode, cycles, pxPerSec, period, fps, durationMs, snapVelocityToFrameGrid } = args;
+    const totalFrames = Math.max(1, Math.round((durationMs / 1000) * fps));
+    let v = speedMode === "pxPerSec" ? pxPerSec : (cycles * period * fps) / totalFrames;
+    if (snapVelocityToFrameGrid) {
+        v = Math.max(1, Math.round(v / fps)) * fps;
+    }
+    return v;
+}
+/** Per-row travel direction: base sign from `direction`, flipped on odd rows when alternating. */
+function rowDirectionSign(direction, row, alternateRowDirection) {
+    const base = direction === "right" ? 1 : -1;
+    return (alternateRowDirection && row % 2 === 1 ? -base : base);
+}
+/**
+ * Per-row phase in `[0, pitch)`. `rowOffsetFrac` is a fraction of PITCH, not
+ * of the period — a phase of `k·pitch` merely relabels which clip sits where
+ * (positions are pitch-multiples mod P), so only a sub-pitch phase actually
+ * breaks vertical column alignment.
+ */
+function rowPhasePx(rowOffsetFrac, row, pitch) {
+    return floorMod(Math.round(rowOffsetFrac * row * pitch), pitch);
+}
+/** Left-direction bias: folds into C so the mod argument stays ≥ 0 for all rendered t. */
+function biasPx(p) {
+    return p.sign < 0 ? p.period * (Math.ceil((p.pxPerSec * p.durationSec) / p.period) + 1) : 0;
+}
+/** The integer phase constant `C_i` for tile `i` of a row. */
+function phaseConstant(p, tileIndex) {
+    return tileIndex * p.pitch + p.phasePx + biasPx(p);
+}
+/**
+ * The emitted `overlay.xExpr` for tile `i` — one shape for both directions:
+ * `mod(C±v*t,P)-SUB` with `SUB_i = pitch + (i mod slots)·pitch` (the engine
+ * adds `baseX_i = (i mod slots)·pitch` back, collapsing to `mod(...) - pitch`).
+ */
+function buildScrollXExpr(p, tileIndex) {
+    const c = phaseConstant(p, tileIndex);
+    const sub = p.pitch + (tileIndex % p.slots) * p.pitch;
+    const v = String(p.pxPerSec);
+    // JS shortest round-trip formatting never yields exponent notation in this
+    // template's velocity range; guard anyway — ffmpeg must see a plain decimal.
+    if (!/^\d+(\.\d+)?$/.test(v)) {
+        throw new Error(`scroll-wall: velocity ${v} px/s does not format as a plain decimal.`);
+    }
+    return `mod(${c}${p.sign < 0 ? "-" : "+"}${v}*t,${p.period})-${sub}`;
+}
+/**
+ * Independent floor-mod reference model for tile `i`'s ABSOLUTE x at time
+ * `t` (i.e. after the engine adds `baseX_i`). Tests prove string ≡ model
+ * without rendering.
+ */
+function scrollAbsX(p, tileIndex, t) {
+    return floorMod(phaseConstant(p, tileIndex) + p.sign * p.pxPerSec * t, p.period) - p.pitch;
+}
+const XEXPR_SHAPE = /^mod\((\d+)([+-])(\d+(?:\.\d+)?)\*t,(\d+)\)-(\d+)$/;
+/** Parse the one expression shape this template emits. Throws on any other. */
+function parseScrollXExpr(expr) {
+    const m = XEXPR_SHAPE.exec(expr);
+    if (!m)
+        throw new Error(`scroll-wall: not a scroll xExpr: "${expr}"`);
+    return {
+        c: Number(m[1]),
+        sign: m[2] === "-" ? -1 : 1,
+        pxPerSec: Number(m[3]),
+        period: Number(m[4]),
+        sub: Number(m[5]),
+    };
+}
+/**
+ * Evaluate an emitted expression at time `t` exactly as ffmpeg's overlay
+ * evaluator would (floor-mod) — this is the OFFSET the engine adds to the
+ * cell's `baseX`. `evalScrollXExpr(expr, t) + baseX` must equal
+ * {@link scrollAbsX} for the same tile.
+ */
+function evalScrollXExpr(expr, t) {
+    const { c, sign, pxPerSec, period, sub } = parseScrollXExpr(expr);
+    return floorMod(c + sign * pxPerSec * t, period) - sub;
+}