@m0saic/templates 0.2.0

package/dist/m0saic/charts/donut/v1/geometry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v1 — ring geometry (pure)
+ * ============================================================================
+ *
+ * Pure math for the donut's annular sectors. No engine imports, no I/O —
+ * deterministic functions a unit test can pin exactly.
+ *
+ * Conventions:
+ *   - Angles in DEGREES, clockwise, 0° at 12 o'clock (screen coords, y down).
+ *   - Paths are authored in the consuming cell's own pixel space; the mask
+ *     `bounds` must match the cell so the engine's scale stays uniform
+ *     (the stat-card triangleSource idiom).
+ * ============================================================================
+ */
+export type DonutSegmentAngles = {
+    /** Clockwise start, degrees from 12 o'clock. */
+    startDeg: number;
+    /** Clockwise end, degrees from 12 o'clock. Always > startDeg. */
+    endDeg: number;
+    /** Normalized share of the whole [0..1]. */
+    frac: number;
+};
+export type AnnularSectorOpts = {
+    cx: number;
+    cy: number;
+    rOuter: number;
+    rInner: number;
+    startDeg: number;
+    endDeg: number;
+};
+/** Max segments the ring accepts — beyond this the slices stop reading. */
+export declare const MAX_SEGMENTS = 12;
+/**
+ * Normalize raw segment weights into cumulative clockwise angle spans,
+ * optionally separated by an angular gap (split evenly off both ends of
+ * each span). Fails fast on degenerate input.
+ */
+export declare function segmentsToAngles(values: number[], opts?: {
+    gapDeg?: number;
+}): DonutSegmentAngles[];
+/**
+ * SVG path for one annular sector (ring slice). Handles the large-arc
+ * flag for spans > 180°; a (near-)full circle is emitted as two half
+ * sectors in one path (a single 360° arc is degenerate in SVG).
+ */
+export declare function annularSectorPath(opts: AnnularSectorOpts): string;
+/**
+ * Visual center of an annular sector — mid-angle at mid-radius. Where a
+ * per-segment label (e.g. "75%") sits, like the classic donut mocks.
+ */
+export declare function sectorCentroid(opts: AnnularSectorOpts): {
+    x: number;
+    y: number;
+};

