@m0saic/templates 0.2.0

package/dist/m0saic/alpine/contributor-table/v1/index.d.ts

@@ -0,0 +1 @@
+export { AlpineContributorTable } from "./contributor-table";

package/dist/m0saic/alpine/contributor-table/v1/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlpineContributorTable = void 0;
+var contributor_table_1 = require("./contributor-table");
+Object.defineProperty(exports, "AlpineContributorTable", { enumerable: true, get: function () { return contributor_table_1.AlpineContributorTable; } });

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

@@ -0,0 +1,55 @@
+/**
+ * ============================================================================
+ * @m0saic/alpine/donut/v1 — Alpine Donut Chart (friendly mobile-marketing)
+ * ============================================================================
+ *
+ * The Alpine pack's donut: a proportional ring (tight cell-local annular-sector
+ * masks, like charts/donut/v3) inside the Alpine white card chrome, with a
+ * center value/label and a side LEGEND (colored dot + label + %). STANDALONE
+ * brand flavor — it reuses the pure donut GEOMETRY math from charts/donut/v3
+ * (annular sectors are shared math, not a composed template) but owns its own
+ * chrome, palette, and legend.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+import { type EaseName, type ThemeSourceConfig } from "@m0saic/template-utils";
+import { type AlpinePreset } from "../../_shared/alpine-theme";
+type DonutSegment = {
+    label: string;
+    value: number;
+    color?: MosaicColor;
+};
+type LegendPosition = "right" | "none";
+type SegLabels = "none" | "percent";
+/** Reveal cost/quality dial. "premium" (default): staggered clockwise alpha
+ *  fade — the softest look, but a per-pixel geq paid on every frame of a nesting
+ *  parent's whole timeline. "light": staggered clockwise enable-gate pop — no geq,
+ *  composable, cheap when nested. */
+type RenderMode = "premium" | "light";
+type DonutAnim = {
+    /** Reveal cost/quality dial (see RenderMode). */
+    renderMode: RenderMode;
+    /** Skip motion; render the final static ring. */
+    reduceMotion: boolean;
+    /** Fraction of the clip the sweep + count-up occupy (0..1). */
+    introFrac: number;
+    countUp: boolean;
+    easing: EaseName;
+};
+type AlpineDonutProps = {
+    segments: DonutSegment[];
+    title?: string;
+    subtitle?: string;
+    centerValue?: string;
+    centerLabel?: string;
+    legend?: LegendPosition;
+    segmentLabels?: SegLabels;
+    preset?: AlpinePreset;
+    ringThicknessFrac?: number;
+    anim?: DonutAnim;
+    /** Opt-in producer theming. The preset is the fallback; a producer's published
+     *  tokens override it. Explicit color props still win. */
+    theme?: ThemeSourceConfig;
+};
+export declare const AlpineDonut: MosaicTemplate<AlpineDonutProps>;
+export {};

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

