@m0saic/templates 0.2.0

package/dist/m0saic/agents/trace-timeline/v1/trace-timeline.js

@@ -0,0 +1,356 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/agents/trace-timeline/v1 — what did the agent do on that run?
+ * ============================================================================
+ *
+ * A waterfall of one agent run: every tool call is a swimlane — the tool and
+ * what it touched on the left, a latency bar placed on a shared time axis on
+ * the right, the tokens it cost at the bar's end. Status colours the bar
+ * (ok = accent, error, retry, cached); a legend and tick labels frame it.
+ * The subtitle carries the run totals. Built for the "agents in production"
+ * crowd: the picture their observability vendor draws, from a JSON of spans.
+ *
+ * RATIO throughout (the alpine card kit): rows are equal bands, every bar is
+ * a weighted column split of its lane (start · duration · rest, on a ~100
+ * basis), tick labels are a column split of the axis row. No hairlines — a
+ * faint lane wash reads as the grid and survives any canvas. Composes at any
+ * size; fonts are sized to H and width-capped.
+ *
+ * Determinism: no clock, no randomness — the sample run is a fixed fixture.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceTimelineV1 = exports.SAMPLE_SPANS = void 0;
+exports.fmtTokens = fmtTokens;
+exports.fmtSeconds = fmtSeconds;
+exports.fmtTick = fmtTick;
+exports.tickStepMs = tickStepMs;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const alpine_card_1 = require("../../../alpine/_shared/alpine-card");
+const alpine_theme_1 = require("../../../alpine/_shared/alpine-theme");
+const alpine_anim_1 = require("../../../alpine/_shared/alpine-anim");
+const TEMPLATE_ID = "@m0saic/agents/trace-timeline/v1";
+const MAX_SPANS = 10;
+const DEFAULT_ERROR = "#f85149";
+const DEFAULT_RETRY = "#e3b341";
+const DEFAULT_CACHED = "#8b949e";
+const DEFAULT_ANIM = { renderMode: "premium", introFrac: 0.7, reduceMotion: false };
+const STATUSES = ["ok", "error", "retry", "cached"];
+/** A fixed sample run: plan → read → edit → tests fail → fix → tests pass → wrap up. 38.2 s, ~14k tokens. */
+exports.SAMPLE_SPANS = [
+    { tool: "plan", target: "read the failing report, pick a fix", startMs: 0, durMs: 1800, tokens: 1900 },
+    { tool: "read_file", target: "package.json", startMs: 1800, durMs: 500, tokens: 400 },
+    { tool: "grep", target: "renderNested", startMs: 2300, durMs: 800, tokens: 600 },
+    { tool: "read_file", target: "render/renderNestedTemplate.ts", startMs: 3100, durMs: 900, tokens: 2200 },
+    { tool: "edit", target: "business-card.ts", startMs: 4000, durMs: 2500, tokens: 3100 },
+    { tool: "bash", target: "npm test -w templates", startMs: 6500, durMs: 12700, tokens: 900, status: "error" },
+    { tool: "read_file", target: "layout.test.ts", startMs: 19200, durMs: 800, tokens: 800 },
+    { tool: "edit", target: "layout.ts", startMs: 20000, durMs: 2400, tokens: 1400 },
+    { tool: "bash", target: "npm test -w templates", startMs: 22400, durMs: 12200, tokens: 900, status: "retry" },
+    { tool: "git", target: "diff --stat", startMs: 34600, durMs: 900, tokens: 300, status: "cached" },
+];
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    title: { type: "string", required: false, description: "Card title.", meta: { control: { placeholder: "none" }, ui: { label: "Title", order: 1, primary: true } } },
+    subtitle: { type: "string", required: false, description: "Line under the title. Empty = the run totals (calls · wall time · tokens).", meta: { control: { placeholder: "run totals" }, ui: { label: "Subtitle", order: 2 } } },
+    spans: {
+        type: "list",
+        required: true,
+        description: "The run's tool calls in order: tool, what it touched, start and duration in ms, tokens, status (ok · error · retry · cached). Up to 10 are drawn.",
+        meta: { ui: { label: "Spans", order: 3, primary: true }, list: { max: 40 } },
+        itemSchema: {
+            tool: { type: "string", required: true, description: "Tool or phase.", meta: { ui: { label: "Tool" } } },
+            target: { type: "string", required: false, description: "What it touched.", meta: { control: { placeholder: "none" }, ui: { label: "Target" } } },
+            startMs: { type: "number", required: true, description: "Start (ms from run start).", meta: { ui: { label: "Start ms" } } },
+            durMs: { type: "number", required: true, description: "Duration (ms).", meta: { ui: { label: "Duration ms" } } },
+            tokens: { type: "number", required: false, description: "Tokens on this hop.", meta: { control: { placeholder: "none" }, ui: { label: "Tokens" } } },
+            status: { type: "string", required: false, description: "ok · error · retry · cached.", meta: { constraints: { oneOf: STATUSES }, control: { placeholder: "ok" }, ui: { label: "Status" } } },
+        },
+    },
+    preset: { type: "string", required: false, description: 'Alpine theme: "light" (default) or "dark".', meta: { constraints: { oneOf: ["light", "dark"] }, ui: { label: "Preset", order: 4 } } },
+    accent: { type: "string", required: false, description: "Bar colour for ok spans.", meta: { constraints: { isColor: true }, control: { colorPicker: true, placeholder: "theme primary" }, ui: { label: "Accent", order: 5 } } },
+    errorColor: { type: "string", required: false, description: "Bar colour for error spans.", meta: { constraints: { isColor: true }, control: { colorPicker: true }, ui: { label: "Error colour", order: 6 } } },
+    retryColor: { type: "string", required: false, description: "Bar colour for retried spans.", meta: { constraints: { isColor: true }, control: { colorPicker: true }, ui: { label: "Retry colour", order: 7 } } },
+    cachedColor: { type: "string", required: false, description: "Bar colour for cached spans.", meta: { constraints: { isColor: true }, control: { colorPicker: true }, ui: { label: "Cached colour", order: 8 } } },
+    showTokens: { type: "boolean", required: false, description: "Print each span's token cost after its bar.", meta: { ui: { label: "Show tokens", order: 9 } } },
+    anim: {
+        type: "group",
+        required: false,
+        description: "Reveal: lanes appear in run order over the intro. reduceMotion renders the final frame.",
+        meta: { ui: { label: "Animation", order: 10, collapsedByDefault: true } },
+        fields: {
+            reduceMotion: alpine_anim_1.ALPINE_ANIM_FIELDS.reduceMotion,
+            introFrac: alpine_anim_1.ALPINE_ANIM_FIELDS.introFrac,
+            renderMode: (0, alpine_anim_1.fEnum)("Render mode", ["premium", "light"], "premium = alpha-fade; light = enable-gate pops (cheaper when nested)."),
+        },
+    },
+    theme: { type: "json", required: false, description: "Opt-in producer theme tokens.", meta: { ui: { label: "Theme", order: 11, collapsedByDefault: true, consumer: "agent" } } },
+    debugLayout: { type: "boolean", required: false, description: "Dev-only: overlay the layout contract.", meta: { ui: { label: "Debug layout", order: 12 } } },
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const color = (v, fallback) => (v && v.trim() ? v : fallback);
+/** "1.2k" / "38.2 s" — compact labels, ASCII only. */
+function fmtTokens(n) {
+    if (n >= 1000000)
+        return `${(n / 1000000).toFixed(1)}M`;
+    if (n >= 1000)
+        return `${(n / 1000).toFixed(1)}k`;
+    return String(Math.round(n));
+}
+function fmtSeconds(ms) {
+    const s = ms / 1000;
+    return s >= 100 ? `${Math.round(s)}s` : s >= 10 ? `${s.toFixed(1)}s` : `${s.toFixed(2)}s`;
+}
+/** Axis tick label: whole seconds when the step allows ("10s"), else the compact form. */
+function fmtTick(ms, stepMs) {
+    if (ms === 0)
+        return "0";
+    if (stepMs >= 1000 && ms % 1000 === 0)
+        return `${ms / 1000}s`;
+    if (stepMs < 1000)
+        return `${ms}ms`;
+    return fmtSeconds(ms);
+}
+/** Tick interval: the smallest 1·2·5·10 step that keeps the axis to at most 7 ticks (so 4–7 over `totalMs`). */
+function tickStepMs(totalMs) {
+    const target = totalMs / 6;
+    const pow = Math.pow(10, Math.floor(Math.log10(Math.max(1, target))));
+    for (const m of [1, 2, 5, 10])
+        if (m * pow >= target)
+            return m * pow;
+    return 10 * pow;
+}
+function roundTile(c, radius) {
+    return (0, template_utils_1.makeColorTile)(c, { effects: { rounding: { cornerStyle: "rounded", borderRadius: radius } } });
+}
+/** Width-capped font: `px` unless `text` would overflow `boxPx` at the rasterizer's 0.72 em/char. */
+function capFont(px, text, boxPx, min) {
+    return Math.max(min, Math.min(px, Math.floor((boxPx * 0.94 - 2) / (Math.max(1, (0, template_utils_1.textEmUnits)(text)) * 0.72))));
+}
+function fitText(text, font, boxPx) {
+    return (0, template_utils_1.fitEmUnits)(text, Math.floor((boxPx * 0.94 - 2) / (font * 0.72)));
+}
+// ---------------------------------------------------------------------------
+// Template
+// ---------------------------------------------------------------------------
+exports.TraceTimelineV1 = {
+    id: (0, types_1.asTemplateId)(TEMPLATE_ID),
+    label: "Agent Trace Timeline",
+    version: 1,
+    description: "What the agent did on a run — a waterfall of tool calls: the tool and its target per lane, a latency bar on a shared time axis, tokens per hop, and status colours for errors, retries and cache hits. Alpine card, composes at any canvas.",
+    capabilities: { tier: "core" },
+    tags: ["agents", "trace", "timeline", "waterfall", "observability", "latency", "tokens", "developers", "sre", "alpine", "animated"],
+    aspectRatio: { ideal: 16 / 10, min: 1, max: 2.2, mode: "warn" },
+    outputHints: { format: { kind: "video", container: "mp4" }, width: 1280, height: 800, fps: 30, durationMs: 3000 },
+    propsSchema,
+    defaultProps: {
+        title: "One agent run, end to end",
+        spans: exports.SAMPLE_SPANS,
+        preset: "light",
+        errorColor: DEFAULT_ERROR,
+        retryColor: DEFAULT_RETRY,
+        cachedColor: DEFAULT_CACHED,
+        showTokens: true,
+        anim: { ...DEFAULT_ANIM },
+        debugLayout: false,
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e;
+        const W = Math.max(1, Math.round(ctx.target.width));
+        const H = Math.max(1, Math.round(ctx.target.height));
+        const fail = (message) => (0, template_utils_1.makeErrorMosaic)(message, { title: "Agent Trace Timeline", width: W, height: H });
+        const spans = ((_a = props.spans) !== null && _a !== void 0 ? _a : [])
+            .filter((s) => s && typeof s.tool === "string" && s.tool.trim() && Number.isFinite(s.startMs) && Number.isFinite(s.durMs) && s.durMs >= 0 && s.startMs >= 0)
+            .slice(0, MAX_SPANS);
+        if (spans.length === 0)
+            return fail("trace-timeline needs spans[] with tool, startMs and durMs");
+        const theme = await (0, alpine_theme_1.resolveAlpineTheme)((_b = props.preset) !== null && _b !== void 0 ? _b : "light", ctx, props.theme);
+        const okColor = color(props.accent, theme.primary);
+        const statusColor = {
+            ok: okColor,
+            error: color(props.errorColor, DEFAULT_ERROR),
+            retry: color(props.retryColor, DEFAULT_RETRY),
+            cached: color(props.cachedColor, DEFAULT_CACHED),
+        };
+        const showTokens = props.showTokens !== false;
+        const anim = { ...DEFAULT_ANIM, ...((_c = props.anim) !== null && _c !== void 0 ? _c : {}) };
+        const animate = !anim.reduceMotion;
+        const light = anim.renderMode === "light";
+        const clipSec = Math.max(0.1, ((_d = ctx.target.durationMs) !== null && _d !== void 0 ? _d : 3000) / 1000);
+        const introSec = Math.max(0.1, Math.min(1, anim.introFrac) * clipSec);
+        // ── run totals ──
+        const totalMs = Math.max(1, ...spans.map((s) => s.startMs + s.durMs));
+        const totalTokens = spans.reduce((a, s) => { var _a; return a + ((_a = s.tokens) !== null && _a !== void 0 ? _a : 0); }, 0);
+        const subtitle = ((_e = props.subtitle) !== null && _e !== void 0 ? _e : "").trim() || `${spans.length} tool calls · ${fmtSeconds(totalMs)} wall time${totalTokens > 0 ? ` · ${fmtTokens(totalTokens)} tokens` : ""}`;
+        // ── chrome ──
+        const card = (0, alpine_card_1.alpineCard)({ theme, W, H, title: props.title, subtitle });
+        const content = card.contentRect;
+        const wOf = (px, ref) => Math.max(1, Math.round((px / ref) * 100));
+        // ── geometry (px → proportions) ──
+        const N = spans.length;
+        const axisH = Math.round(content.h * 0.07);
+        const legendH = Math.round(content.h * 0.08);
+        const gapAxis = Math.round(content.h * 0.02);
+        const gapLegend = Math.round(content.h * 0.04);
+        const lanesH = Math.max(1, content.h - axisH - gapAxis - legendH - gapLegend);
+        const pitch = Math.max(1, Math.floor(lanesH / N));
+        const laneGap = Math.max(2, Math.round(pitch * 0.18));
+        const laneH = Math.max(1, pitch - laneGap);
+        const labelW = Math.round(content.w * 0.28);
+        const gapLabel = Math.round(content.w * 0.02);
+        const trackW = Math.max(1, content.w - labelW - gapLabel);
+        const tokenW = showTokens ? Math.round(content.w * 0.06) : 0;
+        const labelFont = Math.max(10, Math.round(H * 0.024));
+        const targetFont = Math.max(9, Math.round(H * 0.018));
+        const tickFont = Math.max(9, Math.round(H * 0.018));
+        const tokenFont = Math.max(9, Math.round(H * 0.017));
+        const legendFont = Math.max(10, Math.round(H * 0.02));
+        // Reveal: lanes in run order across the intro (premium = fade, light = gate).
+        const laneDur = Math.max(0.05, introSec / (1 + 0.5 * Math.max(0, N - 1)));
+        const reveal = (node, i) => {
+            if (!animate)
+                return node;
+            const at = (introSec * i) / Math.max(1, N);
+            return light ? (0, alpine_anim_1.revealGateNode)(node, at) : (0, alpine_anim_1.revealFadeNode)(node, at, laneDur);
+        };
+        // ── the axis: tick labels at nice intervals, as a column split of the track ──
+        const step = tickStepMs(totalMs);
+        const ticks = [];
+        for (let t = 0; t <= totalMs; t += step)
+            ticks.push(t);
+        const axisBands = ticks.map((t, i) => {
+            var _a;
+            const next = (_a = ticks[i + 1]) !== null && _a !== void 0 ? _a : totalMs;
+            const spanPx = Math.max(1, Math.round(((next - t) / totalMs) * trackW));
+            const label = fmtTick(t, step);
+            return { weight: wOf(spanPx, trackW), node: (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)(label, capFont(tickFont, label, spanPx, 8), theme.muted, "left", "bottom"), "axis-tick")) };
+        });
+        const axisRow = (0, alpine_card_1.colSplit)([
+            { weight: wOf(labelW + gapLabel, content.w), node: alpine_card_1.EMPTY },
+            { weight: wOf(trackW, content.w), node: (0, alpine_card_1.colSplit)(axisBands) },
+        ]);
+        // ── the lanes ──
+        const laneNode = (s, i) => {
+            var _a;
+            const status = STATUSES.includes(s.status) ? s.status : "ok";
+            const barColor = statusColor[status];
+            const tool = s.tool.trim();
+            const target = ((_a = s.target) !== null && _a !== void 0 ? _a : "").trim();
+            // Label column: tool (bold-ish, the lane's name) over its target.
+            const toolFont = capFont(labelFont, tool, labelW, 9);
+            const label = target
+                ? (0, alpine_card_1.rowSplit)([
+                    { weight: 55, node: (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)(fitText(tool, toolFont, labelW), toolFont, theme.title, "left", "bottom"), "span-tool")) },
+                    { weight: 45, node: (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)(fitText(target, targetFont, labelW), capFont(targetFont, fitText(target, targetFont, labelW), labelW, 8), theme.muted, "left", "top"), "span-target")) },
+                ])
+                : (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)(fitText(tool, toolFont, labelW), toolFont, theme.title, "left", "middle"), "span-tool"));
+            // Track: start · bar · (tokens) · rest, as proportions of the track width.
+            const startPx = Math.round((Math.min(s.startMs, totalMs) / totalMs) * trackW);
+            const barPx = Math.max(Math.round(laneH * 0.35), Math.round((s.durMs / totalMs) * trackW));
+            const afterPx = Math.max(0, trackW - startPx - barPx);
+            const tokenLabel = showTokens && s.tokens != null && s.tokens > 0 ? fmtTokens(s.tokens) : "";
+            const tokenPx = tokenLabel ? Math.min(afterPx, tokenW) : 0;
+            const restPx = Math.max(0, afterPx - tokenPx);
+            const barNode = (0, alpine_card_1.rowSplit)([
+                { weight: 20, node: alpine_card_1.EMPTY },
+                { weight: 60, node: (0, alpine_card_1.paint)((0, template_utils_1.tag)(roundTile(barColor, 0.5), `span-bar-${status}`)) },
+                { weight: 20, node: alpine_card_1.EMPTY },
+            ]);
+            const trackBands = [];
+            if (startPx > 0)
+                trackBands.push({ weight: wOf(startPx, trackW), node: alpine_card_1.EMPTY });
+            trackBands.push({ weight: wOf(barPx, trackW), node: barNode });
+            if (tokenPx > 0) {
+                // `padding` is a FRACTION of the box (MosaicBoxFrac) — a small left
+                // margin so the label does not kiss the bar.
+                trackBands.push({ weight: wOf(tokenPx, trackW), node: (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)(tokenLabel, capFont(tokenFont, tokenLabel, tokenPx * 0.86, 8), theme.muted, "left", "middle", { left: 0.14 }), "span-tokens")) });
+            }
+            if (restPx > 0)
+                trackBands.push({ weight: wOf(restPx, trackW), node: alpine_card_1.EMPTY });
+            // A faint lane wash under the track — the "grid" without hairlines.
+            const track = (0, alpine_card_1.overlay)([(0, alpine_card_1.paint)((0, template_utils_1.tag)(roundTile(theme.grid, 0.3), "lane-wash")), (0, alpine_card_1.colSplit)(trackBands)]);
+            const lane = (0, alpine_card_1.colSplit)([
+                { weight: wOf(labelW, content.w), node: label },
+                { weight: wOf(gapLabel, content.w), node: alpine_card_1.EMPTY },
+                { weight: wOf(trackW, content.w), node: track },
+            ]);
+            return reveal(lane, i);
+        };
+        const laneBands = [];
+        spans.forEach((s, i) => {
+            if (i > 0)
+                laneBands.push({ weight: laneGap, node: alpine_card_1.EMPTY });
+            laneBands.push({ weight: laneH, node: laneNode(s, i) });
+        });
+        const lanes = (0, alpine_card_1.rowSplit)(laneBands);
+        // ── the legend: one entry per status that appears (ok always) ──
+        const present = STATUSES.filter((st) => st === "ok" || spans.some((s) => s.status === st));
+        // Entries are laid out at 20% of the TRACK (the legend hangs under the bars).
+        const legendEntryW = Math.round(trackW * 0.2);
+        const legendEntry = (st) => {
+            // A bigger dot and a text budget with slack: these are 15–20 px marks
+            // three splits deep, where the card's coarse inset basis can shave a
+            // few px off either axis.
+            const dot = Math.max(8, Math.round(legendH * 0.5));
+            const gap = Math.round(dot * 0.5);
+            const textPx = legendEntryW - dot - gap;
+            const text = st === "ok" ? "ok" : st;
+            const vPad = Math.max(1, Math.round((legendH - dot) / 2));
+            return (0, alpine_card_1.colSplit)([
+                { weight: wOf(dot, legendEntryW), node: (0, alpine_card_1.rowSplit)([{ weight: vPad, node: alpine_card_1.EMPTY }, { weight: dot, node: (0, alpine_card_1.paint)((0, template_utils_1.tag)(roundTile(statusColor[st], 1), `legend-${st}-dot`)) }, { weight: Math.max(1, legendH - dot - vPad), node: alpine_card_1.EMPTY }]) },
+                { weight: wOf(gap, legendEntryW), node: alpine_card_1.EMPTY },
+                { weight: wOf(textPx, legendEntryW), node: (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)(text, capFont(legendFont, text, textPx * 0.8, 8), theme.label, "left", "middle"), `legend-${st}-text`)) },
+            ]);
+        };
+        const legendBands = [];
+        present.forEach((st, i) => {
+            if (i > 0)
+                legendBands.push({ weight: 2, node: alpine_card_1.EMPTY });
+            legendBands.push({ weight: 20, node: legendEntry(st) });
+        });
+        const legendRow = (0, alpine_card_1.colSplit)([
+            { weight: wOf(labelW + gapLabel, content.w), node: alpine_card_1.EMPTY },
+            { weight: wOf(trackW, content.w), node: (0, alpine_card_1.colSplit)([...legendBands, { weight: Math.max(1, 100 - present.length * 22), node: alpine_card_1.EMPTY }]) },
+        ]);
+        const body = (0, alpine_card_1.rowSplit)([
+            { weight: wOf(axisH, content.h), node: axisRow },
+            { weight: wOf(gapAxis, content.h), node: alpine_card_1.EMPTY },
+            { weight: wOf(lanesH, content.h), node: lanes },
+            { weight: wOf(gapLegend, content.h), node: alpine_card_1.EMPTY },
+            { weight: wOf(legendH, content.h), node: legendRow },
+        ]);
+        const root = card.compose(body);
+        const doc = {
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0: (0, dsl_stdlib_1.toM0String)(root.m0, "TraceTimelineV1"),
+            sources: root.sources,
+            backgroundColor: card.backgroundColor,
+            fps: ctx.target.fps,
+            durationMs: ctx.target.durationMs,
+            size: { width: W, height: H },
+            editor: { label: `Agent Trace Timeline · ${spans.length} calls · ${fmtSeconds(totalMs)}` },
+        };
+        const constraints = [
+            ...card.constraints,
+            { label: "span-tool", textFits: {} },
+            { label: "axis-tick", textFits: {} },
+            { label: "lane-wash", minWidthFrac: 0.5 },
+            ...present.flatMap((st) => [
+                // A rounded mark three splits under the card's coarse inset basis: it may
+                // come out a short pill at some canvases (45×33 at 1080²) — still a
+                // legend swatch, so the aspect tolerance is loose; the text is the gate.
+                { label: `legend-${st}-dot`, aspect: 1, aspectTolerance: 0.5 },
+                { label: `legend-${st}-text`, textFits: {} },
+            ]),
+        ];
+        return (0, template_utils_1.withLayoutContract)(doc, ctx, { templateId: TEMPLATE_ID, constraints, relations: [], debug: props.debugLayout === true });
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.TraceTimelineV1);
+exports.default = exports.TraceTimelineV1;

