@m0saic/templates 0.2.0

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

@@ -0,0 +1,117 @@
+/**
+ * ============================================================================
+ * dsl-tutorial — timing model
+ * ============================================================================
+ *
+ * Pure, deterministic mapping from (step count, speed) → the one timeline every
+ * panel keys off. There is no per-output-frame JS callback; all animation is
+ * ffmpeg expressions over these precomputed windows, so the camera, caret, diff
+ * fields, highlight, and step pill all move together.
+ *
+ * Time is global `t` (seconds). A step `i` (1-based) owns the window
+ * `[stepStartSec(i), stepStartSec(i) + stepDurSec)`, with a short transition at
+ * its head where values cross-fade old→new.
+ * ============================================================================
+ */
+export type Timing = {
+    /** Number of steps (== Step[].length). */
+    stepCount: number;
+    /** Seconds each step holds. */
+    stepDurSec: number;
+    /** Seconds of cross-fade at the head of each step. */
+    transitionSec: number;
+    /** Lead pad seconds before step 1. */
+    leadSec: number;
+    /** Trail pad seconds after the last step. */
+    trailSec: number;
+    /** Total video duration in ms (drives doc.durationMs; children inherit it). */
+    durationMs: number;
+    /** Start time (s) of step `i` (1-based). */
+    stepStartSec: (i: number) => number;
+};
+/**
+ * Build the timeline for `stepCount` steps at `speedMultiplier` (>1 = faster).
+ *
+ * The "natural" duration is the recommendation derived purely from how much
+ * there is to paint: `lead + steps·stepDur + trail`. When `targetDurationMs` is
+ * supplied (the render's authoritative output length), the WHOLE timeline is
+ * uniformly rescaled to fit it EXACTLY — every component (lead, trail, per-step
+ * hold, transition) multiplied by the same factor `k = target / natural`. So a
+ * dense 64-tile walk pinned to 30s simply runs proportionally faster and still
+ * paints every tile, instead of being truncated mid-walk; a sparse walk pinned
+ * to a long duration stretches to fill it instead of ending in dead air. Ratios
+ * (transition vs. step) are preserved, so caret/fields/highlight/camera stay in
+ * lockstep at any duration.
+ *
+ * @param targetDurationMs  when >0, fit the timeline to exactly this length;
+ *   omit (or 0) to use the natural tile-count-driven recommendation.
+ */
+/**
+ * Speed multiplier for a walk whose author left `speedMultiplier` unset
+ * (founder direction 2026-09-05): 1× up to {@link AUTO_SPEED_UNIT_STEPS} steps —
+ * a lesson-sized layout is read at a comfortable pace, numbers and all — then the
+ * SQUARE ROOT of the step count over that unit (a 4× bigger layout runs 2×
+ * faster), capped at {@link AUTO_SPEED_MAX}. Nobody reads the numbers on a
+ * 5,000-step walk; it is watched as an ASSEMBLY, so the pace follows the size:
+ *   16 → 1×, 96 → 2×, 243 → 3.2×, 1000 → 6.5×, 2400 → 10×, ≥ 5400 → 15×.
+ * Pure and monotonic; an explicit `speedMultiplier` is absolute and bypasses it.
+ */
+export declare function autoSpeed(stepCount: number): number;
+/**
+ * Pacing TIERS (founder direction 2026-09-05), picked by the PRETTY string's
+ * character count — a plain proxy for how busy the canvas is:
+ *  - **teach** (≤ {@link TEACH_MAX_CHARS} chars) — the hero experience: show
+ *    everything, read it. Natural length at 1× (auto up to 2× for the bigger
+ *    lessons).
+ *  - **summarize** (≤ {@link SUMMARIZE_MAX_CHARS}) — "watch the renderer paint":
+ *    the whole walk fits {@link SUMMARIZE_TARGET_MS}; passthrough / null visuals
+ *    go light; the camera stays on the full layout.
+ *  - **sloth** (beyond) — tens of thousands of characters, not what the template
+ *    is for: {@link SLOTH_TARGET_MS}, passthroughs not drawn at all, no labels.
+ * An explicit `speedMultiplier` or a pin (user ask) still wins in every tier.
+ */
+export type PaceTier = "teach" | "summarize" | "sloth";
+export declare const TEACH_MAX_CHARS = 400;
+export declare const SUMMARIZE_MAX_CHARS = 8000;
+/** The ABSOLUTE ceiling (founder ruling 2026-09-06): past this many characters the
+ *  tutorial refuses outright, at any output size. The 52k-char / 26k-passthrough
+ *  dictionary pick rendered at 4K (the only size whose canvas panel clears its
+ *  1874×1080 floor) took 93 minutes for 20 s and "is clearly not the intended use
+ *  case" — the template is not the tool for a layout that size (Layout is).
+ *  Why chars: every character is a step, and the per-step work is what scales —
+ *  the cursor track is one drawbox per cursor move in ONE lavfi chain, and ffmpeg
+ *  walks that chain per frame at a cost QUADRATIC in its length (measured 09-06 at
+ *  the 1330×750 panel: 1k boxes 13 ms/frame, 4k 105 ms, 8k 410 ms); a passthrough-
+ *  heavy layout moves the cursor on every comma, ~half its characters. 16k chars
+ *  (2× the sloth line) keeps a 20 s sloth walk's canvas around 4 min at 1080p under
+ *  that model, and the DSL strip (the next wall, O(chars)) in the same order. */
+export declare const MAX_CHARS = 16000;
+/** The ABSOLUTE frame (tile) ceiling (founder, 2026-09-06: "no need to try and render
+ *  something with way too many frames"). Past the canvas's reveal-curtain budget
+ *  (`CURTAIN_BOX_BUDGET`, 6,000 boxes) every tile is visible from t=0 and the
+ *  tile-by-tile reveal — the lesson — is gone, so the walk is refused at the same
+ *  line rather than rendered without it. The 272×272 brand bitmap is 36,770 frames. */
+export declare const MAX_FRAMES = 6000;
+export declare const SUMMARIZE_TARGET_MS = 30000;
+export declare const SLOTH_TARGET_MS = 20000;
+export declare function resolveTier(chars: number, override?: "auto" | PaceTier): PaceTier;
+/** The one timeline for a walk: pin > explicit speed > tier. */
+export declare function tierTiming(opts: {
+    stepCount: number;
+    tier: PaceTier;
+    fps: number;
+    speedMultiplier?: number;
+    pinnedMs?: number;
+}): Timing;
+export declare function computeTiming(stepCount: number, speedMultiplier: number, targetDurationMs?: number, fps?: number): Timing;
+/**
+ * Drawtext-safe expression for the CURRENT step number (a stepped/floored
+ * integer that advances one per step window, clamped to `[0, total]`). Use as
+ * the `expr` of an `eval:"frame"` text layer. Commas/colons are escaped for
+ * `%{eif:…}` expansion.
+ *
+ * Step 0 = the lead (the unparsed canvas, before step 1 begins); then 1..total.
+ *
+ * n(t) = clamp( 1 + floor((t - lead) / stepDur), 0, total )
+ */
+export declare function stepNumberExpr(t: Timing, prefix?: string, suffix?: string): string;

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

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * ============================================================================
+ * dsl-tutorial — timing model
+ * ============================================================================
+ *
+ * Pure, deterministic mapping from (step count, speed) → the one timeline every
+ * panel keys off. There is no per-output-frame JS callback; all animation is
+ * ffmpeg expressions over these precomputed windows, so the camera, caret, diff
+ * fields, highlight, and step pill all move together.
+ *
+ * Time is global `t` (seconds). A step `i` (1-based) owns the window
+ * `[stepStartSec(i), stepStartSec(i) + stepDurSec)`, with a short transition at
+ * its head where values cross-fade old→new.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SLOTH_TARGET_MS = exports.SUMMARIZE_TARGET_MS = exports.MAX_FRAMES = exports.MAX_CHARS = exports.SUMMARIZE_MAX_CHARS = exports.TEACH_MAX_CHARS = void 0;
+exports.autoSpeed = autoSpeed;
+exports.resolveTier = resolveTier;
+exports.tierTiming = tierTiming;
+exports.computeTiming = computeTiming;
+exports.stepNumberExpr = stepNumberExpr;
+/** Base seconds per step at speed 1.0 (before the speed multiplier). */
+const BASE_STEP_SEC = 0.9;
+/** Auto pacing: walks of at most this many steps run at 1× (a lesson is READ). */
+const AUTO_SPEED_UNIT_STEPS = 24;
+/** Auto pacing ceiling — a huge layout still assembles at a watchable rate. */
+const AUTO_SPEED_MAX = 15;
+/** Lead pad before the first step. */
+const LEAD_SEC = 0.5;
+/** Trail pad after the last step. */
+const TRAIL_SEC = 0.9;
+/**
+ * Build the timeline for `stepCount` steps at `speedMultiplier` (>1 = faster).
+ *
+ * The "natural" duration is the recommendation derived purely from how much
+ * there is to paint: `lead + steps·stepDur + trail`. When `targetDurationMs` is
+ * supplied (the render's authoritative output length), the WHOLE timeline is
+ * uniformly rescaled to fit it EXACTLY — every component (lead, trail, per-step
+ * hold, transition) multiplied by the same factor `k = target / natural`. So a
+ * dense 64-tile walk pinned to 30s simply runs proportionally faster and still
+ * paints every tile, instead of being truncated mid-walk; a sparse walk pinned
+ * to a long duration stretches to fill it instead of ending in dead air. Ratios
+ * (transition vs. step) are preserved, so caret/fields/highlight/camera stay in
+ * lockstep at any duration.
+ *
+ * @param targetDurationMs  when >0, fit the timeline to exactly this length;
+ *   omit (or 0) to use the natural tile-count-driven recommendation.
+ */
+/**
+ * Speed multiplier for a walk whose author left `speedMultiplier` unset
+ * (founder direction 2026-09-05): 1× up to {@link AUTO_SPEED_UNIT_STEPS} steps —
+ * a lesson-sized layout is read at a comfortable pace, numbers and all — then the
+ * SQUARE ROOT of the step count over that unit (a 4× bigger layout runs 2×
+ * faster), capped at {@link AUTO_SPEED_MAX}. Nobody reads the numbers on a
+ * 5,000-step walk; it is watched as an ASSEMBLY, so the pace follows the size:
+ *   16 → 1×, 96 → 2×, 243 → 3.2×, 1000 → 6.5×, 2400 → 10×, ≥ 5400 → 15×.
+ * Pure and monotonic; an explicit `speedMultiplier` is absolute and bypasses it.
+ */
+function autoSpeed(stepCount) {
+    const steps = Math.max(1, Math.round(stepCount));
+    return Math.min(AUTO_SPEED_MAX, Math.max(1, Math.sqrt(steps / AUTO_SPEED_UNIT_STEPS)));
+}
+exports.TEACH_MAX_CHARS = 400;
+exports.SUMMARIZE_MAX_CHARS = 8000;
+/** The ABSOLUTE ceiling (founder ruling 2026-09-06): past this many characters the
+ *  tutorial refuses outright, at any output size. The 52k-char / 26k-passthrough
+ *  dictionary pick rendered at 4K (the only size whose canvas panel clears its
+ *  1874×1080 floor) took 93 minutes for 20 s and "is clearly not the intended use
+ *  case" — the template is not the tool for a layout that size (Layout is).
+ *  Why chars: every character is a step, and the per-step work is what scales —
+ *  the cursor track is one drawbox per cursor move in ONE lavfi chain, and ffmpeg
+ *  walks that chain per frame at a cost QUADRATIC in its length (measured 09-06 at
+ *  the 1330×750 panel: 1k boxes 13 ms/frame, 4k 105 ms, 8k 410 ms); a passthrough-
+ *  heavy layout moves the cursor on every comma, ~half its characters. 16k chars
+ *  (2× the sloth line) keeps a 20 s sloth walk's canvas around 4 min at 1080p under
+ *  that model, and the DSL strip (the next wall, O(chars)) in the same order. */
+exports.MAX_CHARS = 16000;
+/** The ABSOLUTE frame (tile) ceiling (founder, 2026-09-06: "no need to try and render
+ *  something with way too many frames"). Past the canvas's reveal-curtain budget
+ *  (`CURTAIN_BOX_BUDGET`, 6,000 boxes) every tile is visible from t=0 and the
+ *  tile-by-tile reveal — the lesson — is gone, so the walk is refused at the same
+ *  line rather than rendered without it. The 272×272 brand bitmap is 36,770 frames. */
+exports.MAX_FRAMES = 6000;
+/** Teach never runs faster than this (auto pacing is for READING here). */
+const TEACH_MAX_AUTO_SPEED = 2;
+exports.SUMMARIZE_TARGET_MS = 30000;
+exports.SLOTH_TARGET_MS = 20000;
+function resolveTier(chars, override) {
+    if (override && override !== "auto")
+        return override;
+    return chars <= exports.TEACH_MAX_CHARS ? "teach" : chars <= exports.SUMMARIZE_MAX_CHARS ? "summarize" : "sloth";
+}
+/** The one timeline for a walk: pin > explicit speed > tier. */
+function tierTiming(opts) {
+    const { stepCount, tier, fps, speedMultiplier, pinnedMs } = opts;
+    if (pinnedMs != null && pinnedMs > 0)
+        return computeTiming(stepCount, speedMultiplier !== null && speedMultiplier !== void 0 ? speedMultiplier : 1, pinnedMs, fps);
+    if (speedMultiplier != null && speedMultiplier > 0)
+        return computeTiming(stepCount, speedMultiplier, undefined, fps);
+    if (tier === "teach")
+        return computeTiming(stepCount, Math.min(autoSpeed(stepCount), TEACH_MAX_AUTO_SPEED), undefined, fps);
+    const target = tier === "summarize" ? exports.SUMMARIZE_TARGET_MS : exports.SLOTH_TARGET_MS;
+    const natural = computeTiming(stepCount, 1, undefined, fps);
+    return natural.durationMs <= target ? natural : computeTiming(stepCount, 1, target, fps);
+}
+function computeTiming(stepCount, speedMultiplier, targetDurationMs, fps = 30) {
+    const speed = speedMultiplier > 0 ? speedMultiplier : 1;
+    const steps = Math.max(1, Math.round(stepCount));
+    let stepDurSec = BASE_STEP_SEC / speed;
+    let transitionSec = Math.min(stepDurSec * 0.45, 0.35 / speed);
+    let leadSec = LEAD_SEC;
+    let trailSec = TRAIL_SEC;
+    let durationSec = leadSec + steps * stepDurSec + trailSec;
+    // Fit to the output duration: uniform rescale of every time component so the
+    // walk fills exactly `targetDurationMs` (no truncation, no trailing dead air).
+    if (targetDurationMs != null && targetDurationMs > 0 && durationSec > 0) {
+        const targetSec = targetDurationMs / 1000;
+        if (targetSec < durationSec && targetSec > leadSec + trailSec + steps * 0.001) {
+            // COMPRESSING (a pin or a tier target shorter than the natural length): only
+            // the per-step pace compresses; the lead and the closing hold stay ABSOLUTE,
+            // so the finished layout is held at the end however hard the walk was
+            // squeezed (a uniform squeeze of a 5k-step walk into 20 s left a 4 ms hold
+            // and a still-zoomed last frame — 2026-09-05). STRETCHING keeps the uniform
+            // rescale below, so a sparse walk fills a long pin without dead air.
+            stepDurSec = (targetSec - leadSec - trailSec) / steps;
+            transitionSec = Math.min(stepDurSec * 0.45, 0.35);
+        }
+        else {
+            const k = targetSec / durationSec;
+            stepDurSec *= k;
+            transitionSec *= k;
+            leadSec *= k;
+            trailSec *= k;
+        }
+        durationSec = targetSec;
+    }
+    else if (fps > 0) {
+        // Snap the NATURAL length UP to a whole frame, and its ms UP past that frame's
+        // end. The panels are nested video children the engine trims with `-t`, which
+        // keeps a frame only when it ENDS inside the trim; the parent takes
+        // round(duration × fps) frames. A duration between those (132.417 s at 30 fps:
+        // parent 3973 frames, children 3972) makes the parent's last frame read past
+        // its children and LOOP to their first frame — "Step 0" as the closing frame
+        // (2026-09-05). Whole-frame lengths (15.8 s = 474 frames) never showed it.
+        const frames = Math.ceil(durationSec * fps - 1e-6);
+        const snappedSec = Math.ceil((frames * 1000) / fps - 1e-6) / 1000;
+        trailSec += snappedSec - durationSec; // the slack rides on the closing hold
+        durationSec = snappedSec;
+    }
+    return {
+        stepCount: steps,
+        stepDurSec,
+        transitionSec,
+        leadSec,
+        trailSec,
+        durationMs: Math.round(durationSec * 1000),
+        stepStartSec: (i) => leadSec + (Math.max(1, i) - 1) * stepDurSec,
+    };
+}
+/**
+ * Drawtext-safe expression for the CURRENT step number (a stepped/floored
+ * integer that advances one per step window, clamped to `[0, total]`). Use as
+ * the `expr` of an `eval:"frame"` text layer. Commas/colons are escaped for
+ * `%{eif:…}` expansion.
+ *
+ * Step 0 = the lead (the unparsed canvas, before step 1 begins); then 1..total.
+ *
+ * n(t) = clamp( 1 + floor((t - lead) / stepDur), 0, total )
+ */
+function stepNumberExpr(t, prefix = "", suffix = "") {
+    const lead = t.leadSec.toFixed(4);
+    const d = t.stepDurSec.toFixed(4);
+    const total = t.stepCount;
+    // eif:d truncates toward zero. During the lead, (t-lead)<0 → 1+frac ∈ (0,1) →
+    // truncates to 0 (step 0). At/after step 1, the value is ≥1.
+    const inner = `min(${total}\\,max(0\\,1+(t-${lead})/${d}))`;
+    return `${prefix}%{eif\\:${inner}\\:d}${suffix}`;
+}

