@cratis/cast 0.0.1 → 0.2.0

package/site/scripts/event-board.ts

@@ -0,0 +1,403 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// Generative Event Modeling board for the hero.
+// Blue commands fire as they cross the "now" line, append orange events, and the
+// events feed green read models. Canvas 2D, DPR aware, paused when not visible.
+import { motionReduced, onMotionChange } from '../lib/motion';
+
+type Kind = 'command' | 'event' | 'view';
+type Card = {
+    id: number;
+    kind: Kind;
+    label: string;
+    band: number;
+    x: number; // world x of the left edge
+    row: 0 | 1; // 0 = command/view row, 1 = event row
+    /** Time (ms) the card became active; Infinity = not yet. */
+    activeAt: number;
+    inputs: Card[];
+};
+type Edge = { from: Card; to: Card };
+
+const COLORS: Record<Kind, { base: string; soft: string; rgb: string }> = {
+    command: { base: '#5b86f2', soft: '#a3bbf8', rgb: '91,134,242' },
+    event: { base: '#f2994a', soft: '#f8bd85', rgb: '242,153,74' },
+    view: { base: '#2dd4bf', soft: '#8eeadc', rgb: '45,212,191' },
+};
+
+/** Real names for the cards: [command, event] pairs and read models, passed in from the page. */
+export type BoardLabels = { flows: [string, string][]; views: string[] };
+const FALLBACK: BoardLabels = { flows: [['MergePullRequest', 'PullRequestMerged']], views: ['Profile.Now'] };
+
+const SPEED = 16; // px per second of world drift
+const PULSE_MS = 700;
+const NOW_X = 0.86; // fraction of width
+
+export function mountEventBoard(canvas: HTMLCanvasElement, host: HTMLElement, labels: BoardLabels = FALLBACK): () => void {
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return () => undefined;
+    const FLOWS = labels.flows.length ? labels.flows : FALLBACK.flows;
+    const VIEWS = labels.views.length ? labels.views : FALLBACK.views;
+
+    let dpr = 1;
+    let W = 0;
+    let H = 0;
+    let cardW = 96;
+    let cardH = 56;
+    let bands: { top: number; depth: number }[] = [];
+
+    let cards: Card[] = [];
+    let edges: Edge[] = [];
+    let nextId = 0;
+    let worldEnd = 0; // world x where generation continues
+    let lastEventsByBand: Card[][] = [];
+
+    let t = 0; // world scroll offset (px)
+    let now = 0; // ms clock that only advances while running
+    let raf = 0;
+    let running = false;
+    let visible = true;
+    let last = 0;
+
+    const pointer = { x: -9999, y: -9999, px: 0, py: 0, tx: 0, ty: 0 };
+    let seed = 1337;
+    const rand = () => {
+        seed = (seed * 16807) % 2147483647;
+        return (seed - 1) / 2147483646;
+    };
+    const pick = <T,>(xs: readonly T[]): T => xs[Math.floor(rand() * xs.length)] as T;
+
+    function layout() {
+        const rect = canvas.getBoundingClientRect();
+        dpr = Math.min(window.devicePixelRatio || 1, 2);
+        W = Math.max(1, Math.round(rect.width));
+        H = Math.max(1, Math.round(rect.height));
+        canvas.width = Math.round(W * dpr);
+        canvas.height = Math.round(H * dpr);
+        cardW = Math.round(Math.min(118, Math.max(78, H * 0.115)));
+        cardH = Math.round(cardW * 0.6);
+        const rowGap = cardH * 0.95;
+        const bandH = cardH * 2 + rowGap;
+        const count = H > bandH * 2.6 ? 2 : 1;
+        const usable = H - bandH * count;
+        const gap = usable / (count + 1);
+        bands = Array.from({ length: count }, (_, i) => ({ top: gap * (i + 1) + bandH * i, depth: i === 0 ? 0.6 : 1 }));
+    }
+
+    function rowY(card: Card) {
+        const band = bands[card.band] ?? bands[0]!;
+        const rowGap = cardH * 0.95;
+        return band.top + (card.row === 1 ? cardH + rowGap : 0);
+    }
+
+    function addCard(kind: Kind, label: string, band: number, x: number, row: 0 | 1, inputs: Card[] = []): Card {
+        const card: Card = { id: nextId++, kind, label, band, x, row, activeAt: Number.POSITIVE_INFINITY, inputs };
+        cards.push(card);
+        for (const from of inputs) edges.push({ from, to: card });
+        return card;
+    }
+
+    function generateUntil(limit: number) {
+        while (worldEnd < limit) {
+            for (let b = 0; b < bands.length; b++) {
+                const jitter = (rand() - 0.5) * cardW * 0.5;
+                const x = worldEnd + jitter + b * cardW * 0.55;
+                const recent = lastEventsByBand[b] ?? (lastEventsByBand[b] = []);
+                if (recent.length >= 2 && rand() < 0.42) {
+                    const inputs = recent.slice(-1 - Math.floor(rand() * 2));
+                    addCard('view', pick(VIEWS), b, x, 0, inputs);
+                    recent.length = 0;
+                } else {
+                    const [command, event] = pick(FLOWS);
+                    const cmd = addCard('command', command, b, x, 0);
+                    const ev = addCard('event', event, b, x + cardW * 0.42, 1, [cmd]);
+                    recent.push(ev);
+                    if (recent.length > 4) recent.shift();
+                }
+            }
+            worldEnd += cardW * (1.32 + rand() * 0.5);
+        }
+    }
+
+    function reset() {
+        cards = [];
+        edges = [];
+        lastEventsByBand = [];
+        nextId = 0;
+        seed = 1337;
+        worldEnd = -cardW * 2;
+        t = 0;
+        generateUntil(W + cardW * 4);
+        // Everything already left of "now" is history: active from the start.
+        settle(Number.NEGATIVE_INFINITY);
+    }
+
+    const screenX = (c: Card, parallax: number) => c.x - t + parallax;
+
+    /** Propagates activation: crossing "now" fires commands, which drive events, which drive views. */
+    function settle(at: number) {
+        const nowLine = W * NOW_X;
+        for (const c of cards) {
+            if (c.activeAt !== Number.POSITIVE_INFINITY) continue;
+            if (c.kind === 'command' && c.x - t + cardW * 0.5 < nowLine) c.activeAt = at;
+        }
+        // Two passes reach views fed by events fed by commands.
+        for (let pass = 0; pass < 2; pass++) {
+            for (const c of cards) {
+                if (c.kind === 'command' || c.activeAt !== Number.POSITIVE_INFINITY || !c.inputs.length) continue;
+                const ready = Math.max(...c.inputs.map((i) => i.activeAt));
+                if (ready === Number.POSITIVE_INFINITY) continue;
+                if (c.kind === 'view' && c.x - t + cardW * 0.5 > nowLine) continue;
+                c.activeAt = ready === Number.NEGATIVE_INFINITY ? ready : Math.max(ready, at) + PULSE_MS;
+            }
+        }
+    }
+
+    function roundRect(x: number, y: number, w: number, h: number, r: number) {
+        ctx!.beginPath();
+        ctx!.roundRect(x, y, w, h, r);
+    }
+
+    function edgePath(e: Edge, pA: number, pB: number) {
+        const ax = screenX(e.from, pA) + cardW / 2;
+        const bx = screenX(e.to, pB) + cardW / 2;
+        const fromBelow = e.from.row === 0; // command -> event goes down; event -> view goes up
+        const ay = rowY(e.from) + (fromBelow ? cardH : 0);
+        const by = rowY(e.to) + (fromBelow ? 0 : cardH);
+        const my = (ay + by) / 2;
+        return { ax, ay, bx, by, c1x: ax, c1y: my, c2x: bx, c2y: my };
+    }
+
+    const bez = (p0: number, p1: number, p2: number, p3: number, s: number) => {
+        const u = 1 - s;
+        return u * u * u * p0 + 3 * u * u * s * p1 + 3 * u * s * s * p2 + s * s * s * p3;
+    };
+
+    function draw(static_ = false) {
+        // Hairlines follow the theme: white on ink, ink on paper.
+        const ink = document.documentElement.dataset['theme'] === 'light' ? '20,22,30' : '255,255,255';
+        ctx!.setTransform(dpr, 0, 0, dpr, 0, 0);
+        ctx!.clearRect(0, 0, W, H);
+        const nowLine = W * NOW_X;
+
+        // Timeline ticks drifting with the world.
+        const tick = cardW * 0.75;
+        ctx!.lineWidth = 1;
+        for (let x = -((t % tick) + tick); x < W + tick; x += tick) {
+            ctx!.strokeStyle = `rgba(${ink},0.035)`;
+            ctx!.beginPath();
+            ctx!.moveTo(Math.round(x) + 0.5, 0);
+            ctx!.lineTo(Math.round(x) + 0.5, H);
+            ctx!.stroke();
+        }
+        // Swimlane guides.
+        for (const band of bands) {
+            for (const row of [0, 1]) {
+                const y = band.top + (row ? cardH * 1.95 : 0) + cardH / 2;
+                ctx!.strokeStyle = `rgba(${ink},0.045)`;
+                ctx!.setLineDash([2, 6]);
+                ctx!.beginPath();
+                ctx!.moveTo(0, Math.round(y) + 0.5);
+                ctx!.lineTo(W, Math.round(y) + 0.5);
+                ctx!.stroke();
+                ctx!.setLineDash([]);
+            }
+        }
+
+        // "now" line.
+        const grad = ctx!.createLinearGradient(0, 0, 0, H);
+        grad.addColorStop(0, 'rgba(242,153,74,0)');
+        grad.addColorStop(0.5, 'rgba(242,153,74,0.35)');
+        grad.addColorStop(1, 'rgba(242,153,74,0)');
+        ctx!.strokeStyle = grad;
+        ctx!.beginPath();
+        ctx!.moveTo(Math.round(nowLine) + 0.5, 0);
+        ctx!.lineTo(Math.round(nowLine) + 0.5, H);
+        ctx!.stroke();
+        ctx!.font = '500 10px "JetBrains Mono Variable", ui-monospace, monospace';
+        ctx!.fillStyle = 'rgba(248,189,133,0.55)';
+        ctx!.fillText('now ▸ append', nowLine + 8, (bands[0]?.top ?? 40) - 14);
+
+        const par = (band: number) => {
+            const depth = bands[band]?.depth ?? 1;
+            return { x: pointer.px * depth, y: pointer.py * depth };
+        };
+
+        // Edges.
+        for (const e of edges) {
+            const pa = par(e.from.band).x;
+            const pb = par(e.to.band).x;
+            const p = edgePath(e, pa, pb);
+            if (Math.max(p.ax, p.bx) < -cardW || Math.min(p.ax, p.bx) > W + cardW) continue;
+            const py = par(e.to.band).y;
+            const active = e.to.activeAt <= now;
+            ctx!.strokeStyle = active ? `rgba(${COLORS[e.to.kind].rgb},0.28)` : `rgba(${ink},0.07)`;
+            ctx!.lineWidth = 1;
+            ctx!.beginPath();
+            ctx!.moveTo(p.ax, p.ay + py);
+            ctx!.bezierCurveTo(p.c1x, p.c1y + py, p.c2x, p.c2y + py, p.bx, p.by + py);
+            ctx!.stroke();
+
+            // Travelling pulse while the target is being activated.
+            const start = e.to.activeAt - PULSE_MS;
+            if (!static_ && Number.isFinite(e.to.activeAt) && now >= start && now < e.to.activeAt) {
+                const s = (now - start) / PULSE_MS;
+                const x = bez(p.ax, p.c1x, p.c2x, p.bx, s);
+                const y = bez(p.ay, p.c1y, p.c2y, p.by, s) + py;
+                const g = ctx!.createRadialGradient(x, y, 0, x, y, 10);
+                g.addColorStop(0, `rgba(${COLORS[e.to.kind].rgb},0.95)`);
+                g.addColorStop(1, `rgba(${COLORS[e.to.kind].rgb},0)`);
+                ctx!.fillStyle = g;
+                ctx!.beginPath();
+                ctx!.arc(x, y, 10, 0, Math.PI * 2);
+                ctx!.fill();
+            }
+        }
+
+        // Cards.
+        for (const c of cards) {
+            const p = par(c.band);
+            const x = screenX(c, p.x);
+            if (x > W + cardW || x < -cardW * 1.5) continue;
+            const y = rowY(c) + p.y;
+            const col = COLORS[c.kind];
+            const active = c.activeAt <= now;
+            const age = active ? now - c.activeAt : 0;
+            const flash = active && Number.isFinite(c.activeAt) ? Math.max(0, 1 - age / 1400) : 0;
+            const dx = pointer.x - (x + cardW / 2);
+            const dy = pointer.y - (y + cardH / 2);
+            const near = Math.max(0, 1 - Math.hypot(dx, dy) / 240);
+
+            ctx!.save();
+            if (flash > 0 || near > 0.2) {
+                ctx!.shadowColor = `rgba(${col.rgb},${0.55 * Math.max(flash, near * 0.6)})`;
+                ctx!.shadowBlur = 24;
+            }
+            roundRect(x, y, cardW, cardH, 7);
+            if (active) {
+                ctx!.fillStyle = `rgba(${col.rgb},${0.1 + 0.16 * flash + 0.08 * near})`;
+                ctx!.fill();
+                ctx!.restore();
+                ctx!.strokeStyle = `rgba(${col.rgb},${0.42 + 0.4 * flash + 0.3 * near})`;
+                ctx!.lineWidth = 1;
+                roundRect(x + 0.5, y + 0.5, cardW - 1, cardH - 1, 7);
+                ctx!.stroke();
+                // Sticky-note tab.
+                ctx!.fillStyle = `rgba(${col.rgb},${0.75 + 0.25 * flash})`;
+                ctx!.fillRect(x + 9, y + 9, 10, 3);
+            } else {
+                ctx!.restore();
+                ctx!.setLineDash([3, 4]);
+                ctx!.strokeStyle = `rgba(${col.rgb},${0.16 + 0.25 * near})`;
+                roundRect(x + 0.5, y + 0.5, cardW - 1, cardH - 1, 7);
+                ctx!.stroke();
+                ctx!.setLineDash([]);
+            }
+
+            // Label, clipped to the card.
+            const labelAlpha = (active ? 0.5 : 0.18) + 0.45 * Math.max(near, flash);
+            ctx!.save();
+            ctx!.beginPath();
+            ctx!.rect(x + 6, y, cardW - 12, cardH);
+            ctx!.clip();
+            ctx!.fillStyle = `rgba(${col.rgb},${labelAlpha})`;
+            const size = Math.max(7.5, Math.min(cardW / 10.5, (cardW - 18) / (c.label.length * 0.6)));
+            ctx!.font = `500 ${size.toFixed(1)}px "JetBrains Mono Variable", ui-monospace, monospace`;
+            ctx!.fillText(c.label, x + 9, y + cardH - 12);
+            ctx!.restore();
+        }
+    }
+
+    function frame(ts: number) {
+        const dt = Math.min(50, last ? ts - last : 16);
+        last = ts;
+        now += dt;
+        t += (SPEED * dt) / 1000;
+        pointer.px += (pointer.tx - pointer.px) * 0.06;
+        pointer.py += (pointer.ty - pointer.py) * 0.06;
+
+        generateUntil(t + W + cardW * 4);
+        settle(now);
+        // Cull cards that drifted off the left edge (keeping any still feeding visible cards).
+        if (cards.length > 160) {
+            const keep = new Set<Card>();
+            for (const c of cards) if (c.x - t > -cardW * 6) keep.add(c);
+            for (const c of [...keep]) c.inputs.forEach((i) => keep.add(i));
+            cards = cards.filter((c) => keep.has(c));
+            edges = edges.filter((e) => keep.has(e.from) && keep.has(e.to));
+        }
+        draw();
+        raf = requestAnimationFrame(frame);
+    }
+
+    function start() {
+        if (running || motionReduced() || !visible || document.hidden) return;
+        running = true;
+        last = 0;
+        raf = requestAnimationFrame(frame);
+    }
+    function stop() {
+        running = false;
+        cancelAnimationFrame(raf);
+    }
+    function renderStatic() {
+        stop();
+        draw(true);
+    }
+
+    layout();
+    reset();
+    if (motionReduced()) renderStatic();
+    else start();
+    host.dataset['boardReady'] = 'true';
+
+    const ro = new ResizeObserver(() => {
+        const prevW = W;
+        const prevH = H;
+        layout();
+        if (Math.abs(prevH - H) > 40 || Math.abs(prevW - W) > 40) reset();
+        if (!running) draw(true);
+    });
+    ro.observe(canvas);
+
+    const io = new IntersectionObserver(([entry]) => {
+        visible = !!entry?.isIntersecting;
+        if (visible) start();
+        else stop();
+    });
+    io.observe(canvas);
+
+    const onVisibility = () => (document.hidden ? stop() : start());
+    document.addEventListener('visibilitychange', onVisibility);
+    const offMotion = onMotionChange((reduced) => (reduced ? renderStatic() : start()));
+    const onTheme = () => !running && draw(true);
+    document.addEventListener('theme:change', onTheme);
+
+    host.addEventListener(
+        'pointermove',
+        (e: PointerEvent) => {
+            const r = canvas.getBoundingClientRect();
+            pointer.x = e.clientX - r.left;
+            pointer.y = e.clientY - r.top;
+            pointer.tx = ((e.clientX - r.left) / r.width - 0.5) * -18;
+            pointer.ty = ((e.clientY - r.top) / r.height - 0.5) * -10;
+            if (!running) draw(true);
+        },
+        { passive: true },
+    );
+    host.addEventListener('pointerleave', () => {
+        pointer.x = pointer.y = -9999;
+        pointer.tx = pointer.ty = 0;
+        if (!running) draw(true);
+    });
+
+    return () => {
+        stop();
+        ro.disconnect();
+        io.disconnect();
+        document.removeEventListener('visibilitychange', onVisibility);
+        offMotion();
+        document.removeEventListener('theme:change', onTheme);
+    };
+}

