@m0saic/templates 0.2.0

package/dist/m0saic/meta/upstream-echo/v1/upstream-echo.d.ts

@@ -0,0 +1,52 @@
+import type { MosaicTemplateOutputs, MosaicTemplateUpstreamData, MosaicTemplateUpstreamVariables } from "@m0saic/types";
+/**
+ * `@m0saic/meta/upstream-echo/v1` — the consumer half of the
+ * capability-layer proof pair (producer: `@m0saic/meta/fixture-fetcher/v1`).
+ *
+ * Core-tier renderable that:
+ *
+ *  - reads the aliased data block `ctx.upstreamData[alias]` plus the
+ *    flat `ctx.upstreamVariables` union (whatever cross-step /
+ *    cross-tile threading delivered);
+ *  - renders a SELF-EVIDENCING status card (duration/fps from
+ *    `ctx.target` via the define-wrapper stamp): pale-green
+ *    background + "UPSTREAM OK" + a deterministic summary of the
+ *    received block when the aliased data arrived; red background +
+ *    "UPSTREAM MISSING" + what WAS available when it didn't — so a
+ *    human eyeballing the rendered tile can read the verdict without
+ *    opening the sidecar;
+ *  - mirrors EXACTLY what it received into `sidecars.upstreamEcho`,
+ *    so e2e suites can byte-assert the data that crossed the
+ *    pipeline boundary;
+ *  - declares `upstreamVariablesSchema` / `upstreamDataSchema`,
+ *    exercising the resolver's VARIABLES_SCHEMA_MISMATCH guard: a
+ *    pipeline that wires it after the fixture-fetcher resolves
+ *    cleanly; a mis-wired pipeline (no producer, wrong alias, drifted
+ *    types) errors at resolve time.
+ *
+ * Standalone renders (no upstream at all) are also fine — the
+ * resolver only checks schemas on invocation paths; the tile then
+ * shows the red MISSING card and the sidecar records both channels
+ * as absent.
+ */
+export type UpstreamEchoProps = {
+    /** Aliased data block to echo. Default `"fixtureData"`. */
+    alias?: string;
+    /**
+     * Optional background OVERRIDE (#rrggbb). Unset → semantic colors:
+     * pale green when the aliased block arrived, red when it didn't.
+     */
+    color?: string;
+};
+/** Semantic backgrounds (exported so tests pin the exact values). */
+export declare const UPSTREAM_ECHO_OK_BG = "#d9efd9";
+export declare const UPSTREAM_ECHO_MISSING_BG = "#a03030";
+type UpstreamEchoSidecars = {
+    upstreamEcho: {
+        alias: string;
+        upstreamData: Record<string, unknown> | null;
+        upstreamVariables: Record<string, unknown> | null;
+    };
+};
+export declare const UpstreamEcho: import("@m0saic/types").MosaicTemplate<UpstreamEchoProps, MosaicTemplateOutputs, MosaicTemplateUpstreamVariables, MosaicTemplateUpstreamData, UpstreamEchoSidecars>;
+export default UpstreamEcho;

