@m0saic/templates 0.2.0

package/dist/m0saic/media/logo-animate/v1/svg-source.d.ts

@@ -0,0 +1,63 @@
+/**
+ * SVG source resolution + the shared-grid conversion pass for
+ * `@m0saic/media/logo-animate/v1`.
+ *
+ * The conversion runs the dsl-stdlib pipeline stage-by-stage
+ * (`parseSvg → extractGeometry → inferGrid → rectsToM0`) instead of the
+ * one-shot `svgToM0`, because masks and ranks must be generated against
+ * the SAME inferred grid the m0 came from — `svgToM0` discards it.
+ */
+import type { BinaryGrid, Grid, MosaicMaskEntry, PackingMode, ViewBox } from "@m0saic/dsl-stdlib";
+/** Actionable guidance when an SVG parses to zero usable shapes. */
+export declare const SVG_SHAPE_GUIDANCE: string;
+export type LogoSourceProps = {
+    svg?: string;
+    svgPath?: string;
+};
+/**
+ * Resolve the SVG text: inline `svg` string (pure), or the file at
+ * `svgPath` (requires the template's `fs.read` capability), or the
+ * caller-supplied fallback when neither is set. Callers validate the
+ * both-set conflict BEFORE calling.
+ */
+export declare function loadSvgText(props: LogoSourceProps, fallback: string): string;
+export type LogoGrid = {
+    /** Canonical m0 string for the inferred grid (brand at doc assembly). */
+    m0: string;
+    /** The inferred grid — masks and ranks must derive from this same pass. */
+    grid: Grid;
+    viewBox: ViewBox | null;
+    rectCount: number;
+    layerCount: number;
+    /** Intrinsic logo dims (viewBox, or grid extent) — the aspect source. */
+    intrinsic: {
+        w: number;
+        h: number;
+    };
+};
+/**
+ * One conversion pass → `{ m0, grid }` sharing a single `inferGrid`
+ * result. Throws (with user-actionable messages) on unparseable SVGs;
+ * callers wrap in try/catch → error mosaic.
+ */
+export declare function buildLogoGrid(svgText: string, opts: {
+    driftPercent: number;
+    packing: PackingMode;
+}): LogoGrid;
+/**
+ * Best-effort silhouette masks keyed by leaf StableKey (rect-only
+ * shapes need no mask and are absent). `generateMasks` THROWS on
+ * shape/frame mismatches (only `generateMasksByStableKey` degrades),
+ * so the whole pass is fenced: any failure → `{}` → every tile renders
+ * as its bounding rect. StableKeys are structural (canvas-independent),
+ * so the keys join against frames queried at any render canvas.
+ */
+export declare function buildMasksByStableKey(grid: Grid, m0: string): Record<string, MosaicMaskEntry | null>;
+/**
+ * Rasterize an SVG to a `res × res` binary silhouette grid. The SVG's ALPHA
+ * channel is the silhouette, so a logo of any ink converts (colour-agnostic).
+ * Its `res²` cells — many ON — become the bitmap m0 the animation stitches:
+ * the deliberately heavy, opt-in path for non-rectilinear marks that don't
+ * decompose into separately-animatable rectangles.
+ */
+export declare function rasterizeSvgToBinaryGrid(svgText: string, res: number): Promise<BinaryGrid>;