package/dist/m0saic/charts/donut/v1/geometry.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v1 — ring geometry (pure)
+ * ============================================================================
+ *
+ * Pure math for the donut's annular sectors. No engine imports, no I/O —
+ * deterministic functions a unit test can pin exactly.
+ *
+ * Conventions:
+ *   - Angles in DEGREES, clockwise, 0° at 12 o'clock (screen coords, y down).
+ *   - Paths are authored in the consuming cell's own pixel space; the mask
+ *     `bounds` must match the cell so the engine's scale stays uniform
+ *     (the stat-card triangleSource idiom).
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SEGMENTS = void 0;
+exports.segmentsToAngles = segmentsToAngles;
+exports.annularSectorPath = annularSectorPath;
+exports.sectorCentroid = sectorCentroid;
+/** Max segments the ring accepts — beyond this the slices stop reading. */
+exports.MAX_SEGMENTS = 12;
+/** Round to 0.1px — keeps paths compact and rasterization deterministic. */
+const n = (x) => Math.round(x * 10) / 10;
+/** Polar → cartesian with 0° at 12 o'clock, clockwise, y down. */
+function pt(cx, cy, r, deg) {
+    const rad = ((deg - 90) * Math.PI) / 180;
+    return [cx + r * Math.cos(rad), cy + r * Math.sin(rad)];
+}
+/**
+ * Normalize raw segment weights into cumulative clockwise angle spans,
+ * optionally separated by an angular gap (split evenly off both ends of
+ * each span). Fails fast on degenerate input.
+ */
+function segmentsToAngles(values, opts = {}) {
+    var _a;
+    const gapDeg = (_a = opts.gapDeg) !== null && _a !== void 0 ? _a : 0;
+    if (!Array.isArray(values) || values.length === 0) {
+        throw new Error("segmentsToAngles: values must be non-empty");
+    }
+    if (values.length > exports.MAX_SEGMENTS) {
+        throw new Error(`segmentsToAngles: at most ${exports.MAX_SEGMENTS} segments, got ${values.length}`);
+    }
+    if (!Number.isFinite(gapDeg) || gapDeg < 0 || gapDeg >= 360 / values.length) {
+        throw new Error(`segmentsToAngles: gapDeg out of range, got ${gapDeg}`);
+    }
+    let sum = 0;
+    for (const v of values) {
+        if (!Number.isFinite(v) || v < 0) {
+            throw new Error(`segmentsToAngles: values must be non-negative numbers, got ${v}`);
+        }
+        sum += v;
+    }
+    if (sum <= 0) {
+        throw new Error("segmentsToAngles: values must sum to > 0");
+    }
+    const out = [];
+    let acc = 0;
+    for (const v of values) {
+        const frac = v / sum;
+        const start = (acc / sum) * 360;
+        const end = ((acc + v) / sum) * 360;
+        out.push({
+            startDeg: start + gapDeg / 2,
+            endDeg: Math.max(start + gapDeg / 2, end - gapDeg / 2),
+            frac,
+        });
+        acc += v;
+    }
+    return out;
+}
+/**
+ * SVG path for one annular sector (ring slice). Handles the large-arc
+ * flag for spans > 180°; a (near-)full circle is emitted as two half
+ * sectors in one path (a single 360° arc is degenerate in SVG).
+ */
+function annularSectorPath(opts) {
+    const { cx, cy, rOuter, rInner, startDeg, endDeg } = opts;
+    if (!(rOuter > 0) || !(rInner >= 0) || rInner >= rOuter) {
+        throw new Error(`annularSectorPath: need 0 <= rInner < rOuter, got rInner=${rInner} rOuter=${rOuter}`);
+    }
+    const sweep = endDeg - startDeg;
+    if (!(sweep > 0)) {
+        throw new Error(`annularSectorPath: endDeg must exceed startDeg (sweep=${sweep})`);
+    }
+    if (sweep >= 359.999) {
+        const mid = startDeg + sweep / 2;
+        return (sectorPath(cx, cy, rOuter, rInner, startDeg, mid) +
+            " " +
+            sectorPath(cx, cy, rOuter, rInner, mid, startDeg + sweep));
+    }
+    return sectorPath(cx, cy, rOuter, rInner, startDeg, endDeg);
+}
+/**
+ * Visual center of an annular sector — mid-angle at mid-radius. Where a
+ * per-segment label (e.g. "75%") sits, like the classic donut mocks.
+ */
+function sectorCentroid(opts) {
+    const midDeg = (opts.startDeg + opts.endDeg) / 2;
+    const rMid = (opts.rOuter + opts.rInner) / 2;
+    const [x, y] = pt(opts.cx, opts.cy, rMid, midDeg);
+    return { x: n(x), y: n(y) };
+}
+function sectorPath(cx, cy, rOuter, rInner, startDeg, endDeg) {
+    const large = endDeg - startDeg > 180 ? 1 : 0;
+    const [ax, ay] = pt(cx, cy, rOuter, startDeg);
+    const [bx, by] = pt(cx, cy, rOuter, endDeg);
+    const [dx, dy] = pt(cx, cy, rInner, endDeg);
+    const [ex, ey] = pt(cx, cy, rInner, startDeg);
+    return (`M ${n(ax)} ${n(ay)} ` +
+        `A ${n(rOuter)} ${n(rOuter)} 0 ${large} 1 ${n(bx)} ${n(by)} ` +
+        `L ${n(dx)} ${n(dy)} ` +
+        `A ${n(rInner)} ${n(rInner)} 0 ${large} 0 ${n(ex)} ${n(ey)} Z`);
+}

