@m0saic/templates 0.2.0

package/dist/m0saic/meta/fixture-fetcher/v1/fixture-fetcher.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FixtureFetcher = exports.FIXTURE_FETCHER_DEFAULT_PAYLOAD = void 0;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+/**
+ * `@m0saic/meta/fixture-fetcher/v1` — the capability-layer PROOF fixture.
+ *
+ * A deterministic, network-free, fs-free stand-in for a real data
+ * fetcher (the GitHub fetcher lands in F5). Its only job is to
+ * exercise the capability plumbing end-to-end and anchor the
+ * regression suites:
+ *
+ *  - publishes a fixed payload as an aliased `MosaicDataSource` in a
+ *    data-only `mosaic_document` (pipeline-step-0 shape);
+ *  - when `secretRef` is set, resolves it via `ctx.secrets` (which
+ *    only reaches this template because it declares
+ *    `tier: "capability"` — the Level 1 gate strips it otherwise) and
+ *    publishes a DERIVED, non-secret marker: `{ secretResolved: true,
+ *    secretLength }`. Cleartext never enters the document, the
+ *    upstream channel, or the sidecar;
+ *  - mirrors the published payload to `sidecars` so the jobs / CLI
+ *    e2e suites can byte-assert what flowed through the pipeline.
+ *
+ * The returned doc pairs the data source with a minimal 1-cell black
+ * CARRIER (the documented "data + renderable coexistence" shape from
+ * `MosaicDataSource`'s contract): a `.mosaicx` wrapper installs the
+ * rendered doc as a child behind a `mosaic` ref, and a ref's cell
+ * must point at something renderable — a strictly data-only child is
+ * unplannable behind a ref today. The carrier renders a black tile;
+ * when the owning pipeline step is `intermediate: true` (the intended
+ * wiring) that tile never reaches the deliverable. The strictly
+ * data-only INLINE step shape (no carrier) is covered by the planner
+ * unit tests (clean skip / PIPELINE_DATA_ONLY_STEP_NOT_INTERMEDIATE).
+ *
+ * Defaults are fully self-contained: no env var, no secret, no
+ * network — the default e2e sweep stays green.
+ */
+/**
+ * The fixed deterministic payload published when `payload` is not
+ * supplied. The e2e suites byte-assert against this exact object —
+ * change it and the sidecar-equality fixtures change with it.
+ */
+exports.FIXTURE_FETCHER_DEFAULT_PAYLOAD = {
+    dataset: "m0saic-fixture",
+    version: 1,
+    series: [3, 5, 8, 13],
+    label: "deterministic fixture payload",
+};
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    alias: {
+        type: "string",
+        required: false,
+        description: 'Alias the published data block appears under in ctx.upstreamData. Default "fixtureData".',
+    },
+    payload: {
+        type: "json",
+        required: false,
+        description: "Plain JSON object to publish instead of the built-in deterministic fixture payload.",
+    },
+    secretRef: {
+        meta: { control: { placeholder: "none" } },
+        type: "string",
+        required: false,
+        description: "Optional SecretRef (e.g. env:M0SAIC_FIXTURE_SECRET). Resolved via ctx.secrets; publishes { secretResolved, secretLength } — never cleartext.",
+    },
+});
+exports.FixtureFetcher = (0, template_utils_1.defineMosaicTemplate)({
+    id: (0, types_1.asTemplateId)("@m0saic/meta/fixture-fetcher/v1"),
+    label: "Fixture Fetcher (internal)",
+    version: 1,
+    description: "Deterministic capability-layer proof fixture: publishes a fixed payload as an aliased data source (pipeline-step-0 shape) and, when secretRef is set, a derived non-secret marker resolved via ctx.secrets. No network, no fs.",
+    role: "data-fetcher",
+    capabilities: { tier: "capability", caps: {} },
+    tags: ["developer", "meta", "fixture", "data-fetcher", "internal"],
+    internal: true,
+    outputHints: {
+        width: 64,
+        height: 64,
+        fps: 1,
+        durationMs: 1000,
+        note: "Publishes upstream variables; renders only a degenerate black carrier tile. Always wrap in a pipeline step with intermediate:true so the carrier never reaches the deliverable.",
+    },
+    // Documents the DEFAULT payload's shape. All keys optional — a
+    // caller-supplied `payload` replaces the object wholesale, and the
+    // post-render outputs guard must not fire on legitimate custom
+    // payloads.
+    outputsSchema: {
+        dataset: { type: "string", required: false },
+        version: { type: "number", required: false },
+        series: { type: "number[]", required: false },
+        label: { type: "string", required: false },
+        secret: { type: "object", required: false },
+    },
+    propsSchema,
+    defaultProps: {
+        alias: "fixtureData",
+    },
+    async render(props, ctx) {
+        var _a, _b;
+        // ── Fail-fast prop validation ────────────────────────────────
+        const alias = (_a = props.alias) !== null && _a !== void 0 ? _a : "fixtureData";
+        if (!(0, types_1.isAliasId)(alias)) {
+            throw new Error(`meta/fixture-fetcher: alias ${JSON.stringify(alias)} is not a valid AliasId (letter/_ start, alphanumeric, max 64 chars).`);
+        }
+        if (props.payload !== undefined &&
+            (props.payload === null ||
+                typeof props.payload !== "object" ||
+                Array.isArray(props.payload))) {
+            throw new Error("meta/fixture-fetcher: payload must be a plain JSON object (MosaicDataSource.variables shape).");
+        }
+        const published = {
+            ...((_b = props.payload) !== null && _b !== void 0 ? _b : exports.FIXTURE_FETCHER_DEFAULT_PAYLOAD),
+        };
+        // ── Optional secret resolution → derived non-secret marker ───
+        if (props.secretRef !== undefined && props.secretRef !== "") {
+            if (!ctx.secrets) {
+                throw new Error("meta/fixture-fetcher: secretRef was set but ctx.secrets is absent. " +
+                    "Either the host threads no secret resolver, or this template lost " +
+                    'its tier:"capability" declaration (the Level 1 gate strips secrets from core-tier templates).');
+            }
+            const has = await ctx.secrets.has(props.secretRef);
+            if (!has) {
+                throw new Error(`meta/fixture-fetcher: secretRef ${JSON.stringify(props.secretRef)} did not resolve (resolver.has() === false).`);
+            }
+            const value = await ctx.secrets.get(props.secretRef);
+            if (typeof value !== "string" || value.length === 0) {
+                throw new Error(`meta/fixture-fetcher: secretRef ${JSON.stringify(props.secretRef)} resolved to an empty value.`);
+            }
+            // Derived marker only — the cleartext value never leaves this scope.
+            published.secret = { secretResolved: true, secretLength: value.length };
+        }
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            m0: (0, dsl_stdlib_1.toM0String)("1", "fixtureFetcher"),
+            assets: {},
+            sources: [
+                // Degenerate carrier — keeps the doc renderable behind a
+                // `.mosaicx` wrapper's mosaic ref (see file-level doc). The
+                // data source below is the actual payload channel.
+                { type: "lavfi", color: "#000000" },
+                {
+                    type: "data",
+                    alias: (0, types_1.asAliasId)(alias),
+                    variables: published,
+                    editor: { owner: "template" },
+                },
+            ],
+            // Mirror to disk so e2e suites can byte-assert the published
+            // payload. Sidecar key is fixed (STRICT_IDENTIFIER-safe)
+            // regardless of the alias prop.
+            sidecars: { fixtureData: published },
+        };
+    },
+});
+(0, template_utils_1.registerTemplate)(exports.FixtureFetcher);
+exports.default = exports.FixtureFetcher;