package/dist/m0saic/media/logo-animate/v1/svg-source.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * SVG source resolution + the shared-grid conversion pass for
+ * `@m0saic/media/logo-animate/v1`.
+ *
+ * The conversion runs the dsl-stdlib pipeline stage-by-stage
+ * (`parseSvg → extractGeometry → inferGrid → rectsToM0`) instead of the
+ * one-shot `svgToM0`, because masks and ranks must be generated against
+ * the SAME inferred grid the m0 came from — `svgToM0` discards it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SVG_SHAPE_GUIDANCE = void 0;
+exports.loadSvgText = loadSvgText;
+exports.buildLogoGrid = buildLogoGrid;
+exports.buildMasksByStableKey = buildMasksByStableKey;
+exports.rasterizeSvgToBinaryGrid = rasterizeSvgToBinaryGrid;
+const node_fs_1 = require("node:fs");
+const svgRaster_1 = require("../../../_shared/svgRaster");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+/** Actionable guidance when an SVG parses to zero usable shapes. */
+exports.SVG_SHAPE_GUIDANCE = "SVG contains no usable <path> or <rect> shapes. Groups, transforms, " +
+    "circles/ellipses/polygons and CSS classes are not parsed — in Inkscape: " +
+    "select all, Path → Object to Path, ungroup, then save as Plain SVG.";
+/**
+ * Resolve the SVG text: inline `svg` string (pure), or the file at
+ * `svgPath` (requires the template's `fs.read` capability), or the
+ * caller-supplied fallback when neither is set. Callers validate the
+ * both-set conflict BEFORE calling.
+ */
+function loadSvgText(props, fallback) {
+    if (props.svgPath) {
+        return (0, node_fs_1.readFileSync)(props.svgPath, "utf8");
+    }
+    if (props.svg)
+        return props.svg;
+    return fallback;
+}
+/**
+ * One conversion pass → `{ m0, grid }` sharing a single `inferGrid`
+ * result. Throws (with user-actionable messages) on unparseable SVGs;
+ * callers wrap in try/catch → error mosaic.
+ */
+function buildLogoGrid(svgText, opts) {
+    const parsed = (0, dsl_stdlib_1.parseSvg)(svgText);
+    const shapes = (0, dsl_stdlib_1.extractGeometry)(parsed.paths);
+    if (shapes.length === 0) {
+        throw new Error(exports.SVG_SHAPE_GUIDANCE);
+    }
+    const grid = (0, dsl_stdlib_1.inferGrid)(shapes, parsed.viewBox, {
+        driftPercent: opts.driftPercent,
+        driftMode: "gcd-snap",
+    });
+    const variant = (0, dsl_stdlib_1.rectsToM0)(grid, { packing: opts.packing });
+    const { w, h } = gridCanvasDims(grid);
+    return {
+        m0: String(variant.m0),
+        grid,
+        viewBox: parsed.viewBox,
+        rectCount: variant.rectCount,
+        layerCount: variant.layerCount,
+        intrinsic: { w, h },
+    };
+}
+/**
+ * The canvas masks are authored in: the grid's own viewBox space (the
+ * space `grid.shapes[].snappedBounds` live in). Shape↔frame matching is
+ * an L1 ≤ 8px test, so both mask passes MUST run at these dims — the
+ * render canvas would miss every match. Mask `bounds` are cell-relative
+ * (the engine maps the path box onto whatever rect the cell renders
+ * at), so viewBox-space masks scale to any output canvas.
+ */
+function gridCanvasDims(grid) {
+    var _a, _b, _c, _d;
+    if (grid.viewBox && grid.viewBox.width > 0 && grid.viewBox.height > 0) {
+        return {
+            w: Math.round(grid.viewBox.width),
+            h: Math.round(grid.viewBox.height),
+        };
+    }
+    const xs = grid.xLines;
+    const ys = grid.yLines;
+    return {
+        w: Math.max(1, Math.round(((_a = xs[xs.length - 1]) !== null && _a !== void 0 ? _a : 1) - ((_b = xs[0]) !== null && _b !== void 0 ? _b : 0))),
+        h: Math.max(1, Math.round(((_c = ys[ys.length - 1]) !== null && _c !== void 0 ? _c : 1) - ((_d = ys[0]) !== null && _d !== void 0 ? _d : 0))),
+    };
+}
+/**
+ * Best-effort silhouette masks keyed by leaf StableKey (rect-only
+ * shapes need no mask and are absent). `generateMasks` THROWS on
+ * shape/frame mismatches (only `generateMasksByStableKey` degrades),
+ * so the whole pass is fenced: any failure → `{}` → every tile renders
+ * as its bounding rect. StableKeys are structural (canvas-independent),
+ * so the keys join against frames queried at any render canvas.
+ */
+function buildMasksByStableKey(grid, m0) {
+    try {
+        const { w, h } = gridCanvasDims(grid);
+        const maskSet = (0, dsl_stdlib_1.generateMasks)(grid, m0, {
+            canvasW: w,
+            canvasH: h,
+            clipToBounds: true,
+        });
+        return (0, dsl_stdlib_1.generateMasksByStableKey)(grid, m0, maskSet, w, h);
+    }
+    catch {
+        return {};
+    }
+}
+/* ── Bitmap mode (opt-in) ─────────────────────────────────────────── */
+/**
+ * Rasterize an SVG to a `res × res` binary silhouette grid. The SVG's ALPHA
+ * channel is the silhouette, so a logo of any ink converts (colour-agnostic).
+ * Its `res²` cells — many ON — become the bitmap m0 the animation stitches:
+ * the deliberately heavy, opt-in path for non-rectilinear marks that don't
+ * decompose into separately-animatable rectangles.
+ */
+async function rasterizeSvgToBinaryGrid(svgText, res) {
+    const { data, width, height } = await (0, svgRaster_1.renderSvgContainRgba)(svgText, res);
+    const info = { width, height };
+    // threshold 0 ⇒ luminance never gates, so every opaque pixel is ON and every
+    // transparent pixel (contain-padding / gaps) is OFF: a pure alpha silhouette.
+    return (0, dsl_stdlib_1.classifyPixels)(data, info.width, info.height, {
+        onMode: "light",
+        threshold: 0,
+        alphaThreshold: 128,
+    });
+}