package/dist/m0saic/meta/upstream-echo/v1/upstream-echo.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpstreamEcho = exports.UPSTREAM_ECHO_MISSING_BG = exports.UPSTREAM_ECHO_OK_BG = void 0;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+/** Semantic backgrounds (exported so tests pin the exact values). */
+exports.UPSTREAM_ECHO_OK_BG = "#d9efd9";
+exports.UPSTREAM_ECHO_MISSING_BG = "#a03030";
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    alias: {
+        type: "string",
+        required: false,
+        description: 'Which ctx.upstreamData block to echo into the sidecar. Default "fixtureData".',
+    },
+    color: {
+        meta: { constraints: { isColor: true }, control: { placeholder: "green when found, red when missing", colorPicker: true } },
+        type: "string",
+        required: false,
+        description: "Optional background override (#rrggbb). Unset: pale green when the aliased upstream block arrived, red when it didn't.",
+    },
+});
+// U / D stay at the loose defaults: narrowing them would break
+// contravariance with `registerTemplate` (which accepts the loose
+// form) — a common trade-off for data-fetcher templates. The
+// consumed shapes are documented via upstreamVariablesSchema /
+// upstreamDataSchema below instead.
+exports.UpstreamEcho = (0, template_utils_1.defineMosaicTemplate)({
+    id: (0, types_1.asTemplateId)("@m0saic/meta/upstream-echo/v1"),
+    label: "Upstream Echo (internal)",
+    version: 1,
+    description: "Consumer proof fixture: reads ctx.upstreamData[alias] + ctx.upstreamVariables, renders a self-evidencing status card (pale green 'UPSTREAM OK' + block summary, or red 'UPSTREAM MISSING'), and mirrors the received upstream into sidecars.upstreamEcho for byte-assertable verification. Declares upstream schemas to exercise the resolver's schema guard.",
+    capabilities: { tier: "core" },
+    tags: ["developer", "meta", "fixture", "upstream", "internal"],
+    internal: true,
+    outputHints: {
+        width: 640,
+        height: 360,
+        fps: 30,
+        durationMs: 1000,
+        note: "Status-card echo tile (green=upstream OK, red=missing); the byte-assertable payload is the sidecar mirror.",
+    },
+    // Consumer contracts — exercised by the resolver's schema guard on
+    // invocation paths. The fixture-fetcher's DEFAULT payload satisfies
+    // the fixtureData block; keys are declared with the types the
+    // default payload carries. Flat-union keys stay optional so the
+    // echo also renders standalone (no producer) without diagnostics.
+    upstreamVariablesSchema: {
+        dataset: { type: "string", required: false },
+        series: { type: "number[]", required: false },
+    },
+    upstreamDataSchema: {
+        fixtureData: {
+            description: "Data block published by @m0saic/meta/fixture-fetcher/v1 under its default alias.",
+            variables: {
+                dataset: { type: "string", required: false },
+                version: { type: "number", required: false },
+                series: { type: "number[]", required: false },
+            },
+        },
+    },
+    propsSchema,
+    // `color` deliberately absent: its deterministic default is the
+    // SEMANTIC background (green when upstream arrived, red when not),
+    // derived in render — a fixed default would defeat the status card.
+    defaultProps: {
+        alias: "fixtureData",
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d;
+        const alias = (_a = props.alias) !== null && _a !== void 0 ? _a : "fixtureData";
+        if (props.color !== undefined && !/^#[0-9a-fA-F]{6}$/.test(props.color)) {
+            throw new Error(`meta/upstream-echo: color ${JSON.stringify(props.color)} must be a #rrggbb hex color.`);
+        }
+        const upstreamData = (_b = (0, template_utils_1.getUpstreamBlock)(ctx, alias)) !== null && _b !== void 0 ? _b : null;
+        const upstreamVariables = (_c = (0, template_utils_1.getUpstreamVariables)(ctx)) !== null && _c !== void 0 ? _c : null;
+        // ── Self-evidencing status card ─────────────────────────────
+        // Green + summary when the aliased block arrived; red + diagnosis
+        // when it didn't. All lines deterministic (sorted keys, counts).
+        const ok = upstreamData !== null;
+        const bg = ((_d = props.color) !== null && _d !== void 0 ? _d : (ok ? exports.UPSTREAM_ECHO_OK_BG : exports.UPSTREAM_ECHO_MISSING_BG));
+        const fg = (ok && props.color === undefined ? "#1e3a26" : "#fff5f5");
+        const flatKeyCount = Object.keys(upstreamVariables !== null && upstreamVariables !== void 0 ? upstreamVariables : {}).length;
+        const bodyLines = ok
+            ? [
+                `alias: ${alias}`,
+                `block keys: ${Object.keys(upstreamData).sort().join(", ") || "(none)"}`,
+                `flat union keys: ${flatKeyCount}`,
+            ]
+            : [
+                `alias: ${alias}`,
+                `available blocks: ${(0, template_utils_1.listUpstreamAliases)(ctx).join(", ") || "(none)"}`,
+                `flat union keys: ${flatKeyCount}`,
+            ];
+        // Generous fixed sizes + margins — app text-fit runs wider than CLI.
+        const titleFont = 34;
+        const bodyFont = 20;
+        const layers = [
+            {
+                content: { kind: "literal", text: ok ? "UPSTREAM OK" : "UPSTREAM MISSING" },
+                style: { fontSize: titleFont, fontColor: fg },
+                placement: { hAlign: "left", vAlign: "top", xExpr: "w*0.06", yExpr: "h*0.08" },
+            },
+            ...bodyLines.map((text, i) => ({
+                content: { kind: "literal", text },
+                style: { fontSize: bodyFont, fontColor: fg },
+                placement: {
+                    hAlign: "left",
+                    vAlign: "top",
+                    xExpr: "w*0.06",
+                    yExpr: `h*${(0.32 + i * 0.14).toFixed(2)}`,
+                },
+            })),
+        ];
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            m0: (0, dsl_stdlib_1.toM0String)("F", "upstreamEcho"),
+            assets: {},
+            sources: [
+                // Layer 1 (`alias: …`) SHOWS the alias prop — bind that layer so Make's
+                // double-click edits it in place.
+                (0, template_utils_1.bindProps)({ type: "text", visual: { backgroundColor: bg }, layers }, [
+                    { propKey: "alias", layer: 1 },
+                ]),
+            ],
+            sidecars: {
+                upstreamEcho: {
+                    alias,
+                    upstreamData,
+                    upstreamVariables,
+                },
+            },
+        };
+    },
+});
+(0, template_utils_1.registerTemplate)(exports.UpstreamEcho);
+exports.default = exports.UpstreamEcho;

