@m0saic/templates 0.2.0

package/dist/m0saic/hero/ffmpeg-pulse/_shared/pulse-data.d.ts

@@ -0,0 +1,178 @@
+/**
+ * ============================================================================
+ * hero/ffmpeg-pulse — the WeeklyPulse data contract + canonical mock
+ * ============================================================================
+ *
+ * ONE typed {@link WeeklyPulse} object feeds the ENTIRE video. The runner passes
+ * it as a direct prop to every beat (Phases 1–3); the Phase-4 GitHub fetcher
+ * publishes the SAME shape on `ctx.upstreamData.weeklyPulse` and beats read
+ * upstream-first, prop-fallback — so the fetcher is a drop-in.
+ *
+ * METRICS SCOPE — API-derivable only. Every field here is a cheap GitHub
+ * REST/GraphQL read (or a free derivation from one). There are NO mock-only
+ * fields: the storyboard's CI-success-rate / review-time / deployments tiles are
+ * intentionally dropped because they need Actions/Checks/Deployments APIs +
+ * heuristics. See the field-by-field source notes below.
+ * ============================================================================
+ */
+import type { MosaicEngineContext, MosaicTemplateVariableDefinition } from "@m0saic/types";
+export type Trend = "up" | "down" | "flat";
+/** A KPI / stat tile. `value` is the raw number; `display` overrides the
+ *  formatted value (e.g. "7/7", "+87") when compaction isn't wanted. */
+export type PulseKpi = {
+    /** Stable id (e.g. "commits"). */
+    key: string;
+    /** Display label (e.g. "Total Commits"). */
+    label: string;
+    /** Raw value — counts up in animation; formatted via {@link compactNum} unless `display` is set. */
+    value: number;
+    /** Pre-formatted value override (e.g. "+87", "7/7", "18.1"). */
+    display?: string;
+    /** Percent change vs. the previous week (signed). */
+    deltaPct?: number;
+    /** Delta direction → arrow + color. */
+    direction?: Trend;
+    /** Muted caption (e.g. "vs last week", "May 15"). */
+    sublabel?: string;
+};
+export type PulsePeriod = {
+    /** ISO week number. */
+    weekNumber: number;
+    /** Window start, "YYYY-MM-DD". */
+    startISO: string;
+    /** Window end, "YYYY-MM-DD". */
+    endISO: string;
+};
+/** A row of the contributors table. */
+export type ContributorRow = {
+    rank: number;
+    login: string;
+    name: string;
+    /** Avatar image url/path (GitHub `author.avatar_url`); optional in the mock. */
+    avatarUrl?: string;
+    commits: number;
+    additions: number;
+    deletions: number;
+};
+/** A slice of the changes-by-area donut + legend. */
+export type AreaSlice = {
+    area: string;
+    files: number;
+    color?: string;
+};
+export type CommitKind = "feat" | "fix" | "perf" | "docs" | "test" | "chore";
+/** A notable-commits feed row. `kind` drives the colored icon tile; `signal` drives
+ *  the left status bar (win/warn/neutral) so maintainers spot risky vs. clean work. */
+export type NotableCommit = {
+    kind: CommitKind;
+    title: string;
+    hash: string;
+    author: string;
+    /** Commit date, "YYYY-MM-DD". */
+    dateISO: string;
+    /** Associated PR number. API: commit → `/commits/{sha}/pulls`. */
+    pr?: number;
+    /** Reviewer logins/names. API: PR `/reviews` (state APPROVED/COMMENTED). */
+    reviewers?: string[];
+    /** Subsystem / package (top-level changed dir). */
+    area?: string;
+    /** Attention signal: a win, a risky/warn change, or neutral. */
+    signal?: "win" | "warn" | "neutral";
+};
+/**
+ * The whole-video data sheet. Field → beat → GitHub source:
+ * - `repo` / `period`  — Title pill + every footer.            `GET /repos/{o}/{r}` + the window args.
+ * - `kpis`             — Beat 1 KPI grid (flexible count).     counts from `/commits`,`/pulls`,`/issues`,`/repos` (stars); deltas free from multi-week stats.
+ * - `activity`         — Beat 2 trend + rail.                  `GET /stats/commit_activity` (daily) — peak/avg/active-days all derived.
+ * - `contributors`     — Beat 3 table + rail.                  `GET /stats/contributors` (weekly c/a/d) + `author.avatar_url`.
+ * - `changes`          — Beat 4 donut + legend + rail.         per-commit `files[]` / compare API; byArea = group changed paths by top dir.
+ * - `notable`          — Beat 5 feed + rail.                   `/commits` in range; `kind` from message prefix.
+ * - `fin`              — Fin card.                             reuses the above aggregates.
+ */
+export type WeeklyPulse = {
+    repo: {
+        name: string;
+        fullName: string;
+        logoAssetId?: string;
+    };
+    period: PulsePeriod;
+    kpis: PulseKpi[];
+    activity: {
+        days: {
+            label: string;
+            commits: number;
+        }[];
+        peak: {
+            dayLabel: string;
+            dateISO: string;
+            commits: number;
+        };
+        /** Trailing N-week contribution grid (7 weekday rows × N week cols) for the
+         *  heatmap beat. API: `GET /stats/commit_activity` (52 weeks × 7 days) — slice the
+         *  trailing N. Last column == this week's `days`. */
+        grid: {
+            weekLabels: string[];
+            rows: {
+                label: string;
+                values: number[];
+            }[];
+        };
+        rail: PulseKpi[];
+    };
+    contributors: {
+        rows: ContributorRow[];
+        rail: PulseKpi[];
+    };
+    changes: {
+        totalFiles: number;
+        byArea: AreaSlice[];
+        rail: PulseKpi[];
+    };
+    notable: {
+        items: NotableCommit[];
+        rail: PulseKpi[];
+    };
+    fin: {
+        headline: string;
+        subhead: string;
+        kpiStrip: PulseKpi[];
+        qr: {
+            url: string;
+            caption: string;
+        };
+        footer: string;
+    };
+};
+/** "2025-05-15" → "May 15". */
+export declare function monthDay(iso: string): string;
+/** Compact a big number: 4500 → "4.5K", 1_234_567 → "1.2M". */
+export declare function compactNum(n: number): string;
+/** A KPI's display string: explicit `display` wins, else compacted value. */
+export declare function kpiValue(k: PulseKpi): string;
+/** Signed percent: 18 → "+18%", -4.3 → "-4.3%". */
+export declare function signedPct(p: number): string;
+/** A KPI's delta string (e.g. "+18%"), or "" when no delta. */
+export declare function kpiDelta(k: PulseKpi): string;
+/** "May 12 – May 18, 2025  ·  WEEK 20" — the title pill / footer label. */
+export declare function periodLabel(p: PulsePeriod): string;
+export declare const MOCK_FFMPEG_PULSE: WeeklyPulse;
+export declare function PULSE_AREA(i: number): string;
+/**
+ * The single pulse-resolution rule for every beat + the runner: upstream data
+ * (published by `@m0saic/github/weekly-pulse-adapter/v1` under the alias
+ * `weeklyPulse`) wins, then the direct prop, then the canonical mock. So a beat
+ * renders standalone on the mock, takes an explicit `pulse` prop when given one,
+ * and becomes a drop-in live consumer when wired behind the adapter — no code
+ * change at the call site beyond this one helper.
+ */
+export declare function resolvePulse(propsPulse: WeeklyPulse | undefined, ctx: MosaicEngineContext): WeeklyPulse;
+/**
+ * The OPTIONAL `weeklyPulse` upstream block every beat + the runner declares.
+ * All keys are `required: false`, so a beat stays standalone-renderable on the
+ * mock (absent block → no diagnostic) while a PRESENT-but-drifted block still
+ * fails loudly at resolve time (`VARIABLES_SCHEMA_MISMATCH`, per F1).
+ */
+export declare const WEEKLY_PULSE_UPSTREAM_SCHEMA: Partial<Record<string, {
+    description?: string;
+    variables: Partial<Record<string, MosaicTemplateVariableDefinition>>;
+}>>;