package/dist/m0saic/media/logo-animate/v1/tutorial.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Logo Animate — the editor "?" tutorial.
+ *
+ * Answers the brand-new-user question: "How do I use this with MY logo,
+ * and what can it do?" Consumed by the Make "?" player AND
+ * `m0saic make <id> --tutorial`. SaaS-page beats (blur-regions precedent):
+ * copy column + visual, progress rail, one brand accent.
+ *
+ * The visuals are REAL: beats nest live logo-animate documents (built-in
+ * marks are baked SVGs and the vector pipeline is pure + sync), so the
+ * hero assembles, the modes beat loops/fills for real, and the marks beat
+ * shows the actual three built-ins — no mocks except the bitmap beat's
+ * pixel grid (rasterization is async/sharp, deliberately not embedded).
+ */
+import type { MosaicDocumentPipeline, MosaicEngineContext } from "@m0saic/types";
+export declare function renderLogoAnimateTutorial(ctx: MosaicEngineContext): MosaicDocumentPipeline;

package/dist/m0saic/media/logo-animate/v1/tutorial.js

@@ -0,0 +1,378 @@
+"use strict";
+/**
+ * Logo Animate — the editor "?" tutorial.
+ *
+ * Answers the brand-new-user question: "How do I use this with MY logo,
+ * and what can it do?" Consumed by the Make "?" player AND
+ * `m0saic make <id> --tutorial`. SaaS-page beats (blur-regions precedent):
+ * copy column + visual, progress rail, one brand accent.
+ *
+ * The visuals are REAL: beats nest live logo-animate documents (built-in
+ * marks are baked SVGs and the vector pipeline is pure + sync), so the
+ * hero assembles, the modes beat loops/fills for real, and the marks beat
+ * shows the actual three built-ins — no mocks except the bitmap beat's
+ * pixel grid (rasterization is async/sharp, deliberately not embedded).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderLogoAnimateTutorial = renderLogoAnimateTutorial;
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const screencap_grid_cover_1 = require("../../screencap_grid/v2/screencap-grid-cover");
+const expressions_1 = require("./expressions");
+const svg_source_1 = require("./svg-source");
+const layout_1 = require("./layout");
+const default_logo_1 = require("./default-logo");
+/** A hand-baked "your logo" for the bring-your-own beat: ascending bars +
+ *  a pennant triangle — deliberately NOT a m0saic brand mark (those live in
+ *  M0saic Brand Marks v3 at their dictionary-locked resolutions). The
+ *  triangle exercises the silhouette-mask path the beat's detail line
+ *  mentions. */
+const DEMO_SVG = `<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><rect x="0" y="9" width="4" height="7"/><rect x="6" y="5" width="4" height="11"/><rect x="12" y="0" width="4" height="16"/><rect x="0" y="4" width="4" height="3"/><path d="M6 3L10 3L8 0Z"/></svg>`;
+const TUTORIAL_FPS = 30;
+// SaaS palette (single dark look, brand accent — the blur-regions family).
+const P = {
+    bg: "#0a0c12",
+    surface: "#141926",
+    raised: "#1d2433",
+    border: "#2a3347",
+    accent: "#f97316",
+    accentSoft: "#fdba74",
+    textHi: "#f4f6fa",
+    textLo: "#aab3c2",
+    textMute: "#5d667a",
+};
+/**
+ * A live logo INLINED as a flat composition (m0 + sources spliced into the
+ * page lattice) — never a nested child: the child-composite pass emits a
+ * video-only deliverable that breaks the tutorial's audio concat, and
+ * nested procedural masks bleed seams (the donut-cover lesson). Returns
+ * null when the mark's lattice would CULL at this cell size (sub-pixel
+ * cells fold and fail the whole doc) — callers degrade to a labeled card.
+ *
+ * `cellW`/`cellH` are the slot's TRUE resolved pixels (the caller probes
+ * them via resolveDocFrames — never layout-parameter approximations, which
+ * is exactly how the gate-21 square-canvas stretch happened). The contain
+ * rect keeps the mark's EXACT intrinsic aspect and is centered on a px/4
+ * basis, so quantization drift is ≤4px per side: the founder's 1:1
+ * contract for square marks, held by construction and locked in tests.
+ */
+function inlineLogo(svg, animation, cellW, cellH) {
+    const logo = (0, svg_source_1.buildLogoGrid)(svg, { driftPercent: 2, packing: "multi" });
+    const masksByKey = (0, svg_source_1.buildMasksByStableKey)(logo.grid, logo.m0);
+    const contain = (0, layout_1.buildContainLayout)(Math.max(2, Math.round(cellW * 0.94)), Math.max(2, Math.round(cellH * 0.94)), logo.intrinsic.w, logo.intrinsic.h);
+    const native = (0, dsl_stdlib_1.queryFrames)(logo.m0, { width: logo.intrinsic.w * 4, height: logo.intrinsic.h * 4 }).logical().length;
+    const frames = (0, dsl_stdlib_1.queryFrames)(logo.m0, { width: contain.rect.w, height: contain.rect.h }).logical();
+    if (frames.length === 0 || frames.length < native)
+        return null; // would cull → degrade
+    const rankSet = (0, dsl_stdlib_1.generateStableKeyRankSet)((0, dsl_stdlib_1.rankFramesFromM0)(logo.m0, { canvasW: contain.rect.w, canvasH: contain.rect.h }), "diag");
+    const overlayFor = (rank) => {
+        switch (animation) {
+            case "assemble":
+                return {
+                    alpha: (0, expressions_1.buildModuleAlphaExpr)(rank, {
+                        spawnDurSec: 1.2,
+                        tileFadeSec: 0.25,
+                        exitStartSec: 9999, // no exit inside a tutorial beat
+                        fadeOutSec: 0.1,
+                    }),
+                };
+            case "logo_loop":
+                return {
+                    enable: (0, expressions_1.buildLoopEnableExpr)(rank, {
+                        loopSec: 2.4,
+                        inEnd: 0.25,
+                        outStart: 0.75,
+                        feather: 0.02,
+                        fps: TUTORIAL_FPS,
+                        startDelay: 0.1,
+                        endDelay: 0.2,
+                        easing: "smoothstep",
+                    }),
+                };
+            case "progress_fill":
+                return {
+                    enable: (0, expressions_1.buildProgressFillEnableExpr)(rank, {
+                        progressSec: 2.0,
+                        oneShot: false,
+                        feather: 0.02,
+                        fps: TUTORIAL_FPS,
+                    }),
+                };
+            case "shimmer":
+                return {
+                    enable: (0, expressions_1.buildShimmerEnableExpr)(rank, {
+                        shimmerSec: 1.4,
+                        shimmerWidth: 0.2,
+                        feather: 0.02,
+                        fps: TUTORIAL_FPS,
+                    }),
+                };
+            case "static":
+            default:
+                return undefined;
+        }
+    };
+    const sources = frames.map((f) => {
+        var _a;
+        const entry = masksByKey[String(f.meta.stableKey)];
+        const mask = entry
+            ? { kind: "inline-mask", localPath: entry.localPath, bounds: entry.bounds }
+            : undefined;
+        const overlay = overlayFor((_a = rankSet.ranks[String(f.meta.stableKey)]) !== null && _a !== void 0 ? _a : 0);
+        return (0, template_utils_1.makeColorTile)(P.accent, { ...(overlay ? { overlay } : {}), mask });
+    });
+    // Center the exact-aspect rect on a px/4 basis (never raw px — the
+    // px-per-weight ≥4 law; never percentage approximations — the stretch).
+    const u = (px) => Math.max(1, Math.round(px / 4));
+    const padW = Math.max(2, (cellW - contain.rect.w) / 2);
+    const padH = Math.max(2, (cellH - contain.rect.h) / 2);
+    const inner = { m0: logo.m0, sources };
+    const centered = (0, screencap_grid_cover_1.onboardingSplit)("col", [u(padW), u(contain.rect.w), u(padW)], [null, inner, null]);
+    return (0, screencap_grid_cover_1.onboardingSplit)("row", [u(padH), u(contain.rect.h), u(padH)], [null, centered, null]);
+}
+// ---------------------------------------------------------------------------
+// Small SaaS primitives (the blur-regions kit dialect).
+// ---------------------------------------------------------------------------
+function cardTile(color, opts = {}) {
+    return (0, screencap_grid_cover_1.onboardingLeaf)((0, template_utils_1.makeColorTile)(color, {
+        effects: {
+            ...(opts.radius != null ? { cornerRadius: opts.radius } : {}),
+            ...(opts.stroke ? { stroke: { color: opts.stroke, widthPx: 1 } } : {}),
+        },
+    }));
+}
+function padded(content, pad = 5) {
+    const mid = (0, screencap_grid_cover_1.onboardingSplit)("col", [pad, 100 - 2 * pad, pad], [null, content, null]);
+    return (0, screencap_grid_cover_1.onboardingSplit)("row", [pad, 100 - 2 * pad, pad], [null, mid, null]);
+}
+/** A live logo in a measured slot, with its degrade label. */
+function logoIn(slot, svg, animation, fallbackLabel, type) {
+    return slot((w, h) => {
+        var _a;
+        return (_a = inlineLogo(svg, animation, w, h)) !== null && _a !== void 0 ? _a : (0, screencap_grid_cover_1.onboardingSplit)("row", [2, 1, 2], [null, (0, screencap_grid_cover_1.onboardingLeaf)((0, screencap_grid_cover_1.onboardingTextSource)({ text: fallbackLabel, fontSize: type.body, color: P.accentSoft, label: `mark ${fallbackLabel.toLowerCase()}` })), null]);
+    });
+}
+function chip(text, type, active = false) {
+    return (0, screencap_grid_cover_1.onboardingOverlay)(cardTile(active ? P.accent : P.raised, { radius: 0.5 }), (0, screencap_grid_cover_1.onboardingLeaf)((0, screencap_grid_cover_1.onboardingTextSource)({ text, fontSize: type.micro, color: active ? P.bg : P.textLo, label: `chip ${text.toLowerCase()}` })));
+}
+/**
+ * Fit-first text block (the timeline-v2 pattern): wrap at the ramp font,
+ * then STEP THE FONT DOWN until every wrapped line's cell can hold its
+ * glyphs (line cell = 3/(3N+2) of the band; 1.18x headroom covers
+ * ascender/descender + leading + the analytic-vs-quantized cell drift). Fonts never clip — they shrink. The
+ * text-fit contract in tutorial.test.ts locks this at four canvases.
+ */
+function fittedTextBlock(args) {
+    const { bandPx, ...blockArgs } = args;
+    let font = args.fontSize;
+    for (let i = 0; i < 12; i++) {
+        const block = (0, screencap_grid_cover_1.onboardingTextBlock)({ ...blockArgs, fontSize: font });
+        const n = block.sources.length;
+        const lineCell = (bandPx * 3) / (3 * n + 2);
+        if (lineCell >= font * 1.32 || font <= 11)
+            return block;
+        font = Math.max(11, Math.floor(font * 0.92));
+    }
+    return (0, screencap_grid_cover_1.onboardingTextBlock)({ ...blockArgs, fontSize: font });
+}
+const BEATS = [
+    {
+        name: "hero",
+        durationMs: 4200,
+        eyebrow: "LOGO ANIMATE",
+        title: "Your logo, assembled.",
+        body: "Drop in an SVG and every shape becomes a tile on the canvas — then the tiles animate. What you see here is the template rendering itself.",
+        detail: "Real geometry, not baked pixels — the DSL view shows every shape",
+        buildVisual: (t, slot) => logoIn(slot, default_logo_1.DEFAULT_LOGO_SVG, "assemble", "Mosaic M", t),
+    },
+    {
+        name: "yoursvg",
+        durationMs: 5200,
+        eyebrow: "BRING YOUR OWN",
+        title: "Any flattened SVG works.",
+        body: "Pick your .svg with the Logo SVG file picker. Only <path> and <rect> shapes parse — in Inkscape: select all, Object to Path, ungroup, save as Plain SVG.",
+        detail: "Rectilinear marks convert exactly · curvy shapes get silhouette masks",
+        buildVisual: (t, slot) => {
+            const steps = (0, screencap_grid_cover_1.onboardingGuttered)("row", [chip("1 · Flatten to paths", t), chip("2 · Drop the .svg in", t), chip("3 · Pick an animation", t, true)], 10, 2);
+            return (0, screencap_grid_cover_1.onboardingSplit)("row", [13, 1, 6], [logoIn(slot, DEMO_SVG, "assemble", "your logo", t), null, steps]);
+        },
+    },
+    {
+        name: "modes",
+        durationMs: 5200,
+        eyebrow: "FIVE WAYS TO MOVE",
+        title: "One logo, five animations.",
+        body: "Assemble spawns the tiles in. Loop reveals seamlessly, forever. Progress fills like a loading bar, breathing pulses, shimmer sweeps a highlight.",
+        detail: "Left: loop · right: progress fill — both rendering live",
+        buildVisual: (t, slot) => {
+            const labeled = (anim, label) => (0, screencap_grid_cover_1.onboardingSplit)("col", [13, 1, 4], [
+                logoIn(slot, default_logo_1.DEFAULT_LOGO_SVG, anim, label, t),
+                null,
+                (0, screencap_grid_cover_1.onboardingSplit)("row", [8, 3, 8], [null, chip(label, t, true), null]),
+            ]);
+            return (0, screencap_grid_cover_1.onboardingGuttered)("row", [labeled("logo_loop", "logo_loop"), labeled("progress_fill", "progress_fill")], 12, 1);
+        },
+    },
+    {
+        name: "bitmap",
+        durationMs: 4600,
+        eyebrow: "CURVY LOGO?",
+        title: "Bitmap mode animates pixels.",
+        body: "A single-shape SVG has nothing to stagger — the template tells you so instead of rendering a static frame. Flip on Bitmap mode to rasterize the mark and animate it pixel-by-pixel.",
+        detail: "Precision: draft 32² to ultra 512² · higher = crisper, slower",
+        buildVisual: (_t, slot) => {
+            // Mock pixel-circle (rasterization is async — deliberately not
+            // embedded). Measured slot + px/4-centered SQUARE, and every pixel
+            // fades in on a diagonal stagger — the mock ASSEMBLES like bitmap
+            // mode actually does.
+            return slot((w, h) => {
+                const N = 11;
+                const rows = [];
+                for (let r = 0; r < N; r++) {
+                    const cells = [];
+                    const weights = [];
+                    for (let c = 0; c < N; c++) {
+                        const dx = c - (N - 1) / 2;
+                        const dy = r - (N - 1) / 2;
+                        const inside = Math.sqrt(dx * dx + dy * dy) <= N / 2 - 0.4;
+                        cells.push(inside
+                            ? (0, screencap_grid_cover_1.onboardingLeaf)((0, template_utils_1.makeColorTile)(P.accent, {
+                                effects: { cornerRadius: 0.14 },
+                                overlay: { alpha: (0, template_utils_1.fadeInExpr)(0.2 + (r + c) * 0.09, 0.22) },
+                            }))
+                            : null);
+                        weights.push(1);
+                    }
+                    rows.push((0, screencap_grid_cover_1.onboardingSplit)("col", weights, cells));
+                }
+                const grid = (0, screencap_grid_cover_1.onboardingSplit)("row", Array(N).fill(1), rows);
+                const side = Math.max(2, Math.round(Math.min(w, h) * 0.9));
+                const u = (px) => Math.max(1, Math.round(px / 4));
+                const padW = Math.max(2, (w - side) / 2);
+                const padH = Math.max(2, (h - side) / 2);
+                const centered = (0, screencap_grid_cover_1.onboardingSplit)("col", [u(padW), u(side), u(padW)], [null, grid, null]);
+                return (0, screencap_grid_cover_1.onboardingSplit)("row", [u(padH), u(side), u(padH)], [null, centered, null]);
+            });
+        },
+    },
+    {
+        name: "finish",
+        durationMs: 3800,
+        eyebrow: "MAKE IT YOURS",
+        title: "Order, color, aspect.",
+        body: "Order picks the sweep: diag, scatter, cascade, radial. Presets pair ink and background — or override both. Render at your logo's own aspect for an undistorted mark.",
+        detail: "MAKE renders exactly what the preview shows",
+        buildVisual: (t, _slot, w) => {
+            // Width-capped row font vs the TRUE text cell (17/20 of the padded
+            // card): the knob list must never clip at narrow canvases (960-wide
+            // caught by the text-fit contract).
+            const rowTextW = w * 0.86 * (17 / 20);
+            const row = (text) => {
+                const font = Math.max(11, Math.min(t.body, Math.floor((rowTextW * 0.94) / (text.length * 0.62))));
+                return (0, screencap_grid_cover_1.onboardingSplit)("col", [2, 1, 17], [
+                    cardTile(P.accent, { radius: 0.5 }),
+                    null,
+                    (0, screencap_grid_cover_1.onboardingLeaf)((0, screencap_grid_cover_1.onboardingTextSource)({ text, fontSize: font, color: P.textLo, hAlign: "left", label: text.slice(0, 22).toLowerCase() })),
+                ]);
+            };
+            const rows = (0, screencap_grid_cover_1.onboardingGuttered)("row", [
+                row("Order: diag · scatter · cascade · radial"),
+                row("Light / dark presets, or your own ink + background"),
+                row("fit: contain letterboxes · fill stretches"),
+                row("Match the canvas to your logo's aspect"),
+            ], 10, 2);
+            return (0, screencap_grid_cover_1.onboardingOverlay)(cardTile(P.surface, { radius: 0.08, stroke: P.border }), padded(rows, 7));
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Page assembly (the blur-regions static-beat dialect).
+// ---------------------------------------------------------------------------
+function beatProgress(index, type) {
+    const dots = (0, screencap_grid_cover_1.onboardingGuttered)("col", BEATS.map((_, i) => cardTile(i === index ? P.accent : i < index ? "#7c4a12" : P.border, { radius: 0.5 })), 3, 2);
+    const counter = (0, screencap_grid_cover_1.onboardingLeaf)((0, screencap_grid_cover_1.onboardingTextSource)({ text: `${index + 1} / ${BEATS.length}`, fontSize: type.micro, color: P.textLo, hAlign: "left", label: "tutorial progress" }));
+    return (0, screencap_grid_cover_1.onboardingSplit)("col", [30, 12, 16, 30, 12], [null, counter, null, dots, null]);
+}
+function buildBeat(spec, index, canvasW, canvasH) {
+    const type = (0, screencap_grid_cover_1.onboardingTypeRamp)(canvasW, canvasH);
+    const stacked = canvasH > canvasW * 0.9;
+    // TRUE copy-column width from the authored lattice fractions below —
+    // never an estimate (the 0.4 legacy estimate let 960-wide canvases skip
+    // the wrap and clip horizontally; the text-fit contract caught it).
+    const copyWidth = stacked ? canvasW * 0.86 : canvasW * 0.34;
+    const visualW = Math.round(canvasW * (stacked ? 0.88 : 0.51));
+    const visualH = Math.round(canvasH * (stacked ? 0.47 : 0.83));
+    const assemblePage = (slot) => {
+        const visual = spec.buildVisual(type, slot, visualW, visualH);
+        // Copy bands in px (fractions ARE the authored lattice below): the
+        // fit-first blocks size their fonts against these, so no canvas can
+        // clip a line (the gate-21 bitmap-title catch).
+        const copyH = Math.round(canvasH * (stacked ? 0.33 : 0.83));
+        const bandPx = (weight) => (copyH * weight) / 56;
+        const copy = (0, screencap_grid_cover_1.onboardingSplit)("row", [3, 4, 15, 20, 3, 6, 5], [
+            null,
+            fittedTextBlock({ text: spec.eyebrow, fontSize: type.label, color: P.accent, cellWidthPx: copyWidth, bandPx: bandPx(4), hAlign: "left", fadeDelaySec: 0.04, label: "beat eyebrow" }),
+            fittedTextBlock({ text: spec.title, fontSize: type.headline, color: P.textHi, cellWidthPx: copyWidth, bandPx: bandPx(15), hAlign: "left", widthFrac: 0.9, fadeDelaySec: 0.08, label: "beat title" }),
+            fittedTextBlock({ text: spec.body, fontSize: type.body, color: P.textLo, cellWidthPx: copyWidth, bandPx: bandPx(20), hAlign: "left", widthFrac: 0.91, fadeDelaySec: 0.12, label: "beat body" }),
+            null,
+            fittedTextBlock({ text: spec.detail, fontSize: type.micro, color: P.accentSoft, cellWidthPx: copyWidth, bandPx: bandPx(6), hAlign: "left", fadeDelaySec: 0.16, label: "beat detail" }),
+            null,
+        ]);
+        const progress = beatProgress(index, type);
+        return stacked
+            ? (0, screencap_grid_cover_1.onboardingSplit)("row", [5, 33, 3, 47, 3, 4, 5], [null, (0, screencap_grid_cover_1.onboardingSplit)("col", [7, 86, 7], [null, copy, null]), null, (0, screencap_grid_cover_1.onboardingSplit)("col", [6, 88, 6], [null, visual, null]), null, progress, null])
+            : (0, screencap_grid_cover_1.onboardingSplit)("row", [7, 83, 2, 5, 3], [null, (0, screencap_grid_cover_1.onboardingSplit)("col", [5, 34, 4, 51, 6], [null, copy, null, visual, null]), null, progress, null]);
+    };
+    const cardShell = (content) => (0, screencap_grid_cover_1.onboardingOverlay)(cardTile(P.surface, { radius: 0.06, stroke: P.border }), padded(content, 6));
+    // ── Pass 1: probe. Each slot places a bare tile inside the SAME card
+    // chrome as the real slot, so its resolved frame IS the logo cell —
+    // true pixels, not layout-parameter estimates (the square-canvas
+    // stretch came from estimating).
+    const probeTiles = [];
+    const probePage = assemblePage(() => {
+        const tile = (0, template_utils_1.makeColorTile)(P.raised);
+        probeTiles.push(tile);
+        return cardShell((0, screencap_grid_cover_1.onboardingLeaf)(tile));
+    });
+    const probed = (0, template_utils_1.resolveDocFrames)({ kind: "mosaic_document", version: 1, m0: probePage.m0, sources: probePage.sources, assets: {} }, canvasW, canvasH);
+    const slotFrames = probeTiles.map((t) => probed.framesByLogical[probePage.sources.indexOf(t)]);
+    // ── Pass 2: real. Each slot's builder receives its probed TRUE pixels.
+    let slotIdx = 0;
+    const page = assemblePage((build) => {
+        const frame = slotFrames[slotIdx++];
+        const content = frame
+            ? build(Math.round(frame.width), Math.round(frame.height))
+            : build(320, 240); // probe miss — arbitrary sane cell, never expected
+        return cardShell(content);
+    });
+    return {
+        doc: {
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            size: { width: canvasW, height: canvasH },
+            backgroundColor: P.bg,
+            m0: page.m0,
+            sources: page.sources,
+        },
+        durationMs: spec.durationMs,
+    };
+}
+function renderLogoAnimateTutorial(ctx) {
+    var _a;
+    const W = Math.max(1, Math.round(ctx.target.width));
+    const H = Math.max(1, Math.round(ctx.target.height));
+    const steps = BEATS.map((spec, i) => {
+        const { doc, durationMs } = buildBeat(spec, i, W, H);
+        return { name: spec.name, label: spec.title, durationMs, file: doc };
+    });
+    return {
+        kind: "mosaic_pipeline",
+        version: 1,
+        fps: (_a = ctx.target.fps) !== null && _a !== void 0 ? _a : TUTORIAL_FPS,
+        durationMs: steps.reduce((a, s) => a + s.durationMs, 0),
+        defaultTransition: { type: "cut" },
+        backgroundColor: P.bg,
+        steps,
+    };
+}

package/dist/m0saic/media/metadata-stamp/index.d.ts

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

package/dist/m0saic/media/metadata-stamp/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);

package/dist/m0saic/media/metadata-stamp/v1/format-date.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure, machine-independent timestamp helpers for
+ * `@m0saic/media/metadata-stamp/v1`.
+ *
+ * Container creation tags arrive as ISO-8601 strings from the engine's
+ * ffprobe pass (`ctx.media[...]`). These helpers parse and format them
+ * WITHOUT `Date.parse`-on-naive-strings, `toLocale*`, or `Intl` — all of
+ * which read machine locale/timezone and would break byte-identical
+ * renders (agent contract §9). A wall time with no zone designator is
+ * treated as UTC, never as local time.
+ */
+/** Apple's QuickTime creation tag — carries the local UTC offset. */
+export declare const APPLE_CREATION_TAG = "com.apple.quicktime.creationdate";
+/** The generic MP4/MOV creation tag — normalized to UTC by ffmpeg. */
+export declare const CREATION_TIME_TAG = "creation_time";
+/** Date-format presets. English month names, fixed — no locale reads. */
+export declare const STAMP_DATE_FORMATS: readonly ["YYYY-MM-DD", "YYYY-MM-DD HH:mm", "MMM D, YYYY", "D MMM YYYY", "MM/DD/YYYY", "DD.MM.YYYY"];
+export type StampDateFormat = (typeof STAMP_DATE_FORMATS)[number];
+/** A parsed creation timestamp: absolute instant + authored offset (if any). */
+export type ParsedVideoTimestamp = {
+    /** Epoch milliseconds (UTC instant). */
+    epochMs: number;
+    /** UTC offset the tag carried, minutes east of UTC; null = none stated. */
+    offsetMinutes: number | null;
+};
+/** The subset of `MosaicMediaMetadata` the tag extraction reads. */
+export type CreationTagCarrier = {
+    /** Merged format + stream tags. */
+    tags?: Record<string, string | undefined>;
+    format?: {
+        tags?: Record<string, string | undefined>;
+    };
+};
+/**
+ * Pull the raw creation-timestamp string off probed metadata. Prefers
+ * the Apple key (it keeps the local UTC offset the camera stamped);
+ * falls back to `creation_time` (UTC). Returns null when neither tag is
+ * present — a common, normal case (transcoded or stripped files).
+ */
+export declare function extractCreationTimestampRaw(meta: CreationTagCarrier | undefined): string | null;
+/**
+ * Parse a creation-tag string into an absolute instant + stated offset.
+ * Missing zone designator = UTC (deterministic; NEVER local time).
+ * Returns null for anything malformed or out of range.
+ */
+export declare function parseVideoTimestamp(raw: string | null | undefined): ParsedVideoTimestamp | null;
+/**
+ * Format a parsed timestamp. The rendered wall time uses, in order:
+ * the explicit `utcOffsetMinutes` override, the offset the tag carried,
+ * else UTC. `new Date(number)` + `getUTC*` only — pure epoch math.
+ */
+export declare function formatVideoTimestamp(ts: ParsedVideoTimestamp, format: StampDateFormat, utcOffsetMinutes?: number | null): string;