package/dist/m0saic/dsl-tutorial/v1/theme/tokens.d.ts

@@ -0,0 +1,87 @@
+/**
+ * ============================================================================
+ * dsl-tutorial — theme tokens (light / dark)
+ * ============================================================================
+ *
+ * One coherent IDE/debugger look shared by the parent orchestrator and every
+ * panel subtemplate, so the whole tutorial reads as a single SaaS-clean app.
+ * Pack-local on purpose (not a re-skin of charts/* or alpine/*): this template
+ * owns the "code editor" aesthetic — deep surface, panel cards, hairline
+ * borders, a purple accent, and git-style positive/negative diff colors.
+ *
+ * `syntax` is the per-token-type color map for the live DSL string panel.
+ * ============================================================================
+ */
+import type { MosaicColor } from "@m0saic/types";
+/** Per-token-type colors for the syntax-highlighted m0 string. */
+export type DslSyntaxTheme = {
+    /** Rendered tile `1` / `F`. */
+    frame: MosaicColor;
+    /** Split count digits (`2`, `4`, `10`). */
+    count: MosaicColor;
+    /** Brackets / parens `( ) [ ]`. */
+    bracket: MosaicColor;
+    /** Separators `,`. */
+    comma: MosaicColor;
+    /** Passthrough `0` / `>` and null `-`. */
+    passthrough: MosaicColor;
+    /** Default / unmatched ink. */
+    base: MosaicColor;
+};
+/** One coherent dsl-tutorial look. Consumed by parent + every panel. */
+export type DslTutorialTheme = {
+    /** App canvas behind the chrome (deepest). */
+    canvas: MosaicColor;
+    /** Panel/card surface. */
+    surface: MosaicColor;
+    /** Slightly raised surface (header bar, pills, chips). */
+    surfaceRaised: MosaicColor;
+    /** Hairline border. */
+    border: MosaicColor;
+    /** Border opacity (0..1). */
+    borderAlpha: number;
+    /** Dominant text (titles, values). */
+    title: MosaicColor;
+    /** Secondary text (labels). */
+    label: MosaicColor;
+    /** De-emphasized text (captions, ruler ticks). */
+    muted: MosaicColor;
+    /** Brand accent (active-tile highlight, caret, selection). */
+    accent: MosaicColor;
+    /** Accent wash (tinted highlight fill). */
+    accentSoft: MosaicColor;
+    /** The geometry CURSOR — the orange box that leads the parse at the live X/Y/W/H bounds. */
+    cursor: MosaicColor;
+    /** Git-style added / new value (green). */
+    positive: MosaicColor;
+    /** Git-style removed / old value (red). */
+    negative: MosaicColor;
+    /** Live status dot (parsing). */
+    live: MosaicColor;
+    /** Tile surface (the numbered wireframe cells — light even in dark mode). */
+    tile: MosaicColor;
+    /** Tile primary text (the order number). */
+    tileText: MosaicColor;
+    /** Tile secondary text (the WxH dimensions). */
+    tileMuted: MosaicColor;
+    /** Tile hairline border. */
+    tileBorder: MosaicColor;
+    /** Outline of the whole canvas Frame (the bounds all tiles paint into). */
+    frameOutline: MosaicColor;
+    /** Panel corner radius as a fraction of the shorter side (0..1). */
+    cornerRadius: number;
+    syntax: DslSyntaxTheme;
+};
+/** Theme presets. `dark` is the canonical look; `light` is the day variant. */
+export declare const DSL_TUTORIAL_PRESETS: Record<"light" | "dark", DslTutorialTheme>;
+/** Preset id union — the `preset` prop type. */
+export type DslTutorialPreset = keyof typeof DSL_TUTORIAL_PRESETS;
+/** Resolve a preset id to its theme (defaults to `light` — the wireframe look). */
+export declare function dslTutorialTheme(preset?: DslTutorialPreset): DslTutorialTheme;
+/**
+ * Resolve a user color field to a concrete color: a cleared / "none" / blank
+ * picker falls back to the default. A bare `value ?? fallback` keeps `""` (not
+ * nullish), which renders the element invisible — so every color knob routes
+ * through this.
+ */
+export declare function resolveColor(value: string | undefined | null, fallback: MosaicColor): MosaicColor;

