headreel 1.0.0

package/dist/core/data/errors.js

@@ -0,0 +1,12 @@
+/** A failure fetching GitHub data. The run fails and the existing banner stays. */
+export class DataError extends Error {
+    code;
+    /** When `code` is `rate_limited`: time at which a retry may succeed. */
+    retryAt;
+    constructor(code, message, retryAt) {
+        super(message);
+        this.name = 'DataError';
+        this.code = code;
+        this.retryAt = retryAt;
+    }
+}

package/dist/core/data/fixture.js

@@ -0,0 +1,18 @@
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+/**
+ * Loads offline data for `--fixture`. The file holds the style's normalized
+ * data (not a raw API response) plus the profile, validated against `schema`.
+ */
+export async function loadFixture(path, schema) {
+    const raw = JSON.parse(await readFile(path, 'utf8'));
+    const fixtureSchema = z.object({
+        profile: z.object({ login: z.string().min(1), name: z.string().min(1) }),
+        data: schema,
+    });
+    const parsed = fixtureSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Invalid fixture ${path}:\n${z.prettifyError(parsed.error)}`);
+    }
+    return parsed.data;
+}

package/dist/core/data/graphql.js

@@ -0,0 +1,65 @@
+import { DataError } from './errors.js';
+const ENDPOINT = 'https://api.github.com/graphql';
+/**
+ * Creates a GitHub GraphQL client. Does not retry: a failed run keeps the
+ * existing banner, and the next scheduled run tries again.
+ */
+export function createGraphQLClient({ token, fetch: fetchFn = fetch, }) {
+    return async (query, variables = {}) => {
+        let res;
+        try {
+            res = await fetchFn(ENDPOINT, {
+                method: 'POST',
+                headers: {
+                    authorization: `bearer ${token}`,
+                    'content-type': 'application/json',
+                    'user-agent': 'headreel',
+                },
+                body: JSON.stringify({ query, variables }),
+            });
+        }
+        catch (err) {
+            throw new DataError('api', `GitHub API request failed: ${err.message}`);
+        }
+        const rateLimit = rateLimitError(res);
+        if (rateLimit)
+            throw rateLimit;
+        if (res.status === 401) {
+            throw new DataError('auth', 'GitHub rejected the token (401). Check that it is valid.');
+        }
+        if (!res.ok) {
+            throw new DataError('api', `GitHub API returned ${res.status} ${res.statusText}`);
+        }
+        const body = (await res.json());
+        const first = body.errors?.[0];
+        if (first) {
+            if (first.type === 'NOT_FOUND')
+                throw new DataError('not_found', first.message);
+            if (first.type === 'RATE_LIMITED')
+                throw new DataError('rate_limited', first.message);
+            throw new DataError('api', `GitHub API error: ${first.message}`);
+        }
+        if (!body.data)
+            throw new DataError('api', 'GitHub API returned no data');
+        return body.data;
+    };
+}
+/** Primary limit: remaining is 0. Secondary limit: 403/429, possibly with retry-after. */
+function rateLimitError(res) {
+    const remaining = res.headers.get('x-ratelimit-remaining');
+    const reset = res.headers.get('x-ratelimit-reset');
+    const retryAfter = res.headers.get('retry-after');
+    if (retryAfter !== null && (res.status === 403 || res.status === 429)) {
+        const at = new Date(Date.now() + Number(retryAfter) * 1000);
+        return new DataError('rate_limited', `GitHub secondary rate limit hit; retry after ${retryAfter}s`, at);
+    }
+    if (remaining === '0') {
+        const at = reset !== null ? new Date(Number(reset) * 1000) : undefined;
+        const when = at ? ` until ${at.toISOString()}` : '';
+        return new DataError('rate_limited', `GitHub rate limit exhausted${when}`, at);
+    }
+    if (res.status === 429) {
+        return new DataError('rate_limited', 'GitHub rate limit hit (429)');
+    }
+    return undefined;
+}

package/dist/core/data/profile.js

@@ -0,0 +1,13 @@
+const QUERY = /* GraphQL */ `
+  query Profile($login: String!) {
+    user(login: $login) {
+      login
+      name
+    }
+  }
+`;
+export async function fetchProfile(client, login) {
+    const { user } = await client(QUERY, { login });
+    const name = user.name?.trim();
+    return { login: user.login, name: name ? name : user.login };
+}

package/dist/core/data/token.js

@@ -0,0 +1,26 @@
+import { execFileSync } from 'node:child_process';
+import { DataError } from './errors.js';
+/**
+ * Resolves a GitHub token: --token, then GITHUB_TOKEN, then `gh auth token`.
+ * GitHub's GraphQL API requires authentication, so no token is an error.
+ */
+export function resolveToken({ flag, env = process.env, ghToken = readGhToken, } = {}) {
+    const token = flag?.trim() || env.GITHUB_TOKEN?.trim() || ghToken();
+    if (!token) {
+        throw new DataError('auth', 'No GitHub token found. Pass --token, set GITHUB_TOKEN, or log in with `gh auth login`.');
+    }
+    return token;
+}
+function readGhToken() {
+    try {
+        const out = execFileSync('gh', ['auth', 'token'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        }).trim();
+        return out || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/encode/gif.js

@@ -0,0 +1,92 @@
+import * as gifencModule from 'gifenc';
+// Node loads gifenc's CommonJS build (functions live on the default export);
+// ESM-aware tools such as vitest load its ESM build (named exports).
+const gifenc = typeof gifencModule.quantize === 'function'
+    ? gifencModule
+    : gifencModule.default;
+const { GIFEncoder, quantize, applyPalette } = gifenc;
+/** Number of frames sampled to build the shared palette. */
+const PALETTE_SAMPLES = 6;
+/** 255 real colors; the last global palette slot is the transparent index. */
+const COLORS = 255;
+const TRANSPARENT = COLORS;
+/** Peak-to-peak dither amplitude, per channel. About one palette step. */
+const DITHER_SPREAD = 14;
+/** GIF disposal: leave the frame in place, so transparent pixels show the previous one. */
+const DISPOSE_KEEP = 1;
+// 8x8 Bayer matrix, normalized to -0.5..0.5.
+const BAYER = (() => {
+    const m = [
+        [0, 32, 8, 40, 2, 34, 10, 42],
+        [48, 16, 56, 24, 50, 18, 58, 26],
+        [12, 44, 4, 36, 14, 46, 6, 38],
+        [60, 28, 52, 20, 62, 30, 54, 22],
+        [3, 35, 11, 43, 1, 33, 9, 41],
+        [51, 19, 59, 27, 49, 17, 57, 25],
+        [15, 47, 7, 39, 13, 45, 5, 37],
+        [63, 31, 55, 23, 61, 29, 53, 21],
+    ];
+    return m.flat().map((v) => (v + 0.5) / 64 - 0.5);
+})();
+/**
+ * Ordered dithering. The pattern depends only on pixel position, so a pixel
+ * that does not change between frames dithers identically, which keeps the
+ * frame deltas small and avoids shimmer.
+ */
+function dither(rgba, width) {
+    const out = new Uint8ClampedArray(rgba.length);
+    for (let i = 0, p = 0; i < rgba.length; i += 4, p++) {
+        const x = p % width;
+        const y = (p - x) / width;
+        const offset = BAYER[(y & 7) * 8 + (x & 7)] * DITHER_SPREAD;
+        out[i] = rgba[i] + offset;
+        out[i + 1] = rgba[i + 1] + offset;
+        out[i + 2] = rgba[i + 2] + offset;
+        out[i + 3] = 255;
+    }
+    return out;
+}
+function buildPalette(frames, frameBytes) {
+    const step = Math.max(1, Math.floor(frames.length / PALETTE_SAMPLES));
+    const picks = frames.filter((_, i) => i % step === 0).slice(0, PALETTE_SAMPLES);
+    const sample = new Uint8ClampedArray(frameBytes * picks.length);
+    picks.forEach((data, i) => sample.set(data, i * frameBytes));
+    return quantize(sample, COLORS);
+}
+/**
+ * Encodes RGBA frames into a looping GIF: one global palette, ordered
+ * dithering, and delta frames where unchanged pixels are transparent.
+ */
+export function encodeGif(frames, spec) {
+    const { width, height } = spec;
+    const palette = buildPalette(frames, width * height * 4);
+    const globalPalette = [...palette];
+    while (globalPalette.length < TRANSPARENT)
+        globalPalette.push([0, 0, 0]);
+    globalPalette.push([0, 0, 0]);
+    const gif = GIFEncoder();
+    const delay = Math.round(1000 / spec.fps);
+    let previous;
+    for (const [i, data] of frames.entries()) {
+        const index = applyPalette(dither(data, width), palette);
+        let pixels = index;
+        if (previous) {
+            pixels = new Uint8Array(index);
+            for (let p = 0; p < pixels.length; p++) {
+                if (index[p] === previous[p])
+                    pixels[p] = TRANSPARENT;
+            }
+        }
+        gif.writeFrame(pixels, width, height, {
+            ...(i === 0 ? { palette: globalPalette } : {}),
+            delay,
+            repeat: 0,
+            transparent: i > 0,
+            transparentIndex: TRANSPARENT,
+            dispose: DISPOSE_KEEP,
+        });
+        previous = index;
+    }
+    gif.finish();
+    return gif.bytes();
+}

package/dist/core/fonts.js

@@ -0,0 +1,22 @@
+import { GlobalFonts } from '@napi-rs/canvas';
+import { fileURLToPath } from 'node:url';
+/** Bundled fonts (OFL). Only these are used, so output never depends on system fonts. */
+const FONT_FILES = [
+    'SpaceGrotesk-Medium.ttf',
+    'SpaceGrotesk-Bold.ttf',
+    'JetBrainsMono-Regular.ttf',
+];
+// Resolves from both src/core (tsx, vitest) and dist/core (published build).
+const FONT_DIR = new URL('../../assets/fonts/', import.meta.url);
+let registered = false;
+export function registerFonts() {
+    if (registered)
+        return;
+    for (const file of FONT_FILES) {
+        const path = fileURLToPath(new URL(file, FONT_DIR));
+        if (!GlobalFonts.registerFromPath(path)) {
+            throw new Error(`Failed to register font ${path}`);
+        }
+    }
+    registered = true;
+}

package/dist/core/pipeline.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { encodeGif } from './encode/gif.js';
+import { registerFonts } from './fonts.js';
+import { createRng, hashSeed } from './prng.js';
+import { renderFrames } from './render/render.js';
+import { CANVAS } from './canvas.js';
+/** Validates raw options against the style's schema. Runs before any API call. */
+export function parseOptions(style, raw = {}) {
+    const parsed = style.options.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Invalid options for ${style.id}:\n${z.prettifyError(parsed.error)}`);
+    }
+    return parsed.data;
+}
+export async function renderBanner(style, input) {
+    const options = parseOptions(style, input.options);
+    registerFonts();
+    const rng = createRng(hashSeed(`${input.login}:${style.id}`));
+    const sketch = style.createSketch({ data: input.data, options, identity: input.identity, rng });
+    const frames = await renderFrames(sketch, { ...CANVAS, frames: style.frames });
+    return encodeGif(frames, { ...CANVAS, fps: style.fps });
+}