package/dist/m0saic/meta/hot-reload-smoke/index.d.ts

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

package/dist/m0saic/meta/hot-reload-smoke/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/hot-reload-smoke"), exports);

package/dist/m0saic/meta/hot-reload-smoke/v1/hot-reload-smoke.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `@m0saic/meta/hot-reload-smoke/v1` — the template hot-reload CANARY.
+ *
+ * A solid color square with the color name printed on it. Deliberately the
+ * dumbest renderable in the library: it has no media inputs, no geometry, and
+ * no upstream, so when it comes out the wrong color the ONLY explanation is
+ * that the app is running stale template code.
+ *
+ * ## How to use it
+ *
+ * The fill color is the module constant {@link HOT_RELOAD_SMOKE_COLOR}, NOT a
+ * prop default. That distinction is the whole point: changing a prop default
+ * can be masked by a prop bag the editor already holds, whereas changing this
+ * constant can only show up if the running process re-executed this file.
+ *
+ * 1. Open `@m0saic/meta/hot-reload-smoke/v1` in Make. It renders RED.
+ * 2. Edit `HOT_RELOAD_SMOKE_COLOR` below to `SMOKE_BLUE`.
+ * 3. `npm run build:templates`.
+ * 4. The desktop app hot-reloads on its own (dev watcher); or click
+ *    "Reload templates" in the Make header.
+ * 5. Preview and render both turn BLUE with no app restart.
+ *
+ * If step 5 still shows red, the hot reload is broken — see
+ * `apps/mosaic/electron/templateHotReload.js`.
+ *
+ * `@m0saic/meta/hot-reload-smoke/v1` is `internal` — it's a dev instrument,
+ * not a template anyone renders for output.
+ */
+/** The canary's two colors, exported so tests can pin the exact values. */
+export declare const SMOKE_RED = "#d02020";
+export declare const SMOKE_BLUE = "#2050d0";
+/**
+ * THE ONE LINE TO FLIP when verifying hot reload. Swap `SMOKE_RED` for
+ * `SMOKE_BLUE`, rebuild templates, and the running app must follow.
+ */
+export declare const HOT_RELOAD_SMOKE_COLOR: string;
+/** Human-readable name for the current constant, printed on the square. */
+export declare function smokeColorLabel(color: string): string;
+export type HotReloadSmokeProps = {
+    /**
+     * Optional fill OVERRIDE (#rrggbb). Unset — the deterministic default — uses
+     * the module constant, which is what makes this a hot-reload canary. Set it
+     * only when you want the square in some other color for an unrelated test.
+     */
+    color?: string;
+    /** Print the color name + template id on the square. Default `true`. */
+    showLabel?: boolean;
+};
+export declare const HotReloadSmoke: import("@m0saic/types").MosaicTemplate<HotReloadSmokeProps, import("@m0saic/types").MosaicTemplateOutputs, import("@m0saic/types").MosaicTemplateUpstreamVariables, import("@m0saic/types").MosaicTemplateUpstreamData, import("@m0saic/types").MosaicTemplateSidecars>;
+export default HotReloadSmoke;