package/dist/m0saic/dsl-tutorial/v1/theme/tokens.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * ============================================================================
+ * dsl-tutorial — theme tokens (light / dark)
+ * ============================================================================
+ *
+ * One coherent IDE/debugger look shared by the parent orchestrator and every
+ * panel subtemplate, so the whole tutorial reads as a single SaaS-clean app.
+ * Pack-local on purpose (not a re-skin of charts/* or alpine/*): this template
+ * owns the "code editor" aesthetic — deep surface, panel cards, hairline
+ * borders, a purple accent, and git-style positive/negative diff colors.
+ *
+ * `syntax` is the per-token-type color map for the live DSL string panel.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DSL_TUTORIAL_PRESETS = void 0;
+exports.dslTutorialTheme = dslTutorialTheme;
+exports.resolveColor = resolveColor;
+/** Theme presets. `dark` is the canonical look; `light` is the day variant. */
+exports.DSL_TUTORIAL_PRESETS = {
+    dark: {
+        canvas: "#0A0E1A",
+        surface: "#111726",
+        surfaceRaised: "#1A2236",
+        border: "#27314A",
+        borderAlpha: 1,
+        title: "#F2F5FB",
+        label: "#AEB9D4",
+        muted: "#697390",
+        accent: "#7C5CFF",
+        accentSoft: "#7C5CFF",
+        cursor: "#FF8A3D",
+        positive: "#3FD17A",
+        negative: "#FF6B6B",
+        live: "#3FD17A",
+        tile: "#EEF1F8",
+        tileText: "#161B2B",
+        tileMuted: "#6B7488",
+        tileBorder: "#C9D1E4",
+        frameOutline: "#4A597C",
+        cornerRadius: 0.06,
+        syntax: {
+            frame: "#E7ECF7",
+            count: "#7C9CFF",
+            bracket: "#C792EA",
+            comma: "#5B6684",
+            passthrough: "#F7A35C",
+            base: "#AEB9D4",
+        },
+    },
+    light: {
+        canvas: "#EEF1F7",
+        surface: "#FFFFFF",
+        surfaceRaised: "#F4F6FB",
+        border: "#D9DEEA",
+        borderAlpha: 1,
+        title: "#101728",
+        label: "#3C4763",
+        muted: "#8A94AC",
+        accent: "#6D4AF0",
+        accentSoft: "#6D4AF0",
+        cursor: "#F97316",
+        positive: "#16A34A",
+        negative: "#DC2626",
+        live: "#16A34A",
+        tile: "#FFFFFF",
+        tileText: "#1A2236",
+        tileMuted: "#8A94AC",
+        tileBorder: "#D9DEEA",
+        frameOutline: "#A9B3CC",
+        cornerRadius: 0.06,
+        syntax: {
+            frame: "#1E2638",
+            count: "#2D5BD6",
+            bracket: "#8B3FC9",
+            comma: "#9AA3BA",
+            passthrough: "#C2701B",
+            base: "#3C4763",
+        },
+    },
+};
+/** Resolve a preset id to its theme (defaults to `light` — the wireframe look). */
+function dslTutorialTheme(preset) {
+    return exports.DSL_TUTORIAL_PRESETS[preset !== null && preset !== void 0 ? preset : "light"];
+}
+/**
+ * Resolve a user color field to a concrete color: a cleared / "none" / blank
+ * picker falls back to the default. A bare `value ?? fallback` keeps `""` (not
+ * nullish), which renders the element invisible — so every color knob routes
+ * through this.
+ */
+function resolveColor(value, fallback) {
+    const v = (value !== null && value !== void 0 ? value : "").trim();
+    return v && v.toLowerCase() !== "none" ? v : fallback;
+}

package/dist/m0saic/forensic/index.d.ts

@@ -0,0 +1 @@
+export * from "./watermark";

package/dist/m0saic/forensic/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./watermark"), exports);

package/dist/m0saic/forensic/watermark/_shared/cellLuminance.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The forensic-watermark family's one way to sample a video into a per-cell
+ * luminance grid: `ctx.analysis.cellLuminance`, the engine-owned pass bound
+ * to the host's toolchain ffmpeg.
+ *
+ * Both halves of the family go through this file so they provably run the
+ * same filtergraph — the embed side probes the SOURCE, the verify side
+ * samples the DELIVERED copy, and baseline subtraction only recovers the
+ * payload because the two chains match. The chain itself lives in
+ * `@m0saic/core` (`probeCellLuminance`); templates never spawn ffmpeg
+ * themselves, so a packaged desktop with no `ffmpeg` on PATH works exactly
+ * like the CLI.
+ *
+ * `ctx.analysis` is absent in `mode: "design"` (previews must never spawn)
+ * and on hosts without a toolchain. Callers turn {@link CellSampleError}
+ * into an error card / error verdict — never a throw out of `render()`.
+ */
+import type { MosaicCellLuminanceOpts, MosaicCellLuminanceResult, MosaicEngineContext } from "@m0saic/types";
+export type CellLuminanceSampler = (mediaPath: string, opts: MosaicCellLuminanceOpts) => Promise<MosaicCellLuminanceResult>;
+export declare class CellSampleError extends Error {
+    readonly code: "ANALYSIS_UNAVAILABLE" | "SAMPLING_FAILED";
+    constructor(code: "ANALYSIS_UNAVAILABLE" | "SAMPLING_FAILED", message: string);
+}
+export declare const ANALYSIS_UNAVAILABLE_MESSAGE: string;
+/**
+ * Resolve the sampler off the engine context. Undefined when the host
+ * attached no analysis surface — callers decide how to degrade.
+ */
+export declare function cellLuminanceSampler(ctx: Pick<MosaicEngineContext, "analysis">): CellLuminanceSampler | undefined;
+/**
+ * Sample through the engine pass, re-homing every failure onto
+ * {@link CellSampleError} so callers branch on one class.
+ *
+ * @param label Verb for the message ("probe" / "sampling") — cosmetic, it
+ * lets each caller's failure read naturally on a user-facing card.
+ */
+export declare function sampleCellLuminance(sampler: CellLuminanceSampler | undefined, mediaPath: string, opts: MosaicCellLuminanceOpts, label?: "probe" | "sampling"): Promise<MosaicCellLuminanceResult>;

package/dist/m0saic/forensic/watermark/_shared/cellLuminance.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * The forensic-watermark family's one way to sample a video into a per-cell
+ * luminance grid: `ctx.analysis.cellLuminance`, the engine-owned pass bound
+ * to the host's toolchain ffmpeg.
+ *
+ * Both halves of the family go through this file so they provably run the
+ * same filtergraph — the embed side probes the SOURCE, the verify side
+ * samples the DELIVERED copy, and baseline subtraction only recovers the
+ * payload because the two chains match. The chain itself lives in
+ * `@m0saic/core` (`probeCellLuminance`); templates never spawn ffmpeg
+ * themselves, so a packaged desktop with no `ffmpeg` on PATH works exactly
+ * like the CLI.
+ *
+ * `ctx.analysis` is absent in `mode: "design"` (previews must never spawn)
+ * and on hosts without a toolchain. Callers turn {@link CellSampleError}
+ * into an error card / error verdict — never a throw out of `render()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANALYSIS_UNAVAILABLE_MESSAGE = exports.CellSampleError = void 0;
+exports.cellLuminanceSampler = cellLuminanceSampler;
+exports.sampleCellLuminance = sampleCellLuminance;
+class CellSampleError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "CellSampleError";
+        this.code = code;
+    }
+}
+exports.CellSampleError = CellSampleError;
+exports.ANALYSIS_UNAVAILABLE_MESSAGE = "This host attached no media analysis (ffmpeg toolchain not available). " +
+    "Run `m0saic setup` (CLI) or pick a toolchain under Tools (desktop) and render again.";
+/**
+ * Resolve the sampler off the engine context. Undefined when the host
+ * attached no analysis surface — callers decide how to degrade.
+ */
+function cellLuminanceSampler(ctx) {
+    var _a;
+    const fn = (_a = ctx.analysis) === null || _a === void 0 ? void 0 : _a.cellLuminance;
+    if (typeof fn !== "function")
+        return undefined;
+    return (mediaPath, opts) => fn.call(ctx.analysis, mediaPath, opts);
+}
+/**
+ * Sample through the engine pass, re-homing every failure onto
+ * {@link CellSampleError} so callers branch on one class.
+ *
+ * @param label Verb for the message ("probe" / "sampling") — cosmetic, it
+ * lets each caller's failure read naturally on a user-facing card.
+ */
+async function sampleCellLuminance(sampler, mediaPath, opts, label = "sampling") {
+    if (!sampler) {
+        throw new CellSampleError("ANALYSIS_UNAVAILABLE", exports.ANALYSIS_UNAVAILABLE_MESSAGE);
+    }
+    try {
+        return await sampler(mediaPath, opts);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new CellSampleError("SAMPLING_FAILED", `ffmpeg ${label} failed for ${mediaPath}: ${message}`);
+    }
+}

package/dist/m0saic/forensic/watermark/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./video";
+export * from "./verify";

package/dist/m0saic/forensic/watermark/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./video"), exports);
+__exportStar(require("./verify"), exports);

package/dist/m0saic/forensic/watermark/verify/index.d.ts

@@ -0,0 +1 @@
+export * from "./v1";

package/dist/m0saic/forensic/watermark/verify/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./v1"), exports);