package/dist/m0saic/primitives/grid/index.d.ts

@@ -0,0 +1,2 @@
+export { PrimitiveGrid } from "./v1/grid";
+export { PrimitiveGridV2 } from "./v2/grid";

package/dist/m0saic/primitives/grid/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrimitiveGridV2 = exports.PrimitiveGrid = void 0;
+var grid_1 = require("./v1/grid");
+Object.defineProperty(exports, "PrimitiveGrid", { enumerable: true, get: function () { return grid_1.PrimitiveGrid; } });
+var grid_2 = require("./v2/grid");
+Object.defineProperty(exports, "PrimitiveGridV2", { enumerable: true, get: function () { return grid_2.PrimitiveGridV2; } });

package/dist/m0saic/primitives/grid/v1/grid.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ============================================================================
+ * @m0saic/primitives/grid/v1
+ * ============================================================================
+ *
+ * A reusable gridline overlay primitive.
+ *
+ * Renders thin lavfi strips as an overlay paint stack:
+ *   base (transparent) -> line1 -> line2 -> ... -> lineN
+ *
+ * - Does NOT own background fills.
+ * - Does NOT render a baseline (callers can layer their own baseline above/below).
+ * - Does NOT animate.
+ * - Designed to be composed inside higher-level templates (charts, dashboards, frames).
+ *
+ * Counting semantics:
+ * - `count` is the number of equal intervals across the axis.
+ * - When `excludeEdges=true`, we render interior lines only:
+ *     i = 1..count-1  => (count-1) lines
+ * - When `excludeEdges=false`, we render edges too:
+ *     i = 0..count    => (count+1) lines
+ *
+ * Axis / origin semantics:
+ * - direction="horizontal" positions lines by Y fraction.
+ * - direction="vertical"   positions lines by X fraction.
+ * - origin controls how the fraction is interpreted:
+ *     - for horizontal: "top" or "bottom"
+ *     - for vertical:   "left" or "right"
+ *
+ * Implementation detail:
+ * - Each line is generated as an intrinsic strip (fitMode="content") sized via TW/TH.
+ * - Positioning uses tile-local overlay offsets (W/H) for deterministic placement.
+ *
+ * Why placeRects, not a "portable" weightedSplit (measured):
+ * - For THIN LINES a placeRects grid is pixel-EXACT (~0px spread) at every
+ *   size/count, while the interleaved gap/line weightedSplit ranges from fine
+ *   (~0.5px) to CATASTROPHIC (count=6 @ 400px → ~67px; count=8 @ 333px → ~42px) —
+ *   the basis sits ≈ the axis length and any mismatch spreads wildly. So there is
+ *   no imperceptible-weightedSplit to fall back to here; placeRects strictly wins.
+ *   (See `dsl-stdlib` `quantizationSpread` + its test for the matrix.) The general
+ *   "weightedSplit when imperceptible, else placeRects" rule still pays off for
+ *   REGION layouts with small natural bases — just not for thin-line grids.
+ *
+ * RESOLUTION-AWARE — pass a `slot` when exact alignment matters:
+ * - The single-axis path computes ABSOLUTE pixel line positions from `ctx.target`
+ *   (see `buildAxisSplitGrid`), rounding each boundary independently so gaps are
+ *   exact at the rendered size. The emitted m0 is still a weighted-band split, so
+ *   for EVEN divisions the lines stay uniform even if the grid is later scaled into
+ *   a different-size cell (proportional bands scale uniformly — verified: bar-graph
+ *   nests this with bare `ctx` and its gaps are uniform to ≤0.5px at odd canvases).
+ * - Pass `renderNestedTemplate(..., ctx, { slot: { width, height } })` with the
+ *   grid's REAL rendered px whenever the grid must align with SIBLING geometry at
+ *   exact pixels, or line THICKNESS must be exact for the cell — compute at the
+ *   slot, don't let the grid bake the parent-canvas dims and scale in.
+ * - Canonical example: line-chart `chrome.ts` `renderGrid` passes
+ *   `{ slot: { width: plotW, height: plotH } }` so its gridlines line up with the
+ *   data layer's plot rect.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+export type PrimitiveGridDirection = "horizontal" | "vertical" | "both";
+export type PrimitiveGridOrigin = "top" | "bottom" | "left" | "right";
+export type PrimitiveGridProps = {
+    show?: boolean;
+    /** Number of equal intervals across the chosen axis. */
+    count?: number;
+    /** Which axes to draw. */
+    direction?: PrimitiveGridDirection;
+    /**
+     * Fraction origin for placement.
+     * - horizontal: "bottom" (chart-style) or "top" (screen-style)
+     * - vertical:   "left" (screen-style) or "right"
+     */
+    origin?: PrimitiveGridOrigin;
+    /** Exclude the outer boundary lines. Default true. */
+    excludeEdges?: boolean;
+    /** Line color (FFmpeg-compatible). */
+    color?: MosaicColor;
+    /** Constant opacity multiplier (0..1). */
+    opacity?: number;
+    /** Thickness as a fraction of the short side. Engine clamps to >= 1px. */
+    thicknessFrac?: number;
+};
+export declare const PRIMITIVE_GRID_TEMPLATE_ID: import("@m0saic/types").TemplateId;
+export declare const PrimitiveGrid: MosaicTemplate<PrimitiveGridProps>;