package/dist/m0saic/alpine/_shared/alpine-anim.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ============================================================================
+ * Alpine pack — shared reveal + animation-schema helpers (F4 U-A0)
+ * ============================================================================
+ *
+ * Two shared pieces the alpine tier adopts:
+ *
+ *  1. `revealGate` — the geq-free intro reveal. Alpine templates each carried a
+ *     local `fadeIn`/`wrapFade` wrapper that set a time-varying `overlay.alpha`
+ *     (`fadeInExpr`) — which compiles to a per-pixel `geq` fold (cost-model R3/R4,
+ *     paid every frame of a nesting parent's whole timeline). `revealGate` swaps
+ *     that for a free scalar `overlay.enable` gate: the element pops in at its
+ *     moment, no geq. (For elements that also SLIDE — a bar/fill growing via an
+ *     `xExpr`/`yExpr` translate — just drop the `alpha`; keep the translate. The
+ *     slide is the grow; the alpha was redundant fade sugar.)
+ *
+ *  2. `ALPINE_ANIM_FIELDS` + field helpers — the `anim` prop group shipped as a
+ *     `type:"group"` with NO `fields`, so it rendered as a raw JSON bag in Make.
+ *     These give it real labeled sub-fields. Templates with extra anim knobs
+ *     spread + add: `fields: { ...ALPINE_ANIM_FIELDS, countUp: fBool("Count up") }`.
+ * ============================================================================
+ */
+import type { MosaicSource } from "@m0saic/types";
+import type { Node } from "./alpine-card";
+/**
+ * Reveal a source at `atSec` via a free `overlay.enable` gate (no geq). Raw
+ * `gte(t,X)` form — the engine escapes commas natively; do NOT use the
+ * comma-escaped `gatedEnableExpr`. `on = false` returns the source untouched
+ * (reduceMotion / static). Preserves any existing overlay (position/slide).
+ */
+export declare function revealGate<T extends MosaicSource>(src: T, atSec: number, on?: boolean): T;
+/** Map `revealGate` over every source in a node (the enable-gate analog of the
+ *  per-template `wrapFade` that fanned a fade over `node.sources`). */
+export declare function revealGateNode(node: Node, atSec: number, on?: boolean): Node;
+/**
+ * Soft slide-in reveal — still geq-free. Enable-gates the source at `atSec` AND
+ * slides it up `distPx` into place over `durSec` via a per-frame `yExpr` translate
+ * (a position anim — cheap, NO alpha/geq). Reads softer than a hard `enable` pop
+ * without the per-pixel fade cost. `on=false` returns the source untouched.
+ */
+export declare function revealSlide<T extends MosaicSource>(src: T, atSec: number, durSec: number, distPx: number, on?: boolean): T;
+/** Map `revealSlide` over every source in a node. */
+export declare function revealSlideNode(node: Node, atSec: number, durSec: number, distPx: number, on?: boolean): Node;
+/**
+ * Premium fade reveal — a time-varying `overlay.alpha` crossfade (`fadeInExpr`).
+ * This IS a per-pixel geq (heavier), used by a template's `renderMode:"premium"`
+ * path for the softest look; the `light` path uses `revealGate`/`revealSlide`
+ * instead. `on=false` returns the source untouched.
+ */
+export declare function revealFade<T extends MosaicSource>(src: T, atSec: number, durSec: number, on?: boolean): T;
+/** Map `revealFade` over every source in a node. */
+export declare function revealFadeNode(node: Node, atSec: number, durSec: number, on?: boolean): Node;
+/** Boolean sub-field. */
+export declare const fBool: (label: string, description?: string) => any;
+/** String sub-field. */
+export declare const fStr: (label: string, description?: string, placeholder?: string) => any;
+/** Number sub-field. */
+export declare const fNum: (label: string, description?: string, control?: any, constraints?: any) => any;
+/** 0..1 slider sub-field. */
+export declare const fFrac: (label: string, description?: string, placeholder?: string) => any;
+/** Enum (oneOf) sub-field. */
+export declare const fEnum: (label: string, oneOf: string[], description?: string) => any;
+/** The common alpine `anim` group fields. Templates spread + extend for extras
+ *  (e.g. `countUp`). Field names match the pack's `AnimConfig` keys. */
+export declare const ALPINE_ANIM_FIELDS: Record<string, any>;

package/dist/m0saic/alpine/_shared/alpine-anim.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * ============================================================================
+ * Alpine pack — shared reveal + animation-schema helpers (F4 U-A0)
+ * ============================================================================
+ *
+ * Two shared pieces the alpine tier adopts:
+ *
+ *  1. `revealGate` — the geq-free intro reveal. Alpine templates each carried a
+ *     local `fadeIn`/`wrapFade` wrapper that set a time-varying `overlay.alpha`
+ *     (`fadeInExpr`) — which compiles to a per-pixel `geq` fold (cost-model R3/R4,
+ *     paid every frame of a nesting parent's whole timeline). `revealGate` swaps
+ *     that for a free scalar `overlay.enable` gate: the element pops in at its
+ *     moment, no geq. (For elements that also SLIDE — a bar/fill growing via an
+ *     `xExpr`/`yExpr` translate — just drop the `alpha`; keep the translate. The
+ *     slide is the grow; the alpha was redundant fade sugar.)
+ *
+ *  2. `ALPINE_ANIM_FIELDS` + field helpers — the `anim` prop group shipped as a
+ *     `type:"group"` with NO `fields`, so it rendered as a raw JSON bag in Make.
+ *     These give it real labeled sub-fields. Templates with extra anim knobs
+ *     spread + add: `fields: { ...ALPINE_ANIM_FIELDS, countUp: fBool("Count up") }`.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALPINE_ANIM_FIELDS = exports.fEnum = exports.fFrac = exports.fNum = exports.fStr = exports.fBool = void 0;
+exports.revealGate = revealGate;
+exports.revealGateNode = revealGateNode;
+exports.revealSlide = revealSlide;
+exports.revealSlideNode = revealSlideNode;
+exports.revealFade = revealFade;
+exports.revealFadeNode = revealFadeNode;
+const template_utils_1 = require("@m0saic/template-utils");
+/**
+ * Reveal a source at `atSec` via a free `overlay.enable` gate (no geq). Raw
+ * `gte(t,X)` form — the engine escapes commas natively; do NOT use the
+ * comma-escaped `gatedEnableExpr`. `on = false` returns the source untouched
+ * (reduceMotion / static). Preserves any existing overlay (position/slide).
+ */
+function revealGate(src, atSec, on = true) {
+    var _a;
+    if (!on)
+        return src;
+    const prev = (_a = src.overlay) !== null && _a !== void 0 ? _a : {};
+    const at = Number(atSec.toFixed(3));
+    return {
+        ...src,
+        overlay: {
+            ...prev,
+            enable: `gte(t,${atSec.toFixed(3)})`,
+            // Structured twin of the gate (enable-gating sprint): lets the engine
+            // trim the source's upstream chain to its lifetime.
+            window: { startSec: at },
+        },
+    };
+}
+/** Map `revealGate` over every source in a node (the enable-gate analog of the
+ *  per-template `wrapFade` that fanned a fade over `node.sources`). */
+function revealGateNode(node, atSec, on = true) {
+    if (!on)
+        return node;
+    return { ...node, sources: node.sources.map((s) => revealGate(s, atSec, true)) };
+}
+/**
+ * Soft slide-in reveal — still geq-free. Enable-gates the source at `atSec` AND
+ * slides it up `distPx` into place over `durSec` via a per-frame `yExpr` translate
+ * (a position anim — cheap, NO alpha/geq). Reads softer than a hard `enable` pop
+ * without the per-pixel fade cost. `on=false` returns the source untouched.
+ */
+function revealSlide(src, atSec, durSec, distPx, on = true) {
+    var _a;
+    if (!on)
+        return src;
+    const prev = (_a = src.overlay) !== null && _a !== void 0 ? _a : {};
+    const eased = `min(1,max(0,lt/${Math.max(0.001, durSec).toFixed(3)}))`; // 0..1 over the window (local time)
+    return {
+        ...src,
+        overlay: {
+            ...prev,
+            startAtSec: atSec,
+            enable: `gte(t,${atSec.toFixed(3)})`,
+            yExpr: `${Math.round(distPx)}*(1-(${eased}))`,
+            window: { startSec: Number(atSec.toFixed(3)) },
+        },
+    };
+}
+/** Map `revealSlide` over every source in a node. */
+function revealSlideNode(node, atSec, durSec, distPx, on = true) {
+    if (!on)
+        return node;
+    return { ...node, sources: node.sources.map((s) => revealSlide(s, atSec, durSec, distPx, true)) };
+}
+/**
+ * Premium fade reveal — a time-varying `overlay.alpha` crossfade (`fadeInExpr`).
+ * This IS a per-pixel geq (heavier), used by a template's `renderMode:"premium"`
+ * path for the softest look; the `light` path uses `revealGate`/`revealSlide`
+ * instead. `on=false` returns the source untouched.
+ */
+function revealFade(src, atSec, durSec, on = true) {
+    var _a;
+    if (!on)
+        return src;
+    const prev = (_a = src.overlay) !== null && _a !== void 0 ? _a : {};
+    return {
+        ...src,
+        overlay: {
+            ...prev,
+            alpha: (0, template_utils_1.fadeInExpr)(atSec, durSec),
+            // The ramp holds alpha 0 before atSec — the source's lifetime starts
+            // there (feeds the engine's trim; the fade itself lowers natively).
+            window: { startSec: atSec },
+        },
+    };
+}
+/** Map `revealFade` over every source in a node. */
+function revealFadeNode(node, atSec, durSec, on = true) {
+    if (!on)
+        return node;
+    return { ...node, sources: node.sources.map((s) => revealFade(s, atSec, durSec, true)) };
+}
+// ── anim-group schema fields (kills the JSON-bag `anim` group) ────────────────
+/** Boolean sub-field. */
+const fBool = (label, description = "") => ({ type: "boolean", required: false, description, meta: { ui: { label } } });
+exports.fBool = fBool;
+/** String sub-field. */
+const fStr = (label, description = "", placeholder) => ({ type: "string", required: false, description, meta: { ui: { label }, ...(placeholder ? { control: { placeholder } } : {}) } });
+exports.fStr = fStr;
+/** Number sub-field. */
+const fNum = (label, description = "", control, constraints) => ({ type: "number", required: false, description, meta: { ...(constraints ? { constraints } : {}), ...(control ? { control } : {}), ui: { label } } });
+exports.fNum = fNum;
+/** 0..1 slider sub-field. */
+const fFrac = (label, description = "", placeholder) => (0, exports.fNum)(label, description, { flavor: "slider", step: 0.05, ...(placeholder ? { placeholder } : {}) }, { min: 0, max: 1 });
+exports.fFrac = fFrac;
+/** Enum (oneOf) sub-field. */
+const fEnum = (label, oneOf, description = "") => ({ type: "string", required: false, description, meta: { constraints: { oneOf }, ui: { label } } });
+exports.fEnum = fEnum;
+/** The common alpine `anim` group fields. Templates spread + extend for extras
+ *  (e.g. `countUp`). Field names match the pack's `AnimConfig` keys. */
+exports.ALPINE_ANIM_FIELDS = {
+    reduceMotion: (0, exports.fBool)("Reduce motion", "Skip motion; render the final static card."),
+    introFrac: (0, exports.fFrac)("Intro length", "Share of the clip the intro fills (the rest holds)."),
+    easing: (0, exports.fEnum)("Easing", ["easeOut", "smoothstep", "easeInOut", "linear"], "Intro easing curve."),
+};