package/dist/m0saic/meta/hot-reload-smoke/v1/hot-reload-smoke.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HotReloadSmoke = exports.HOT_RELOAD_SMOKE_COLOR = exports.SMOKE_BLUE = exports.SMOKE_RED = void 0;
+exports.smokeColorLabel = smokeColorLabel;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+/**
+ * `@m0saic/meta/hot-reload-smoke/v1` — the template hot-reload CANARY.
+ *
+ * A solid color square with the color name printed on it. Deliberately the
+ * dumbest renderable in the library: it has no media inputs, no geometry, and
+ * no upstream, so when it comes out the wrong color the ONLY explanation is
+ * that the app is running stale template code.
+ *
+ * ## How to use it
+ *
+ * The fill color is the module constant {@link HOT_RELOAD_SMOKE_COLOR}, NOT a
+ * prop default. That distinction is the whole point: changing a prop default
+ * can be masked by a prop bag the editor already holds, whereas changing this
+ * constant can only show up if the running process re-executed this file.
+ *
+ * 1. Open `@m0saic/meta/hot-reload-smoke/v1` in Make. It renders RED.
+ * 2. Edit `HOT_RELOAD_SMOKE_COLOR` below to `SMOKE_BLUE`.
+ * 3. `npm run build:templates`.
+ * 4. The desktop app hot-reloads on its own (dev watcher); or click
+ *    "Reload templates" in the Make header.
+ * 5. Preview and render both turn BLUE with no app restart.
+ *
+ * If step 5 still shows red, the hot reload is broken — see
+ * `apps/mosaic/electron/templateHotReload.js`.
+ *
+ * `@m0saic/meta/hot-reload-smoke/v1` is `internal` — it's a dev instrument,
+ * not a template anyone renders for output.
+ */
+/** The canary's two colors, exported so tests can pin the exact values. */
+exports.SMOKE_RED = "#d02020";
+exports.SMOKE_BLUE = "#2050d0";
+/**
+ * THE ONE LINE TO FLIP when verifying hot reload. Swap `SMOKE_RED` for
+ * `SMOKE_BLUE`, rebuild templates, and the running app must follow.
+ */
+exports.HOT_RELOAD_SMOKE_COLOR = exports.SMOKE_RED;
+/** Human-readable name for the current constant, printed on the square. */
+function smokeColorLabel(color) {
+    if (color === exports.SMOKE_RED)
+        return "RED";
+    if (color === exports.SMOKE_BLUE)
+        return "BLUE";
+    return color.toUpperCase();
+}
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    color: {
+        meta: { constraints: { isColor: true }, control: { placeholder: "module constant HOT_RELOAD_SMOKE_COLOR", colorPicker: true } },
+        type: "string",
+        required: false,
+        description: "Optional fill override (#rrggbb). Unset: the HOT_RELOAD_SMOKE_COLOR constant baked into the template source.",
+    },
+    showLabel: {
+        type: "boolean",
+        required: false,
+        description: "Print the color name and template id on the square.",
+    },
+});
+exports.HotReloadSmoke = (0, template_utils_1.defineMosaicTemplate)({
+    id: (0, types_1.asTemplateId)("@m0saic/meta/hot-reload-smoke/v1"),
+    label: "Hot Reload Smoke (internal)",
+    version: 1,
+    description: "Dev canary for the desktop app's template hot reload: a solid color square whose fill comes from a constant in the template SOURCE (not a prop default), so a rebuilt dist can only show through if the running process re-executed the file. Flip HOT_RELOAD_SMOKE_COLOR red → blue, rebuild, and the app must follow without a restart.",
+    capabilities: { tier: "core" },
+    tags: ["developer", "meta", "fixture", "internal"],
+    internal: true,
+    outputHints: {
+        width: 720,
+        height: 720,
+        fps: 30,
+        durationMs: 1000,
+        note: "Square canvas — the canary is a solid fill, so the aspect only has to be unmistakable.",
+    },
+    propsSchema,
+    // `color` deliberately absent: its deterministic default is the module
+    // constant resolved in render(). Baking it in here would make the default
+    // travel in the editor's prop bag, which is exactly the staleness this
+    // template exists to detect.
+    defaultProps: {
+        showLabel: true,
+    },
+    async render(props, _ctx) {
+        var _a, _b;
+        if (props.color !== undefined && !/^#[0-9a-fA-F]{6}$/.test(props.color)) {
+            throw new Error(`meta/hot-reload-smoke: color ${JSON.stringify(props.color)} must be a #rrggbb hex color.`);
+        }
+        const fill = (_a = props.color) !== null && _a !== void 0 ? _a : exports.HOT_RELOAD_SMOKE_COLOR;
+        const showLabel = (_b = props.showLabel) !== null && _b !== void 0 ? _b : true;
+        // xExpr / yExpr are ffmpeg drawtext expressions and OVERRIDE hAlign /
+        // vAlign, so centering is spelled `(w-text_w)/2` rather than
+        // `hAlign: "center"` (which the expr would ignore).
+        // Generous fixed sizes — the app fits text wider than the CLI does.
+        const layers = [
+            {
+                content: { kind: "literal", text: smokeColorLabel(fill) },
+                style: { fontSize: 96, fontColor: "#ffffff" },
+                placement: { xExpr: "(w-text_w)/2", yExpr: "h*0.44-text_h/2" },
+            },
+            {
+                content: { kind: "literal", text: "hot-reload-smoke/v1" },
+                style: { fontSize: 26, fontColor: "#ffffff" },
+                placement: { xExpr: "(w-text_w)/2", yExpr: "h*0.62-text_h/2" },
+            },
+        ];
+        // A text source must carry at least one layer (TEXT_LAYERS_EMPTY), so the
+        // label-off variant is a lavfi color tile rather than a text source with
+        // an empty layers[] — the canonical solid-fill route either way.
+        const source = showLabel
+            ? {
+                type: "text",
+                visual: { backgroundColor: (0, template_utils_1.solidBackground)(fill) },
+                layers,
+            }
+            : (0, template_utils_1.makeColorTile)((0, template_utils_1.solidBackground)(fill));
+        return {
+            kind: "mosaic_document",
+            version: 1,
+            m0: (0, dsl_stdlib_1.toM0String)("F", "hotReloadSmoke"),
+            assets: {},
+            sources: [source],
+        };
+    },
+});
+(0, template_utils_1.registerTemplate)(exports.HotReloadSmoke);
+exports.default = exports.HotReloadSmoke;

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