package/dist/core/prng.js

@@ -0,0 +1,19 @@
+/** FNV-1a 32-bit hash of a string. Used to derive seeds from login + style. */
+export function hashSeed(input) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/** mulberry32: small, fast, deterministic PRNG returning floats in [0, 1). */
+export function createRng(seed) {
+    let s = seed | 0;
+    return () => {
+        s = (s + 0x6d2b79f5) | 0;
+        let t = Math.imul(s ^ (s >>> 15), 1 | s);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/core/render/dom.js

@@ -0,0 +1,66 @@
+import { createCanvas, DOMMatrix, ImageData, Path2D } from '@napi-rs/canvas';
+import { JSDOM } from 'jsdom';
+const DOM_GLOBALS = [
+    'window',
+    'document',
+    'navigator',
+    'HTMLElement',
+    'HTMLCanvasElement',
+    'Image',
+    'Event',
+    'MouseEvent',
+    'getComputedStyle',
+    'screen',
+    'devicePixelRatio',
+    // p5 passes an AbortSignal to addEventListener; jsdom rejects Node's own.
+    'AbortController',
+    'AbortSignal',
+];
+let installed = false;
+/**
+ * Installs a jsdom window on globalThis with canvas elements backed by
+ * @napi-rs/canvas. p5 2.x draws shapes through Path2D, which node-canvas lacks.
+ * Idempotent; must run before importing p5.
+ */
+export function installDom() {
+    if (installed)
+        return;
+    const dom = new JSDOM('<!doctype html><html><body></body></html>', { pretendToBeVisual: true });
+    const win = dom.window;
+    for (const key of DOM_GLOBALS) {
+        if (win[key] !== undefined) {
+            Object.defineProperty(globalThis, key, {
+                value: win[key],
+                configurable: true,
+                writable: true,
+            });
+        }
+    }
+    const backing = new WeakMap();
+    dom.window.HTMLCanvasElement.prototype.getContext = function (type) {
+        if (type !== '2d')
+            return null;
+        let canvas = backing.get(this);
+        if (!canvas || canvas.width !== this.width || canvas.height !== this.height) {
+            canvas = createCanvas(this.width, this.height);
+            backing.set(this, canvas);
+        }
+        return canvas.getContext('2d');
+    };
+    // p5 draws offscreen layers (createGraphics) by passing their jsdom canvas
+    // element; Skia only accepts its own canvases, so swap in the backing one.
+    const ctxProto = Object.getPrototypeOf(createCanvas(1, 1).getContext('2d'));
+    const drawImage = ctxProto.drawImage;
+    ctxProto.drawImage = function (image, ...args) {
+        const source = backing.get(image) ?? image;
+        drawImage.call(this, source, ...args);
+    };
+    Object.assign(globalThis, {
+        Path2D,
+        ImageData,
+        DOMMatrix,
+        requestAnimationFrame: () => 0,
+        cancelAnimationFrame: () => { },
+    });
+    installed = true;
+}

package/dist/core/render/render.js

@@ -0,0 +1,46 @@
+import { installDom } from './dom.js';
+/** Renders every frame of a sketch headlessly and returns RGBA buffers. */
+export async function renderFrames(sketch, spec) {
+    installDom();
+    const { default: P5 } = (await import('p5/node'));
+    let frame = 0;
+    let capturing = false;
+    const instance = new P5((p) => {
+        p.setup = async () => {
+            p.pixelDensity(1);
+            p.createCanvas(spec.width, spec.height);
+            p.noLoop();
+            await sketch.setup?.(p);
+        };
+        // p5 runs one draw after setup even under noLoop(); skip it.
+        p.draw = () => {
+            if (capturing)
+                sketch.draw(p, frame, frame / spec.frames);
+        };
+    });
+    await untilIdle(instance);
+    capturing = true;
+    const ctx = instance.drawingContext;
+    const out = [];
+    for (frame = 0; frame < spec.frames; frame++) {
+        // redraw() is async in p5 2.x; not awaiting it captures blank frames.
+        await instance.redraw();
+        out.push(ctx.getImageData(0, 0, spec.width, spec.height).data);
+    }
+    instance.remove();
+    return out;
+}
+const SETUP_TIMEOUT_MS = 30_000;
+/**
+ * p5's redraw() silently does nothing until setup has finished and while a
+ * draw is in progress. Wait for both before driving frames.
+ */
+async function untilIdle(instance) {
+    const state = instance;
+    const deadline = Date.now() + SETUP_TIMEOUT_MS;
+    while (!state._setupDone || state._inUserDraw) {
+        if (Date.now() > deadline)
+            throw new Error('p5 sketch setup timed out');
+        await new Promise((r) => setImmediate(r));
+    }
+}

package/dist/styles/contribution-city/city.js

@@ -0,0 +1,123 @@
+export const LAYOUT = {
+    width: 1280,
+    height: 400,
+    /** Week column width. */
+    cell: 18,
+    /** Street between buildings. */
+    gap: 4,
+    /** Oblique offset per weekday row. */
+    depthX: 6,
+    depthY: 7,
+    /** Tallest tower, px. */
+    maxH: 150,
+    /** Ground line of the front row. */
+    baseY: 352,
+    rightMargin: 28,
+    arcs: 4,
+    arcTowers: 24,
+    arcMinWeeks: 8,
+    stars: 180,
+    grain: 2600,
+};
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/** Front-left ground corner of the whole city. */
+export function cityOrigin(weeks) {
+    const span = weeks * LAYOUT.cell + 7 * LAYOUT.depthX;
+    return { x: LAYOUT.width - span - LAYOUT.rightMargin, y: LAYOUT.baseY };
+}
+/** Screen position of the front-left ground corner for (week, weekday). */
+export function tileAt(weeks, w, d) {
+    const o = cityOrigin(weeks);
+    const depth = 6 - d;
+    return { x: o.x + w * LAYOUT.cell + depth * LAYOUT.depthX, y: o.y - depth * LAYOUT.depthY };
+}
+export function buildCity(data, rng, beacons) {
+    const between = (min, max) => min + rng() * (max - min);
+    const weeks = data.weeks.length;
+    const maxCount = Math.max(0, ...data.weeks.flat().map((d) => d.count));
+    const buildings = [];
+    data.weeks.forEach((week, w) => {
+        for (const day of week) {
+            const t = maxCount > 0 ? Math.sqrt(day.count / maxCount) : 0;
+            const h = day.count === 0 ? 0 : 6 + t * (LAYOUT.maxH - 6);
+            const b = {
+                w,
+                d: day.weekday,
+                count: day.count,
+                t,
+                h,
+                ...tileAt(weeks, w, day.weekday),
+                bw: LAYOUT.cell - LAYOUT.gap,
+                windows: [],
+                beacon: false,
+                beaconOffset: rng(),
+            };
+            if (h > 14) {
+                const rows = Math.floor((h - 8) / 6);
+                for (let r = 0; r < rows; r++) {
+                    for (let k = 0; k < 2; k++) {
+                        b.windows.push({
+                            x: 3 + k * 6,
+                            y: 6 + r * 6,
+                            lit: rng() < 0.25 + t * 0.5,
+                            cycles: rng() < 0.12 ? Math.floor(between(1, 4)) : 0,
+                            off: rng(),
+                        });
+                    }
+                }
+            }
+            buildings.push(b);
+        }
+    });
+    // Stable ranking: count, then chronological order, so ties never depend on sort internals.
+    const ranked = buildings
+        .filter((b) => b.count > 0)
+        .sort((a, b) => b.count - a.count || a.w - b.w || a.d - b.d);
+    for (const b of ranked.slice(0, beacons))
+        b.beacon = true;
+    // Back rows first, then left to right, so front towers occlude correctly.
+    buildings.sort((a, b) => a.d - b.d || a.w - b.w);
+    const stars = Array.from({ length: LAYOUT.stars }, () => ({
+        x: rng() * LAYOUT.width,
+        y: Math.pow(rng(), 1.6) * 250,
+        s: rng() < 0.08 ? 2 : 1,
+        a: between(40, 160),
+        cycles: Math.floor(between(1, 4)),
+        off: rng(),
+    }));
+    const arcs = [];
+    const towers = ranked.slice(0, LAYOUT.arcTowers);
+    if (towers.length >= 2) {
+        const pick = () => towers[Math.floor(rng() * towers.length)];
+        for (let i = 0; i < LAYOUT.arcs; i++) {
+            const a = pick();
+            let b = pick();
+            for (let tries = 0; Math.abs(a.w - b.w) < LAYOUT.arcMinWeeks && tries < 20; tries++)
+                b = pick();
+            if (a === b)
+                continue;
+            arcs.push({ a, b, off: i / LAYOUT.arcs, lift: between(40, 80) });
+        }
+    }
+    return { weeks, total: data.total, maxCount, buildings, stars, arcs, months: monthLabels(data) };
+}
+/** A label at the first week of each month; drops a partial leading month that would collide. */
+export function monthLabels(data) {
+    const months = [];
+    let last = -1;
+    data.weeks.forEach((week, w) => {
+        const first = week[0];
+        if (!first)
+            return;
+        const date = new Date(`${first.date}T00:00:00Z`);
+        const m = date.getUTCMonth();
+        if (m !== last) {
+            if (w > 0 || date.getUTCDate() <= 7)
+                months.push({ w, label: MONTHS[m] });
+            last = m;
+        }
+    });
+    if (months[0]?.w === 0 && months[1] && months[1].w < 3)
+        months.shift();
+    return months;
+}

package/dist/styles/contribution-city/index.js

@@ -0,0 +1,14 @@
+import { contributionsSchema, fetchContributions, } from '../../core/data/contributions.js';
+import { buildCity } from './city.js';
+import { options } from './options.js';
+import { createCitySketch } from './sketch.js';
+export const contributionCity = {
+    id: 'contribution-city',
+    fps: 25,
+    frames: 150,
+    data: { schema: contributionsSchema, fetch: fetchContributions },
+    options,
+    createSketch({ data, options, identity, rng }) {
+        return createCitySketch(buildCity(data, rng, options.beacons), identity, rng);
+    },
+};

package/dist/styles/contribution-city/options.js

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export const options = z
+    .object({
+    /** Number of busiest days marked with a beacon. */
+    beacons: z.coerce.number().int().min(0).max(10).default(8),
+})
+    .strict();