package/site/scripts/event-model.ts

@@ -0,0 +1,155 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// Event Modeling board: highlight a card's flow on hover/focus/click, step through, or play.
+import { disposer } from '../lib/lifecycle';
+
+type CardData = { id: string; kind: string; name: string; source: string; note: string };
+type StepData = { title: string; text: string; cards: string[] };
+const KIND = { ui: 'Screen', command: 'Command', event: 'Event', view: 'Read model' } as Record<string, string>;
+const STEP_MS = 2600;
+
+export function initEventModel(): (() => void) | void {
+    const root = document.querySelector<HTMLElement>('[data-model]');
+    const json = document.querySelector<HTMLScriptElement>('[data-model-json]');
+    if (!root || !json) return;
+    const data = JSON.parse(json.textContent ?? '{}') as { cards: CardData[]; steps: StepData[]; root: string };
+    const cards = new Map(data.cards.map((c) => [c.id, c]));
+    const cardEls = [...root.querySelectorAll<HTMLButtonElement>('[data-card]')];
+    const edgeEls = [...root.querySelectorAll<SVGPathElement>('.edge')];
+    const stepEls = [...root.querySelectorAll<HTMLButtonElement>('[data-step]')];
+    const meta = root.querySelector<HTMLElement>('[data-model-detail-meta]');
+    const text = root.querySelector<HTMLElement>('[data-model-detail-text]');
+    const play = root.querySelector<HTMLButtonElement>('[data-model-play]');
+    const playLabel = root.querySelector<HTMLElement>('[data-model-play-label]');
+    const reset = root.querySelector<HTMLButtonElement>('[data-model-reset]');
+    const scroller = root.querySelector<HTMLElement>('[data-model-scroll]');
+    const initial = { meta: meta?.textContent ?? '', text: text?.textContent ?? '' };
+    const d = disposer();
+
+    let pinned: { type: 'card' | 'step'; key: string | number } | null = null;
+    let timer = 0;
+    let playing = false;
+
+    const light = (ids: Set<string>) => {
+        root.toggleAttribute('data-focus', ids.size > 0);
+        cardEls.forEach((el) => el.toggleAttribute('data-lit', ids.has(el.dataset['card'] ?? '')));
+        edgeEls.forEach((el) => el.toggleAttribute('data-lit', ids.has(el.dataset['from'] ?? '') && ids.has(el.dataset['to'] ?? '')));
+        if (reset) reset.hidden = ids.size === 0;
+    };
+    const detail = (metaText: string, body: string, href?: string) => {
+        if (meta) {
+            meta.replaceChildren(metaText);
+            if (href) {
+                const a = document.createElement('a');
+                a.href = href;
+                a.rel = 'noopener';
+                a.className = 'ml-2 underline decoration-line-strong hover:text-fg';
+                a.textContent = href.slice(data.root.length + 1);
+                meta.append(a);
+            }
+        }
+        if (text) text.textContent = body;
+    };
+    const markStep = (i: number | null) => stepEls.forEach((el, j) => el.setAttribute('aria-pressed', String(i === j)));
+
+    const showCard = (id: string) => {
+        const card = cards.get(id);
+        if (!card) return;
+        const ids = new Set<string>([id]);
+        for (const s of data.steps) if (s.cards.includes(id)) s.cards.forEach((c) => ids.add(c));
+        light(ids);
+        markStep(null);
+        detail(`${KIND[card.kind] ?? card.kind} · ${card.name} ·`, card.note, `${data.root}/${card.source}`);
+    };
+    const showStep = (i: number) => {
+        const step = data.steps[i];
+        if (!step) return;
+        light(new Set(step.cards));
+        markStep(i);
+        detail(`Step ${i + 1} of ${data.steps.length} · ${step.title}`, step.text);
+        // Keep the lit cards in view when the board scrolls.
+        const first = cardEls.find((el) => el.dataset['card'] === step.cards[0]);
+        const last = cardEls.find((el) => el.dataset['card'] === step.cards[step.cards.length - 1]);
+        if (scroller && first && last && scroller.scrollWidth > scroller.clientWidth) {
+            const mid = (first.offsetLeft + last.offsetLeft + last.offsetWidth) / 2;
+            scroller.scrollTo({ left: mid - scroller.clientWidth / 2, behavior: 'smooth' });
+        }
+    };
+    const clear = () => {
+        light(new Set());
+        markStep(null);
+        detail(initial.meta, initial.text);
+    };
+    const restore = () => {
+        if (playing) return;
+        if (!pinned) clear();
+        else if (pinned.type === 'card') showCard(String(pinned.key));
+        else showStep(Number(pinned.key));
+    };
+
+    const stop = () => {
+        playing = false;
+        window.clearTimeout(timer);
+        play?.setAttribute('aria-pressed', 'false');
+        root.querySelector('[data-icon-play]')?.classList.remove('hidden');
+        root.querySelector('[data-icon-pause]')?.classList.add('hidden');
+        if (playLabel) playLabel.textContent = 'Play the flow';
+    };
+    const run = (i: number) => {
+        if (i >= data.steps.length) {
+            stop();
+            pinned = { type: 'step', key: data.steps.length - 1 };
+            return;
+        }
+        showStep(i);
+        timer = window.setTimeout(() => run(i + 1), STEP_MS);
+    };
+    const start = () => {
+        playing = true;
+        play?.setAttribute('aria-pressed', 'true');
+        root.querySelector('[data-icon-play]')?.classList.add('hidden');
+        root.querySelector('[data-icon-pause]')?.classList.remove('hidden');
+        if (playLabel) playLabel.textContent = 'Pause';
+        run(0);
+    };
+
+    for (const el of cardEls) {
+        const id = el.dataset['card'] ?? '';
+        d.on(el, 'pointerenter', () => !playing && showCard(id));
+        d.on(el, 'pointerleave', restore);
+        d.on(el, 'focus', () => !playing && showCard(id));
+        d.on(el, 'blur', restore);
+        d.on(el, 'click', () => {
+            stop();
+            pinned = pinned?.type === 'card' && pinned.key === id ? null : { type: 'card', key: id };
+            restore();
+        });
+    }
+    stepEls.forEach((el, i) =>
+        d.on(el, 'click', () => {
+            stop();
+            pinned = pinned?.type === 'step' && pinned.key === i ? null : { type: 'step', key: i };
+            restore();
+        }),
+    );
+    if (play) d.on(play, 'click', () => (playing ? stop() : start()));
+    if (reset)
+        d.on(reset, 'click', () => {
+            stop();
+            pinned = null;
+            clear();
+        });
+    d.on<KeyboardEvent>(root, 'keydown', (e) => {
+        if (e.key === 'Escape' && (pinned || playing)) {
+            stop();
+            pinned = null;
+            clear();
+        }
+    });
+
+    return () => {
+        stop();
+        d.dispose();
+    };
+}

