@m0saic/templates 0.2.0

package/dist/m0saic/charts/bar-graph/v2/index.d.ts

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

package/dist/m0saic/charts/bar-graph/v2/index.js

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

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

@@ -0,0 +1,54 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v1 — sweep animation math (pure)
+ * ============================================================================
+ *
+ * Timing math for the donut's intro animation, kept out of the template
+ * body per the bar-graph contract (math in anim.ts, 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 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 to fit.
+ */
+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`. Used schedule-side (plain JS, deterministic) so
+ * sliver start times line up with the ffmpeg-side eased count-up.
+ *
+ * Exact for "easeOut" (quadratic, matching template-utils' easingExpr)
+ * and "linear". The cubic pair (smoothstep / easeInOut) falls back to
+ * linear scheduling — the sweep still completes with the intro, it just
+ * doesn't decelerate in lockstep.
+ */
+export declare function sweepInverseEase(ease: EaseName, p: number): number;

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

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v1 — sweep animation math (pure)
+ * ============================================================================
+ *
+ * Timing math for the donut's intro animation, kept out of the template
+ * body per the bar-graph contract (math in anim.ts, 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 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.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SLIVERS = exports.DEFAULT_SLIVER_DEG = void 0;
+exports.subdivideForSweep = subdivideForSweep;
+exports.sweepInverseEase = sweepInverseEase;
+exports.DEFAULT_SLIVER_DEG = 12;
+exports.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 to fit.
+ */
+function subdivideForSweep(angles, opts = {}) {
+    var _a, _b;
+    const maxSlivers = (_a = opts.maxSlivers) !== null && _a !== void 0 ? _a : exports.MAX_SLIVERS;
+    let sliverDeg = (_b = opts.sliverDeg) !== null && _b !== void 0 ? _b : exports.DEFAULT_SLIVER_DEG;
+    if (!(sliverDeg > 0) || !(maxSlivers >= 1)) {
+        throw new Error("subdivideForSweep: sliverDeg and maxSlivers must be positive");
+    }
+    if (360 / sliverDeg > maxSlivers)
+        sliverDeg = 360 / maxSlivers;
+    const out = [];
+    for (let i = 0; i < angles.length; i++) {
+        const a = angles[i];
+        const span = a.endDeg - a.startDeg;
+        if (span <= 0.0001)
+            continue;
+        const n = Math.max(1, Math.ceil(span / sliverDeg));
+        const step = span / n;
+        for (let k = 0; k < n; k++) {
+            const s = a.startDeg + k * step;
+            out.push({
+                segIndex: i,
+                startDeg: s,
+                endDeg: a.startDeg + (k + 1) * step,
+                frac0: s / 360,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Inverse of the easing curve: the TIME fraction u at which the eased
+ * progress reaches `p`. Used schedule-side (plain JS, deterministic) so
+ * sliver start times line up with the ffmpeg-side eased count-up.
+ *
+ * Exact for "easeOut" (quadratic, matching template-utils' easingExpr)
+ * and "linear". The cubic pair (smoothstep / easeInOut) falls back to
+ * linear scheduling — the sweep still completes with the intro, it just
+ * doesn't decelerate in lockstep.
+ */
+function sweepInverseEase(ease, p) {
+    const c = Math.max(0, Math.min(1, p));
+    switch (ease) {
+        case "easeOut":
+            return 1 - Math.sqrt(1 - c);
+        case "linear":
+        case "smoothstep":
+        case "easeInOut":
+        default:
+            return c;
+    }
+}

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

@@ -0,0 +1,87 @@
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v1 — Canonical Donut Chart (data-viz primitive)
+ * ============================================================================
+ *
+ * A proportional ring with a dominant total in the hole — the "Commit
+ * Distribution" tile of the GitHub repo-tracker hero. Renders the ring as
+ * ONE cell: each segment is a color source (makeColorTile — ffmpeg composes)
+ * masked by an annular-sector SVG path (SVG draws), all stacked as overlay
+ * layers in a single frame. No grid cells per segment, no split-rounding
+ * exposure.
+ *
+ * GEOMETRY (sandbox session 2026-06-12-donut-distribution; the human's
+ * hand-corrected candidate-004 set the defaults):
+ *
+ *   - ring centered in the canvas; outer diameter ≈ 0.92 × min(W, H)
+ *     (the "Donut Chart Area" region the human drew)
+ *   - hole carries the value — the human's 100×100 "Number Area" on a
+ *     ~178px circle ⇒ ringThicknessFrac default 0.36
+ *   - segments run CLOCKWISE from 12 o'clock in input order (the 75%
+ *     majority sweeps right/down; the 25% minority lands upper-left,
+ *     matching the reference crop)
+ *   - flush segments (no angular gap), per the reference
+ *
+ * No title/legend surface: "Commit Distribution / Weekday vs Weekend" is
+ * panel chrome (a separate primitive); the reference shows no legend rows.
+ * A legend prop can land later — the surface stays lean until asked for.
+ *
+ * ANIMATION (first-class, per the hero plan):
+ *   - "sweep" (default): quantized clockwise wipe — the ring subdivides
+ *     into thin angular slivers (anim.ts), each revealed on an
+ *     inverse-eased schedule so the ring closes exactly as the eased
+ *     count-up in the hole lands on its number. Overlapping fades keep
+ *     the leading edge continuous; slivers within a segment overlap by
+ *     a hair so anti-aliased seams can't show through.
+ *   - "fade": one whole sector per segment, staggered fade — the cheap
+ *     variant (~3 sources instead of ~30).
+ *   - reduceMotion: static final frame.
+ * Expressions stay confined to leaf sources (the bar-graph BarFill model);
+ * all timing math lives in anim.ts / template-utils.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+import { type EaseName } from "@m0saic/template-utils";
+type DonutSegment = {
+    /** Series name (e.g. "Weekday Commits"). Carried for tooling/legend-later. */
+    label: string;
+    /** Raw weight — normalized internally. Non-negative. */
+    value: number;
+    /** Slice color. Defaults to the theme palette by index. */
+    color?: MosaicColor;
+};
+type DonutAnim = {
+    /** Intro mode: quantized clockwise "sweep" (default) or per-segment "fade". */
+    mode?: "sweep" | "fade";
+    /** Count the hole value up from 0 on intro. Default true. */
+    countUp?: boolean;
+    /** Fraction of the OUTPUT duration the intro fills. Default 0.7. */
+    introFrac?: number;
+    /** Absolute intro duration (ms). Overrides introFrac when set. */
+    introMs?: number;
+    /** Easing — the sweep schedule runs through its inverse. Default "easeOut". */
+    easing?: EaseName;
+    /** Disable all motion — render the final static ring. Default false. */
+    reduceMotion?: boolean;
+};
+type DonutProps = {
+    segments: DonutSegment[];
+    /** Pre-formatted hole value (e.g. "247"). Absent → the segments' sum. */
+    centerValue?: string;
+    /** Small muted caption under the value. Absent → value only (reference). */
+    centerLabel?: string;
+    /** Annulus thickness as a fraction of the outer radius. Default 0.36. */
+    ringThicknessFrac?: number;
+    /**
+     * Per-segment labels rendered ON the slices (mid-angle, mid-radius).
+     * "percent" = the derived share ("19%"), auto black/white text by
+     * slice luminance; slices too thin to fit a label are skipped.
+     * Default "none" (the reference tile carries no slice labels).
+     */
+    segmentLabels?: "none" | "percent";
+    /** Card surface color. Pass "none" when composed under card chrome. */
+    backgroundColor?: MosaicColor;
+    anim?: DonutAnim;
+};
+export declare const Donut: MosaicTemplate<DonutProps>;
+export {};

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

@@ -0,0 +1,400 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/charts/donut/v1 — Canonical Donut Chart (data-viz primitive)
+ * ============================================================================
+ *
+ * A proportional ring with a dominant total in the hole — the "Commit
+ * Distribution" tile of the GitHub repo-tracker hero. Renders the ring as
+ * ONE cell: each segment is a color source (makeColorTile — ffmpeg composes)
+ * masked by an annular-sector SVG path (SVG draws), all stacked as overlay
+ * layers in a single frame. No grid cells per segment, no split-rounding
+ * exposure.
+ *
+ * GEOMETRY (sandbox session 2026-06-12-donut-distribution; the human's
+ * hand-corrected candidate-004 set the defaults):
+ *
+ *   - ring centered in the canvas; outer diameter ≈ 0.92 × min(W, H)
+ *     (the "Donut Chart Area" region the human drew)
+ *   - hole carries the value — the human's 100×100 "Number Area" on a
+ *     ~178px circle ⇒ ringThicknessFrac default 0.36
+ *   - segments run CLOCKWISE from 12 o'clock in input order (the 75%
+ *     majority sweeps right/down; the 25% minority lands upper-left,
+ *     matching the reference crop)
+ *   - flush segments (no angular gap), per the reference
+ *
+ * No title/legend surface: "Commit Distribution / Weekday vs Weekend" is
+ * panel chrome (a separate primitive); the reference shows no legend rows.
+ * A legend prop can land later — the surface stays lean until asked for.
+ *
+ * ANIMATION (first-class, per the hero plan):
+ *   - "sweep" (default): quantized clockwise wipe — the ring subdivides
+ *     into thin angular slivers (anim.ts), each revealed on an
+ *     inverse-eased schedule so the ring closes exactly as the eased
+ *     count-up in the hole lands on its number. Overlapping fades keep
+ *     the leading edge continuous; slivers within a segment overlap by
+ *     a hair so anti-aliased seams can't show through.
+ *   - "fade": one whole sector per segment, staggered fade — the cheap
+ *     variant (~3 sources instead of ~30).
+ *   - reduceMotion: static final frame.
+ * Expressions stay confined to leaf sources (the bar-graph BarFill model);
+ * all timing math lives in anim.ts / template-utils.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Donut = void 0;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const geometry_1 = require("./geometry");
+const anim_1 = require("./anim");
+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 } },
+    },
+    segmentLabels: {
+        type: "string",
+        required: false,
+        description: "Per-segment labels on the slices. \"percent\" shows each segment's derived share; thin slices are skipped.",
+        meta: { constraints: { oneOf: ["none", "percent"] }, ui: { label: "Segment labels", order: 4 } },
+    },
+    backgroundColor: {
+        type: "string",
+        required: false,
+        description: "Card surface color. Pass \"none\" to render transparent when composed under a card-chrome primitive.",
+        meta: { constraints: { isColor: true }, control: { colorPicker: true }, ui: { label: "Card Color", order: 10 } },
+    },
+    anim: {
+        type: "group",
+        required: false,
+        description: "Intro animation: clockwise sweep (or per-segment fade), count-up total, easing, duration, reduceMotion.",
+        meta: { ui: { label: "Animation", collapsedByDefault: true } },
+        fields: {
+            mode: { type: "string", required: false, description: "Quantized clockwise sweep, or staggered per-segment fade.", meta: { constraints: { oneOf: ["sweep", "fade"] }, ui: { label: "Mode" } } },
+            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 intro 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: "Sweep + count-up easing.", meta: { constraints: { oneOf: ["easeOut", "smoothstep", "easeInOut", "linear"] }, ui: { label: "Easing" } } },
+            reduceMotion: { type: "boolean", required: false, description: "Disable all motion — render the static final ring.", meta: { ui: { label: "Reduce motion" } } },
+        },
+    },
+});
+// ---------------------------------------------------------------------------
+// Theme (dark — GitHub-palette aligned; ring colors sampled from the
+// reference crop: majority muted sage, minority light sage)
+// ---------------------------------------------------------------------------
+const CARD_BG = "#161b22";
+const VALUE_COLOR = "#e6edf3";
+const CAPTION_COLOR = "#8b949e";
+const PALETTE = [
+    "#588168", // majority — muted sage (reference ring)
+    "#95c6a7", // minority — light sage (reference ring)
+    "#3fb950",
+    "#2f6f44",
+    "#bfdcc8",
+    "#1f4f30",
+];
+/** Ring outer diameter as a fraction of min(W, H). */
+const RADIUS_SCALE = 0.92;
+/** Default annulus thickness / outer radius (human-corrected candidate-004). */
+const DEFAULT_THICKNESS_FRAC = 0.36;
+/** Flush segments per the reference (no angular gap). */
+const GAP_DEG = 0;
+/** Value font as a fraction of the HOLE diameter (human-tuned, c-008). */
+const VALUE_FONT_FRAC = 0.3;
+/** Caption font as a fraction of the hole diameter (human-tuned, c-008:
+ *  "reduce by ~20%"). */
+const CAPTION_FONT_FRAC = 0.11;
+/** Segment-label font as a fraction of the annulus thickness. */
+const SEG_LABEL_FONT_FRAC = 0.42;
+/** Slices sweeping less than this get no label — the text can't fit. */
+const SEG_LABEL_MIN_SWEEP_DEG = 14;
+/** Segment-label text colors, picked by slice luminance. */
+const SEG_LABEL_LIGHT = "#f0f6f1";
+const SEG_LABEL_DARK = "#10141a";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+// Horizontally centered text, vertically pinned to an exact pixel line
+// via explicit drawtext expressions (`cyPx` = the glyph box's vertical
+// CENTER). `cyPx` omitted → canvas center. Exact-expression placement —
+// alignment-padding offsets proved unreliable for the value/caption
+// pair (they overlapped), so the hole text uses the same xExpr/yExpr
+// mechanism as the per-segment labels.
+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` },
+            },
+        ],
+    };
+}
+// Animated hole value: an expr text layer evaluated per-frame on a
+// video-renderMode source — the stat-card count-up idiom, centered.
+// FIXED fontSize so the digits don't rescale as the number grows.
+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` },
+            },
+        ],
+    };
+}
+// Premium content reveal: fade a source in via overlay.alpha (evaluated
+// per frame at composite time, so still sources animate in a video render).
+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) } };
+}
+// Per-segment label pinned to an exact point via explicit drawtext
+// expressions (text_w/text_h center the glyph box on the centroid) —
+// no cell math, no width estimation.
+function pointText(text, px, py, fontSize, color) {
+    return {
+        type: "text",
+        visual: { backgroundColor: "black@0" },
+        layers: [
+            {
+                content: { kind: "literal", text },
+                style: { fontSize, fontColor: color },
+                placement: { xExpr: `${px}-text_w/2`, yExpr: `${py}-text_h/2` },
+            },
+        ],
+    };
+}
+/** Black-or-white label text by slice luminance (WCAG-ish quick check). */
+function labelColorFor(hex) {
+    const m = /^#?([0-9a-f]{6})/i.exec(String(hex));
+    if (!m)
+        return SEG_LABEL_LIGHT;
+    const v = parseInt(m[1], 16);
+    const r = (v >> 16) & 0xff;
+    const g = (v >> 8) & 0xff;
+    const b = v & 0xff;
+    const luminance = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+    return luminance > 0.6 ? SEG_LABEL_DARK : SEG_LABEL_LIGHT;
+}
+// ---------------------------------------------------------------------------
+// Template
+// ---------------------------------------------------------------------------
+exports.Donut = {
+    id: (0, types_1.asTemplateId)("@m0saic/charts/donut/v1"),
+    label: "Donut Chart",
+    version: 1,
+    description: "Canonical donut chart: proportional ring + dominant center total. Building block of the repo-tracker hero (Commit Distribution tile).",
+    capabilities: { tier: "core" },
+    primitive: true, // foundational data-viz building block (composed by the repo-tracker hero)
+    deprecated: {
+        reason: "Full-canvas mask antipattern: every slice (and every sweep sliver) is a 360×360 color tile masked to a thin sector, so renders are slow and intermediates huge for what paints as a sliver. Kept as the canonical 'bad' example. Use v4 — same picture, each slice placed as a tight bbox with a cell-local mask.",
+        replacement: (0, types_1.asTemplateId)("@m0saic/charts/donut/v4"),
+        since: "2026-06-21",
+    },
+    tags: ["charts", "donut", "distribution", "data-viz"],
+    aspectRatio: { ideal: 1.0, min: 0.6, max: 1.8, mode: "warn" },
+    outputHints: { width: 360, height: 360, fps: 30, durationMs: 2000, note: "Square ring tile; the hero places it inside the panel's donut region" },
+    propsSchema,
+    defaultProps: {
+        segmentLabels: "none",
+        ringThicknessFrac: 0.36,
+        segments: [
+            { label: "Weekday Commits", value: 75 },
+            { label: "Weekend Commits", value: 25 },
+        ],
+        centerValue: "247",
+        backgroundColor: CARD_BG,
+        anim: { mode: "sweep", countUp: true, introFrac: 0.7, easing: "easeOut", reduceMotion: false },
+    },
+    render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        const W = ctx.output.width;
+        const H = ctx.output.height;
+        // ── Fail-fast validation ──
+        if (!Array.isArray(props.segments) || props.segments.length === 0) {
+            throw new Error("@m0saic/charts/donut/v1: segments must be a non-empty array");
+        }
+        if (props.segments.length > geometry_1.MAX_SEGMENTS) {
+            throw new Error(`@m0saic/charts/donut/v1: 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/v1: ringThicknessFrac must be in [0.05, 0.9], got ${thickness}`);
+        }
+        // ── Ring geometry (all in canvas px; mask bounds = the full canvas) ──
+        const cx = W / 2;
+        const cy = H / 2;
+        const rOuter = (Math.min(W, H) / 2) * RADIUS_SCALE;
+        const rInner = rOuter * (1 - thickness);
+        const holeDia = 2 * rInner;
+        const angles = (0, geometry_1.segmentsToAngles)(props.segments.map((s) => s.value), { gapDeg: GAP_DEG });
+        // ── Intro timing (the §10 time source: ctx.target) ──
+        const anim = (_b = props.anim) !== null && _b !== void 0 ? _b : {};
+        const reduceMotion = (_c = anim.reduceMotion) !== null && _c !== void 0 ? _c : false;
+        const mode = (_d = anim.mode) !== null && _d !== void 0 ? _d : "sweep";
+        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;
+        const segColor = (i) => { var _a; return (_a = props.segments[i].color) !== null && _a !== void 0 ? _a : PALETTE[i % PALETTE.length]; };
+        const sectorTile = (segIndex, startDeg, endDeg, overlay) => (0, template_utils_1.makeColorTile)(segColor(segIndex), {
+            mask: {
+                kind: "inline-mask",
+                localPath: (0, geometry_1.annularSectorPath)({ cx, cy, rOuter, rInner, startDeg, endDeg }),
+                bounds: { x: 0, y: 0, width: W, height: H },
+            },
+            ...(overlay ? { overlay } : {}),
+        });
+        // ── Sector sources. Zero-share segments contribute no source (a
+        // 0°-sweep path is degenerate); proportions already account for them.
+        const sectorSources = [];
+        if (animateRing && mode === "sweep") {
+            // Quantized clockwise sweep: thin slivers on an inverse-eased
+            // schedule, so angular progress tracks the eased count-up and the
+            // ring closes exactly as the number lands. Within a segment each
+            // sliver overlaps the next by a hair (later paints on top) so
+            // anti-aliased seams can't show through; segment boundaries stay
+            // exact so colors never bleed.
+            const slivers = (0, anim_1.subdivideForSweep)(angles);
+            const fadeDur = Math.max(0.05, (introSec / Math.max(1, slivers.length)) * 2.5);
+            for (const s of slivers) {
+                const segEnd = angles[s.segIndex].endDeg;
+                const end = Math.min(segEnd, s.endDeg + 0.35);
+                const startAtSec = introSec * (0, anim_1.sweepInverseEase)(ease, s.frac0);
+                sectorSources.push(sectorTile(s.segIndex, s.startDeg, end, {
+                    startAtSec,
+                    alpha: (0, template_utils_1.fadeInExpr)(startAtSec, fadeDur),
+                }));
+            }
+        }
+        else if (animateRing && mode === "fade") {
+            // Cheap variant: whole sectors, staggered fade in clockwise order.
+            const fadeDur = introSec * 0.45;
+            for (let i = 0; i < angles.length; i++) {
+                const a = angles[i];
+                if (a.endDeg - a.startDeg <= 0.0001)
+                    continue;
+                const startAtSec = introSec * 0.5 * (a.startDeg / 360);
+                sectorSources.push(sectorTile(i, a.startDeg, a.endDeg, {
+                    startAtSec,
+                    alpha: (0, template_utils_1.fadeInExpr)(startAtSec, fadeDur),
+                }));
+            }
+        }
+        else {
+            for (let i = 0; i < angles.length; i++) {
+                const a = angles[i];
+                if (a.endDeg - a.startDeg <= 0.0001)
+                    continue;
+                sectorSources.push(sectorTile(i, a.startDeg, a.endDeg));
+            }
+        }
+        // ── Center value (+ optional caption) in the hole ──
+        const valueText = (_g = props.centerValue) !== null && _g !== void 0 ? _g : String(Math.round(props.segments.reduce((s, x) => s + x.value, 0)));
+        const valueFont = Math.max(12, Math.round(holeDia * VALUE_FONT_FRAC));
+        // Caption font shrinks with text length so long captions ("Issues
+        // Raised") stay inside the hole instead of grazing the ring —
+        // ~0.55 em average glyph width against 92% of the hole diameter.
+        const captionLen = Math.max(1, ((_h = props.centerLabel) !== null && _h !== void 0 ? _h : "").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() !== "");
+        // With a caption the pair splits around the hole center: the value
+        // nudges up (less than before — "drop lower a bit", c-008), the
+        // caption sits below it — exact pixel lines.
+        const valueCy = hasCaption ? cy - rInner * 0.12 : undefined;
+        const captionCy = cy + rInner * 0.44;
+        const animateValue = ((_j = anim.countUp) !== null && _j !== void 0 ? _j : 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) {
+            // Caption reveals late — the value lands first, then its label.
+            textSources.push(fadeIn(centeredText(props.centerLabel, captionFont, CAPTION_COLOR, captionCy), introSec * 0.8, introSec * 0.2, !reduceMotion));
+        }
+        // ── Per-segment labels ON the slices (mid-angle, mid-radius) ──
+        // Percent shares derived from the normalized values; thin slices
+        // skip the label. In sweep mode each label fades in as its segment
+        // COMPLETES (the sweep's leading edge passes its end angle).
+        const segLabelSources = [];
+        if (((_k = props.segmentLabels) !== null && _k !== void 0 ? _k : "none") === "percent") {
+            const ringPx = rOuter - rInner;
+            const segFont = Math.max(9, Math.round(ringPx * SEG_LABEL_FONT_FRAC));
+            for (let i = 0; i < angles.length; i++) {
+                const a = angles[i];
+                if (a.endDeg - a.startDeg < SEG_LABEL_MIN_SWEEP_DEG)
+                    continue;
+                const { x, y } = (0, geometry_1.sectorCentroid)({
+                    cx,
+                    cy,
+                    rOuter,
+                    rInner,
+                    startDeg: a.startDeg,
+                    endDeg: a.endDeg,
+                });
+                const pct = `${Math.round(a.frac * 100)}%`;
+                const label = pointText(pct, x, y, segFont, labelColorFor(segColor(i)));
+                if (animateRing) {
+                    const revealAt = mode === "sweep"
+                        ? introSec * (0, anim_1.sweepInverseEase)(ease, a.endDeg / 360)
+                        : introSec * 0.5 * (a.startDeg / 360) + introSec * 0.45;
+                    segLabelSources.push(fadeIn(label, revealAt, introSec * 0.15, true));
+                }
+                else {
+                    segLabelSources.push(label);
+                }
+            }
+        }
+        // ── One cell, K overlay layers (sectors below, labels + text on top) ──
+        const sources = [...sectorSources, ...segLabelSources, ...textSources];
+        const m0 = (0, template_utils_1.buildOverlayStack)(sources.length);
+        return Promise.resolve({
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0,
+            sources,
+            backgroundColor: (_l = props.backgroundColor) !== null && _l !== void 0 ? _l : CARD_BG,
+            fps: ctx.target.fps,
+            durationMs: ctx.target.durationMs,
+        });
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.Donut);