@@ -0,0 +1,13 @@
+/**
+ * Meta templates — templates *about* mosaic itself. Currently:
+ *   - post-mortem/v1     : renders a sandbox session as a watchable video
+ *   - fixture-fetcher/v1 : capability-layer proof fixture (data-fetcher shape)
+ *   - upstream-echo/v1   : consumer proof fixture (echoes upstream into sidecars)
+ *   - camera-debug/v1    : camera viewport visualized over a gray-box layout
+ *   - hot-reload-smoke/v1: dev canary for the desktop app's template hot reload
+ */
+export * from "./post-mortem";
+export * from "./fixture-fetcher";
+export * from "./upstream-echo";
+export * from "./camera-debug";
+export * from "./hot-reload-smoke";

package/dist/m0saic/meta/index.js

@@ -0,0 +1,29 @@
+"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 });
+/**
+ * Meta templates — templates *about* mosaic itself. Currently:
+ *   - post-mortem/v1     : renders a sandbox session as a watchable video
+ *   - fixture-fetcher/v1 : capability-layer proof fixture (data-fetcher shape)
+ *   - upstream-echo/v1   : consumer proof fixture (echoes upstream into sidecars)
+ *   - camera-debug/v1    : camera viewport visualized over a gray-box layout
+ *   - hot-reload-smoke/v1: dev canary for the desktop app's template hot reload
+ */
+__exportStar(require("./post-mortem"), exports);
+__exportStar(require("./fixture-fetcher"), exports);
+__exportStar(require("./upstream-echo"), exports);
+__exportStar(require("./camera-debug"), exports);
+__exportStar(require("./hot-reload-smoke"), exports);

