@m0saic/templates 0.2.0

package/dist/m0saic/github/year-card/v1/year-card.js

@@ -0,0 +1,476 @@
+"use strict";
+/**
+ * ============================================================================
+ * @m0saic/github/year-card/v1 — a developer's year on GitHub, on one card
+ * ============================================================================
+ *
+ * The contribution calendar (7 weekday rows × 53 week columns, month labels
+ * along the top, weekday labels down the side, a Less → More legend) with a
+ * row of four numbers above it — commits, pull requests, stars, top language
+ * — and the handle + year in the header. The vanity share every developer
+ * posts; hand it a year of daily counts (365 numbers, or a comma string) and
+ * the totals in the KPI tiles.
+ *
+ * Construction is the alpine heatmap's v2 move at calendar scale: the cell
+ * matrix is one gutterless `grid(7×53)` — its precision is the cell COUNT,
+ * not the canvas — and the inter-cell gap is applied AFTER composition by
+ * lattice retargeting (`latticeCellInset` over the parsed cell rects), so
+ * the cells are equal and the gaps exact at any canvas. The cells are plain
+ * square tiles (no per-tile rounding mask — at 371 tiles that quadruples the
+ * render) and the reveal is ONE curtain track, not 371 overlays. Chrome is the alpine
+ * card kit, RATIO throughout. The weeks are placed by real calendar math
+ * (UTC, deterministic): the first column is the week of January 1st, cells
+ * outside the year paint the card colour.
+ *
+ * Determinism: the sample year is a fixed literal, no clock, no randomness.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YearCardV1 = exports.SAMPLE_CONTRIBUTIONS = void 0;
+exports.parseContributions = parseContributions;
+exports.calendarLayout = calendarLayout;
+exports.bucketOf = bucketOf;
+exports.longestStreak = longestStreak;
+exports.fmtCount = fmtCount;
+exports.smoothTileRow = smoothTileRow;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const dsl_1 = require("@m0saic/dsl");
+const template_utils_1 = require("@m0saic/template-utils");
+const alpine_card_1 = require("../../../alpine/_shared/alpine-card");
+const alpine_theme_1 = require("../../../alpine/_shared/alpine-theme");
+const alpine_anim_1 = require("../../../alpine/_shared/alpine-anim");
+const TEMPLATE_ID = "@m0saic/github/year-card/v1";
+const WEEKS = 53;
+const DAYS = 7;
+const LEVELS = 5;
+/** Light by default: the year unfolds week by week under ONE curtain track; premium fades every cell on the diagonal (371 overlays, ~40 s for a 3 s clip). */
+const DEFAULT_ANIM = { renderMode: "light", introFrac: 0.7, reduceMotion: false };
+/** GitHub's calendar greens, light and dark. */
+const GREENS = {
+    light: ["#ebedf0", "#9be9a8", "#40c463", "#30a14e", "#216e39"],
+    dark: ["#161b22", "#0e4429", "#006d32", "#26a641", "#39d353"],
+};
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const WEEKDAY_LABELS = [[1, "Mon"], [3, "Wed"], [5, "Fri"]];
+/** A fixed sample year (2026): 905 contributions over 217 days, a two-week break in August. */
+exports.SAMPLE_CONTRIBUTIONS = "4,2,0,0,1,0,5,0,1,0,0,4,5,5,0,4,0,0,6,0,0,0,4,0,0,0,0,0,0,0,4,1,0,0,0,4,1,0,5,7,0,0,0,2,3,1,2,4,2,2,8,0,2,1,3,0,6,0,0,3,5,3,10,5,1,0,0,2,0,0,8,0,11,1,3,1,7,2,1,0,0,3,0,6,1,1,0,0,7,8,0,0,4,3,7,7,5,5,12,0,0,11,6,3,3,1,1,0,0,8,3,3,4,0,1,4,14,1,8,14,9,0,1,6,11,1,5,4,0,1,6,1,15,1,4,0,0,7,9,0,3,2,0,0,4,9,4,1,0,4,0,10,2,2,4,1,0,2,4,1,3,1,1,2,0,0,4,3,0,4,0,0,2,3,1,7,0,0,1,0,11,0,4,4,2,0,0,2,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,5,0,2,0,3,1,2,1,1,0,3,9,6,5,1,1,3,0,7,6,3,8,3,4,0,5,0,8,13,15,0,2,2,2,3,6,11,0,0,2,9,3,1,2,2,0,2,5,3,3,2,15,3,4,3,3,6,3,0,3,3,5,5,5,1,0,0,3,8,5,1,2,0,0,2,3,6,1,7,0,0,10,4,2,6,5,0,1,0,2,10,2,3,0,2,8,5,0,7,6,0,3,9,6,4,5,0,0,0,0,0,5,1,4,2,0,2,1,0,0,0,0,0,5,0,0,0,0,0,0,1,1,0,3,0,0,0,0,0,0,0,0,0,0,0,1,0,0";
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    handle: { type: "string", required: false, description: "GitHub handle for the header.", meta: { control: { placeholder: "none" }, ui: { label: "Handle", order: 1, primary: true } } },
+    year: { type: "number", required: false, description: "Calendar year (places the weeks and month labels).", meta: { constraints: { min: 2008, max: 2100 }, ui: { label: "Year", order: 2 } } },
+    contributions: {
+        type: "json",
+        required: true,
+        description: "Daily contribution counts from January 1st — an array of 365/366 numbers, or one comma-separated string. Missing days count as 0.",
+        meta: { ui: { label: "Contributions", order: 3, primary: true, consumer: "agent" } },
+    },
+    commits: { type: "number", required: false, description: "Commits this year (KPI tile).", meta: { control: { placeholder: "none" }, ui: { label: "Commits", order: 4 } } },
+    pullRequests: { type: "number", required: false, description: "Pull requests this year (KPI tile).", meta: { control: { placeholder: "none" }, ui: { label: "Pull requests", order: 5 } } },
+    stars: { type: "number", required: false, description: "Stars earned this year (KPI tile).", meta: { control: { placeholder: "none" }, ui: { label: "Stars", order: 6 } } },
+    topLanguage: { type: "string", required: false, description: "Most-used language (KPI tile).", meta: { control: { placeholder: "none" }, ui: { label: "Top language", order: 7 } } },
+    showKpis: { type: "boolean", required: false, description: "Show the four KPI tiles above the calendar.", meta: { ui: { label: "Show KPIs", order: 8 } } },
+    preset: { type: "string", required: false, description: 'Alpine theme: "light" (default) or "dark" — the calendar greens follow.', meta: { constraints: { oneOf: ["light", "dark"] }, ui: { label: "Preset", order: 9 } } },
+    anim: {
+        type: "group",
+        required: false,
+        description: "Reveal: the calendar unfolds week by week (light) or fades in on the diagonal (premium). reduceMotion renders the final frame.",
+        meta: { ui: { label: "Animation", order: 10, collapsedByDefault: true } },
+        fields: {
+            reduceMotion: alpine_anim_1.ALPINE_ANIM_FIELDS.reduceMotion,
+            introFrac: alpine_anim_1.ALPINE_ANIM_FIELDS.introFrac,
+            renderMode: (0, alpine_anim_1.fEnum)("Render mode", ["premium", "light"], "light (default) = the year unfolds week by week under one curtain — free; premium = every cell fades in on the diagonal, ~10× the render time."),
+        },
+    },
+    theme: { type: "json", required: false, description: "Opt-in producer theme tokens.", meta: { ui: { label: "Theme", order: 11, collapsedByDefault: true, consumer: "agent" } } },
+    debugLayout: { type: "boolean", required: false, description: "Dev-only: overlay the layout contract.", meta: { ui: { label: "Debug layout", order: 12 } } },
+});
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for tests)
+// ---------------------------------------------------------------------------
+/** Daily counts from an array or a comma string; non-numbers → 0. */
+function parseContributions(v) {
+    const raw = Array.isArray(v) ? v : typeof v === "string" && v.trim() ? v.trim().split(/[,\s]+/) : [];
+    return raw.map((x) => {
+        const n = typeof x === "number" ? x : Number(x);
+        return Number.isFinite(n) && n > 0 ? Math.round(n) : 0;
+    });
+}
+/** Calendar geometry for `year` — UTC math, no clock. */
+function calendarLayout(year) {
+    const jan1 = Date.UTC(year, 0, 1);
+    const days = Math.round((Date.UTC(year + 1, 0, 1) - jan1) / 86400000);
+    const firstDow = new Date(jan1).getUTCDay();
+    const monthCols = MONTHS.map((label, m) => {
+        const dayIndex = Math.round((Date.UTC(year, m, 1) - jan1) / 86400000);
+        return { label, col: Math.floor((dayIndex + firstDow) / DAYS) };
+    });
+    return { days, firstDow, monthCols };
+}
+/** GitHub-style buckets: 0 for none, then four quartiles of the year's max. */
+function bucketOf(v, max) {
+    if (v <= 0 || max <= 0)
+        return 0;
+    return Math.max(1, Math.min(LEVELS - 1, 1 + Math.floor((v / max) * (LEVELS - 1) * 0.99999)));
+}
+/** Longest run of consecutive active days. */
+function longestStreak(counts) {
+    let run = 0, best = 0;
+    for (const v of counts) {
+        run = v > 0 ? run + 1 : 0;
+        if (run > best)
+            best = run;
+    }
+    return best;
+}
+function fmtCount(n) {
+    return n >= 1000000 ? `${(n / 1000000).toFixed(1)}M` : n >= 10000 ? `${(n / 1000).toFixed(1)}k` : n.toLocaleString("en-US");
+}
+/**
+ * `n` equal tiles separated by `n − 1` equal gutters of ~`gapFrac` of the row,
+ * as weights whose total is 5-smooth (≤ 120, the lattice). Rounding each band
+ * to a percent on its own (`wOf`) sums to 100 ± a few — 4×24 + 3×2 = 102 → a
+ * 51 = 3·17 basis — and `latticeWeights` cannot rewrite an item/gutter list
+ * onto a smooth total without making the tiles unequal, so the basis is
+ * chosen here, exactly: the smooth total whose gutter is nearest `gapFrac`.
+ */
+function smoothTileRow(n, gapFrac) {
+    if (n <= 1)
+        return { tile: 1, gap: 0, total: 1 };
+    let best = null;
+    for (let total = template_utils_1.FAMILY_GCD; total >= 2 * n - 1; total--) {
+        if (!(0, template_utils_1.isSmooth)(total))
+            continue;
+        const g0 = Math.round(total * gapFrac);
+        for (const gap of [g0, g0 - 1, g0 + 1]) {
+            if (gap < 1)
+                continue;
+            const rest = total - gap * (n - 1);
+            if (rest % n !== 0)
+                continue;
+            const tile = rest / n;
+            if (tile <= gap)
+                continue;
+            const err = Math.abs(gap / total - gapFrac);
+            if (!best || err < best.err)
+                best = { tile, gap, total, err };
+        }
+    }
+    if (!best)
+        return { tile: 1, gap: 0, total: n };
+    return { tile: best.tile, gap: best.gap, total: best.total };
+}
+function roundTile(c, radius) {
+    return (0, template_utils_1.makeColorTile)(c, { effects: { rounding: { cornerStyle: "rounded", borderRadius: radius } } });
+}
+function capFont(px, text, boxPx, min) {
+    return Math.max(min, Math.min(px, Math.floor((boxPx * 0.94 - 2) / (Math.max(1, (0, template_utils_1.textEmUnits)(text)) * 0.72))));
+}
+/** A KPI tile: big value over a small label, on the theme's grid surface. */
+function kpiTile(value, label, theme, w, h, key, propKey) {
+    const big = capFont(Math.round(h * 0.42), value, w, 12);
+    const small = capFont(Math.round(h * 0.16), label, w, 8);
+    const stack = (0, alpine_card_1.rowSplit)([
+        { weight: 10, node: alpine_card_1.EMPTY },
+        // The value IS the prop → Make's double-click edits it in place.
+        { weight: 50, node: (0, alpine_card_1.paint)((0, template_utils_1.bindProp)((0, template_utils_1.tag)((0, alpine_card_1.textCell)(value, big, theme.title, "center", "bottom"), `kpi-${key}-value`), propKey)) },
+        { weight: 26, node: (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)(label, small, theme.muted, "center", "top"), `kpi-${key}-label`)) },
+        { weight: 14, node: alpine_card_1.EMPTY },
+    ]);
+    return (0, alpine_card_1.overlay)([(0, alpine_card_1.paint)((0, template_utils_1.tag)(roundTile(theme.grid, 0.12), `kpi-${key}-tile`)), stack]);
+}
+/**
+ * Exact inter-cell gaps via lattice retargeting — the alpine heatmap v2 move
+ * (copied: `_shared` and shipped templates are frozen). Parse the composed m0
+ * at the render canvas, take each cell's RAW rect as truth, retarget all of
+ * them onto an integer lattice spanning the grid's region — equal cells, gaps
+ * of exactly `gapPx` — and hand every cell tile a `placement.inset`.
+ * Degrades to a gapless grid (never dies) when the lattice cannot fit.
+ */
+function applyLatticeGapInsets(root, cellSources, gapPx, W, H) {
+    const N = cellSources.length;
+    if (gapPx <= 0 || N === 0)
+        return;
+    try {
+        const iCells = root.sources.indexOf(cellSources[0]);
+        if (iCells < 0 || root.sources[iCells + N - 1] !== cellSources[N - 1])
+            return;
+        const frames = (0, dsl_1.parseM0StringToRenderFrames)(root.m0, W, H);
+        const byLogical = [];
+        for (const f of frames)
+            byLogical[f.logicalIndex] = f;
+        const raws = [];
+        for (let k = 0; k < N; k++) {
+            const f = byLogical[iCells + k];
+            if (!f || f.width < 1 || f.height < 1)
+                return;
+            raws.push({ x: f.x, y: f.y, w: f.width, h: f.height });
+        }
+        const minX = Math.min(...raws.map((r) => r.x)), minY = Math.min(...raws.map((r) => r.y));
+        const maxX = Math.max(...raws.map((r) => r.x + r.w)), maxY = Math.max(...raws.map((r) => r.y + r.h));
+        const lat = (0, template_utils_1.latticeCellInset)({
+            cols: WEEKS,
+            rows: DAYS,
+            canvasW: maxX - minX,
+            canvasH: maxY - minY,
+            gutterXPx: gapPx,
+            gutterYPx: gapPx,
+            marginPx: 0,
+            cells: raws.map((r, k) => ({ unit: { c0: k % WEEKS, r0: Math.floor(k / WEEKS), cs: 1, rs: 1 }, raw: { x: r.x - minX, y: r.y - minY, w: r.w, h: r.h } })),
+        });
+        for (let k = 0; k < N; k++) {
+            const box = lat.insetAt(k);
+            if (box)
+                cellSources[k].placement = { inset: box };
+        }
+    }
+    catch {
+        // Degenerate lattice (tiny canvas) — render gapless rather than dying.
+    }
+}
+// ---------------------------------------------------------------------------
+// Template
+// ---------------------------------------------------------------------------
+exports.YearCardV1 = {
+    id: (0, types_1.asTemplateId)(TEMPLATE_ID),
+    label: "GitHub Year Card",
+    version: 1,
+    description: "A developer's year on GitHub on one card: the 7×53 contribution calendar with month and weekday labels and a Less→More legend, four KPI tiles (commits, pull requests, stars, top language) and the handle + year in the header. Gutterless grid with lattice-exact gaps; composes at any canvas.",
+    capabilities: { tier: "core" },
+    tags: ["github", "contributions", "calendar", "heatmap", "year", "developers", "vanity", "share", "alpine", "animated"],
+    aspectRatio: { ideal: 16 / 9, min: 1.3, max: 2.4, mode: "warn" },
+    // The calendar's 53 week columns are content cardinality (GitHub's own
+    // grid: a year spans up to 53 ISO weeks), not a layout basis — declared,
+    // like the convention's own example. The gaps live in the fiber
+    // (latticeCellInset), so the grid itself stays a clean 7×53.
+    lattice: { allow: [{ count: WEEKS, reason: "the contribution calendar's 53 week columns — a year spans up to 53 ISO weeks (content cardinality, GitHub's own grid)" }] },
+    outputHints: { format: { kind: "video", container: "mp4" }, width: 1280, height: 720, fps: 30, durationMs: 3000 },
+    propsSchema,
+    defaultProps: {
+        handle: "@qsbuilds",
+        year: 2026,
+        contributions: exports.SAMPLE_CONTRIBUTIONS,
+        commits: 1102,
+        pullRequests: 96,
+        stars: 412,
+        topLanguage: "TypeScript",
+        showKpis: true,
+        preset: "light",
+        anim: { ...DEFAULT_ANIM },
+        debugLayout: false,
+    },
+    async render(props, ctx) {
+        var _a, _b, _c;
+        const W = Math.max(1, Math.round(ctx.target.width));
+        const H = Math.max(1, Math.round(ctx.target.height));
+        const fail = (message) => (0, template_utils_1.makeErrorMosaic)(message, { title: "GitHub Year Card", width: W, height: H });
+        const counts = parseContributions(props.contributions);
+        if (counts.length === 0)
+            return fail("year-card needs contributions (365 daily counts, or a comma string)");
+        const year = Number.isFinite(props.year) && props.year >= 2008 && props.year <= 2100 ? Math.round(props.year) : 2026;
+        const cal = calendarLayout(year);
+        const daily = Array.from({ length: cal.days }, (_, i) => { var _a; return (_a = counts[i]) !== null && _a !== void 0 ? _a : 0; });
+        const total = daily.reduce((a, b) => a + b, 0);
+        const max = Math.max(0, ...daily);
+        const streak = longestStreak(daily);
+        const preset = props.preset === "dark" ? "dark" : "light";
+        const theme = await (0, alpine_theme_1.resolveAlpineTheme)(preset, ctx, props.theme);
+        const greens = GREENS[preset];
+        const anim = { ...DEFAULT_ANIM, ...((_a = props.anim) !== null && _a !== void 0 ? _a : {}) };
+        const animate = !anim.reduceMotion;
+        const light = anim.renderMode === "light";
+        const clipSec = Math.max(0.1, ((_b = ctx.target.durationMs) !== null && _b !== void 0 ? _b : 3000) / 1000);
+        const introSec = Math.max(0.1, Math.min(1, anim.introFrac) * clipSec);
+        const fadeDur = Math.max(0.08, introSec * 0.3);
+        const showKpis = props.showKpis !== false;
+        const handle = ((_c = props.handle) !== null && _c !== void 0 ? _c : "").trim();
+        const title = handle ? `${handle} · ${year} on GitHub` : `${year} on GitHub`;
+        const subtitle = `${fmtCount(total)} contributions · longest streak ${streak} ${streak === 1 ? "day" : "days"}`;
+        // ── chrome ──
+        // The title shows the handle (+ the year); the subtitle is derived.
+        const card = (0, alpine_card_1.alpineCard)({ theme, W, H, title, subtitle, headerBinding: handle ? { title: "handle" } : false });
+        const content = card.contentRect;
+        const wOf = (px, ref) => Math.max(1, Math.round((px / ref) * 100));
+        // ── geometry ──
+        const kpiH = showKpis ? Math.round(content.h * 0.24) : 0;
+        const kpiGap = showKpis ? Math.round(content.h * 0.06) : 0;
+        const monthH = Math.round(content.h * 0.07);
+        const legendH = Math.round(content.h * 0.08);
+        const legendGap = Math.round(content.h * 0.03);
+        const dayLabelW = Math.round(content.w * 0.045);
+        const calAreaW = content.w - dayLabelW;
+        const calAreaH = Math.max(1, content.h - kpiH - kpiGap - monthH - legendH - legendGap);
+        // Square cells that fit the area on both axes; the grid is letterboxed inside it.
+        const cell = Math.max(4, Math.floor(Math.min(calAreaW / WEEKS, calAreaH / DAYS)));
+        const gridW = cell * WEEKS, gridH = cell * DAYS;
+        const gap = Math.max(1, Math.round(cell * 0.2));
+        const lbX = Math.max(0, Math.round((calAreaW - gridW) / 2));
+        const labelFont = Math.max(8, Math.round(H * 0.019));
+        // ── KPI row ──
+        const kpis = [
+            { key: "commits", prop: "commits", value: props.commits, label: "commits" },
+            { key: "prs", prop: "pullRequests", value: props.pullRequests, label: "pull requests" },
+            { key: "stars", prop: "stars", value: props.stars, label: "stars earned" },
+            { key: "lang", prop: "topLanguage", value: props.topLanguage, label: "top language" },
+        ].filter((k) => k.value != null && k.value !== "" && (typeof k.value !== "number" || Number.isFinite(k.value)));
+        let kpiRow = alpine_card_1.EMPTY;
+        if (showKpis && kpis.length > 0) {
+            // Tiles + 2 % gutters on a smooth basis (not per-band percents — see smoothTileRow).
+            const row = smoothTileRow(kpis.length, 0.02);
+            const tileW = Math.max(1, Math.round((content.w * row.tile) / row.total));
+            const bands = [];
+            kpis.forEach((k, i) => {
+                if (i > 0)
+                    bands.push({ weight: row.gap, node: alpine_card_1.EMPTY });
+                const value = typeof k.value === "number" ? fmtCount(k.value) : String(k.value).trim();
+                bands.push({ weight: row.tile, node: kpiTile(value, k.label, theme, tileW, kpiH, k.key, k.prop) });
+            });
+            kpiRow = (0, alpine_card_1.colSplit)(bands);
+        }
+        // ── month labels: one band per month, weighted by its week span ──
+        const monthBands = [];
+        if (cal.monthCols[0].col > 0)
+            monthBands.push({ weight: cal.monthCols[0].col, node: alpine_card_1.EMPTY });
+        cal.monthCols.forEach((m, i) => {
+            var _a, _b;
+            const next = (_b = (_a = cal.monthCols[i + 1]) === null || _a === void 0 ? void 0 : _a.col) !== null && _b !== void 0 ? _b : WEEKS;
+            const span = Math.max(1, next - m.col);
+            const spanPx = span * cell;
+            monthBands.push({ weight: span, node: (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)(m.label, capFont(labelFont, m.label, spanPx, 7), theme.muted, "left", "bottom"), "month-label")) });
+        });
+        const monthRow = (0, alpine_card_1.colSplit)([
+            { weight: wOf(dayLabelW + lbX, content.w), node: alpine_card_1.EMPTY },
+            { weight: wOf(gridW, content.w), node: (0, alpine_card_1.colSplit)(monthBands) },
+            ...(calAreaW - gridW - lbX > 0 ? [{ weight: wOf(calAreaW - gridW - lbX, content.w), node: alpine_card_1.EMPTY }] : []),
+        ]);
+        // ── weekday labels: 7 rows, Mon / Wed / Fri ──
+        const dayRows = Array.from({ length: DAYS }, (_, d) => {
+            var _a;
+            const lbl = (_a = WEEKDAY_LABELS.find(([row]) => row === d)) === null || _a === void 0 ? void 0 : _a[1];
+            return { weight: 1, node: lbl ? (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)(lbl, capFont(labelFont, lbl, dayLabelW, 7), theme.muted, "left", "middle"), "day-label")) : alpine_card_1.EMPTY };
+        });
+        const dayCol = (0, alpine_card_1.rowSplit)(dayRows);
+        // ── the cells: one tile per gutterless grid frame (row-major over 7×53) ──
+        const gridM0 = String((0, dsl_stdlib_1.grid)({ rows: DAYS, cols: WEEKS }).m0);
+        const cellSources = [];
+        const maxDiag = Math.max(1, DAYS + WEEKS - 2);
+        for (let r = 0; r < DAYS; r++) {
+            for (let c = 0; c < WEEKS; c++) {
+                const dayIndex = c * DAYS + r - cal.firstDow;
+                const inYear = dayIndex >= 0 && dayIndex < cal.days;
+                const fill = inYear ? greens[bucketOf(daily[dayIndex], max)] : theme.card;
+                // premium = a per-cell alpha fade on the diagonal (371 overlays keep
+                // the tiles off the xstack sheet: ~40 s for a 3 s clip). light (the
+                // default) leaves every cell STATIC and reveals them with ONE curtain
+                // track below — the year unfolds left to right, zero per-cell cost.
+                const at = animate && !light ? (introSec - fadeDur) * ((r + c) / maxDiag) : 0;
+                const rev = animate && !light ? { startAtSec: at, alpha: (0, template_utils_1.fadeInExpr)(at, fadeDur) } : {};
+                // Plain square tiles on purpose: a rounding effect is an inline mask per
+                // tile, and 371 of them quadruple the render (37 s → 9 s for the still).
+                const tile = (0, template_utils_1.makeColorTile)(fill, {
+                    ...(Object.keys(rev).length ? { overlay: rev } : {}),
+                });
+                tile.editor = { label: inYear ? "cell" : "cell-outside" };
+                cellSources.push(tile);
+            }
+        }
+        const cellsNode = { m0: gridM0, sources: cellSources };
+        // The light reveal: one hide-coloured box per week column, gated to drop
+        // in run order across the intro (the hello-world field wipe, per week).
+        let gridNode = cellsNode;
+        if (animate && light) {
+            const boxes = Array.from({ length: WEEKS }, (_, c) => ({
+                x: c * cell,
+                y: 0,
+                w: cell,
+                h: gridH,
+                revealAtSec: Number((introSec * ((c + 1) / WEEKS)).toFixed(3)),
+            }));
+            const curtain = (0, template_utils_1.curtainSource)(boxes, theme.card);
+            if (curtain)
+                gridNode = (0, alpine_card_1.overlay)([cellsNode, (0, alpine_card_1.paint)((0, template_utils_1.tag)(curtain, "calendar-curtain"))]);
+        }
+        const calendarRow = (0, alpine_card_1.colSplit)([
+            { weight: wOf(dayLabelW, content.w), node: dayCol },
+            ...(lbX > 0 ? [{ weight: wOf(lbX, content.w), node: alpine_card_1.EMPTY }] : []),
+            { weight: wOf(gridW, content.w), node: gridNode },
+            ...(calAreaW - gridW - lbX > 0 ? [{ weight: wOf(calAreaW - gridW - lbX, content.w), node: alpine_card_1.EMPTY }] : []),
+        ]);
+        // ── legend: Less · five swatches · More, right-aligned under the grid ──
+        const sw = Math.max(6, Math.round(legendH * 0.4));
+        const legendTextW = Math.round(content.w * 0.05);
+        const swatchBands = [];
+        greens.forEach((g, i) => {
+            if (i > 0)
+                swatchBands.push({ weight: Math.max(1, Math.round(sw * 0.3)), node: alpine_card_1.EMPTY });
+            swatchBands.push({ weight: sw, node: (0, alpine_card_1.rowSplit)([{ weight: 1, node: alpine_card_1.EMPTY }, { weight: 1, node: (0, alpine_card_1.paint)((0, template_utils_1.tag)(roundTile(g, 0.25), "legend-swatch")) }, { weight: 1, node: alpine_card_1.EMPTY }]) });
+        });
+        const swatchesW = sw * greens.length + Math.round(sw * 0.3) * (greens.length - 1);
+        const legendW = legendTextW * 2 + swatchesW + Math.round(sw * 0.8) * 2;
+        const legend = (0, alpine_card_1.colSplit)([
+            { weight: legendTextW, node: (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)("Less", capFont(labelFont, "Less", legendTextW, 7), theme.muted, "right", "middle"), "legend-less")) },
+            { weight: Math.round(sw * 0.8), node: alpine_card_1.EMPTY },
+            { weight: swatchesW, node: (0, alpine_card_1.colSplit)(swatchBands) },
+            { weight: Math.round(sw * 0.8), node: alpine_card_1.EMPTY },
+            { weight: legendTextW, node: (0, alpine_card_1.paint)((0, template_utils_1.tag)((0, alpine_card_1.textCell)("More", capFont(labelFont, "More", legendTextW, 7), theme.muted, "left", "middle"), "legend-more")) },
+        ]);
+        const legendRow = (0, alpine_card_1.colSplit)([
+            { weight: wOf(Math.max(1, content.w - legendW), content.w), node: alpine_card_1.EMPTY },
+            { weight: wOf(legendW, content.w), node: legend },
+        ]);
+        // ── stack ──
+        const bands = [];
+        if (showKpis && kpis.length > 0) {
+            bands.push({ weight: wOf(kpiH, content.h), node: kpiRow });
+            bands.push({ weight: wOf(kpiGap, content.h), node: alpine_card_1.EMPTY });
+        }
+        else if (kpiH + kpiGap > 0) {
+            bands.push({ weight: wOf(kpiH + kpiGap, content.h), node: alpine_card_1.EMPTY });
+        }
+        // The grid is usually width-bound, so the calendar area has vertical
+        // slack: a little above the month labels, the rest under the grid.
+        const slack = Math.max(0, calAreaH - gridH);
+        const monthGap = Math.min(slack, Math.max(2, Math.round(content.h * 0.018)));
+        const slackTop = Math.round((slack - monthGap) * 0.3);
+        if (slackTop > 0)
+            bands.push({ weight: wOf(slackTop, content.h), node: alpine_card_1.EMPTY });
+        bands.push({ weight: wOf(monthH, content.h), node: monthRow });
+        if (monthGap > 0)
+            bands.push({ weight: wOf(monthGap, content.h), node: alpine_card_1.EMPTY });
+        bands.push({ weight: wOf(gridH, content.h), node: calendarRow });
+        if (slack - monthGap - slackTop > 0)
+            bands.push({ weight: wOf(slack - monthGap - slackTop, content.h), node: alpine_card_1.EMPTY });
+        bands.push({ weight: wOf(legendGap, content.h), node: alpine_card_1.EMPTY });
+        bands.push({ weight: wOf(legendH, content.h), node: legendRow });
+        const root = card.compose((0, alpine_card_1.rowSplit)(bands));
+        // Exact gaps between the calendar cells, against the composed truth.
+        applyLatticeGapInsets(root, cellSources, gap, W, H);
+        const doc = {
+            kind: "mosaic_document",
+            version: 1,
+            assets: {},
+            m0: (0, dsl_stdlib_1.toM0String)(root.m0, "YearCardV1"),
+            sources: root.sources,
+            backgroundColor: card.backgroundColor,
+            fps: ctx.target.fps,
+            durationMs: ctx.target.durationMs,
+            size: { width: W, height: H },
+            editor: { label: `GitHub Year Card · ${title}` },
+        };
+        const constraints = [
+            ...card.constraints,
+            { label: "month-label", textFits: {} },
+            { label: "day-label", textFits: {} },
+            { label: "legend-less", textFits: {} },
+            { label: "legend-more", textFits: {} },
+            ...kpis.map((k) => ({ label: `kpi-${k.key}-value`, textFits: {} })),
+        ];
+        return (0, template_utils_1.withLayoutContract)(doc, ctx, {
+            templateId: TEMPLATE_ID,
+            constraints,
+            relations: [{ label: "cell", equal: "size", tolerance: 0.02, tolerancePx: 1 }],
+            debug: props.debugLayout === true,
+        });
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.YearCardV1);
+exports.default = exports.YearCardV1;