@@ -0,0 +1,322 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlpineDonut = 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("../../../charts/donut/v3/geometry");
+const anim_1 = require("../../../charts/donut/v3/anim");
+const alpine_card_1 = require("../../_shared/alpine-card");
+const alpine_theme_1 = require("../../_shared/alpine-theme");
+const alpine_anim_1 = require("../../_shared/alpine-anim");
+const DEFAULT_PRESET = "light";
+const DEFAULT_RENDER_MODE = "premium";
+const DEFAULT_THICKNESS = 0.42;
+const DEFAULT_SEG_LABELS = "percent";
+const DEFAULT_LEGEND = "right";
+const DEFAULT_ANIM = { renderMode: DEFAULT_RENDER_MODE, introFrac: 0.7, countUp: true, easing: "easeOut", reduceMotion: false };
+// Ring geometry / packing constants (mirrors charts/donut/v3).
+const RADIUS_SCALE = 0.9;
+const GAP_DEG = 2;
+const VALUE_FONT_FRAC = 0.26;
+const CAPTION_FONT_FRAC = 0.1;
+const SEG_LABEL_FONT_FRAC = 0.42;
+const SEG_LABEL_MIN_SWEEP_DEG = 16;
+const EDGE_PAD = 1.5;
+const SNAP_PX = 4;
+// Fraction of the card content width the ring occupies (legend takes the rest).
+const RING_FRAC_WITH_LEGEND = 0.56;
+const clampInt = (v, lo, hi) => Math.max(lo, Math.min(hi, Math.round(v)));
+function placePiece(W, H, bbox, makeSource) {
+    const snapDown = (v) => Math.floor((v - EDGE_PAD) / SNAP_PX) * SNAP_PX;
+    const snapUp = (v) => Math.ceil((v + EDGE_PAD) / SNAP_PX) * SNAP_PX;
+    const x = clampInt(snapDown(bbox.minX), 0, W - 1);
+    const y = clampInt(snapDown(bbox.minY), 0, H - 1);
+    const x2 = clampInt(snapUp(bbox.maxX), x + SNAP_PX, W);
+    const y2 = clampInt(snapUp(bbox.maxY), y + SNAP_PX, H);
+    return { rect: { x, y, w: x2 - x, h: y2 - y, claimant: "F" }, source: makeSource(x2 - x, y2 - y, x, y) };
+}
+function cellText(text, fontSize, color) {
+    return { type: "text", visual: { backgroundColor: "black@0" }, layers: [{ content: { kind: "literal", text: text || " " }, style: { fontSize, fontColor: color }, placement: { hAlign: "center", vAlign: "middle" } }] };
+}
+function cellExprText(expr, fontSize, color) {
+    return { type: "text", renderMode: { kind: "video" }, visual: { backgroundColor: "black@0" }, layers: [{ content: { kind: "expr", expr, eval: "frame" }, style: { fontSize, fontColor: color }, placement: { hAlign: "center", vAlign: "middle" } }] };
+}
+function textBBox(cxp, cyp, text, font) {
+    const w = Math.max(font, text.length * font * 0.85 + font);
+    const h = font * 1.6;
+    return { minX: cxp - w / 2, minY: cyp - h / 2, maxX: cxp + w / 2, maxY: cyp + h / 2 };
+}
+function labelColorFor(hex, light, dark) {
+    const m = /^#?([0-9a-f]{6})/i.exec(String(hex));
+    if (!m)
+        return light;
+    const v = parseInt(m[1], 16);
+    const lum = (0.2126 * ((v >> 16) & 0xff) + 0.7152 * ((v >> 8) & 0xff) + 0.0722 * (v & 0xff)) / 255;
+    return lum > 0.6 ? dark : light;
+}
+// ---------------------------------------------------------------------------
+// Ring (placeRects of tight annular-sector cells) → { m0, sources }
+// ---------------------------------------------------------------------------
+function buildRing(opts) {
+    const { W, H, rx, ry, rw, rh, values, colors, theme } = opts;
+    const light = opts.renderMode === "light";
+    // Mode-aware text reveal: premium = soft alpha fade (a geq); light = geq-free
+    // enable-gate pop; reduceMotion = static. Premium is byte-identical to the old
+    // local `fadeIn` (same `fadeInExpr` overlay).
+    const revealText = (src, startSec, durSec) => opts.reduceMotion ? src : light ? (0, alpine_anim_1.revealGate)(src, startSec) : (0, alpine_anim_1.revealFade)(src, startSec, durSec);
+    const cx = rx + rw / 2, cy = ry + rh / 2;
+    const rOuter = (Math.min(rw, rh) / 2) * RADIUS_SCALE;
+    const rInner = rOuter * (1 - Math.max(0.05, Math.min(0.9, opts.thicknessFrac)));
+    const holeDia = rInner * 2;
+    // One segment = a full ring (no gap to carve into nothing); 2+ segments get
+    // the GAP_DEG separators between them.
+    const angles = (0, geometry_1.segmentsToAngles)(values, { gapDeg: values.length > 1 ? GAP_DEG : 0 });
+    const segColor = (i) => colors[i % colors.length];
+    const sectorPieces = [];
+    const labelPieces = [];
+    const textPieces = [];
+    const sectorPiece = (segIndex, startDeg, endDeg, overlay) => {
+        const p = placePiece(W, H, (0, geometry_1.annularSectorBBox)({ cx, cy, rOuter, rInner, startDeg, endDeg }), (cw, ch, ox, oy) => (0, template_utils_1.makeColorTile)(segColor(segIndex), {
+            mask: { kind: "inline-mask", localPath: (0, geometry_1.annularSectorPath)({ cx: cx - ox, cy: cy - oy, rOuter, rInner, startDeg, endDeg }), bounds: { x: 0, y: 0, width: cw, height: ch } },
+            ...(overlay ? { overlay } : {}),
+        }));
+        // Ring sectors are the BACK layer; % labels + center value/caption float above
+        // (importance 1). Explicit importance on every piece → deterministic layering,
+        // no reliance on the packer's incidental stacking.
+        p.rect.importance = 0;
+        return p;
+    };
+    // Staggered FULL-SECTOR reveal (clockwise from 12 o'clock): one solid tile per
+    // segment, each fading in at a time proportional to its start angle, so the
+    // ring still "fills in" clockwise but every segment is a clean GCD-aligned arc.
+    // (The prior per-sliver sweep subdivided each segment into many tight cells
+    // that snapped to the 4px grid independently → staircased edges for many/thin
+    // segments.) reduceMotion → all sectors solid from frame 0.
+    if (opts.reduceMotion) {
+        for (let i = 0; i < angles.length; i++)
+            sectorPieces.push(sectorPiece(i, angles[i].startDeg, angles[i].endDeg));
+    }
+    else {
+        const fadeDur = Math.max(0.1, opts.introSec * 0.32);
+        for (let i = 0; i < angles.length; i++) {
+            const a = angles[i];
+            const startAtSec = Math.max(0, (opts.introSec - fadeDur) * (0, anim_1.sweepInverseEase)(opts.ease, a.startDeg / 360));
+            // premium = clockwise alpha fade (geq); light = clockwise enable-gate pop (no
+            // geq). The staggered `startAtSec` keeps the clockwise fill order in both.
+            const rev = light
+                ? { startAtSec, enable: `gte(t,${startAtSec.toFixed(3)})` }
+                : { startAtSec, alpha: (0, template_utils_1.fadeInExpr)(startAtSec, fadeDur) };
+            sectorPieces.push(sectorPiece(i, a.startDeg, a.endDeg, rev));
+        }
+    }
+    // Per-segment percent labels.
+    if (opts.segLabels === "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 color = labelColorFor(segColor(i), theme.card, theme.title);
+            const piece = placePiece(W, H, textBBox(x, y, pct, segFont), () => revealText(cellText(pct, segFont, color), opts.introSec * 0.6, Math.max(0.1, opts.introSec * 0.3)));
+            piece.rect.importance = 1;
+            labelPieces.push(piece);
+        }
+    }
+    // Center value + caption.
+    const valueText = opts.centerValue;
+    const hasCaption = !!(opts.centerLabel && opts.centerLabel.trim());
+    // Fit the value to the hole WIDTH (length-aware) so long values like "$12,480"
+    // don't spill onto the ring; cap by VALUE_FONT_FRAC so short values don't balloon.
+    const valueFont = Math.max(10, Math.round(Math.min(holeDia * VALUE_FONT_FRAC, (holeDia * 0.72) / Math.max(1, valueText.length * 0.62))));
+    const captionFont = Math.max(9, Math.round(holeDia * CAPTION_FONT_FRAC));
+    const valueCy = hasCaption ? cy - rInner * 0.12 : cy;
+    const animateValue = opts.countUp && !opts.reduceMotion && /\d/.test(valueText);
+    const valPiece = placePiece(W, H, textBBox(cx, valueCy, valueText, valueFont), () => animateValue
+        ? cellExprText((0, template_utils_1.animateNumbersInText)(valueText, { durationSec: opts.introSec, ease: opts.ease }), valueFont, theme.title)
+        : cellText(valueText, valueFont, theme.title));
+    valPiece.rect.importance = 1;
+    textPieces.push(valPiece);
+    if (hasCaption) {
+        const capPiece = placePiece(W, H, textBBox(cx, cy + rInner * 0.44, opts.centerLabel, captionFont), () => revealText(cellText(opts.centerLabel, captionFont, theme.subtitle), opts.introSec * 0.7, Math.max(0.1, opts.introSec * 0.3)));
+        capPiece.rect.importance = 1; // text above the ring (was missing → could layer under a sector)
+        textPieces.push(capPiece);
+    }
+    const pieces = [...sectorPieces, ...labelPieces, ...textPieces];
+    const placed = (0, dsl_stdlib_1.placeRects)({ rootW: W, rootH: H, rects: pieces.map((p) => p.rect) });
+    const sources = [];
+    for (const layer of placed.layers) {
+        const ordered = [...layer.rectIndices].sort((a, b) => pieces[a].rect.y - pieces[b].rect.y || pieces[a].rect.x - pieces[b].rect.x);
+        for (const idx of ordered)
+            sources.push(pieces[idx].source);
+    }
+    return { m0: String(placed.m0), sources };
+}
+// ---------------------------------------------------------------------------
+// Legend (Node) — colored dot + label + percent, stacked, vertically centered
+// ---------------------------------------------------------------------------
+function legendNode(opts) {
+    var _a, _b;
+    const { labels, percents, colors, theme, font, cellH } = opts;
+    const N = labels.length;
+    // Pixel-tight rows: each ~1.7× the font, gaps ~0.5× — a compact cluster,
+    // centered by computed margins (vs the old weighted fill that stretched the
+    // rows across the whole cell).
+    const rowH = Math.max(font, Math.round(font * 1.7));
+    const rowGap = Math.round(font * 0.5);
+    const stackH = N * rowH + (N - 1) * rowGap;
+    const margin = Math.max(0, Math.round((cellH - stackH) / 2));
+    const bands = [];
+    if (margin > 0)
+        bands.push({ weight: margin, node: alpine_card_1.EMPTY });
+    for (let i = 0; i < N; i++) {
+        // dot: a rounded square ~half the row height, vertically centered.
+        const dot = (0, alpine_card_1.rowSplit)([
+            { weight: 1, node: alpine_card_1.EMPTY },
+            { weight: 2, node: (0, alpine_card_1.paint)((0, template_utils_1.makeColorTile)(colors[i % colors.length], { effects: { rounding: { cornerStyle: "rounded", borderRadius: 0.4 } } })) },
+            { weight: 1, node: alpine_card_1.EMPTY },
+        ]);
+        const row = (0, alpine_card_1.colSplit)([
+            { weight: 1, node: alpine_card_1.EMPTY },
+            { weight: 2, node: dot },
+            { weight: 1, node: alpine_card_1.EMPTY },
+            { weight: 11, node: (0, alpine_card_1.paint)((0, alpine_card_1.textCell)((_a = labels[i]) !== null && _a !== void 0 ? _a : "", font, theme.label, "left", "middle")) },
+            { weight: 5, node: (0, alpine_card_1.paint)((0, alpine_card_1.textCell)((_b = percents[i]) !== null && _b !== void 0 ? _b : "", font, theme.subtitle, "right", "middle", { right: 0.1 })) },
+        ]);
+        bands.push({ weight: rowH, node: row });
+        if (i < N - 1)
+            bands.push({ weight: rowGap, node: alpine_card_1.EMPTY });
+    }
+    if (margin > 0)
+        bands.push({ weight: margin, node: alpine_card_1.EMPTY });
+    return (0, alpine_card_1.rowSplit)(bands);
+}
+// ---------------------------------------------------------------------------
+// Template
+// ---------------------------------------------------------------------------
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    // ── Primary props — flat, always visible up top (declaration order = display order). ──
+    segments: { type: "array", required: true, description: "Ring segments (clockwise from 12 o'clock). Raw weights — normalized internally.", meta: { control: { flavor: "objectRows", columns: [{ label: "Label", key: "label", kind: "text", placeholder: "Segment" }, { label: "Value", key: "value", kind: "number" }, { label: "Color", key: "color", kind: "color" }], palette: alpine_theme_1.ALPINE_PALETTE }, ui: { label: "Segments", order: 1 } } },
+    title: { type: "string", required: false, description: "Card title.", meta: { control: { placeholder: "e.g., DONUT CHART" }, ui: { label: "Title", order: 2 } } },
+    subtitle: { type: "string", required: false, description: "Card subtitle.", meta: { control: { placeholder: "e.g., Revenue Mix" }, ui: { label: "Subtitle", order: 3 } } },
+    centerValue: { type: "string", required: false, description: "Pre-formatted hole value (e.g. \"$12,480\"). Omit to derive the sum.", meta: { control: { placeholder: "e.g. $12,480" }, ui: { label: "Center value", order: 4 } } },
+    centerLabel: { type: "string", required: false, description: "Small caption under the center value (e.g. \"Total\").", meta: { control: { placeholder: "e.g. Total" }, ui: { label: "Center label", order: 5 } } },
+    legend: { type: "string", required: false, description: "Side legend: right or none.", meta: { constraints: { oneOf: ["right", "none"] }, ui: { label: "Legend", order: 6 } } },
+    segmentLabels: { type: "string", required: false, description: "Per-segment labels: none or percent.", meta: { constraints: { oneOf: ["none", "percent"] }, ui: { label: "Segment Labels", order: 7 } } },
+    preset: { type: "string", required: false, description: "Alpine theme variant.", meta: { constraints: { oneOf: ["light", "dark"] }, ui: { label: "Preset", order: 8 } } },
+    ringThicknessFrac: { type: "number", required: false, description: "Ring thickness as a fraction of the outer radius.", meta: { constraints: { min: 0.05, max: 0.9 }, control: { flavor: "slider", step: 0.02 }, ui: { label: "Ring thickness", order: 9 } } },
+    // ── Everything else grouped into collapsible sections. ──
+    anim: {
+        type: "group", required: false, description: "Reveal mode + clockwise sweep intro.",
+        meta: { ui: { label: "Animation", order: 10, collapsedByDefault: true } },
+        fields: {
+            renderMode: (0, alpine_anim_1.fEnum)("Render mode", ["premium", "light"], "\"premium\" (default): clockwise alpha-fade sweep — the softest look, but a per-pixel geq paid on every frame of a nesting parent's whole timeline. \"light\": clockwise enable-gate pop — no geq, composable, cheap when nested."),
+            reduceMotion: alpine_anim_1.ALPINE_ANIM_FIELDS.reduceMotion,
+            introFrac: alpine_anim_1.ALPINE_ANIM_FIELDS.introFrac,
+            countUp: (0, alpine_anim_1.fBool)("Count up", "Count the center value up during the intro."),
+            easing: alpine_anim_1.ALPINE_ANIM_FIELDS.easing,
+        },
+    },
+    theme: {
+        type: "group", required: false, description: "Opt into a theme source. Uses the alpine preset by default; set a producer slug + namespace to pull shared design tokens. Explicit segment colors still win.",
+        meta: { ui: { label: "Theme", order: 11, collapsedByDefault: true } },
+        fields: { slug: (0, alpine_anim_1.fStr)("Producer slug", "Producer template to seed tokens from (e.g. \"@m0saic/theming/v1\").", "preset palette (no producer)"), preset: (0, alpine_anim_1.fStr)("Preset", "Producer preset/variant (light | dark | high-contrast; producer-defined).", "producer default"), namespace: (0, alpine_anim_1.fStr)("Namespace", "Upstream alias to read tokens from. Default \"theme\".", "theme"), forceFetch: (0, alpine_anim_1.fBool)("Force fetch", "Re-seed via the slug even if the namespace is populated.") },
+    },
+});
+exports.AlpineDonut = {
+    id: (0, types_1.asTemplateId)("@m0saic/alpine/donut/v1"),
+    label: "Alpine Donut Chart",
+    version: 1,
+    description: "Alpine donut chart — friendly mobile-marketing card: proportional ring, center value + label, side legend, sweep + count-up animation.",
+    capabilities: { tier: "core" },
+    primitive: true,
+    deprecated: {
+        reason: "Absolute-placement antipattern: each sector's tight bbox (+ the % labels + center text) is packed full-canvas via placeRects, so precision tracks the canvas (audit: ABSOLUTE, slope 1.04) and it pins its parent when nested. The sweep is already static per-segment masks (reveal on the overlay, not per-frame path carving), so v2 scopes the same single-coordinate-system idea to ONE ratio 'ring cell' — the sectors + labels + center text are masks/text filling that cell in ring-local coords, registering around the shared center while the cell is a ratio split → bounded precision. Composes at any canvas.",
+        replacement: (0, types_1.asTemplateId)("@m0saic/alpine/donut/v2"),
+        since: "2026-07-09",
+    },
+    tags: ["alpine", "donut", "distribution", "data-viz"],
+    outputHints: { width: 1280, height: 800, fps: 30, durationMs: 2000 },
+    propsSchema,
+    defaultProps: {
+        theme: { forceFetch: false },
+        segments: [
+            { label: "Enterprise", value: 42, color: alpine_theme_1.ALPINE_PALETTE[0] },
+            { label: "Pro", value: 33, color: alpine_theme_1.ALPINE_PALETTE[1] },
+            { label: "Free", value: 25, color: alpine_theme_1.ALPINE_PALETTE[2] },
+        ],
+        title: "DONUT CHART",
+        subtitle: "Revenue Mix",
+        centerValue: "$12,480",
+        centerLabel: "Total",
+        preset: DEFAULT_PRESET,
+        ringThicknessFrac: DEFAULT_THICKNESS,
+        segmentLabels: DEFAULT_SEG_LABELS,
+        legend: DEFAULT_LEGEND,
+        anim: DEFAULT_ANIM,
+    },
+    async render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        const W = Math.max(1, Math.round(ctx.target.width));
+        const H = Math.max(1, Math.round(ctx.target.height));
+        const segments = ((_a = props.segments) !== null && _a !== void 0 ? _a : []).slice(0, geometry_1.MAX_SEGMENTS).filter((s) => s && Number.isFinite(s.value) && s.value > 0);
+        if (segments.length === 0) {
+            return (0, template_utils_1.makeErrorMosaic)("segments[] must have at least one positive value", { title: `${this.id}`, width: W, height: H });
+        }
+        // Theming: the shared alpine theme (light default via the preset). A producer
+        // overrides card/text/palette tokens through `props.theme`; explicit segment
+        // colors still win. Unthemed → byte-identical to the sync `alpineTheme`.
+        const theme = await (0, alpine_theme_1.resolveAlpineTheme)((_b = props.preset) !== null && _b !== void 0 ? _b : DEFAULT_PRESET, ctx, props.theme);
+        const anim = { ...DEFAULT_ANIM, ...((_c = props.anim) !== null && _c !== void 0 ? _c : {}) };
+        const renderMode = (_d = anim.renderMode) !== null && _d !== void 0 ? _d : DEFAULT_RENDER_MODE;
+        const legend = (_e = props.legend) !== null && _e !== void 0 ? _e : DEFAULT_LEGEND;
+        const values = segments.map((s) => s.value);
+        const total = values.reduce((a, b) => a + b, 0);
+        const colors = segments.map((s, i) => (0, alpine_card_1.resolveColor)(s.color, alpine_theme_1.ALPINE_PALETTE[i % alpine_theme_1.ALPINE_PALETTE.length]));
+        const percents = values.map((v) => `${Math.round((v / total) * 100)}%`);
+        const clipSec = Math.max(0.1, ((_f = ctx.target.durationMs) !== null && _f !== void 0 ? _f : 2000) / 1000);
+        const introSec = Math.max(0.1, Math.min(1, anim.introFrac) * clipSec);
+        // Card chrome → content rect. The ring is placed DIRECTLY on the full canvas
+        // (its tight-cell masks snap to the canvas grid → GCD-aligned, no seams) and
+        // OVERLAID on the card; the legend lives in the content's right cell. (The
+        // prior child-doc ring got scaled into the left cell, which broke the mask
+        // alignment and showed seams — donut/v3's GCD trick only holds full-canvas.)
+        const card = (0, alpine_card_1.alpineCard)({ theme, W, H, title: props.title, subtitle: props.subtitle });
+        const cr = card.contentRect;
+        const showLegend = legend === "right" && segments.length > 0;
+        const ringW = showLegend ? Math.max(16, Math.round(cr.w * RING_FRAC_WITH_LEGEND)) : cr.w;
+        const legendW = cr.w - ringW;
+        const ring = buildRing({
+            W, H, rx: cr.x, ry: cr.y, rw: ringW, rh: cr.h, values, colors,
+            thicknessFrac: (_g = props.ringThicknessFrac) !== null && _g !== void 0 ? _g : DEFAULT_THICKNESS,
+            segLabels: (_h = props.segmentLabels) !== null && _h !== void 0 ? _h : DEFAULT_SEG_LABELS,
+            centerValue: (_j = props.centerValue) !== null && _j !== void 0 ? _j : String(Math.round(total)),
+            centerLabel: props.centerLabel,
+            theme, introSec, ease: anim.easing, countUp: anim.countUp, reduceMotion: anim.reduceMotion, renderMode,
+            fps: ctx.target.fps, durationMs: ctx.target.durationMs,
+        });
+        // Card content holds an EMPTY left cell (the ring overlays it) + the legend.
+        const legendFont = Math.max(11, Math.round(H * 0.024));
+        const content = showLegend
+            ? (0, alpine_card_1.colSplit)([
+                { weight: ringW, node: alpine_card_1.EMPTY },
+                { weight: legendW, node: legendNode({ labels: segments.map((s) => s.label), percents, colors, theme, font: legendFont, cellH: cr.h }) },
+            ])
+            : alpine_card_1.EMPTY;
+        const root = card.compose(content, ring);
+        return Promise.resolve({
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0: root.m0,
+            sources: root.sources,
+            backgroundColor: card.backgroundColor,
+            fps: ctx.target.fps,
+            durationMs: ctx.target.durationMs,
+        });
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.AlpineDonut);

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