package/dist/m0saic/hero/ffmpeg-pulse/_shared/pulse-data.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * ============================================================================
+ * hero/ffmpeg-pulse — the WeeklyPulse data contract + canonical mock
+ * ============================================================================
+ *
+ * ONE typed {@link WeeklyPulse} object feeds the ENTIRE video. The runner passes
+ * it as a direct prop to every beat (Phases 1–3); the Phase-4 GitHub fetcher
+ * publishes the SAME shape on `ctx.upstreamData.weeklyPulse` and beats read
+ * upstream-first, prop-fallback — so the fetcher is a drop-in.
+ *
+ * METRICS SCOPE — API-derivable only. Every field here is a cheap GitHub
+ * REST/GraphQL read (or a free derivation from one). There are NO mock-only
+ * fields: the storyboard's CI-success-rate / review-time / deployments tiles are
+ * intentionally dropped because they need Actions/Checks/Deployments APIs +
+ * heuristics. See the field-by-field source notes below.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEEKLY_PULSE_UPSTREAM_SCHEMA = exports.MOCK_FFMPEG_PULSE = void 0;
+exports.monthDay = monthDay;
+exports.compactNum = compactNum;
+exports.kpiValue = kpiValue;
+exports.signedPct = signedPct;
+exports.kpiDelta = kpiDelta;
+exports.periodLabel = periodLabel;
+exports.PULSE_AREA = PULSE_AREA;
+exports.resolvePulse = resolvePulse;
+// ---------------------------------------------------------------------------
+// Derive helpers (deterministic — no wall-clock, no Date() reads of `now`)
+// ---------------------------------------------------------------------------
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/** Parse a "YYYY-MM-DD" string into integer parts (no Date construction). */
+function parseISODate(iso) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(iso);
+    if (!m)
+        return { y: 0, m: 1, d: 1 };
+    return { y: Number(m[1]), m: Number(m[2]), d: Number(m[3]) };
+}
+/** "2025-05-15" → "May 15". */
+function monthDay(iso) {
+    const { m, d } = parseISODate(iso);
+    return `${MONTHS[Math.max(0, Math.min(11, m - 1))]} ${d}`;
+}
+/** Compact a big number: 4500 → "4.5K", 1_234_567 → "1.2M". */
+function compactNum(n) {
+    const abs = Math.abs(n);
+    const sign = n < 0 ? "-" : "";
+    if (abs >= 1000000)
+        return sign + trimOne(abs / 1000000) + "M";
+    if (abs >= 1000)
+        return sign + trimOne(abs / 1000) + "K";
+    return String(Math.round(n));
+}
+function trimOne(v) {
+    return String(Math.round(v * 10) / 10);
+}
+/** A KPI's display string: explicit `display` wins, else compacted value. */
+function kpiValue(k) {
+    return k.display != null && k.display !== "" ? k.display : compactNum(k.value);
+}
+/** Signed percent: 18 → "+18%", -4.3 → "-4.3%". */
+function signedPct(p) {
+    const r = Math.round(p * 10) / 10;
+    return (r >= 0 ? "+" : "") + r + "%";
+}
+/** A KPI's delta string (e.g. "+18%"), or "" when no delta. */
+function kpiDelta(k) {
+    return k.deltaPct == null ? "" : signedPct(k.deltaPct);
+}
+/** "May 12 – May 18, 2025  ·  WEEK 20" — the title pill / footer label. */
+function periodLabel(p) {
+    const { y } = parseISODate(p.endISO);
+    return `${monthDay(p.startISO)} – ${monthDay(p.endISO)}, ${y}`;
+}
+// ---------------------------------------------------------------------------
+// Canonical mock — FFmpeg, Week 20 (May 12–18, 2025)
+// ---------------------------------------------------------------------------
+// Internally coherent numbers (the storyboard's two KPI sets disagreed; this is
+// one consistent week). Every value is shaped like a real fetch result.
+const up = (deltaPct) => ({ deltaPct, direction: "up" });
+const down = (deltaPct) => ({ deltaPct, direction: "down" });
+exports.MOCK_FFMPEG_PULSE = {
+    repo: { name: "FFmpeg", fullName: "FFmpeg/FFmpeg" },
+    period: { weekNumber: 20, startISO: "2025-05-12", endISO: "2025-05-18" },
+    // Beat 1 — KPI overview (8 derivable headline metrics).
+    kpis: [
+        { key: "commits", label: "Commits", value: 127, ...up(18), sublabel: "vs last week" },
+        { key: "pullRequests", label: "Pull Requests", value: 34, ...up(8.7), sublabel: "vs last week" },
+        { key: "mergedPrs", label: "Merged PRs", value: 28, ...up(9.1), sublabel: "vs last week" },
+        { key: "openIssues", label: "Open Issues", value: 156, ...down(4.3), sublabel: "vs last week" },
+        { key: "contributors", label: "Contributors", value: 19, ...up(26), sublabel: "vs last week" },
+        { key: "additions", label: "Additions", value: 18463, ...up(22), sublabel: "vs last week" },
+        { key: "deletions", label: "Deletions", value: 9731, ...up(8), sublabel: "vs last week" },
+        { key: "stars", label: "Stars Δ", value: 87, display: "+87", ...up(9), sublabel: "vs last week" },
+    ],
+    // Beat 2 — activity trend (Mon–Sun = 127 commits, peak Thu).
+    activity: {
+        days: [
+            { label: "Mon", commits: 12 },
+            { label: "Tue", commits: 18 },
+            { label: "Wed", commits: 21 },
+            { label: "Thu", commits: 35 },
+            { label: "Fri", commits: 22 },
+            { label: "Sat", commits: 11 },
+            { label: "Sun", commits: 8 },
+        ],
+        peak: { dayLabel: "Thu", dateISO: "2025-05-15", commits: 35 },
+        // Trailing 8-week heatmap grid (W13→W20); last column == this week's `days` above.
+        grid: {
+            weekLabels: ["W13", "W14", "W15", "W16", "W17", "W18", "W19", "W20"],
+            rows: [
+                { label: "Mon", values: [10, 14, 8, 16, 11, 13, 9, 12] },
+                { label: "Tue", values: [16, 20, 15, 22, 18, 19, 14, 18] },
+                { label: "Wed", values: [19, 24, 17, 26, 20, 23, 16, 21] },
+                { label: "Thu", values: [28, 33, 25, 38, 30, 34, 24, 35] },
+                { label: "Fri", values: [18, 22, 16, 25, 19, 24, 17, 22] },
+                { label: "Sat", values: [8, 12, 6, 14, 9, 13, 7, 11] },
+                { label: "Sun", values: [5, 8, 4, 10, 6, 9, 5, 8] },
+            ],
+        },
+        rail: [
+            { key: "totalCommits", label: "Total Commits", value: 127, ...up(18), sublabel: "vs last week" },
+            { key: "peakDay", label: "Peak Day", value: 35, sublabel: "May 15, 2025" },
+            { key: "dailyAvg", label: "Daily Avg", value: 18, display: "18.1", ...up(12), sublabel: "vs last week" },
+            { key: "activeDays", label: "Active Days", value: 7, display: "7/7", sublabel: "100% of week" },
+        ],
+    },
+    // Beat 3 — top contributors (weekly commits / additions / deletions).
+    contributors: {
+        rows: [
+            { rank: 1, login: "akhirnov", name: "Anton Khirnov", commits: 23, additions: 4512, deletions: 2103 },
+            { rank: 2, login: "michaelni", name: "Michael Niedermayer", commits: 18, additions: 3204, deletions: 1034 },
+            { rank: 3, login: "jamrial", name: "James Almer", commits: 14, additions: 2193, deletions: 812 },
+            { rank: 4, login: "cus", name: "Marton Balint", commits: 11, additions: 1842, deletions: 1201 },
+            { rank: 5, login: "lance-lmwang", name: "Limin Wang", commits: 9, additions: 1503, deletions: 623 },
+        ],
+        rail: [
+            { key: "totalCommits", label: "Total Commits", value: 127, ...up(18), sublabel: "vs last week" },
+            { key: "contributors", label: "Total Contributors", value: 19, ...up(26), sublabel: "vs last week" },
+            { key: "additions", label: "Additions", value: 18463, ...up(22), sublabel: "vs last week" },
+            { key: "deletions", label: "Deletions", value: 9731, ...up(8), sublabel: "vs last week" },
+            { key: "stars", label: "Stars Δ", value: 87, display: "+87", ...up(9), sublabel: "vs last week" },
+        ],
+    },
+    // Beat 4 — changes by area (files sum to totalFiles).
+    changes: {
+        totalFiles: 842,
+        byArea: [
+            { area: "libavcodec", files: 286, color: PULSE_AREA(0) },
+            { area: "libavformat", files: 185, color: PULSE_AREA(1) },
+            { area: "libavfilter", files: 126, color: PULSE_AREA(2) },
+            { area: "doc", files: 84, color: PULSE_AREA(3) },
+            { area: "tests", files: 67, color: PULSE_AREA(4) },
+            { area: "tools", files: 50, color: PULSE_AREA(5) },
+            { area: "other", files: 44, color: PULSE_AREA(5) },
+        ],
+        rail: [
+            { key: "totalFiles", label: "Total Files Changed", value: 842, ...up(14), sublabel: "vs last week" },
+            { key: "additions", label: "Additions", value: 18463, ...up(22), sublabel: "vs last week" },
+            { key: "deletions", label: "Deletions", value: 9731, ...up(8), sublabel: "vs last week" },
+            { key: "netChanges", label: "Net Changes", value: 8732, display: "+8,732", ...up(16), sublabel: "vs last week" },
+        ],
+    },
+    // Beat 5 — notable commits (message-prefix kind).
+    notable: {
+        items: [
+            { kind: "perf", area: "avcodec", title: "avcodec: improve AV1 decode performance", hash: "a1b2c3d", author: "Anton Khirnov", dateISO: "2025-05-15", pr: 14201, reviewers: ["James Almer", "Michael Niedermayer"], signal: "warn" },
+            { kind: "feat", area: "avformat", title: "avformat: add support for new container", hash: "d4e5f6g", author: "James Almer", dateISO: "2025-05-14", pr: 14198, reviewers: ["Anton Khirnov"], signal: "neutral" },
+            { kind: "fix", area: "avfilter", title: "avfilter: fix memory leak in overlay filter", hash: "h7i8j9k", author: "Marton Balint", dateISO: "2025-05-13", pr: 14185, reviewers: ["Anton Khirnov", "Limin Wang"], signal: "win" },
+            { kind: "docs", area: "doc", title: "doc: update HLS documentation", hash: "l0m1n2o", author: "Limin Wang", dateISO: "2025-05-12", pr: 14180, reviewers: ["Marton Balint"], signal: "neutral" },
+            { kind: "test", area: "tests", title: "tests: add FATE test for edge case", hash: "p3q4r5s", author: "Michael Niedermayer", dateISO: "2025-05-16", pr: 14205, reviewers: ["James Almer"], signal: "win" },
+        ],
+        rail: [
+            { key: "mergedPrs", label: "Merged PRs", value: 31, ...up(18), sublabel: "vs last week" },
+            { key: "reviewCoverage", label: "Review Coverage", value: 92, display: "92%", sublabel: "of merged PRs" },
+            { key: "openIssues", label: "Open Issues", value: 47, ...up(6), sublabel: "vs last week" },
+            { key: "contributors", label: "Contributors", value: 19, ...up(26), sublabel: "vs last week" },
+        ],
+    },
+    // Fin.
+    fin: {
+        headline: "THANK YOU!",
+        subhead: "ANOTHER WEEK OF PROGRESS.",
+        kpiStrip: [
+            { key: "commits", label: "Commits", value: 127, ...up(18), sublabel: "vs last week" },
+            { key: "contributors", label: "Contributors", value: 19, ...up(26), sublabel: "vs last week" },
+            { key: "filesChanged", label: "Files Changed", value: 842, ...up(14), sublabel: "vs last week" },
+            { key: "stars", label: "Stars Δ", value: 87, display: "+87", ...up(9), sublabel: "vs last week" },
+        ],
+        qr: { url: "https://www.m0saic.io", caption: "Make your own — m0saic.io" },
+        footer: "Built with m0saic",
+    },
+};
+// Area color lookup kept tiny + local (avoids importing the theme into the data
+// sheet — the data stays render-agnostic; the chrome can re-color if it wants).
+// Exported so the weekly-pulse-adapter colors its derived changes-by-area donut
+// from the same ramp (F5 Seam C).
+function PULSE_AREA(i) {
+    const ramp = ["#2ea043", "#238636", "#3fb950", "#d29922", "#8957e5", "#6e7681"];
+    return ramp[i % ramp.length];
+}
+// ---------------------------------------------------------------------------
+// Upstream-first resolution (F5 Seam D)
+// ---------------------------------------------------------------------------
+/**
+ * The single pulse-resolution rule for every beat + the runner: upstream data
+ * (published by `@m0saic/github/weekly-pulse-adapter/v1` under the alias
+ * `weeklyPulse`) wins, then the direct prop, then the canonical mock. So a beat
+ * renders standalone on the mock, takes an explicit `pulse` prop when given one,
+ * and becomes a drop-in live consumer when wired behind the adapter — no code
+ * change at the call site beyond this one helper.
+ */
+function resolvePulse(propsPulse, ctx) {
+    var _a, _b, _c;
+    return (_c = (_b = (_a = ctx.upstreamData) === null || _a === void 0 ? void 0 : _a.weeklyPulse) !== null && _b !== void 0 ? _b : propsPulse) !== null && _c !== void 0 ? _c : exports.MOCK_FFMPEG_PULSE;
+}
+/**
+ * The OPTIONAL `weeklyPulse` upstream block every beat + the runner declares.
+ * All keys are `required: false`, so a beat stays standalone-renderable on the
+ * mock (absent block → no diagnostic) while a PRESENT-but-drifted block still
+ * fails loudly at resolve time (`VARIABLES_SCHEMA_MISMATCH`, per F1).
+ */
+exports.WEEKLY_PULSE_UPSTREAM_SCHEMA = {
+    weeklyPulse: {
+        description: "Optional WeeklyPulse sheet from @m0saic/github/weekly-pulse-adapter/v1. Absent → the beat renders on its mock; present-but-drifted → resolve-time VARIABLES_SCHEMA_MISMATCH.",
+        variables: {
+            repo: { type: "object", required: false },
+            period: { type: "object", required: false },
+            kpis: { type: "any", required: false },
+            activity: { type: "object", required: false },
+            contributors: { type: "object", required: false },
+            changes: { type: "object", required: false },
+            notable: { type: "object", required: false },
+            fin: { type: "object", required: false },
+        },
+    },
+};