package/dist/m0saic/hello-world/index.d.ts

@@ -0,0 +1 @@
+export * from "./v1";

package/dist/m0saic/hello-world/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/* Hello, World — the CLI's first render (`m0saic hello-world`). Packless id, like theming/ and dsl-tutorial/. */
+__exportStar(require("./v1"), exports);

package/dist/m0saic/hello-world/v1/hello-world.d.ts

@@ -0,0 +1,4 @@
+export type { HelloGeometry, HelloMarkReveal, HelloSweep, HelloTextLine, HelloTimeline, HelloWorldProps, HelloWorldTemplateOptions, MarkAssembly, Rect, } from "@m0saic/template-utils";
+export { ASSEMBLE_BOXES_PER_TRACK, DEFAULT_FIELD_OPACITY, HELLO_MARK_REVEALS, HELLO_SWEEPS, NAVY, NAVY_SOFT, assemblyTracks, buildHelloGeometry, coverFitField, fieldWipe, helloLayoutConstraints, helloTimeline, inverseSmoothstep, isPortraitField, markAssembly, markRectsIn, mixHex, sweepStripPx, } from "@m0saic/template-utils";
+export declare const HelloWorld: import("@m0saic/types").MosaicTemplate<import("@m0saic/template-utils").HelloWorldProps, import("@m0saic/types").MosaicTemplateOutputs, import("@m0saic/types").MosaicTemplateUpstreamVariables, import("@m0saic/types").MosaicTemplateUpstreamData, import("@m0saic/types").MosaicTemplateSidecars>;
+export default HelloWorld;