package/site/scripts/heatmap.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// Contribution heatmap: fill-in on first view, pointer/keyboard tooltip, scroll to "now".
+import { motionReduced } from '../lib/motion';
+import { disposer } from '../lib/lifecycle';
+
+const fmt = new Intl.NumberFormat('en-US');
+const dayLabel = (date: string) =>
+    new Date(`${date}T00:00:00Z`).toLocaleDateString('en-US', { weekday: 'short', day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC' });
+const describe = (cell: HTMLElement) => {
+    const n = Number(cell.dataset['n']);
+    return `${n === 0 ? 'No' : fmt.format(n)} event${n === 1 ? '' : 's'} · ${dayLabel(cell.dataset['d'] ?? '')}`;
+};
+
+export function initHeatmap(): (() => void) | void {
+    const root = document.querySelector<HTMLElement>('[data-heatmap]');
+    const grid = root?.querySelector<HTMLElement>('[data-heatmap-grid]');
+    const tip = document.querySelector<HTMLElement>('[data-heatmap-tip]');
+    const keys = root?.querySelector<HTMLElement>('[data-heatmap-keys]');
+    const live = root?.querySelector<HTMLElement>('[data-heatmap-live]');
+    const scroller = root?.querySelector<HTMLElement>('[data-heatmap-scroll]');
+    if (!root || !grid || !tip) return;
+    const d = disposer();
+    const cells = [...grid.querySelectorAll<HTMLElement>('.c')];
+
+    // Most recent weeks are on the right; start there on narrow screens.
+    if (scroller) scroller.scrollLeft = scroller.scrollWidth;
+
+    if (motionReduced() || !('IntersectionObserver' in window)) {
+        root.classList.add('filled');
+    } else {
+        const io = new IntersectionObserver(
+            ([entry]) => {
+                if (!entry?.isIntersecting) return;
+                root.classList.add('filled');
+                io.disconnect();
+            },
+            { threshold: 0.25 },
+        );
+        io.observe(grid);
+        d.add(() => io.disconnect());
+    }
+
+    let current: HTMLElement | null = null;
+    const show = (cell: HTMLElement | null) => {
+        current?.removeAttribute('data-on');
+        current = cell;
+        if (!cell) {
+            tip.hidden = true;
+            return;
+        }
+        cell.setAttribute('data-on', '');
+        const r = cell.getBoundingClientRect();
+        tip.textContent = describe(cell);
+        tip.hidden = false;
+        const half = tip.offsetWidth / 2 + 8;
+        tip.style.left = `${Math.min(window.innerWidth - half, Math.max(half, r.left + r.width / 2))}px`;
+        tip.style.top = `${r.top}px`;
+    };
+
+    d.on<PointerEvent>(grid, 'pointerover', (e) => {
+        const cell = (e.target as Element).closest<HTMLElement>('.c');
+        if (cell) show(cell);
+    });
+    d.on(grid, 'pointerleave', () => show(null));
+    d.on(window, 'scroll', () => current && document.activeElement !== keys && show(null), { passive: true });
+
+    if (keys) {
+        let index = cells.length - 1;
+        const announce = () => {
+            const cell = cells[index];
+            if (!cell) return;
+            cell.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+            show(cell);
+            if (live) live.textContent = describe(cell);
+        };
+        d.on(keys, 'focus', announce);
+        d.on(keys, 'blur', () => show(null));
+        d.on<KeyboardEvent>(keys, 'keydown', (e) => {
+            const step: Record<string, number> = { ArrowLeft: -7, ArrowRight: 7, ArrowUp: -1, ArrowDown: 1, Home: -Infinity, End: Infinity };
+            const s = step[e.key];
+            if (s === undefined) return;
+            e.preventDefault();
+            index = Number.isFinite(s) ? Math.min(cells.length - 1, Math.max(0, index + s)) : s < 0 ? 0 : cells.length - 1;
+            announce();
+        });
+    }
+
+    return () => {
+        show(null);
+        d.dispose();
+    };
+}