package/dist/m0saic/charts/donut/v1/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v1 — Entry Point
+ * ============================================================================
+ *
+ * Single import entry for the donut template. Importing this file
+ * triggers side-effect registration via registerTemplate().
+ * ============================================================================
+ */
+export { Donut } from "./donut";
+export { annularSectorPath, segmentsToAngles } from "./geometry";

package/dist/m0saic/charts/donut/v1/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v1 — Entry Point
+ * ============================================================================
+ *
+ * Single import entry for the donut template. Importing this file
+ * triggers side-effect registration via registerTemplate().
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.segmentsToAngles = exports.annularSectorPath = exports.Donut = void 0;
+var donut_1 = require("./donut");
+Object.defineProperty(exports, "Donut", { enumerable: true, get: function () { return donut_1.Donut; } });
+var geometry_1 = require("./geometry");
+Object.defineProperty(exports, "annularSectorPath", { enumerable: true, get: function () { return geometry_1.annularSectorPath; } });
+Object.defineProperty(exports, "segmentsToAngles", { enumerable: true, get: function () { return geometry_1.segmentsToAngles; } });

package/dist/m0saic/charts/donut/v2/donut.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v2 — Bitmap Donut (the "complexity in the grid" probe)
+ * ============================================================================
+ *
+ * SAME picture as v1, OPPOSITE cost structure. A deliberate experiment to test
+ * a thesis surfaced by the benchmark heavy tier:
+ *
+ *   v1 puts complexity in the ENCODER — a trivial m0 (one cell) with ~31
+ *   full-canvas color tiles, each MASKED by an annular-sector SVG path and
+ *   composited every frame. A circle that reads as one item is 31 masked
+ *   sources alive for the whole clip.
+ *
+ *   v2 puts complexity in the m0 STRING / SOURCE COUNT — an N×N grid of tiny
+ *   UNMASKED `color=` tiles (a bitmap ring). Each ring cell is a plain lavfi
+ *   color revealed on a clockwise alpha schedule (the sweep). No SVG masks, no
+ *   per-source path geometry — just many trivial inputs the engine chunks.
+ *
+ * COMPOSITION (two layers, the v1 idiom):
+ *   1. base   — the ring, a nested mosaic CHILD whose m0 is the N×N grid. The
+ *               grid does ONE job: rasterize the circle.
+ *   2. overlay — the center value (+ optional caption), placed with the same
+ *               traditional text DSL v1 uses (centered drawtext, count-up). The
+ *               grid never carries text; the overlay layer does.
+ *
+ * RESOLUTION: grid() emits nested per-row / per-col splits (each at most N-way),
+ * NOT one giant >200-way split, so the literal-split rounding cap does not
+ * apply — the engine chunks thousands of color tiles fine. N trades smoothness
+ * for render time (cost grows ~linearly with N² cells): N≈14 is fast+blocky,
+ * N≈72 reads as a clean ring. Default 72.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+import { type EaseName } from "@m0saic/template-utils";
+type DonutSegment = {
+    label: string;
+    value: number;
+    color?: MosaicColor;
+};
+type DonutV2Anim = {
+    /** Count the hole value up from 0 on intro. Default true. */
+    countUp?: boolean;
+    /** Fraction of the OUTPUT duration the clockwise reveal fills. Default 0.7. */
+    introFrac?: number;
+    /** Absolute intro duration (ms). Overrides introFrac when set. */
+    introMs?: number;
+    /** Reveal + count-up easing. Default "easeOut". */
+    easing?: EaseName;
+    /** Disable motion — render the static final ring. Default false. */
+    reduceMotion?: boolean;
+};
+type DonutV2Props = {
+    segments: DonutSegment[];
+    /** Pre-formatted hole value (e.g. "247"). Absent → the segments' sum. */
+    centerValue?: string;
+    /** Small muted caption under the value. Absent → value only. */
+    centerLabel?: string;
+    /** Annulus thickness as a fraction of the outer radius. Default 0.4. */
+    ringThicknessFrac?: number;
+    /** Bitmap resolution — the ring is rasterized on an N×N grid. Default 72. */
+    resolution?: number;
+    /** Card surface color (also the hole + gaps). Default v1's card. */
+    backgroundColor?: MosaicColor;
+    anim?: DonutV2Anim;
+};
+export declare const DonutV2: MosaicTemplate<DonutV2Props>;
+export {};