package/dist/m0saic/primitives/grid/v1/grid.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrimitiveGrid = exports.PRIMITIVE_GRID_TEMPLATE_ID = void 0;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    show: {
+        type: "boolean",
+        required: false,
+        description: "Whether the grid renders. Default true.",
+    },
+    count: {
+        type: "number",
+        required: false,
+        description: "Number of equal intervals across the axis. Default 5.",
+    },
+    direction: {
+        type: "string",
+        required: false,
+        description: 'Which axes to draw: "horizontal" | "vertical" | "both". Default "horizontal".',
+    },
+    origin: {
+        type: "string",
+        required: false,
+        description: 'Origin for fractions: "top" | "bottom" | "left" | "right". Default depends on direction.',
+    },
+    excludeEdges: {
+        type: "boolean",
+        required: false,
+        description: "If true, do not render the outer boundary lines. Default true.",
+    },
+    color: {
+        type: "string",
+        required: false,
+        description: "Line color (FFmpeg-compatible). Default #ffffff.",
+        meta: { constraints: { isColor: true }, control: { colorPicker: true } },
+    },
+    opacity: {
+        type: "number",
+        required: false,
+        description: "Line opacity multiplier (0..1). Default 0.12.",
+    },
+    thicknessFrac: {
+        type: "number",
+        required: false,
+        description: "Line thickness fraction. Default 0.002.",
+    },
+});
+exports.PRIMITIVE_GRID_TEMPLATE_ID = (0, types_1.asTemplateId)("@m0saic/primitives/grid/v1");
+const DEFAULT_COLOR = "#ffffff";
+const DEFAULT_OPACITY = 0.12;
+const DEFAULT_THICKNESS_FRAC = 0.002;
+const DEFAULT_COUNT = 5;
+exports.PrimitiveGrid = {
+    id: exports.PRIMITIVE_GRID_TEMPLATE_ID,
+    label: "Primitive — Grid",
+    version: 1,
+    internal: false,
+    primitive: true, // reusable layout building block composed into other templates
+    description: "Reusable gridline overlay primitive (horizontal/vertical/both) for composition into templates.",
+    capabilities: { tier: "core" },
+    deprecated: {
+        reason: "The 'absolute → fine ratio' anti-pattern: the single-axis path computes each line's ABSOLUTE pixel position from ctx.target, then re-encodes them as a placeRects split whose basis ≈ the plot dimension in px. Renders exactly STANDALONE but the per-pixel basis does NOT nest — the engine re-divides it below 1px at certain canvases (e.g. 1024², 1000²) and the grid is SILENTLY DROPPED. Kept registered as a 'what not to do' reference. Use v2 — thin fixed-px strips at proportional overlay offsets (ratio positioning) that compose at any canvas.",
+        replacement: (0, types_1.asTemplateId)("@m0saic/primitives/grid/v2"),
+        since: "2026-07-07",
+    },
+    tags: ["primitive", "grid"],
+    propsSchema,
+    defaultProps: {
+        show: true,
+        count: DEFAULT_COUNT,
+        direction: "horizontal",
+        origin: "bottom",
+        excludeEdges: true,
+        color: DEFAULT_COLOR,
+        opacity: DEFAULT_OPACITY,
+        thicknessFrac: DEFAULT_THICKNESS_FRAC,
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f;
+        const show = props.show !== false;
+        const count = Math.max(0, Math.floor((_a = props.count) !== null && _a !== void 0 ? _a : DEFAULT_COUNT));
+        if (!show || count <= 1) {
+            return {
+                kind: "mosaic_document",
+                version: 1,
+                assets: {},
+                m0: (0, template_utils_1.buildOverlayStack)(1),
+                sources: [(0, template_utils_1.transparentSlot)()], durationMs: ctx.target.durationMs,
+            };
+        }
+        const direction = (_b = props.direction) !== null && _b !== void 0 ? _b : "horizontal";
+        const color = (_c = props.color) !== null && _c !== void 0 ? _c : DEFAULT_COLOR;
+        const opacity = (_d = props.opacity) !== null && _d !== void 0 ? _d : DEFAULT_OPACITY;
+        const thicknessFrac = (_e = props.thicknessFrac) !== null && _e !== void 0 ? _e : DEFAULT_THICKNESS_FRAC;
+        const excludeEdges = props.excludeEdges !== false;
+        // ---- Single-axis fast path (row/col split) ------------------------
+        //
+        // The legacy implementation emits one lavfi-strip-overlay per line and
+        // stacks them with buildOverlayStack(), which expands to a nested
+        // overlay chain (F{F{F{...}}}) — every line costs one ffmpeg overlay
+        // op. For N=5 grid lines that is N+1 nested overlays *just for the
+        // grid*, multiplied across every chunk in the render plan.
+        //
+        // For "horizontal" / "vertical" we instead express the grid as a
+        // single row/col split: thin line cells (weight 1) separated by
+        // wide gap cells (weight derived from thicknessFrac), with spacer
+        // tokens for the gaps. One composition op, N sources.
+        //
+        //   m0 vertical-bars horizontal-grid example (count=5, excludeEdges):
+        //     row-split, weights [99,1,99,1,99,1,99,1,99]
+        //     claimants            [ - , 1 , - , 1 , - , 1 , - , 1 , - ]
+        //
+        // "both" still walks the legacy overlay path — it's not on the chart
+        // hot path today and the layout would be a nested split (out of scope
+        // for this optimisation).
+        if (direction === "horizontal" || direction === "vertical") {
+            return buildAxisSplitGrid({
+                direction,
+                count,
+                excludeEdges,
+                color,
+                opacity,
+                thicknessFrac,
+                ctx,
+            });
+        }
+        // ---- Legacy overlay-stack path (only direction="both") ------------
+        // direction is narrowed to "both" here; the single-axis fast path
+        // already returned above. We render both axes by composing two
+        // gridline sets with the legacy overlay-stack model.
+        const origin = (_f = props.origin) !== null && _f !== void 0 ? _f : "bottom";
+        const lines = [];
+        const horizOrigin = origin === "top" ? "top" : "bottom";
+        lines.push(...(0, template_utils_1.buildGridlineSources)({
+            direction: "horizontal",
+            count,
+            excludeEdges,
+            origin: horizOrigin,
+            color,
+            opacity,
+            thicknessFrac,
+        }));
+        const vertOrigin = origin === "right" ? "right" : "left";
+        lines.push(...(0, template_utils_1.buildGridlineSources)({
+            direction: "vertical",
+            count,
+            excludeEdges,
+            origin: vertOrigin,
+            color,
+            opacity,
+            thicknessFrac,
+        }));
+        const sources = [(0, template_utils_1.transparentSlot)(), ...lines];
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            sources,
+            assets: {},
+            m0: (0, template_utils_1.buildOverlayStack)(sources.length),
+            durationMs: ctx.target.durationMs,
+        };
+    },
+};
+function buildAxisSplitGrid(opts) {
+    const { direction, count, excludeEdges, color, opacity, thicknessFrac, ctx } = opts;
+    // QUANTIZATION-FREE gridlines: instead of one interleaved [gap,line,gap,…]
+    // split (a small weight basis that doesn't divide the axis → the remainder
+    // spreads and lines drift), compute each line's ABSOLUTE pixel position by
+    // even division, then `placeRects` a thin rect at each. The placeRects band
+    // weights are pixels that sum to the axis length, so the render is exact —
+    // lines are uniformly spaced at any resolution / cell count.
+    // (Resolution-dependent by design: uses the slot's `ctx.target` dims.)
+    const W = Math.max(1, Math.round(ctx.target.width));
+    const H = Math.max(1, Math.round(ctx.target.height));
+    const horizontal = direction === "horizontal";
+    const axisLen = horizontal ? H : W; // lines are spaced along this axis
+    const span = horizontal ? W : H; //    lines span the cross axis fully
+    const th = Math.max(1, Math.round(thicknessFrac * Math.min(W, H)));
+    // Line indices at even-division boundaries. excludeEdges → interior only
+    // (1..count-1); else include the 0 and count edges.
+    const lo = excludeEdges ? 1 : 0;
+    const hi = excludeEdges ? count - 1 : count;
+    const rects = [];
+    for (let i = lo; i <= hi; i++) {
+        const pos = Math.max(0, Math.min(axisLen - th, Math.round((i / count) * axisLen) - Math.floor(th / 2)));
+        rects.push(horizontal ? { x: 0, y: pos, w: span, h: th, claimant: "1" } : { x: pos, y: 0, w: th, h: span, claimant: "1" });
+    }
+    if (rects.length === 0) {
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0: (0, template_utils_1.buildOverlayStack)(1),
+            sources: [(0, template_utils_1.transparentSlot)()],
+            durationMs: ctx.target.durationMs,
+        };
+    }
+    const placed = (0, dsl_stdlib_1.placeRects)({ rootW: W, rootH: H, rects });
+    // One lavfi line per placed rect — all identical, so emission order is moot.
+    const sources = rects.map(() => ({
+        type: "lavfi",
+        color,
+        fitMode: "tile",
+        visual: opacity == null ? undefined : { opacity },
+    }));
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        assets: {},
+        m0: String(placed.m0),
+        sources,
+        durationMs: ctx.target.durationMs,
+    };
+}
+(0, template_utils_1.registerTemplate)(exports.PrimitiveGrid);