@@ -0,0 +1,5 @@
+/**
+ * @m0saic/alpine/donut/v1 — entry point. Importing triggers side-effect
+ * registration via registerTemplate().
+ */
+export { AlpineDonut } from "./donut";

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

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlpineDonut = void 0;
+/**
+ * @m0saic/alpine/donut/v1 — entry point. Importing triggers side-effect
+ * registration via registerTemplate().
+ */
+var donut_1 = require("./donut");
+Object.defineProperty(exports, "AlpineDonut", { enumerable: true, get: function () { return donut_1.AlpineDonut; } });

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

@@ -0,0 +1,58 @@
+/**
+ * ============================================================================
+ * @m0saic/alpine/donut/v2 — Alpine Donut Chart (RATIO rebuild)
+ * ============================================================================
+ *
+ * Same picture as v1 — a proportional ring (annular-sector masks) + center
+ * value/label + side legend — but rebuilt as a RATIO layout instead of absolute
+ * full-canvas `placeRects`.
+ *
+ * v1 packed each sector's tight bbox (+ the % labels + center text) via
+ * `placeRects` on the full canvas, so precision tracked the canvas (audit:
+ * ABSOLUTE, slope 1.04). The KEY realization: the sweep is NOT per-frame path
+ * carving — each segment is ONE static annular-sector mask whose reveal rides on
+ * the OVERLAY (alpha fade / enable-gate). So this is the line-chart case: put
+ * every ring mark into ONE ratio "ring cell" with geometry in ring-local coords
+ * — a mask's path is relative to its own cell, so all the sectors + labels +
+ * center text register around the shared center, while the cell is a ratio split
+ * → bounded precision. The legend is a sibling ratio cell (unchanged from v1).
+ * Composes at any canvas (audit: RATIO).
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicTemplate } from "@m0saic/types";
+import { type EaseName, type ThemeSourceConfig } from "@m0saic/template-utils";
+import { type AlpinePreset } from "../../_shared/alpine-theme";
+type DonutSegment = {
+    label: string;
+    value: number;
+    color?: MosaicColor;
+};
+type LegendPosition = "right" | "none";
+type SegLabels = "none" | "percent";
+/** Reveal cost/quality dial. "premium" (default): staggered clockwise alpha
+ *  fade (a geq). "light": staggered clockwise enable-gate pop — no geq. */
+type RenderMode = "premium" | "light";
+type DonutAnim = {
+    renderMode: RenderMode;
+    reduceMotion: boolean;
+    introFrac: number;
+    countUp: boolean;
+    easing: EaseName;
+};
+type AlpineDonutV2Props = {
+    segments: DonutSegment[];
+    title?: string;
+    subtitle?: string;
+    centerValue?: string;
+    centerLabel?: string;
+    legend?: LegendPosition;
+    segmentLabels?: SegLabels;
+    preset?: AlpinePreset;
+    ringThicknessFrac?: number;
+    anim?: DonutAnim;
+    /** Opt-in producer theming. The preset is the fallback; a producer's published
+     *  tokens override it. Explicit color props still win. */
+    theme?: ThemeSourceConfig;
+};
+export declare const AlpineDonutV2: MosaicTemplate<AlpineDonutV2Props>;
+export {};