package/dist/m0saic/charts/donut/v2/donut.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v2 — Bitmap Donut (the "complexity in the grid" probe)
+ * ============================================================================
+ *
+ * SAME picture as v1, OPPOSITE cost structure. A deliberate experiment to test
+ * a thesis surfaced by the benchmark heavy tier:
+ *
+ *   v1 puts complexity in the ENCODER — a trivial m0 (one cell) with ~31
+ *   full-canvas color tiles, each MASKED by an annular-sector SVG path and
+ *   composited every frame. A circle that reads as one item is 31 masked
+ *   sources alive for the whole clip.
+ *
+ *   v2 puts complexity in the m0 STRING / SOURCE COUNT — an N×N grid of tiny
+ *   UNMASKED `color=` tiles (a bitmap ring). Each ring cell is a plain lavfi
+ *   color revealed on a clockwise alpha schedule (the sweep). No SVG masks, no
+ *   per-source path geometry — just many trivial inputs the engine chunks.
+ *
+ * COMPOSITION (two layers, the v1 idiom):
+ *   1. base   — the ring, a nested mosaic CHILD whose m0 is the N×N grid. The
+ *               grid does ONE job: rasterize the circle.
+ *   2. overlay — the center value (+ optional caption), placed with the same
+ *               traditional text DSL v1 uses (centered drawtext, count-up). The
+ *               grid never carries text; the overlay layer does.
+ *
+ * RESOLUTION: grid() emits nested per-row / per-col splits (each at most N-way),
+ * NOT one giant >200-way split, so the literal-split rounding cap does not
+ * apply — the engine chunks thousands of color tiles fine. N trades smoothness
+ * for render time (cost grows ~linearly with N² cells): N≈14 is fast+blocky,
+ * N≈72 reads as a clean ring. Default 72.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DonutV2 = 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 geometry_1 = require("../v1/geometry");
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    segments: {
+        type: "array",
+        required: true,
+        description: "Ring segments in clockwise order from 12 o'clock. Raw weights — normalized internally.",
+        meta: { ui: { label: "Segments", order: 1 } },
+    },
+    centerValue: {
+        type: "string",
+        required: false,
+        description: "Pre-formatted hole value (e.g. \"247\"). Omit to derive the segments' sum.",
+        meta: { control: { placeholder: "e.g. 247" }, ui: { label: "Center value", order: 2 } },
+    },
+    centerLabel: {
+        type: "string",
+        required: false,
+        description: "Small muted caption under the value (e.g. \"Total Commits\").",
+        meta: { control: { placeholder: "e.g. Total Commits" }, ui: { label: "Center label", order: 3 } },
+    },
+    ringThicknessFrac: {
+        type: "number",
+        required: false,
+        description: "Annulus thickness as a fraction of the outer radius (0.05–0.9).",
+        meta: { constraints: { min: 0.05, max: 0.9 }, control: { flavor: "slider", step: 0.01 }, ui: { label: "Ring thickness", order: 9 } },
+    },
+    resolution: {
+        type: "number",
+        required: false,
+        description: "Bitmap grid resolution N (the ring is rasterized on N×N cells). Higher = smoother but render cost grows ~N². 14 is fast+blocky; 72 reads as a clean ring.",
+        meta: { constraints: { min: 6, max: 160 }, control: { flavor: "slider", step: 2 }, ui: { label: "Resolution (N×N)", order: 8 } },
+    },
+    backgroundColor: {
+        type: "string",
+        required: false,
+        description: "Card surface color (fills the hole and the corners behind the ring).",
+        meta: { constraints: { isColor: true }, control: { colorPicker: true }, ui: { label: "Card Color", order: 10 } },
+    },
+    anim: {
+        type: "group",
+        required: false,
+        description: "Clockwise reveal + count-up: intro length, easing, reduceMotion.",
+        meta: { ui: { label: "Animation", collapsedByDefault: true } },
+        fields: {
+            countUp: { type: "boolean", required: false, description: "Count the hole value up on intro.", meta: { ui: { label: "Count up" } } },
+            introFrac: { type: "number", required: false, description: "Fraction of the output duration the reveal fills (the rest holds).", meta: { constraints: { min: 0.1, max: 1 }, control: { flavor: "slider", step: 0.05 }, ui: { label: "Intro length (× duration)" } } },
+            introMs: { type: "number", required: false, description: "Absolute intro duration (ms). Overrides Intro length when set.", meta: { control: { placeholder: "from Intro fraction" }, constraints: { min: 0, max: 20000 }, ui: { label: "Intro (ms, override)" } } },
+            easing: { type: "string", required: false, description: "Reveal + count-up easing.", meta: { constraints: { oneOf: ["easeOut", "smoothstep", "easeInOut", "linear"] }, ui: { label: "Easing" } } },
+            reduceMotion: { type: "boolean", required: false, description: "Disable motion — render the static final ring.", meta: { ui: { label: "Reduce motion" } } },
+        },
+    },
+});
+// ---------------------------------------------------------------------------
+// Theme (mirror v1 so v1↔v2 read as the same chart)
+// ---------------------------------------------------------------------------
+const CARD_BG = "#161b22";
+const VALUE_COLOR = "#e6edf3";
+const CAPTION_COLOR = "#8b949e";
+const PALETTE = [
+    "#588168", "#95c6a7", "#3fb950", "#2f6f44", "#bfdcc8", "#1f4f30",
+];
+const DEFAULT_THICKNESS_FRAC = 0.4;
+const DEFAULT_RESOLUTION = 72;
+const MIN_RESOLUTION = 6;
+const MAX_RESOLUTION = 160;
+/** Outer ring radius as a fraction of the half-canvas (leaves a card margin). */
+const OUTER_R01 = 0.46;
+/** Value font as a fraction of the HOLE diameter (v1's tuned value). */
+const VALUE_FONT_FRAC = 0.3;
+/** Caption font as a fraction of the hole diameter (v1's tuned value). */
+const CAPTION_FONT_FRAC = 0.11;
+// ---------------------------------------------------------------------------
+// Center-text helpers (the v1 idiom: centered drawtext pinned by expression)
+// ---------------------------------------------------------------------------
+function centeredText(text, fontSize, color, cyPx) {
+    return {
+        type: "text",
+        visual: { backgroundColor: "black@0" },
+        layers: [
+            {
+                content: { kind: "literal", text: text || " " },
+                style: { fontSize, fontColor: color },
+                placement: cyPx == null
+                    ? { hAlign: "center", vAlign: "middle" }
+                    : { xExpr: "(w-text_w)/2", yExpr: `${Math.round(cyPx)}-text_h/2` },
+            },
+        ],
+    };
+}
+function centeredExprText(expr, fontSize, color, cyPx) {
+    return {
+        type: "text",
+        renderMode: { kind: "video" },
+        visual: { backgroundColor: "black@0" },
+        layers: [
+            {
+                content: { kind: "expr", expr, eval: "frame" },
+                style: { fontSize, fontColor: color },
+                placement: cyPx == null
+                    ? { hAlign: "center", vAlign: "middle" }
+                    : { xExpr: "(w-text_w)/2", yExpr: `${Math.round(cyPx)}-text_h/2` },
+            },
+        ],
+    };
+}
+function fadeIn(src, startSec, durSec, on) {
+    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)(startSec, durSec) } };
+}
+// ---------------------------------------------------------------------------
+// Template
+// ---------------------------------------------------------------------------
+exports.DonutV2 = {
+    id: (0, types_1.asTemplateId)("@m0saic/charts/donut/v2"),
+    label: "Donut Chart (bitmap)",
+    version: 2,
+    description: "Bitmap donut — the same ring + center total as v1, with the ring rendered as an N×N grid of tiny unmasked color tiles (complexity in source count, not in masked encoder work). A render-cost experiment paired with the benchmark heavy tier.",
+    capabilities: { tier: "core" },
+    // Shipped as a render-cost EXPERIMENT, not a production surface. The finding
+    // (see the internal source-count-duration-cost notes): the bitmap
+    // ring only beats v1 while coarse — at smooth resolution the grid-stitch cost
+    // grows ≈N² and v1's annular-sector masks are both crisper and faster. Kept
+    // for reference/benchmark use; not the recommended donut.
+    deprecated: {
+        reason: "Render-cost experiment. The bitmap ring wins only at low resolution; at smooth resolution the grid-stitch cost grows ≈N² and vector masks are both crisper and faster. Use v4 for production donuts (tight-bbox vector masks).",
+        replacement: (0, types_1.asTemplateId)("@m0saic/charts/donut/v4"),
+        since: "2026-06-18",
+    },
+    tags: ["charts", "donut", "distribution", "data-viz", "experiment", "bitmap"],
+    aspectRatio: { ideal: 1.0, min: 0.6, max: 1.8, mode: "warn" },
+    outputHints: { width: 360, height: 360, fps: 30, durationMs: 2000, note: "Square bitmap ring tile" },
+    propsSchema,
+    defaultProps: {
+        segments: [
+            { label: "Weekday Commits", value: 75 },
+            { label: "Weekend Commits", value: 25 },
+        ],
+        centerValue: "247",
+        ringThicknessFrac: DEFAULT_THICKNESS_FRAC,
+        resolution: DEFAULT_RESOLUTION,
+        backgroundColor: CARD_BG,
+        anim: { countUp: true, introFrac: 0.7, easing: "easeOut", reduceMotion: false },
+    },
+    render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        const W = ctx.output.width;
+        const H = ctx.output.height;
+        // ── Fail-fast validation (mirror v1) ──
+        if (!Array.isArray(props.segments) || props.segments.length === 0) {
+            throw new Error("@m0saic/charts/donut/v2: segments must be a non-empty array");
+        }
+        if (props.segments.length > geometry_1.MAX_SEGMENTS) {
+            throw new Error(`@m0saic/charts/donut/v2: at most ${geometry_1.MAX_SEGMENTS} segments`);
+        }
+        const thickness = (_a = props.ringThicknessFrac) !== null && _a !== void 0 ? _a : DEFAULT_THICKNESS_FRAC;
+        if (!Number.isFinite(thickness) || thickness < 0.05 || thickness > 0.9) {
+            throw new Error(`@m0saic/charts/donut/v2: ringThicknessFrac must be in [0.05, 0.9], got ${thickness}`);
+        }
+        const N = Math.max(MIN_RESOLUTION, Math.min(MAX_RESOLUTION, Math.round((_b = props.resolution) !== null && _b !== void 0 ? _b : DEFAULT_RESOLUTION)));
+        // ── Normalized segment fraction boundaries (clockwise from 12 o'clock) ──
+        const values = props.segments.map((s) => (Number.isFinite(s.value) && s.value > 0 ? s.value : 0));
+        const total = values.reduce((a, b) => a + b, 0);
+        if (total <= 0)
+            throw new Error("@m0saic/charts/donut/v2: segment values must sum to > 0");
+        const cum = [];
+        let acc = 0;
+        for (const v of values) {
+            acc += v;
+            cum.push(acc / total);
+        }
+        const segColor = (i) => { var _a; return (_a = props.segments[i].color) !== null && _a !== void 0 ? _a : PALETTE[i % PALETTE.length]; };
+        /** angle-fraction [0,1) clockwise from top → segment index */
+        const segOf = (af) => {
+            for (let k = 0; k < cum.length; k++)
+                if (af < cum[k] - 1e-9)
+                    return k;
+            return cum.length - 1;
+        };
+        // ── Ring geometry on the unit square ──
+        const outerR = OUTER_R01;
+        const innerR = OUTER_R01 * (1 - thickness);
+        // ── Intro timing (ctx.target is the only time source) ──
+        const anim = (_c = props.anim) !== null && _c !== void 0 ? _c : {};
+        const reduceMotion = (_d = anim.reduceMotion) !== null && _d !== void 0 ? _d : false;
+        const ease = (_e = anim.easing) !== null && _e !== void 0 ? _e : "easeOut";
+        const totalSec = ctx.target.durationMs / 1000;
+        const introSec = anim.introMs != null ? anim.introMs / 1000 : totalSec * ((_f = anim.introFrac) !== null && _f !== void 0 ? _f : 0.7);
+        const animateRing = !reduceMotion && introSec > 0;
+        // Fade a cell in over a couple cells' worth of the clockwise dwell so the
+        // leading edge isn't a hard pop.
+        const fadeDur = Math.max(0.05, introSec * (2 / Math.max(1, N)));
+        const bg = (_g = props.backgroundColor) !== null && _g !== void 0 ? _g : CARD_BG;
+        // ── LAYER 1: the ring, rasterized as an N×N grid (its own child doc) ──
+        const { m0: gridM0 } = (0, dsl_stdlib_1.grid)({ rows: N, cols: N });
+        const ringSources = new Array(N * N);
+        for (let i = 0; i < N * N; i++) {
+            const row = Math.floor(i / N);
+            const col = i % N;
+            const x = (col + 0.5) / N - 0.5; // [-0.5, 0.5]
+            const y = (row + 0.5) / N - 0.5;
+            const dist = Math.hypot(x, y);
+            const inRing = dist >= innerR && dist <= outerR;
+            if (!inRing) {
+                ringSources[i] = (0, template_utils_1.makeColorTile)(bg); // hole + corners: card fill
+                continue;
+            }
+            // Clockwise angle fraction from 12 o'clock: atan2(x, -y) ∈ (-π, π].
+            let ang = Math.atan2(x, -y);
+            if (ang < 0)
+                ang += 2 * Math.PI;
+            const af = ang / (2 * Math.PI);
+            const color = segColor(segOf(af));
+            if (!animateRing) {
+                ringSources[i] = (0, template_utils_1.makeColorTile)(color);
+                continue;
+            }
+            const startAtSec = introSec * af; // reveal when the sweep reaches this angle
+            ringSources[i] = (0, template_utils_1.makeColorTile)(color, { overlay: { alpha: (0, template_utils_1.fadeInExpr)(startAtSec, fadeDur, ease) } });
+        }
+        const ringDoc = {
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0: gridM0,
+            sources: ringSources,
+            backgroundColor: bg,
+            fps: ctx.target.fps,
+            durationMs: ctx.target.durationMs,
+        };
+        // ── LAYER 2+: center value (+ optional caption) — traditional v1 text DSL ──
+        const cx = W / 2;
+        const cy = H / 2;
+        const holeDia = 2 * innerR * Math.min(W, H);
+        const valueText = (_h = props.centerValue) !== null && _h !== void 0 ? _h : String(Math.round(props.segments.reduce((s, x) => s + x.value, 0)));
+        const valueFont = Math.max(12, Math.round(holeDia * VALUE_FONT_FRAC));
+        const captionLen = Math.max(1, ((_j = props.centerLabel) !== null && _j !== void 0 ? _j : "").trim().length);
+        const captionFont = Math.max(9, Math.round(Math.min(holeDia * CAPTION_FONT_FRAC, (holeDia * 0.92) / (0.55 * captionLen))));
+        const hasCaption = !!(props.centerLabel && props.centerLabel.trim() !== "");
+        const valueCy = hasCaption ? cy - innerR * Math.min(W, H) * 0.12 : undefined;
+        const captionCy = cy + innerR * Math.min(W, H) * 0.44;
+        const animateValue = ((_k = anim.countUp) !== null && _k !== void 0 ? _k : true) && !reduceMotion && /\d/.test(valueText);
+        const textSources = [
+            animateValue
+                ? centeredExprText((0, template_utils_1.animateNumbersInText)(valueText, { durationSec: introSec, ease }), valueFont, VALUE_COLOR, valueCy)
+                : centeredText(valueText, valueFont, VALUE_COLOR, valueCy),
+        ];
+        if (hasCaption) {
+            textSources.push(fadeIn(centeredText(props.centerLabel, captionFont, CAPTION_COLOR, captionCy), introSec * 0.8, introSec * 0.2, !reduceMotion));
+        }
+        // ── Root: overlay stack — ring child below, text on top ──
+        const rootSources = [{ type: "mosaic", ref: "ring" }, ...textSources];
+        const m0 = (0, template_utils_1.buildOverlayStack)(rootSources.length);
+        return Promise.resolve({
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0,
+            sources: rootSources,
+            children: { ring: ringDoc },
+            backgroundColor: bg,
+            fps: ctx.target.fps,
+            durationMs: ctx.target.durationMs,
+        });
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.DonutV2);