package/dist/m0saic/hero/ffmpeg-pulse/_shared/pulse-glyphs.d.ts

@@ -0,0 +1 @@
+export declare const KPI_GLYPHS: Record<string, string>;

package/dist/m0saic/hero/ffmpeg-pulse/_shared/pulse-glyphs.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KPI_GLYPHS = void 0;
+/* Per-KPI glyphs — GitHub Octicon (MIT) SVG path `d` strings, 24×24 viewBox.
+ * Drawn as inline-mask lavfi tiles on the stat-card accent chip (NOT media images,
+ * which mis-lay-out the card). Keyed by PulseKpi.key.
+ *
+ * The catalog itself moved to `alpine/_shared/alpine-glyphs.ts` (2026-08-20)
+ * so the alpine cards' friendly `icon` knob and these programmatic callers
+ * share one source of truth. This alias keeps every pulse-beat import working. */
+const alpine_glyphs_1 = require("../../../alpine/_shared/alpine-glyphs");
+exports.KPI_GLYPHS = alpine_glyphs_1.ALPINE_GLYPHS;

package/dist/m0saic/hero/ffmpeg-pulse/_shared/pulse-theme.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ============================================================================
+ * hero/ffmpeg-pulse — pack theme tokens
+ * ============================================================================
+ *
+ * The FFmpeg Weekly Pulse hero is a single, dark, GitHub-flavored look: a deep
+ * slate canvas (#0d1117), #161b22 cards with hairline borders, restrained green
+ * accents, and a scattered field of dark/green rectangles behind every beat.
+ *
+ * Every beat-chrome + nested viz pulls its colors from ONE {@link PulseTheme}
+ * so the whole pack reads as one set. The nested Alpine cards are themed via
+ * their `dark` preset + color props passed from these tokens, so the composed
+ * panels match the chrome.
+ * ============================================================================
+ */
+import type { MosaicColor } from "@m0saic/types";
+/** One coherent FFmpeg-Pulse look. Consumed by the chrome + every beat. */
+export type PulseTheme = {
+    /** Page/canvas behind everything. */
+    canvas: MosaicColor;
+    /** Card / panel surface. */
+    card: MosaicColor;
+    /** Hairline border color. */
+    border: MosaicColor;
+    /** Border opacity (0..1). */
+    borderAlpha: number;
+    /** "BEAT N" eyebrow label (green). */
+    eyebrow: MosaicColor;
+    /** Big beat title (near-white). */
+    title: MosaicColor;
+    /** Subtitle under the title (muted). */
+    subtitle: MosaicColor;
+    /** In-panel labels. */
+    label: MosaicColor;
+    /** Footer / de-emphasized text. */
+    muted: MosaicColor;
+    /** Brand green (darker fills). */
+    primary: MosaicColor;
+    /** Bright green (highlights, markers). */
+    primaryBright: MosaicColor;
+    /** Positive delta / up-trend. */
+    positive: MosaicColor;
+    /** Negative delta / down-trend. */
+    negative: MosaicColor;
+    /** Gridline color. */
+    grid: MosaicColor;
+    /** Gridline opacity (0..1). */
+    gridAlpha: number;
+    /** Dark rectangle shades for the background field. */
+    scatterDark: MosaicColor[];
+    /** Occasional green accents in the background field. */
+    scatterGreen: MosaicColor[];
+    /** Corner radius as a fraction of the shorter side (0..1). */
+    cornerRadius: number;
+};
+/**
+ * Categorical ramp for multi-segment marks (donut slices, area legend).
+ * Index 0 is the primary green; cycle for additional series. Mirrors the
+ * storyboard's "changes by area" colors.
+ */
+export declare const PULSE_PALETTE: MosaicColor[];
+/** Preset id union. The pack ships a single dark look today; structured for
+ *  extension (a light variant could follow without changing call sites). */
+export type PulsePreset = "dark";
+export declare const PULSE_PRESETS: Record<PulsePreset, PulseTheme>;
+/** Resolve a preset id to its theme (defaults to `dark`). */
+export declare function pulseTheme(preset?: PulsePreset): PulseTheme;

package/dist/m0saic/hero/ffmpeg-pulse/_shared/pulse-theme.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * ============================================================================
+ * hero/ffmpeg-pulse — pack theme tokens
+ * ============================================================================
+ *
+ * The FFmpeg Weekly Pulse hero is a single, dark, GitHub-flavored look: a deep
+ * slate canvas (#0d1117), #161b22 cards with hairline borders, restrained green
+ * accents, and a scattered field of dark/green rectangles behind every beat.
+ *
+ * Every beat-chrome + nested viz pulls its colors from ONE {@link PulseTheme}
+ * so the whole pack reads as one set. The nested Alpine cards are themed via
+ * their `dark` preset + color props passed from these tokens, so the composed
+ * panels match the chrome.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PULSE_PRESETS = exports.PULSE_PALETTE = void 0;
+exports.pulseTheme = pulseTheme;
+/**
+ * Categorical ramp for multi-segment marks (donut slices, area legend).
+ * Index 0 is the primary green; cycle for additional series. Mirrors the
+ * storyboard's "changes by area" colors.
+ */
+exports.PULSE_PALETTE = [
+    "#2ea043", // green (libavcodec)
+    "#238636", // dark green (libavformat)
+    "#3fb950", // bright green (libavfilter)
+    "#d29922", // amber (doc)
+    "#8957e5", // violet (tests)
+    "#6e7681", // grey (other)
+];
+const PULSE_DARK = {
+    canvas: "#0d1117",
+    card: "#161b22",
+    border: "#30363d",
+    borderAlpha: 1,
+    eyebrow: "#3fb950",
+    title: "#f0f6fc",
+    subtitle: "#8b949e",
+    label: "#c9d1d9",
+    muted: "#8b949e",
+    primary: "#238636",
+    primaryBright: "#3fb950",
+    positive: "#3fb950",
+    negative: "#f85149",
+    grid: "#21262d",
+    gridAlpha: 1,
+    scatterDark: ["#161b22", "#1c2128", "#21262d", "#272e36"],
+    scatterGreen: ["#238636", "#2ea043", "#196c2e"],
+    cornerRadius: 0.06,
+};
+exports.PULSE_PRESETS = {
+    dark: PULSE_DARK,
+};
+/** Resolve a preset id to its theme (defaults to `dark`). */
+function pulseTheme(preset) {
+    return exports.PULSE_PRESETS[preset !== null && preset !== void 0 ? preset : "dark"];
+}

package/dist/m0saic/hero/ffmpeg-pulse/_shared/scatter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ============================================================================
+ * hero/ffmpeg-pulse — background scatter (loads the shipped layout)
+ * ============================================================================
+ *
+ * The signature backdrop: a field of dark rounded squares with the occasional
+ * green accent, behind every beat. The geometry is NOT generated — it's the
+ * HUMAN-TRACED scatter shipped as a sidecar `.m0p` (`scatter-layout.m0p`, the
+ * sandbox-approved desktop trace + cover-fit square/mobile derivations, each
+ * variant carrying per-tile fill colors). At render the loader:
+ *   1. picks the variant matching the canvas aspect,
+ *   2. scales its tiles to the actual render dims,
+ *   3. paints each as a rounded `makeColorTile` of its stored fill color,
+ *   4. packs them into `placeRects` layers (a valid overlay base each).
+ *
+ * Returns per-layer Nodes so the chrome can nest its content as the frontmost
+ * child over the backdrop ({@link pulseChrome} `scatter` opt). Resolution is
+ * baked per render (the px are scaled from the variant's native size), the
+ * deliberate trade for matching the approved trace exactly.
+ * ============================================================================
+ */
+import { type EaseName } from "@m0saic/template-utils";
+import { type M0pFile } from "@m0saic/dsl-file-formats";
+import { type Node } from "../../../alpine/_shared/alpine-card";
+export type ScatterOpts = {
+    W: number;
+    H: number;
+    /** Override the shipped scatter pack. */
+    pack?: M0pFile;
+    /** Corner radius as a fraction of the tile's shorter side (0..0.5). */
+    cornerRadius?: number;
+    /**
+     * Rank-set reveal: stagger each tile's fade-in by its rank over `spanSec`,
+     * each tile fading over `tileSec`. Order is a deterministic sweep (default
+     * top-left → bottom-right by x+y; `"random"` for a seeded sparkle). Omitted →
+     * tiles are static (no per-tile animation).
+     */
+    reveal?: {
+        startSec: number;
+        spanSec: number;
+        tileSec: number;
+        order?: "sweep" | "random" | "horizontal";
+        ease?: EaseName;
+    };
+};
+/**
+ * Build the scatter as per-layer Nodes (one per `placeRects` layer, each a
+ * single split → a valid overlay base). Spread into `overlay([...layers, top])`
+ * so caller content nests over the backdrop. Returns `[]` for degenerate dims.
+ */
+export declare function scatterLayers(opts: ScatterOpts): Node[];
+/** The scatter composed into a single full-canvas Node (standalone backdrop).
+ *  EMPTY when nothing is emitted. */
+export declare function scatterNode(opts: ScatterOpts): Node;