package/dist/m0saic/hello-world/v1/hello-world.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HelloWorld = exports.sweepStripPx = exports.mixHex = exports.markRectsIn = exports.markAssembly = exports.isPortraitField = exports.inverseSmoothstep = exports.helloTimeline = exports.helloLayoutConstraints = exports.fieldWipe = exports.coverFitField = exports.buildHelloGeometry = exports.assemblyTracks = exports.NAVY_SOFT = exports.NAVY = exports.HELLO_SWEEPS = exports.HELLO_MARK_REVEALS = exports.DEFAULT_FIELD_OPACITY = exports.ASSEMBLE_BOXES_PER_TRACK = void 0;
+/**
+ * @m0saic/hello-world/v1 — Hello, World (the CLI's first render).
+ *
+ * The brand card — the app's Home screen, said as a greeting. Since
+ * 2026-09-14 the card lives in `@m0saic/template-utils` as
+ * `defineHelloWorldTemplate`, so every template repo (the starters, a
+ * third-party pack) ships the same canonical card with one call; this file is
+ * that call for the core id. The chrome, the props, the geometry, the motion
+ * and the layout contract are documented on the factory.
+ */
+const template_utils_1 = require("@m0saic/template-utils");
+var template_utils_2 = require("@m0saic/template-utils");
+Object.defineProperty(exports, "ASSEMBLE_BOXES_PER_TRACK", { enumerable: true, get: function () { return template_utils_2.ASSEMBLE_BOXES_PER_TRACK; } });
+Object.defineProperty(exports, "DEFAULT_FIELD_OPACITY", { enumerable: true, get: function () { return template_utils_2.DEFAULT_FIELD_OPACITY; } });
+Object.defineProperty(exports, "HELLO_MARK_REVEALS", { enumerable: true, get: function () { return template_utils_2.HELLO_MARK_REVEALS; } });
+Object.defineProperty(exports, "HELLO_SWEEPS", { enumerable: true, get: function () { return template_utils_2.HELLO_SWEEPS; } });
+Object.defineProperty(exports, "NAVY", { enumerable: true, get: function () { return template_utils_2.NAVY; } });
+Object.defineProperty(exports, "NAVY_SOFT", { enumerable: true, get: function () { return template_utils_2.NAVY_SOFT; } });
+Object.defineProperty(exports, "assemblyTracks", { enumerable: true, get: function () { return template_utils_2.assemblyTracks; } });
+Object.defineProperty(exports, "buildHelloGeometry", { enumerable: true, get: function () { return template_utils_2.buildHelloGeometry; } });
+Object.defineProperty(exports, "coverFitField", { enumerable: true, get: function () { return template_utils_2.coverFitField; } });
+Object.defineProperty(exports, "fieldWipe", { enumerable: true, get: function () { return template_utils_2.fieldWipe; } });
+Object.defineProperty(exports, "helloLayoutConstraints", { enumerable: true, get: function () { return template_utils_2.helloLayoutConstraints; } });
+Object.defineProperty(exports, "helloTimeline", { enumerable: true, get: function () { return template_utils_2.helloTimeline; } });
+Object.defineProperty(exports, "inverseSmoothstep", { enumerable: true, get: function () { return template_utils_2.inverseSmoothstep; } });
+Object.defineProperty(exports, "isPortraitField", { enumerable: true, get: function () { return template_utils_2.isPortraitField; } });
+Object.defineProperty(exports, "markAssembly", { enumerable: true, get: function () { return template_utils_2.markAssembly; } });
+Object.defineProperty(exports, "markRectsIn", { enumerable: true, get: function () { return template_utils_2.markRectsIn; } });
+Object.defineProperty(exports, "mixHex", { enumerable: true, get: function () { return template_utils_2.mixHex; } });
+Object.defineProperty(exports, "sweepStripPx", { enumerable: true, get: function () { return template_utils_2.sweepStripPx; } });
+exports.HelloWorld = (0, template_utils_1.defineHelloWorldTemplate)({ id: "@m0saic/hello-world/v1" });
+(0, template_utils_1.registerTemplate)(exports.HelloWorld);
+exports.default = exports.HelloWorld;