package/dist/m0saic/meta/post-mortem/index.d.ts

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

package/dist/m0saic/meta/post-mortem/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/post-mortem"), exports);

package/dist/m0saic/meta/post-mortem/v1/post-mortem.d.ts

@@ -0,0 +1,47 @@
+import type { MosaicTemplate } from "@m0saic/types";
+/**
+ * `post-mortem/v1` — render a sandbox session as a watchable video.
+ *
+ * Reading experience (Stack Overflow / Reddit thread → video):
+ *   - Left half  : chat thread. Accumulates downward as the pipeline advances.
+ *   - Right half : the candidate's geometry, rendered as a wireframe.
+ *   - Bottom strip (deferred to v1.1): chess-style move list with score sparkline.
+ *
+ * v1 is **structural / placeholder visuals**. The layout split is in place,
+ * the chat advances, the canvas swaps per candidate — but the styling is
+ * deliberately plain. We iterate the look-and-feel against real sandbox
+ * sessions (dogfooding the sandbox package itself).
+ *
+ * Deferred to v1.1+ (TODOs in source):
+ *   - Per-party chat-bubble styling, grade/score badges, region overlays.
+ *   - Game-review-board summary step (eval graph + per-party stats + per-phase chips).
+ *   - Cross-fade/slide transitions between candidate steps.
+ *   - Comments thread rendering.
+ *   - Coach speech-bubble takeaway on the end card.
+ *   - `.m0c` first-class rendering (background image + masks).
+ */
+export type PostMortemProps = {
+    /**
+     * Path to a sandbox session directory. Absolute, or relative to the
+     * repo root (e.g. `"packages/sandbox/sessions/2026-06-09-bar-graph"`).
+     */
+    sessionPath: string;
+    /** Hard cap on candidates to render. Default: render all. */
+    maxCandidates?: number;
+    /** Per-candidate dwell time in milliseconds. */
+    msPerCandidate?: number;
+    /** Title-card dwell time in milliseconds. */
+    msTitleCard?: number;
+    /** End-card dwell time in milliseconds. */
+    msEndCard?: number;
+    /**
+     * Tunable split: chat-column weight (integer slots). Default 1.
+     * Together with {@link canvasWeightSlots} this drives the
+     * `weightedSplit([chat, canvas], "col")` for each candidate step.
+     * Bump granularity (e.g. 2 + 7 → 2/9 chat) when fine-tuning the ratio.
+     */
+    chatWeightSlots?: number;
+    /** Tunable split: canvas-column weight (integer slots). Default 3. */
+    canvasWeightSlots?: number;
+};
+export declare const PostMortem: MosaicTemplate<PostMortemProps>;