package/dist/m0saic/primitives/grid/v2/grid.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ============================================================================
+ * @m0saic/primitives/grid/v2
+ * ============================================================================
+ *
+ * A reusable, COMPOSABLE gridline overlay primitive.
+ *
+ * Renders each gridline as a thin lavfi strip positioned by a PROPORTIONAL
+ * overlay offset (`H*frac` / `W*frac`), stacked over a transparent base:
+ *   base (transparent) -> line1 -> line2 -> ... -> lineN
+ *
+ * Why v2 exists (the v1 bug):
+ * - v1's single-axis path computed each line's ABSOLUTE pixel position from
+ *   `ctx.target`, then re-encoded them as a `placeRects` split whose basis ≈ the
+ *   axis length in px (e.g. `853[0,1,0,…]` for an 853px plot). That is the
+ *   "absolute → fine ratio" anti-pattern: it renders exactly STANDALONE (853
+ *   slices of 853px = 1px each) but the per-pixel basis does NOT nest — the
+ *   engine folds the child split into the parent layout, re-divides the basis
+ *   below 1px, cells round to 0, and the grid is SILENTLY DROPPED at certain
+ *   canvases (gridlines gone at 1024², 1000², … while 1080² survives). See
+ *   the internal ratio-vs-absolute-m0-drafting notes.
+ *
+ * How v2 fixes it (ratio positioning, decoupled thickness):
+ * - Position is a PROPORTION of the cell, expressed as an overlay offset
+ *   (`H*frac`) evaluated against the actual cell W/H at render time. A ratio
+ *   scales to whatever cell it lands in, so the grid composes cleanly at every
+ *   canvas — no per-pixel basis to re-divide, no silent drop.
+ * - Thickness is DECOUPLED from positioning: each line is a fixed thin strip
+ *   (`thicknessFrac` of the short side, engine-clamped to >= 1px), not a cell in
+ *   an interleaved [gap,line,gap,…] split. That interleave is the OTHER trap
+ *   (its basis sits ≈ the axis length and the remainder spreads wildly — up to
+ *   ~67px at count=6 @ 400px); proportional strips sidestep it entirely.
+ *
+ * Cost trade (deliberate):
+ * - v1 single-axis was 1 composition op (placeRects) but non-nestable. v2 is
+ *   N+1 nested overlays (one per line) but nestable. For a primitive meant to be
+ *   composed, composability wins — the whole point of the shelf is that it drops
+ *   into any cell. Grids are small (typically count 3–12), so the overlay depth
+ *   stays modest; these are plain colored strips (no masks), so they are not
+ *   subject to the mask-drop overlay-depth ceiling.
+ *
+ * Counting / axis / origin semantics are unchanged from v1:
+ * - `count` = number of equal intervals across the axis.
+ * - `excludeEdges=true` (default) → interior lines only (i = 1..count-1);
+ *   `excludeEdges=false` → include the 0 and count edges (i = 0..count).
+ * - direction "horizontal" spaces lines by Y fraction; "vertical" by X fraction;
+ *   "both" draws both sets.
+ * - origin: horizontal uses "bottom" (chart-style, default) or "top"; vertical
+ *   uses "left" (default) or "right".
+ *
+ * Not owned by this primitive: background fills, baselines, animation. Callers
+ * layer those themselves.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+export type PrimitiveGridV2Direction = "horizontal" | "vertical" | "both";
+export type PrimitiveGridV2Origin = "top" | "bottom" | "left" | "right";
+export type PrimitiveGridV2Props = {
+    show?: boolean;
+    /** Number of equal intervals across the chosen axis. */
+    count?: number;
+    /** Which axes to draw. */
+    direction?: PrimitiveGridV2Direction;
+    /**
+     * Fraction origin for placement.
+     * - horizontal: "bottom" (chart-style) or "top" (screen-style)
+     * - vertical:   "left" (screen-style) or "right"
+     */
+    origin?: PrimitiveGridV2Origin;
+    /** Exclude the outer boundary lines. Default true. */
+    excludeEdges?: boolean;
+    /** Line color (FFmpeg-compatible). */
+    color?: MosaicColor;
+    /** Constant opacity multiplier (0..1). */
+    opacity?: number;
+    /** Thickness as a fraction of the short side. Engine clamps to >= 1px. */
+    thicknessFrac?: number;
+};
+export declare const PRIMITIVE_GRID_V2_TEMPLATE_ID: import("@m0saic/types").TemplateId;
+export declare const PrimitiveGridV2: MosaicTemplate<PrimitiveGridV2Props>;