package/dist/m0saic/hello-world/v1/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @m0saic/hello-world/v1 — entry point. Importing this file registers the
+ * template via `registerTemplate` (module side effect).
+ */
+export { HelloWorld } from "./hello-world";

package/dist/m0saic/hello-world/v1/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HelloWorld = void 0;
+/**
+ * @m0saic/hello-world/v1 — entry point. Importing this file registers the
+ * template via `registerTemplate` (module side effect).
+ */
+var hello_world_1 = require("./hello-world");
+Object.defineProperty(exports, "HelloWorld", { enumerable: true, get: function () { return hello_world_1.HelloWorld; } });

package/dist/m0saic/hero/ffmpeg-pulse/_shared/assets/bake-fin-qr.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Re-bake the Fin premium QR (green QR Code + FFmpeg logo center, pixelate assemble)
+# to a flat video the fin beat references as chromeAssets.qrFin. Run from repo root.
+# (Originally baked via qr-carve/v1, deleted 2026-07-22 — QR Code's Center group
+# + Output mp4 spawn are the same engine; square style renders radius-0 eyes.)
+set -euo pipefail
+AD="packages/templates/src/m0saic/hero/ffmpeg-pulse/_shared/assets"
+LOGO="$(pwd)/$AD/ffmpeg-logo.png"
+m0saic make "@m0saic/media/qr/code/v1" -o "$AD/qr-fin.mp4" --width 720 --height 720 --durationMs 6000 --no-alpha \
+  --props "{\"text\":\"https://www.m0saic.io\",\"moduleColor\":\"#3fb950\",\"version\":8,\"mode\":\"dark\",\"moduleStyle\":\"square\",\"outputFormat\":\"mp4\",\"center\":{\"assetPath\":\"$LOGO\",\"width\":170,\"height\":170}}"
+echo "baked → $AD/qr-fin.mp4"