package/dist/m0saic/charts/donut/v2/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v2 — Entry Point
+ * ============================================================================
+ *
+ * Single import entry for the bitmap-donut experiment. Importing this file
+ * triggers side-effect registration via registerTemplate().
+ * ============================================================================
+ */
+export { DonutV2 } from "./donut";

package/dist/m0saic/charts/donut/v2/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v2 — Entry Point
+ * ============================================================================
+ *
+ * Single import entry for the bitmap-donut experiment. Importing this file
+ * triggers side-effect registration via registerTemplate().
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DonutV2 = void 0;
+var donut_1 = require("./donut");
+Object.defineProperty(exports, "DonutV2", { enumerable: true, get: function () { return donut_1.DonutV2; } });

package/dist/m0saic/charts/donut/v3/anim.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v3 — sweep animation math (pure)
+ * ============================================================================
+ *
+ * Timing math for the donut's intro animation, kept out of the template body
+ * (math here, ffmpeg expressions confined to leaf sources).
+ *
+ * The engine has no radial primitive, so a continuous clockwise wipe is
+ * approximated by a QUANTIZED SWEEP: the ring subdivides into thin angular
+ * slivers, each its own (tightly-placed) masked color source, revealed on a
+ * staggered schedule. Overlapping alpha fades soften the leading edge so it
+ * reads as one motion, not a strobing fan.
+ *
+ * The schedule runs through the INVERSE of the easing so the sweep's angular
+ * progress matches the eased count-up in the hole — the ring closes exactly as
+ * the number lands.
+ * ============================================================================
+ */
+import type { EaseName } from "@m0saic/template-utils";
+import type { DonutSegmentAngles } from "./geometry";
+export type SweepSliver = {
+    /** Which input segment this sliver belongs to (color lookup). */
+    segIndex: number;
+    /** Sliver span, degrees clockwise from 12 o'clock. */
+    startDeg: number;
+    endDeg: number;
+    /** Sweep progress [0..1] at the sliver's LEADING edge (startDeg/360). */
+    frac0: number;
+};
+export declare const DEFAULT_SLIVER_DEG = 12;
+export declare const MAX_SLIVERS = 36;
+/**
+ * Subdivide the segment spans into a single global clockwise schedule of
+ * slivers. Each segment gets ceil(span/sliverDeg) uniform slivers; when the
+ * whole ring would exceed `maxSlivers`, the pitch widens deterministically.
+ */
+export declare function subdivideForSweep(angles: DonutSegmentAngles[], opts?: {
+    sliverDeg?: number;
+    maxSlivers?: number;
+}): SweepSliver[];
+/**
+ * Inverse of the easing curve: the TIME fraction u at which the eased progress
+ * reaches `p`. Exact for "easeOut" (quadratic) and "linear"; the cubic pair
+ * (smoothstep / easeInOut) falls back to linear scheduling.
+ */
+export declare function sweepInverseEase(ease: EaseName, p: number): number;