@m0saic/templates 0.2.0

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

@@ -0,0 +1,114 @@
+/**
+ * ============================================================================
+ * Alpine pack — shared card chrome + geometry kit
+ * ============================================================================
+ *
+ * The signature Alpine surface: a rounded white card with a hairline border and
+ * a left-aligned title / subtitle header band, with the chart body laid out in
+ * the region below. Every template in the pack wraps its content in
+ * {@link alpineCard} so the whole pack looks like one set.
+ *
+ * Geometry follows the construction-strategy hard rule (real m0 cells, not
+ * full-frame drawtext): the card is a rounded `makeColorTile` overlay base, the
+ * header + body are a row split, all placed via the small {@link Node} combinator
+ * kit below (lifted from `@m0saic/charts/bar-graph/v2`, the canonical tight-rect
+ * template). The kit is exported so Alpine templates build their interiors with
+ * the same primitives.
+ *
+ * `alpineCard` returns a two-part contract:
+ *   - `contentRect` — the pixel rect available to the body (so the template can
+ *     size fonts / rails against real dimensions);
+ *   - `compose(content)` — wraps that body in the card + header and returns the
+ *     root {@link Node}.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicSource, MosaicTextSource } from "@m0saic/types";
+import { tag, fitEmUnits } from "@m0saic/template-utils";
+import type { AlpineTheme } from "./alpine-theme";
+/** One cell's m0 plus the sources its painted leaves contribute, in order. */
+export type Node = {
+    m0: string;
+    sources: MosaicSource[];
+};
+export type Band = {
+    weight: number;
+    node: Node;
+};
+export declare const EMPTY: Node;
+export declare const paint: (source: MosaicSource) => Node;
+/** Resolve a user color field to a concrete color: a cleared / "none" / blank
+ *  picker falls back to the default. A bare `props.color ?? fallback` keeps `""`
+ *  (not nullish), which renders the element in no color — i.e. invisible. Every
+ *  Alpine color knob goes through this so clearing the field never blanks a mark. */
+export declare function resolveColor(value: string | undefined | null, fallback: MosaicColor): MosaicColor;
+/** Weighted split along an axis; drops zero/neg-weight bands, collapses singletons. */
+export declare function split(axis: "row" | "col", bands: Band[]): Node;
+export declare const rowSplit: (bands: Band[]) => Node;
+export declare const colSplit: (bands: Band[]) => Node;
+/** Overlay layers as nested overlays: base{l1{l2{…}}}. Sources concat in order. */
+export declare function overlay(layers: Node[]): Node;
+/** Wrap a node in empty margins so it occupies an inset rect of the parent. */
+export declare function insetNode(node: Node, top: number, right: number, bottom: number, left: number, W: number, H: number): Node;
+type HAlign = "left" | "center" | "right";
+type VAlign = "top" | "middle" | "bottom";
+/** A single fitted text cell. */
+export declare function textCell(text: string, fontSize: number, color: MosaicColor, hAlign?: HAlign, vAlign?: VAlign, padding?: {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}): MosaicTextSource;
+export { tag, fitEmUnits };
+/** Which template props the header displays — `bindProp` targets for Make's
+ *  double-click edit. Every curated alpine template names them `title` /
+ *  `subtitle`, so that is the default; pass `false` for a header that shows
+ *  derived text (nothing to edit). */
+export type AlpineHeaderBinding = {
+    title?: string;
+    subtitle?: string;
+} | false;
+/** Pixel rect (canvas coordinates). */
+export type AlpineRect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type AlpineCardResult = {
+    /** The rect available to the chart body (inside padding, below the header). */
+    contentRect: AlpineRect;
+    /** Wrap a body node in the card surface + header; returns the root node.
+     *  `extraLayers` overlay ON TOP of the content within the card's overlay chain
+     *  (for full-canvas absolutely-positioned content). */
+    compose: (content: Node, ...extraLayers: Node[]) => Node;
+    /** Canvas color behind the card. */
+    backgroundColor: MosaicColor;
+    /** Layout-contract entries the card chrome contributes (header text-fit).
+     *  Templates spread these into their `withLayoutContract` constraints so a
+     *  clipping title/subtitle reds the debug wireframe during stress. */
+    constraints: Array<{
+        label: string;
+        textFits: {
+            charWidthEm?: number;
+            padPx?: number;
+        };
+    }>;
+};
+/**
+ * Build the Alpine card chrome for a `W×H` canvas. Returns the body's pixel rect
+ * plus a `compose(body)` that stacks card surface → (header) → body.
+ */
+export declare function alpineCard(opts: {
+    theme: AlpineTheme;
+    W: number;
+    H: number;
+    title?: string;
+    subtitle?: string;
+    /** Outer padding in px. Defaults to ~5.5% of the shorter side. */
+    padding?: number;
+    /** Corner radius fraction (0..1). Defaults to the theme's. */
+    cornerRadius?: number;
+    /** Prop keys the header displays (Make inline-edit). Default `title` /
+     *  `subtitle`; `false` = the header is not editable. */
+    headerBinding?: AlpineHeaderBinding;
+}): AlpineCardResult;

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

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * ============================================================================
+ * Alpine pack — shared card chrome + geometry kit
+ * ============================================================================
+ *
+ * The signature Alpine surface: a rounded white card with a hairline border and
+ * a left-aligned title / subtitle header band, with the chart body laid out in
+ * the region below. Every template in the pack wraps its content in
+ * {@link alpineCard} so the whole pack looks like one set.
+ *
+ * Geometry follows the construction-strategy hard rule (real m0 cells, not
+ * full-frame drawtext): the card is a rounded `makeColorTile` overlay base, the
+ * header + body are a row split, all placed via the small {@link Node} combinator
+ * kit below (lifted from `@m0saic/charts/bar-graph/v2`, the canonical tight-rect
+ * template). The kit is exported so Alpine templates build their interiors with
+ * the same primitives.
+ *
+ * `alpineCard` returns a two-part contract:
+ *   - `contentRect` — the pixel rect available to the body (so the template can
+ *     size fonts / rails against real dimensions);
+ *   - `compose(content)` — wraps that body in the card + header and returns the
+ *     root {@link Node}.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fitEmUnits = exports.tag = exports.colSplit = exports.rowSplit = exports.paint = exports.EMPTY = void 0;
+exports.resolveColor = resolveColor;
+exports.split = split;
+exports.overlay = overlay;
+exports.insetNode = insetNode;
+exports.textCell = textCell;
+exports.alpineCard = alpineCard;
+const template_utils_1 = require("@m0saic/template-utils");
+Object.defineProperty(exports, "tag", { enumerable: true, get: function () { return template_utils_1.tag; } });
+Object.defineProperty(exports, "fitEmUnits", { enumerable: true, get: function () { return template_utils_1.fitEmUnits; } });
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+exports.EMPTY = { m0: "-", sources: [] };
+const paint = (source) => ({ m0: "F", sources: [source] });
+exports.paint = paint;
+/** Resolve a user color field to a concrete color: a cleared / "none" / blank
+ *  picker falls back to the default. A bare `props.color ?? fallback` keeps `""`
+ *  (not nullish), which renders the element in no color — i.e. invisible. Every
+ *  Alpine color knob goes through this so clearing the field never blanks a mark. */
+function resolveColor(value, fallback) {
+    const v = (value !== null && value !== void 0 ? value : "").trim();
+    return v && v.toLowerCase() !== "none" ? v : fallback;
+}
+// Cap on a single split's cell count — scale weights to a small basis before
+// weightedSplit so coprime pixel weights don't expand the DSL to their sum.
+// 120 is the per-axis gcd of the modern canvas family (1080/1920/2160/3840…):
+// a total of exactly 120 GCD-reduces to a divisor of 120, which is 5-smooth and
+// pixel-exact on every family member (handbook composition-arithmetic §2).
+const SPLIT_BASIS_CAP = 120;
+/** Weighted split along an axis; drops zero/neg-weight bands, collapses singletons. */
+function split(axis, bands) {
+    const bs = bands.filter((b) => b.weight > 0);
+    if (bs.length === 0)
+        return exports.EMPTY;
+    // A split whose every cell paints nothing is itself empty — collapse to EMPTY
+    // so it doesn't reach weightedSplit as an all-`-` container (NO_SOURCES). This
+    // happens when a card has no header and its content lives in an overlay layer.
+    if (bs.every((b) => b.node.sources.length === 0))
+        return exports.EMPTY;
+    if (bs.length === 1)
+        return bs[0].node;
+    const weights = bs.map((b) => Math.max(1, Math.round(b.weight)));
+    // Basis on the 5-smooth lattice (latticeWeights, @m0saic/template-utils):
+    // over the cap the bands are Hamilton-scaled to EXACTLY the cap (GCD ⇒ a
+    // divisor of it); a rough pixel sum under the cap drifts ≤ 1 px onto the
+    // nearest smooth basis; a symmetric inset or an item/gutter list is rewritten
+    // as the same pattern on a smooth total (every item stays equal to its
+    // siblings); smooth, tiny and equal-weight splits keep their basis.
+    const m0 = String((0, dsl_stdlib_1.weightedSplit)((0, template_utils_1.latticeWeights)(weights, { cap: SPLIT_BASIS_CAP }), axis, { claimants: bs.map((b) => b.node.m0) }));
+    return { m0, sources: bs.flatMap((b) => b.node.sources) };
+}
+const rowSplit = (bands) => split("row", bands);
+exports.rowSplit = rowSplit;
+const colSplit = (bands) => split("col", bands);
+exports.colSplit = colSplit;
+/** Overlay layers as nested overlays: base{l1{l2{…}}}. Sources concat in order. */
+function overlay(layers) {
+    const ls = layers.filter((l) => l.sources.length > 0 || l.m0 !== "-");
+    if (ls.length === 0)
+        return exports.EMPTY;
+    if (ls.length === 1)
+        return ls[0];
+    let m0 = ls[ls.length - 1].m0;
+    for (let i = ls.length - 2; i >= 0; i--)
+        m0 = `${ls[i].m0}{${m0}}`;
+    return { m0, sources: ls.flatMap((l) => l.sources) };
+}
+/** Wrap a node in empty margins so it occupies an inset rect of the parent. */
+function insetNode(node, top, right, bottom, left, W, H) {
+    const mid = (0, exports.colSplit)([{ weight: left, node: exports.EMPTY }, { weight: W - left - right, node }, { weight: right, node: exports.EMPTY }]);
+    return (0, exports.rowSplit)([{ weight: top, node: exports.EMPTY }, { weight: H - top - bottom, node: mid }, { weight: bottom, node: exports.EMPTY }]);
+}
+/** A single fitted text cell. */
+function textCell(text, fontSize, color, hAlign = "center", vAlign = "middle", padding) {
+    const placement = { fit: "contain", hAlign, vAlign };
+    if (padding)
+        placement.padding = padding;
+    return {
+        type: "text",
+        visual: { backgroundColor: "black@0" },
+        layers: [{ content: { kind: "literal", text: text || " " }, style: { fontSize, fontColor: color }, placement }],
+    };
+}
+const DEFAULT_HEADER_BINDING = { title: "title", subtitle: "subtitle" };
+/** Left-aligned title (top) + subtitle (bottom) — the Alpine header signature.
+ *  One source, two layers: each layer binds its own prop (Make opens the rect
+ *  as a stacked Title / Subtitle form). */
+function headerCell(opts) {
+    const layers = [];
+    if (opts.title)
+        layers.push({ content: { kind: "literal", text: opts.title }, style: { fontSize: opts.titleFont, fontColor: opts.titleColor }, placement: { fit: "contain", hAlign: "left", vAlign: opts.subtitle ? "top" : "middle" } });
+    if (opts.subtitle)
+        layers.push({ content: { kind: "literal", text: opts.subtitle }, style: { fontSize: opts.subFont, fontColor: opts.subColor }, placement: { fit: "contain", hAlign: "left", vAlign: opts.title ? "bottom" : "middle" } });
+    const src = (0, template_utils_1.tag)({ type: "text", visual: { backgroundColor: "black@0" }, layers }, "card-header");
+    if (!opts.binding)
+        return src;
+    const entries = [];
+    if (opts.title && opts.binding.title)
+        entries.push({ propKey: opts.binding.title, layer: 0 });
+    if (opts.subtitle && opts.binding.subtitle)
+        entries.push({ propKey: opts.binding.subtitle, layer: opts.title ? 1 : 0 });
+    if (entries.length === 0)
+        return src;
+    return entries.length === 1 ? (0, template_utils_1.bindProp)(src, entries[0].propKey) : (0, template_utils_1.bindProps)(src, entries);
+}
+/**
+ * Build the Alpine card chrome for a `W×H` canvas. Returns the body's pixel rect
+ * plus a `compose(body)` that stacks card surface → (header) → body.
+ */
+function alpineCard(opts) {
+    var _a, _b, _c;
+    const { theme, W, H } = opts;
+    const pad = (_a = opts.padding) !== null && _a !== void 0 ? _a : Math.round(Math.min(W, H) * 0.055);
+    const cornerRadius = (_b = opts.cornerRadius) !== null && _b !== void 0 ? _b : theme.cornerRadius;
+    const hasTitle = !!(opts.title && opts.title.trim());
+    const hasSubtitle = !!(opts.subtitle && opts.subtitle.trim());
+    const hasHeader = hasTitle || hasSubtitle;
+    // Width-capped: H-scaled fonts clip long titles at the canvas edge (the
+    // header text is plain, hAlign left — it runs off the card). 0.72em/char:
+    // titles render ALL-CAPS-ish wide. Script-aware length (textEmUnits):
+    // Cyrillic/CJK run wider than a Latin char — a flat .length let a Cyrillic
+    // title clip at the card edge. Caps bind only when the string would
+    // overflow the inner width — ASCII titles render byte-identical.
+    const capW = (px, text, slotPx, min) => Math.max(min, Math.min(px, Math.floor(slotPx / (Math.max(1, (0, template_utils_1.textEmUnits)(text !== null && text !== void 0 ? text : "")) * 0.72))));
+    const titleFont = capW(Math.max(12, Math.round(H * 0.05)), opts.title, (W - 2 * pad) * 0.96, 12);
+    const subFont = capW(Math.max(10, Math.round(H * 0.026)), opts.subtitle, (W - 2 * pad) * 0.96, 10);
+    const headerH = hasHeader
+        ? Math.round((hasSubtitle ? titleFont * 1.25 + subFont * 1.6 : titleFont * 1.5) + H * 0.018)
+        : 0;
+    const innerW = W - 2 * pad;
+    const innerH = H - 2 * pad;
+    const contentRect = { x: pad, y: pad + headerH, w: innerW, h: innerH - headerH };
+    const headerNode = hasHeader
+        ? (0, exports.paint)(headerCell({
+            title: hasTitle ? opts.title : undefined,
+            subtitle: hasSubtitle ? opts.subtitle : undefined,
+            titleFont, subFont,
+            titleColor: theme.title, subColor: theme.subtitle,
+            binding: (_c = opts.headerBinding) !== null && _c !== void 0 ? _c : DEFAULT_HEADER_BINDING,
+        }))
+        : exports.EMPTY;
+    const cardSurface = (0, exports.paint)((0, template_utils_1.makeColorTile)(theme.card, {
+        effects: {
+            rounding: { cornerStyle: "rounded", borderRadius: cornerRadius },
+            stroke: { position: "inner", width: 0.002, color: theme.border, alpha: theme.borderAlpha },
+        },
+    }));
+    // `extraLayers` are full-canvas overlay layers composited ON TOP of the
+    // content, INSIDE the card's overlay chain (so the chain stays legal:
+    // cardSurface{ content{ layer1{ … } } }). Use for absolutely-positioned
+    // content (e.g. a donut ring placed on the full-canvas grid) that must NOT go
+    // through a scaled child cell.
+    const compose = (content, ...extraLayers) => {
+        const stack = hasHeader
+            ? (0, exports.rowSplit)([{ weight: headerH, node: headerNode }, { weight: contentRect.h, node: content }])
+            : content;
+        return overlay([cardSurface, insetNode(stack, pad, pad, pad, pad, W, H), ...extraLayers]);
+    };
+    return {
+        contentRect,
+        compose,
+        backgroundColor: theme.canvas,
+        // capW sizes header fonts so text fits by construction; the contract entry
+        // turns that from a convention into a guarantee (breaks loudly if capW or
+        // the header geometry ever regress).
+        constraints: hasHeader ? [{ label: "card-header", textFits: {} }] : [],
+    };
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Named 24×24 glyph catalog — the human-friendly door to the raw `iconPath`
+ * agent props.
+ *
+ * The agent-prop pattern (founder ruling 2026-08-20): the RAW prop stores the
+ * code-friendly value (an SVG path `d` string) and stays agent-scoped; where
+ * it makes sense, a friendly named knob (`icon: "commits"`) drives the SAME
+ * underlying value through this catalog. The raw prop always wins as the
+ * override, so programmatic callers (the ffmpeg-pulse beats) are unaffected.
+ *
+ * Paths are GitHub Octicon (MIT) SVG `d` strings, 24×24 viewBox, drawn as
+ * inline-mask lavfi tiles (NOT media images, which mis-lay-out the cards).
+ * Formerly `hero/ffmpeg-pulse/_shared/pulse-glyphs.ts` (which now re-exports
+ * this catalog as `KPI_GLYPHS`).
+ */
+export declare const ALPINE_GLYPHS: Record<string, string>;
+/** The friendly-knob option list (schema `oneOf` + error messages). */
+export declare const ALPINE_GLYPH_NAMES: string[];
+/**
+ * Resolve the (friendly `icon`, raw `iconPath`) pair to one SVG path.
+ * The RAW agent prop wins; an unknown friendly name fails fast.
+ */
+export declare function resolveAlpineGlyph(icon: string | undefined, rawPath: string | undefined, templateId: string): string | undefined;

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

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALPINE_GLYPH_NAMES = exports.ALPINE_GLYPHS = void 0;
+exports.resolveAlpineGlyph = resolveAlpineGlyph;
+/**
+ * Named 24×24 glyph catalog — the human-friendly door to the raw `iconPath`
+ * agent props.
+ *
+ * The agent-prop pattern (founder ruling 2026-08-20): the RAW prop stores the
+ * code-friendly value (an SVG path `d` string) and stays agent-scoped; where
+ * it makes sense, a friendly named knob (`icon: "commits"`) drives the SAME
+ * underlying value through this catalog. The raw prop always wins as the
+ * override, so programmatic callers (the ffmpeg-pulse beats) are unaffected.
+ *
+ * Paths are GitHub Octicon (MIT) SVG `d` strings, 24×24 viewBox, drawn as
+ * inline-mask lavfi tiles (NOT media images, which mis-lay-out the cards).
+ * Formerly `hero/ffmpeg-pulse/_shared/pulse-glyphs.ts` (which now re-exports
+ * this catalog as `KPI_GLYPHS`).
+ */
+exports.ALPINE_GLYPHS = {
+    commits: "M16.944 11h4.306a.75.75 0 0 1 0 1.5h-4.306a5.001 5.001 0 0 1-9.888 0H2.75a.75.75 0 0 1 0-1.5h4.306a5.001 5.001 0 0 1 9.888 0Zm-1.444.75a3.5 3.5 0 1 0-7 0 3.5 3.5 0 0 0 7 0Z",
+    pullRequests: "M16 19.25a3.25 3.25 0 1 1 6.5 0 3.25 3.25 0 0 1-6.5 0Zm-14.5 0a3.25 3.25 0 1 1 6.5 0 3.25 3.25 0 0 1-6.5 0Zm0-14.5a3.25 3.25 0 1 1 6.5 0 3.25 3.25 0 0 1-6.5 0ZM4.75 3a1.75 1.75 0 1 0 .001 3.501A1.75 1.75 0 0 0 4.75 3Zm0 14.5a1.75 1.75 0 1 0 .001 3.501A1.75 1.75 0 0 0 4.75 17.5Zm14.5 0a1.75 1.75 0 1 0 .001 3.501 1.75 1.75 0 0 0-.001-3.501Z M13.405 1.72a.75.75 0 0 1 0 1.06L12.185 4h4.065A3.75 3.75 0 0 1 20 7.75v8.75a.75.75 0 0 1-1.5 0V7.75a2.25 2.25 0 0 0-2.25-2.25h-4.064l1.22 1.22a.75.75 0 0 1-1.061 1.06l-2.5-2.5a.75.75 0 0 1 0-1.06l2.5-2.5a.75.75 0 0 1 1.06 0ZM4.75 7.25A.75.75 0 0 1 5.5 8v8A.75.75 0 0 1 4 16V8a.75.75 0 0 1 .75-.75Z",
+    mergedPrs: "M15 13.25a3.25 3.25 0 1 1 6.5 0 3.25 3.25 0 0 1-6.5 0Zm-12.5 6a3.25 3.25 0 1 1 6.5 0 3.25 3.25 0 0 1-6.5 0Zm0-14.5a3.25 3.25 0 1 1 6.5 0 3.25 3.25 0 0 1-6.5 0ZM5.75 6.5a1.75 1.75 0 1 0-.001-3.501A1.75 1.75 0 0 0 5.75 6.5Zm0 14.5a1.75 1.75 0 1 0-.001-3.501A1.75 1.75 0 0 0 5.75 21Zm12.5-6a1.75 1.75 0 1 0-.001-3.501A1.75 1.75 0 0 0 18.25 15Z M6.5 7.25c0 2.9 2.35 5.25 5.25 5.25h4.5V14h-4.5A6.75 6.75 0 0 1 5 7.25Z M5.75 16.75A.75.75 0 0 1 5 16V8a.75.75 0 0 1 1.5 0v8a.75.75 0 0 1-.75.75Z",
+    openIssues: "M12 1c6.075 0 11 4.925 11 11s-4.925 11-11 11S1 18.075 1 12 5.925 1 12 1ZM2.5 12a9.5 9.5 0 0 0 9.5 9.5 9.5 9.5 0 0 0 9.5-9.5A9.5 9.5 0 0 0 12 2.5 9.5 9.5 0 0 0 2.5 12Zm9.5 2a2 2 0 1 1-.001-3.999A2 2 0 0 1 12 14Z",
+    contributors: "M3.5 8a5.5 5.5 0 1 1 8.596 4.547 9.005 9.005 0 0 1 5.9 8.18.751.751 0 0 1-1.5.045 7.5 7.5 0 0 0-14.993 0 .75.75 0 0 1-1.499-.044 9.005 9.005 0 0 1 5.9-8.181A5.496 5.496 0 0 1 3.5 8ZM9 4a4 4 0 1 0 0 8 4 4 0 0 0 0-8Zm8.29 4c-.148 0-.292.01-.434.03a.75.75 0 1 1-.212-1.484 4.53 4.53 0 0 1 3.38 8.097 6.69 6.69 0 0 1 3.956 6.107.75.75 0 0 1-1.5 0 5.193 5.193 0 0 0-3.696-4.972l-.534-.16v-1.676l.41-.209A3.03 3.03 0 0 0 17.29 8Z",
+    additions: "M12.75 7a.75.75 0 0 0-1.5 0v4.25H7a.75.75 0 0 0 0 1.5h4.25V17a.75.75 0 0 0 1.5 0v-4.25H17a.75.75 0 0 0 0-1.5h-4.25V7Z M3.75 2A1.75 1.75 0 0 0 2 3.75v16.5c0 .966.784 1.75 1.75 1.75h16.5A1.75 1.75 0 0 0 22 20.25V3.75A1.75 1.75 0 0 0 20.25 2H3.75ZM3.5 3.75a.25.25 0 0 1 .25-.25h16.5a.25.25 0 0 1 .25.25v16.5a.25.25 0 0 1-.25.25H3.75a.25.25 0 0 1-.25-.25V3.75Z",
+    deletions: "M7.313 11.25a.75.75 0 0 0 0 1.5h9.937a.75.75 0 0 0 0-1.5H7.312Z M3.75 2A1.75 1.75 0 0 0 2 3.75v16.5c0 .966.784 1.75 1.75 1.75h16.5A1.75 1.75 0 0 0 22 20.25V3.75A1.75 1.75 0 0 0 20.25 2H3.75ZM3.5 3.75a.25.25 0 0 1 .25-.25h16.5a.25.25 0 0 1 .25.25v16.5a.25.25 0 0 1-.25.25H3.75a.25.25 0 0 1-.25-.25V3.75Z",
+    stars: "M12 .25a.75.75 0 0 1 .673.418l3.058 6.197 6.839.994a.75.75 0 0 1 .415 1.279l-4.948 4.823 1.168 6.811a.751.751 0 0 1-1.088.791L12 18.347l-6.117 3.216a.75.75 0 0 1-1.088-.79l1.168-6.812-4.948-4.823a.75.75 0 0 1 .416-1.28l6.838-.993L11.328.668A.75.75 0 0 1 12 .25Zm0 2.445L9.44 7.882a.75.75 0 0 1-.565.41l-5.725.832 4.143 4.038a.748.748 0 0 1 .215.664l-.978 5.702 5.121-2.692a.75.75 0 0 1 .698 0l5.12 2.692-.977-5.702a.748.748 0 0 1 .215-.664l4.143-4.038-5.725-.831a.75.75 0 0 1-.565-.41L12 2.694Z",
+};
+/** The friendly-knob option list (schema `oneOf` + error messages). */
+exports.ALPINE_GLYPH_NAMES = Object.keys(exports.ALPINE_GLYPHS);
+/**
+ * Resolve the (friendly `icon`, raw `iconPath`) pair to one SVG path.
+ * The RAW agent prop wins; an unknown friendly name fails fast.
+ */
+function resolveAlpineGlyph(icon, rawPath, templateId) {
+    if (rawPath)
+        return rawPath;
+    if (!icon)
+        return undefined;
+    const path = exports.ALPINE_GLYPHS[icon];
+    if (!path) {
+        throw new Error(`${templateId}: unknown icon "${icon}" — one of: ${exports.ALPINE_GLYPH_NAMES.join(", ")}`);
+    }
+    return path;
+}

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

@@ -0,0 +1,84 @@
+/**
+ * ============================================================================
+ * Alpine pack — shared theme tokens
+ * ============================================================================
+ *
+ * The Alpine data-viz pack (`@m0saic/alpine/*`) is a single brand flavor: a
+ * friendly, mobile-marketing aesthetic — white rounded cards, soft borders, a
+ * clean type scale, and a warm-but-trustworthy palette. Every Alpine template
+ * pulls its colors from ONE {@link AlpineTheme} so the whole pack reads as a
+ * coherent set.
+ *
+ * These tokens are pack-local on purpose: Alpine is standalone, NOT a re-skin of
+ * the generic `@m0saic/charts/*` primitives. The generic charts keep their own
+ * presets; Alpine owns this look.
+ *
+ * Palette derived from the Alpine dashboard reference: a #2563EB primary, slate
+ * text, hairline gridlines, and a six-color categorical ramp matching the
+ * reference treemap/donut colors.
+ * ============================================================================
+ */
+import type { MosaicColor, MosaicEngineContext, MosaicThemeTokens } from "@m0saic/types";
+import { type ThemeSourceConfig } from "@m0saic/template-utils";
+/** One coherent Alpine look. Consumed by every template in the pack. */
+export type AlpineTheme = {
+    /** Page/canvas behind the card. */
+    canvas: MosaicColor;
+    /** Card surface (the rounded panel a chart sits on). */
+    card: MosaicColor;
+    /** Hairline card border color. */
+    border: MosaicColor;
+    /** Card border opacity (0..1). */
+    borderAlpha: number;
+    /** Card title (bold, dominant). */
+    title: MosaicColor;
+    /** Card subtitle (muted caption under the title). */
+    subtitle: MosaicColor;
+    /** In-chart labels (categories, axis values). */
+    label: MosaicColor;
+    /** De-emphasized text (secondary captions, ticks). */
+    muted: MosaicColor;
+    /** Primary series / bar / line color. */
+    primary: MosaicColor;
+    /** Positive delta / up-trend. */
+    positive: MosaicColor;
+    /** Negative delta / down-trend. */
+    negative: MosaicColor;
+    /** Gridline color. */
+    grid: MosaicColor;
+    /** Gridline opacity (0..1). */
+    gridAlpha: number;
+    /** Axis line color. */
+    axis: MosaicColor;
+    /** Axis line opacity (0..1). */
+    axisAlpha: number;
+    /** Card corner radius as a fraction of the shorter side (0..1). Friendly = generous. */
+    cornerRadius: number;
+};
+/**
+ * Categorical ramp for multi-series / multi-segment marks (donut slices, stacked
+ * bars, treemap tiles). Index 0 is the primary; cycle for additional series.
+ * Mirrors the reference dashboard's tile colors.
+ */
+export declare const ALPINE_PALETTE: MosaicColor[];
+/** Theme presets. `light` is the canonical Alpine look; `dark` is the night variant. */
+export declare const ALPINE_PRESETS: Record<"light" | "dark", AlpineTheme>;
+/** Preset id union — the `preset` prop type Alpine templates expose. */
+export type AlpinePreset = keyof typeof ALPINE_PRESETS;
+/** Resolve a preset id to its theme (defaults to `light`). */
+export declare function alpineTheme(preset?: AlpinePreset): AlpineTheme;
+/** Map an `AlpineTheme` onto the 21-key `MosaicThemeTokens` (the resolver fallback). */
+export declare function alpineToTokens(t: AlpineTheme): MosaicThemeTokens;
+/** Overlay resolved `MosaicThemeTokens` back onto `AlpineTheme` keys. `base`
+ *  supplies the scalars with no token home (`borderAlpha`). Inverse of
+ *  `alpineToTokens` on the used keys → round-trip identity when unthemed. */
+export declare function tokensToAlpine(tk: MosaicThemeTokens, base: AlpineTheme): AlpineTheme;
+/**
+ * Producer-overridable theme resolver — the Family-A theming chokepoint. Drop-in
+ * async replacement for `alpineTheme(preset)`: builds the preset fallback, runs it
+ * through `resolveThemeTokens` (which overlays `ctx.upstreamData["theme"]` / a
+ * seeded `config.slug` per-key), and maps back to `AlpineTheme`. Unthemed →
+ * returns the preset unchanged (byte-identical). `props.theme` (producer) wins over
+ * `props.preset`; explicit per-mark color props still win at each callsite.
+ */
+export declare function resolveAlpineTheme(preset: AlpinePreset | undefined, ctx: MosaicEngineContext, config?: ThemeSourceConfig): Promise<AlpineTheme>;

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

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * ============================================================================
+ * Alpine pack — shared theme tokens
+ * ============================================================================
+ *
+ * The Alpine data-viz pack (`@m0saic/alpine/*`) is a single brand flavor: a
+ * friendly, mobile-marketing aesthetic — white rounded cards, soft borders, a
+ * clean type scale, and a warm-but-trustworthy palette. Every Alpine template
+ * pulls its colors from ONE {@link AlpineTheme} so the whole pack reads as a
+ * coherent set.
+ *
+ * These tokens are pack-local on purpose: Alpine is standalone, NOT a re-skin of
+ * the generic `@m0saic/charts/*` primitives. The generic charts keep their own
+ * presets; Alpine owns this look.
+ *
+ * Palette derived from the Alpine dashboard reference: a #2563EB primary, slate
+ * text, hairline gridlines, and a six-color categorical ramp matching the
+ * reference treemap/donut colors.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALPINE_PRESETS = exports.ALPINE_PALETTE = void 0;
+exports.alpineTheme = alpineTheme;
+exports.alpineToTokens = alpineToTokens;
+exports.tokensToAlpine = tokensToAlpine;
+exports.resolveAlpineTheme = resolveAlpineTheme;
+const template_utils_1 = require("@m0saic/template-utils");
+/**
+ * Categorical ramp for multi-series / multi-segment marks (donut slices, stacked
+ * bars, treemap tiles). Index 0 is the primary; cycle for additional series.
+ * Mirrors the reference dashboard's tile colors.
+ */
+exports.ALPINE_PALETTE = [
+    "#2563EB", // blue (primary)
+    "#10B981", // emerald
+    "#F59E0B", // amber
+    "#EF4444", // red
+    "#8B5CF6", // violet
+    "#0EA5E9", // sky
+];
+/** Theme presets. `light` is the canonical Alpine look; `dark` is the night variant. */
+exports.ALPINE_PRESETS = {
+    light: {
+        canvas: "#F8FAFC",
+        card: "#FFFFFF",
+        border: "#E5E7EB",
+        borderAlpha: 1,
+        title: "#0F172A",
+        subtitle: "#64748B",
+        label: "#334155",
+        muted: "#94A3B8",
+        primary: "#2563EB",
+        positive: "#16A34A",
+        negative: "#DC2626",
+        grid: "#E2E8F0",
+        gridAlpha: 1,
+        axis: "#CBD5E1",
+        axisAlpha: 1,
+        cornerRadius: 0.08,
+    },
+    dark: {
+        canvas: "#0B1120",
+        card: "#111827",
+        border: "#1F2937",
+        borderAlpha: 1,
+        title: "#F1F5F9",
+        subtitle: "#94A3B8",
+        label: "#CBD5E1",
+        muted: "#64748B",
+        primary: "#3B82F6",
+        positive: "#22C55E",
+        negative: "#F87171",
+        grid: "#1E293B",
+        gridAlpha: 1,
+        axis: "#334155",
+        axisAlpha: 1,
+        cornerRadius: 0.08,
+    },
+};
+/** Resolve a preset id to its theme (defaults to `light`). */
+function alpineTheme(preset) {
+    return exports.ALPINE_PRESETS[preset !== null && preset !== void 0 ? preset : "light"];
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Producer theming (F4 U-A0). Bridge the pack-local `AlpineTheme` (20 keys) to
+// the repo's 21-key `MosaicThemeTokens` so a producer (`@m0saic/theming/v1`) can
+// re-skin every Family-A alpine template through ONE resolver. The two maps are
+// exact inverses on the used keys, so an UNTHEMED render is byte-identical to the
+// old `alpineTheme(preset)` path (verified by round-trip). The categorical
+// `ALPINE_PALETTE` stays local for now — per-mark colors already resolve with
+// explicit-prop-wins at each callsite (`resolveColor(item.color ?? …, palette)`).
+// ─────────────────────────────────────────────────────────────────────────────
+/** Map an `AlpineTheme` onto the 21-key `MosaicThemeTokens` (the resolver fallback). */
+function alpineToTokens(t) {
+    return {
+        surfaceApp: t.canvas,
+        surface: t.card,
+        surfaceRaised: t.card,
+        surfaceInset: t.canvas,
+        border: t.border,
+        borderStrong: t.border,
+        textPrimary: t.title,
+        textSecondary: t.subtitle,
+        textMuted: t.label,
+        eyebrow: t.muted,
+        accent: t.primary,
+        accentSoft: t.primary,
+        accentGlow: t.primary,
+        positive: t.positive,
+        negative: t.negative,
+        grid: t.grid,
+        gridAlpha: t.gridAlpha,
+        axis: t.axis,
+        axisAlpha: t.axisAlpha,
+        radius: t.cornerRadius,
+        dataPalette: exports.ALPINE_PALETTE,
+    };
+}
+/** Overlay resolved `MosaicThemeTokens` back onto `AlpineTheme` keys. `base`
+ *  supplies the scalars with no token home (`borderAlpha`). Inverse of
+ *  `alpineToTokens` on the used keys → round-trip identity when unthemed. */
+function tokensToAlpine(tk, base) {
+    return {
+        canvas: tk.surfaceApp,
+        card: tk.surface,
+        border: tk.border,
+        borderAlpha: base.borderAlpha,
+        title: tk.textPrimary,
+        subtitle: tk.textSecondary,
+        label: tk.textMuted,
+        muted: tk.eyebrow,
+        primary: tk.accent,
+        positive: tk.positive,
+        negative: tk.negative,
+        grid: tk.grid,
+        gridAlpha: tk.gridAlpha,
+        axis: tk.axis,
+        axisAlpha: tk.axisAlpha,
+        cornerRadius: tk.radius,
+    };
+}
+/**
+ * Producer-overridable theme resolver — the Family-A theming chokepoint. Drop-in
+ * async replacement for `alpineTheme(preset)`: builds the preset fallback, runs it
+ * through `resolveThemeTokens` (which overlays `ctx.upstreamData["theme"]` / a
+ * seeded `config.slug` per-key), and maps back to `AlpineTheme`. Unthemed →
+ * returns the preset unchanged (byte-identical). `props.theme` (producer) wins over
+ * `props.preset`; explicit per-mark color props still win at each callsite.
+ */
+async function resolveAlpineTheme(preset, ctx, config) {
+    const base = alpineTheme(preset);
+    const resolved = await (0, template_utils_1.resolveThemeTokens)(alpineToTokens(base), ctx, config);
+    return tokensToAlpine(resolved, base);
+}