package/dist/m0saic/hero/ffmpeg-pulse/_shared/assets/ffmpeg_logo_480x480.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="utf-8"?><!-- Generator: Adobe Illustrator 21.0.2, SVG Export Plug-In . SVG Version: 6.00 Build 0)  --><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 48 48" width="480px" height="480px"><path style="fill:#388E3C;" d="M39.5,42h-9c-1,0-1.9-0.6-2.3-1.5c-0.4-0.9-0.2-2,0.5-2.7l8.3-8.3v-3.9L21.3,41.3  c-0.5,0.5-1.1,0.7-1.8,0.7h-11c-1,0-1.9-0.6-2.3-1.5c-0.4-0.9-0.2-2,0.5-2.7L33.5,11h-3.9L10.3,30.3c-0.7,0.7-1.8,0.9-2.7,0.5  C6.6,30.4,6,29.5,6,28.5v-11c0-0.7,0.3-1.3,0.7-1.8l4.7-4.7h-3C7.1,11,6,9.9,6,8.5S7.1,6,8.5,6h9c1,0,1.9,0.6,2.3,1.5  c0.4,0.9,0.2,2-0.5,2.7L11,18.5v3.9L26.7,6.7C27.2,6.3,27.8,6,28.5,6h11c1,0,1.9,0.6,2.3,1.5c0.4,0.9,0.2,2-0.5,2.7L14.5,37h3.9  l19.3-19.3c0.7-0.7,1.8-0.9,2.7-0.5c0.9,0.4,1.5,1.3,1.5,2.3v11c0,0.7-0.3,1.3-0.7,1.8L36.5,37h3c1.4,0,2.5,1.1,2.5,2.5  S40.9,42,39.5,42z"/></svg>