headreel 1.4.0 → 1.5.0

package/README.md

@@ -99,6 +99,10 @@ Empty settings do not show on the banner. Your name comes from your GitHub profi
 
 Set the style with `style: <name>` in the Action, or `--style <name>` in the command. Set an option with `options: 'accent: green'` in the Action, or `--option accent=green` in the command. For more than one option in the Action, put each on its own line.
 
+<table>
+<tr>
+<td>
+
 ### Contribution City
 
 `contribution-city`: each day of the last 12 months is one building. A taller building means more contributions. Beacons glow on your busiest days.
@@ -109,6 +113,14 @@ Set the style with `style: <name>` in the Action, or `--style <name>` in the com
 | -------- | ------- | --------------------------------------------------------------------------------------------- |
 | `accent` | `cyan`  | Color of the roofs, windows, lights and links: `cyan`, `cobalt`, `green`, `violet` or `pink`. |
 
+</td>
+</tr>
+</table>
+
+<table>
+<tr>
+<td>
+
 ### Highlights Reel
 
 `highlights-reel`: a few profile facts, each on its own card, filmed by one camera. The camera travels between the cards, pushes into your busiest week, and ends on a wide shot of the whole reel.
@@ -120,6 +132,14 @@ Set the style with `style: <name>` in the Action, or `--style <name>` in the com
 | `theme`  | `light`  | `light` or `dark`. Use `dark` if your profile is mostly viewed in GitHub dark mode.    |
 | `accent` | `cobalt` | Color of the bars, numbers and links: `cobalt`, `green`, `violet`, `orange` or `pink`. |
 
+</td>
+</tr>
+</table>
+
+<table>
+<tr>
+<td>
+
 ### Now Playing
 
 `now-playing`: a cassette deck playing the repository you committed to most in the last 30 days. The label names its language, your commit messages on it scroll across the deck's display as lyrics, and the level meter shows the month day by day. When nothing was committed in the last 30 days, the deck shows the repository you pushed to last as `LAST PLAYED`.
@@ -132,6 +152,34 @@ Set the style with `style: <name>` in the Action, or `--style <name>` in the com
 | `accent`  | `cyan`  | Display color, meter and links: `cyan`, `green` or `orange`.                                        |
 | `exclude` | empty   | Comma-separated repositories never picked, for example your profile repository: `exclude: octocat`. |
 
+</td>
+</tr>
+</table>
+
+<table>
+<tr>
+<td>
+
+### Receipt
+
+`receipt`: a thermal printer feeds out your last 12 months as a till receipt: repositories as items, contribution counts as the totals, streaks and your best day printed below, and a barcode encoding your activity week by week. The paper prints line by line, tears off, and the next receipt starts.
+
+![Receipt banner](https://raw.githubusercontent.com/arifszn/headreel/main/docs/samples/receipt.gif)
+
+| Option   | Default  | Description                                                                     |
+| -------- | -------- | ------------------------------------------------------------------------------- |
+| `theme`  | `dark`   | `dark` or `light`. Use `light` if your profile is mostly viewed in light mode.  |
+| `accent` | `cobalt` | Prompt, cursor, tagline and LED: `cobalt`, `green`, `violet`, `orange`, `pink`. |
+| `items`  | `5`      | Repositories printed as line items, `0` to `5`.                                 |
+
+</td>
+</tr>
+</table>
+
+<table>
+<tr>
+<td>
+
 ### Repo Galaxy
 
 `repo-galaxy`: your most starred repositories orbit a sun. A bigger planet has more stars, and its color is the repository's main language. Repositories you pushed to recently orbit closer to the sun.
@@ -144,6 +192,10 @@ Set the style with `style: <name>` in the Action, or `--style <name>` in the com
 | `include_forks` | `false` | Show forked repositories too.                                         |
 | `labels`        | `top3`  | `top3` names the three most starred repositories. `none` hides names. |
 
+</td>
+</tr>
+</table>
+
 ## Troubleshooting
 
 | Problem                          | Fix                                                      |

package/dist/core/data/receipt.js

@@ -0,0 +1,144 @@
+import { z } from 'zod';
+import { contributionWindow } from './contributions.js';
+// One query for the whole receipt: the 365-day calendar (TOTAL, the streaks,
+// the best day and the barcode), the per-type contribution counts, and the
+// repositories the user committed to (the line items). Field names checked
+// against the live GraphQL schema (2026-09-19).
+const QUERY = /* GraphQL */ `
+  query Receipt($login: String!, $from: DateTime!, $to: DateTime!) {
+    user(login: $login) {
+      contributionsCollection(from: $from, to: $to) {
+        contributionCalendar {
+          totalContributions
+          weeks {
+            contributionDays {
+              date
+              contributionCount
+            }
+          }
+        }
+        totalCommitContributions
+        totalPullRequestContributions
+        totalPullRequestReviewContributions
+        totalIssueContributions
+        totalRepositoryContributions
+        restrictedContributionsCount
+        commitContributionsByRepository(maxRepositories: 25) {
+          repository {
+            name
+            owner {
+              login
+            }
+            isPrivate
+            primaryLanguage {
+              name
+              color
+            }
+          }
+          contributions {
+            totalCount
+          }
+        }
+      }
+    }
+  }
+`;
+/** Line items printed, at most. */
+export const MAX_ITEMS = 5;
+/** Days in the contribution window: 364 back plus the run date. */
+export const WINDOW_DAYS = 365;
+const languageSchema = z
+    .object({
+    name: z.string().min(1),
+    /** Linguist color; null when the repo has no language or color. */
+    color: z
+        .string()
+        .regex(/^#[0-9a-fA-F]{6}$/)
+        .nullable(),
+})
+    .nullable();
+export const receiptSchema = z.object({
+    /** Fetch date (= window end), YYYY-MM-DD (UTC). */
+    asOf: z.iso.date(),
+    from: z.iso.date(),
+    to: z.iso.date(),
+    /** The calendar's total, the number the profile shows. */
+    total: z.number().int().min(0),
+    commits: z.number().int().min(0),
+    pullRequests: z.number().int().min(0),
+    reviews: z.number().int().min(0),
+    issues: z.number().int().min(0),
+    newRepos: z.number().int().min(0),
+    /** Private contributions the token could see, without any repository named. */
+    restricted: z.number().int().min(0),
+    /** Public repositories committed to, most commits first. */
+    items: z
+        .array(z.object({
+        /** A repository the user does not own prints as `owner/name`. */
+        name: z.string().min(1),
+        language: languageSchema,
+        commits: z.number().int().min(1),
+    }))
+        .max(MAX_ITEMS),
+    /** Commits summed over the private repositories, never named. */
+    privateCommits: z.number().int().min(0),
+    /** Daily counts over the window, oldest first. */
+    days: z.array(z.number().int().min(0)).length(WINDOW_DAYS),
+});
+/**
+ * The line items: public repositories by commits in the window, ties by name.
+ * Private repositories are dropped here, before ranking; their commits are
+ * summed into `privateCommits` and never named.
+ */
+export function selectItems(entries, login, cap = MAX_ITEMS) {
+    const items = [];
+    let privateCommits = 0;
+    for (const entry of entries) {
+        const { repository } = entry;
+        if (repository.isPrivate) {
+            privateCommits += entry.contributions.totalCount;
+            continue;
+        }
+        items.push({
+            name: repository.owner.login === login
+                ? repository.name
+                : `${repository.owner.login}/${repository.name}`,
+            language: repository.primaryLanguage
+                ? { name: repository.primaryLanguage.name, color: repository.primaryLanguage.color }
+                : null,
+            commits: entry.contributions.totalCount,
+        });
+    }
+    items.sort((a, b) => b.commits - a.commits || a.name.localeCompare(b.name));
+    return { items: items.slice(0, cap), privateCommits };
+}
+export async function fetchReceipt(client, login, now) {
+    const { from, to } = contributionWindow(now);
+    const { user } = await client(QUERY, {
+        login,
+        from: `${from}T00:00:00Z`,
+        to: `${to}T23:59:59Z`,
+    });
+    const cc = user.contributionsCollection;
+    // Calendar weeks are padded to full weeks; keep only the window's days.
+    const days = cc.contributionCalendar.weeks
+        .flatMap((week) => week.contributionDays)
+        .filter((day) => day.date >= from && day.date <= to)
+        .map((day) => day.contributionCount);
+    const { items, privateCommits } = selectItems(cc.commitContributionsByRepository, login);
+    return {
+        asOf: to,
+        from,
+        to,
+        total: cc.contributionCalendar.totalContributions,
+        commits: cc.totalCommitContributions,
+        pullRequests: cc.totalPullRequestContributions,
+        reviews: cc.totalPullRequestReviewContributions,
+        issues: cc.totalIssueContributions,
+        newRepos: cc.totalRepositoryContributions,
+        restricted: cc.restrictedContributionsCount,
+        items,
+        privateCommits,
+        days,
+    };
+}

package/dist/core/streaks.js

@@ -0,0 +1,38 @@
+/**
+ * Streaks and peaks over a flat array of daily contribution counts, oldest
+ * first. Shared by Highlights Reel and Receipt.
+ */
+/** Longest run of consecutive days with at least one contribution. */
+export function longestStreak(days) {
+    let best = 0;
+    let run = 0;
+    for (const count of days) {
+        run = count > 0 ? run + 1 : 0;
+        if (run > best)
+            best = run;
+    }
+    return best;
+}
+/**
+ * Consecutive active days ending on the last day, or on the day before it
+ * when the last day is still empty: a scheduled run often happens before the
+ * day's work.
+ */
+export function currentStreak(days) {
+    let end = days.length - 1;
+    if (days[end] <= 0)
+        end--;
+    let run = 0;
+    for (let i = end; i >= 0 && days[i] > 0; i--)
+        run++;
+    return run;
+}
+/** The day with the highest count, or null when every day is empty. */
+export function bestDay(days) {
+    let best = null;
+    days.forEach((count, index) => {
+        if (count > 0 && (best === null || count >= best.count))
+            best = { index, count };
+    });
+    return best;
+}

package/dist/styles/highlights-reel/palette.js

@@ -2,8 +2,9 @@ const AMBER = [232, 163, 61];
 /**
  * Accent presets, [light, dark]. Each passes 4.5:1 against its theme's desk,
  * the lowest background its small type sits on (see SPEC, Highlights Reel).
+ * Receipt shares them: its counter is this desk.
  */
-const ACCENT_VALUES = {
+export const ACCENT_VALUES = {
     cobalt: [
         [53, 88, 232],
         [123, 147, 255],

package/dist/styles/highlights-reel/reel.js

@@ -1,3 +1,4 @@
+import { longestStreak as coreLongestStreak } from '../../core/streaks.js';
 import { paletteOf } from './palette.js';
 /**
  * Where the reel lives: four cards on one desk, filmed by one camera.
@@ -54,16 +55,7 @@ const NEUTRAL = { light: [102, 106, 124], dark: [140, 146, 168] };
 const CARD_ORDER = ['contributions', 'top_repo', 'pull_requests', 'languages'];
 /** Longest run of consecutive days with at least one contribution. */
 export function longestStreak(contributions) {
-    let best = 0;
-    let run = 0;
-    for (const week of contributions.weeks) {
-        for (const day of week) {
-            run = day.count > 0 ? run + 1 : 0;
-            if (run > best)
-                best = run;
-        }
-    }
-    return best;
+    return coreLongestStreak(contributions.weeks.flat().map((day) => day.count));
 }
 /** "2026-03-28" .. "2026-04-03" -> "Mar 28 to Apr 3". */
 function dateRange(from, to) {

package/dist/styles/index.js

@@ -1,11 +1,13 @@
 import { contributionCity } from './contribution-city/index.js';
 import { highlightsReel } from './highlights-reel/index.js';
 import { nowPlaying } from './now-playing/index.js';
+import { receipt } from './receipt/index.js';
 import { repoGalaxy } from './repo-galaxy/index.js';
 /** Built-in styles, keyed by id. */
 export const styles = {
     [contributionCity.id]: contributionCity,
     [highlightsReel.id]: highlightsReel,
     [nowPlaying.id]: nowPlaying,
+    [receipt.id]: receipt,
     [repoGalaxy.id]: repoGalaxy,
 };

package/dist/styles/receipt/index.js

@@ -0,0 +1,16 @@
+import { fetchReceipt, receiptSchema } from '../../core/data/receipt.js';
+import { buildReceipt, FRAMES } from './receipt.js';
+import { options } from './options.js';
+import { paletteOf, pinnedOf } from './palette.js';
+import { createReceiptSketch } from './sketch.js';
+export const receipt = {
+    id: 'receipt',
+    fps: 25,
+    frames: FRAMES,
+    pinned: (options) => pinnedOf(paletteOf(options)),
+    data: { name: 'receipt', schema: receiptSchema, fetch: fetchReceipt },
+    options,
+    createSketch({ data, login, options, identity, rng }) {
+        return createReceiptSketch(buildReceipt(data, login, identity, options, paletteOf(options), rng), identity);
+    },
+};

package/dist/styles/receipt/options.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { MAX_ITEMS } from '../../core/data/receipt.js';
+export const THEMES = ['dark', 'light'];
+export const ACCENTS = ['cobalt', 'green', 'violet', 'orange', 'pink'];
+export const options = z
+    .object({
+    /** The counter and the printer: dark slate, or the light desk. */
+    theme: z.enum(THEMES).default('dark'),
+    /** Prompt, cursor, tagline, website and the printer LED, as Highlights Reel. */
+    accent: z.enum(ACCENTS).default('cobalt'),
+    /** Line items printed, most commits first. 0 prints the totals only. */
+    items: z.coerce.number().int().min(0).max(MAX_ITEMS).default(MAX_ITEMS),
+})
+    .strict();

package/dist/styles/receipt/palette.js

@@ -0,0 +1,48 @@
+import { ACCENT_VALUES } from '../highlights-reel/palette.js';
+const PAPER = {
+    paper: [250, 249, 245],
+    ink: [30, 30, 34],
+    fadedInk: [106, 106, 112],
+};
+const BASE = {
+    dark: {
+        ...PAPER,
+        counter: [13, 15, 23],
+        body: [28, 31, 41],
+        slot: [5, 6, 10],
+        bevel: [58, 61, 74],
+        identityInk: [238, 240, 246],
+        identityMuted: [140, 146, 168],
+        paperBorder: null,
+        shadow: 0,
+    },
+    light: {
+        ...PAPER,
+        counter: [236, 237, 241],
+        body: [201, 204, 211],
+        slot: [42, 45, 53],
+        bevel: [246, 247, 249],
+        identityInk: [11, 12, 20],
+        identityMuted: [102, 106, 124],
+        paperBorder: [11, 12, 20],
+        shadow: 0.09,
+    },
+};
+export function paletteOf(options) {
+    const [light, dark] = ACCENT_VALUES[options.accent];
+    return {
+        ...BASE[options.theme],
+        accent: options.theme === 'light' ? light : dark,
+    };
+}
+/** Flat colors the encoder keeps exact and undithered. */
+export function pinnedOf(palette) {
+    return [
+        palette.counter,
+        palette.paper,
+        palette.ink,
+        palette.fadedInk,
+        palette.body,
+        palette.accent,
+    ];
+}

package/dist/styles/receipt/receipt.js

@@ -0,0 +1,229 @@
+import { bestDay, currentStreak, longestStreak } from '../../core/streaks.js';
+import { canvasMeasure, fitLine } from '../../core/text.js';
+/**
+ * What the printer prints. The whole receipt is one list of text lines plus a
+ * tail (barcode, footer, tear line); the sketch rasterizes them into one
+ * offscreen strip and feeds it out of the slot. Everything here is a pure
+ * function of the data.
+ */
+export const FRAMES = 400;
+/** Paper geometry, px: a 58 mm thermal printer prints 384 dots per line. */
+export const PAPER = {
+    width: 384,
+    /** Side margins; the 32-column text grid lives between them. */
+    margin: 16,
+    text: 352,
+    size: 18,
+    line: 26,
+    /** Barcode bars, full height. */
+    bars: 48,
+};
+/** The tail: everything after the last text line, to the next header. */
+export const TAIL = {
+    gapAboveBars: 10,
+    gapBelowBars: 12,
+    footer: PAPER.line,
+    gapBelowFooter: 8,
+    tear: PAPER.line,
+    /** Paper between the tear line and the next receipt's header. */
+    leader: 18,
+};
+/** Step, pause and hold weights, in frames, normalized to `FRAMES` below. */
+const WEIGHTS = { hold: 40, step: 3, pause: 5 };
+/** Constant feed speed of the barcode tail, px per frame. */
+const FEED_SPEED = 2;
+const easeInOut = (t) => (t < 0.5 ? 4 * t ** 3 : 1 - (-2 * t + 2) ** 3 / 2);
+/**
+ * The feed timeline: a hold, then one eased step per text line with a pause
+ * after each, then the tail at constant speed. Weights are normalized to the
+ * loop, so a short receipt feeds more slowly over the same 16 s.
+ */
+export function buildFeedPlan(textHeights, tail) {
+    const raw = [
+        { w: WEIGHTS.hold, dist: 0, kind: 'hold' },
+    ];
+    for (const h of textHeights) {
+        raw.push({ w: WEIGHTS.step, dist: h, kind: 'step' });
+        raw.push({ w: WEIGHTS.pause, dist: 0, kind: 'pause' });
+    }
+    raw.push({ w: tail / FEED_SPEED, dist: tail, kind: 'feed' });
+    const scale = FRAMES / raw.reduce((sum, g) => sum + g.w, 0);
+    const segments = [];
+    let at = 0;
+    let length = 0;
+    for (const g of raw) {
+        const end = at + g.w * scale;
+        segments.push({ start: at, end, dist: g.dist, kind: g.kind });
+        length += g.dist;
+        at = end;
+    }
+    return { length, segments };
+}
+/** Where the paper is at `t`, and whether the printer's LED is on. */
+export function feedAt(plan, t) {
+    const pos = Math.min(Math.max(t, 0), 1) * FRAMES;
+    let dist = 0;
+    for (const seg of plan.segments) {
+        const last = seg === plan.segments.at(-1);
+        if (pos < seg.end || last) {
+            const u = Math.min(1, Math.max(0, (pos - seg.start) / (seg.end - seg.start)));
+            dist += seg.kind === 'step' ? seg.dist * easeInOut(u) : seg.dist * u;
+            const led = seg.kind === 'pause' ? false : seg.kind === 'step' ? u < 0.6 : true;
+            return { offset: Math.round(dist) % plan.length, led };
+        }
+        dist += seg.dist;
+    }
+    return { offset: 0, led: true };
+}
+/**
+ * Barcode bar widths, one per calendar week: 0 for a week without
+ * contributions, otherwise 1 to 4 px by quartile of the non-zero weeks, so
+ * the busiest weeks print as the widest bars.
+ */
+export function barcodeWidths(days, from) {
+    // Calendar columns start on Sunday; the window's first week may be partial.
+    const lead = new Date(`${from}T00:00:00Z`).getUTCDay();
+    const weeks = [];
+    days.forEach((count, i) => {
+        const w = Math.floor((lead + i) / 7);
+        weeks[w] = (weeks[w] ?? 0) + count;
+    });
+    const active = weeks.filter((t) => t > 0).sort((a, b) => a - b);
+    if (active.length === 0)
+        return weeks.map(() => 0);
+    const at = (p) => active[Math.min(active.length - 1, Math.floor(p * (active.length - 1)))];
+    const [q1, q2, q3] = [at(0.25), at(0.5), at(0.75)];
+    return weeks.map((total) => total <= 0 ? 0 : total >= q3 ? 4 : total >= q2 ? 3 : total >= q1 ? 2 : 1);
+}
+const MONTHS = [
+    'JAN',
+    'FEB',
+    'MAR',
+    'APR',
+    'MAY',
+    'JUN',
+    'JUL',
+    'AUG',
+    'SEP',
+    'OCT',
+    'NOV',
+    'DEC',
+];
+/** "2026-03-12" -> "12 MAR 2026". */
+export function printDate(date) {
+    const [, m, d] = date.split('-');
+    return `${d} ${MONTHS[Number(m) - 1]} ${date.slice(0, 4)}`;
+}
+const measure = canvasMeasure('JetBrains Mono', PAPER.size);
+/** Right-aligned value with room to breathe: the till-receipt column gap. */
+const GAP = 12;
+export function buildReceipt(data, login, identity, options, palette, rng) {
+    // Thermal texture: per-line density, with a lighter band every few lines.
+    const texture = () => {
+        const d = 0.88 + rng() * 0.12;
+        return rng() < 0.15 ? d * 0.8 : d;
+    };
+    const line = (h, fields) => ({
+        h,
+        ...fields,
+        density: texture(),
+    });
+    const text = (fields) => line(PAPER.line, fields);
+    const rule = () => text({ left: '-'.repeat(32) });
+    const doubleRule = () => text({ left: '='.repeat(32) });
+    const count = (label, value) => text({ left: label, right: String(value) });
+    const lines = [];
+    // Header: the store is the user.
+    const name = fitLine(identity.name.toUpperCase(), PAPER.text, PAPER.size, PAPER.size, measure);
+    lines.push(line(PAPER.line * 2, { center: name.text, double: true }));
+    lines.push(text({ center: `github.com/${login}`, faded: true }));
+    const txn = `${Math.floor(rng() * 0x10000)
+        .toString(16)
+        .toUpperCase()
+        .padStart(4, '0')}-${String(Math.floor(rng() * 99) + 1).padStart(2, '0')}`;
+    lines.push(text({ left: `TXN ${txn}`, right: 'REG 01' }));
+    lines.push(text({ center: `${printDate(data.from)}  -  ${printDate(data.to)}`, faded: true }));
+    lines.push(rule());
+    // Items: the repositories the user committed to.
+    const empty = data.total === 0;
+    const items = data.items.slice(0, options.items);
+    if (empty) {
+        lines.push(text({ center: 'NO ITEMS' }));
+        lines.push(rule());
+    }
+    else if (items.length > 0 || data.privateCommits > 0) {
+        lines.push(text({ left: 'ITEM', right: 'QTY' }));
+        for (const item of items) {
+            const qty = String(item.commits);
+            const fitted = fitLine(item.name, PAPER.text - measure(qty, PAPER.size) - GAP, PAPER.size, PAPER.size, measure);
+            lines.push(text({ left: fitted.text, right: qty }));
+            if (item.language) {
+                lines.push(text({ left: `  @ ${item.language.name}`, faded: true }));
+            }
+        }
+        if (data.privateCommits > 0) {
+            lines.push(count('private repos', data.privateCommits));
+        }
+        lines.push(rule());
+    }
+    // Totals; a line whose count is 0 is left out. OTHER is what the per-type
+    // counts do not add up to, so the receipt always adds up.
+    const totals = [
+        count('COMMITS', data.commits),
+        count('PULL REQUESTS', data.pullRequests),
+        count('REVIEWS', data.reviews),
+        count('ISSUES', data.issues),
+        count('NEW REPOS', data.newRepos),
+        count('PRIVATE', data.restricted),
+    ].filter((l) => l.right !== '0');
+    const other = data.total -
+        (data.commits +
+            data.pullRequests +
+            data.reviews +
+            data.issues +
+            data.newRepos +
+            data.restricted);
+    if (other > 0)
+        totals.push(count('OTHER', other));
+    else if (other < 0)
+        console.warn('receipt: per-type counts exceed the calendar total; OTHER left out');
+    lines.push(...totals);
+    lines.push(doubleRule());
+    lines.push(count('TOTAL', data.total));
+    lines.push(doubleRule());
+    // Streaks and the best day; a streak of 0 is left out.
+    const longest = longestStreak(data.days);
+    if (longest > 0)
+        lines.push(text({ left: 'LONGEST STREAK', right: `${longest} DAYS` }));
+    const current = currentStreak(data.days);
+    if (current > 0)
+        lines.push(text({ left: 'CURRENT STREAK', right: `${current} DAYS` }));
+    const best = bestDay(data.days);
+    if (best) {
+        const date = new Date(Date.parse(`${data.from}T00:00:00Z`) + best.index * 86_400_000)
+            .toISOString()
+            .slice(0, 10);
+        const qty = String(best.count);
+        const label = fitLine(`BEST DAY ${printDate(date)}`, PAPER.text - measure(qty, PAPER.size) - GAP, PAPER.size, PAPER.size, measure);
+        lines.push(text({ left: label.text, right: qty }));
+    }
+    const barcode = barcodeWidths(data.days, data.from);
+    const tail = TAIL.gapAboveBars +
+        PAPER.bars +
+        TAIL.gapBelowBars +
+        TAIL.footer +
+        TAIL.gapBelowFooter +
+        TAIL.tear +
+        TAIL.leader;
+    const feed = buildFeedPlan(lines.map((l) => l.h), tail);
+    return {
+        palette,
+        total: data.total,
+        lines,
+        barcode,
+        footer: `${login.toUpperCase()}-${data.asOf.slice(0, 4)}`,
+        feed,
+        length: feed.length,
+        txn,
+    };
+}

package/dist/styles/receipt/sketch.js

@@ -0,0 +1,296 @@
+import { fitIdentity } from '../../core/text.js';
+import { feedAt, PAPER, TAIL } from './receipt.js';
+/**
+ * A thermal printer feeding the user's year as a till receipt.
+ *
+ * The whole receipt, tear line included, is rasterized once in setup into one
+ * offscreen strip (the paper). Each frame draws that strip at a whole-pixel
+ * offset, clipped at the printer's slot, tiling around at the strip's length:
+ * the roll prints the same receipt back to back, so the loop closes. Nothing
+ * on the paper is re-rasterized per frame, so held frames are byte-identical.
+ *
+ * Everything is drawn through the raw 2D context with the style set right
+ * before each draw (see Highlights Reel's note on p5's cached fill state).
+ */
+const SANS = '"Space Grotesk"';
+const MONO = '"JetBrains Mono"';
+const PROMPT = '~/receipt --last-12-months';
+const W = 1280;
+const H = 400;
+const TAU = Math.PI * 2;
+/** Width of the identity column: x 48 to 640, the printer body's left edge minus 20. */
+export const IDENTITY_COLUMN = 640 - 48;
+/** Paper and printer geometry, screen space. */
+const PAPER_X = 708;
+const SLOT_Y = 336;
+const PRINTER = { left: 660, right: 1140, bottom: 400 };
+const SLOT = { left: 700, right: 1100, bottom: 350 };
+const LED = { x: 1104, y: 369 };
+function rgba(color, alpha = 1) {
+    return `rgba(${color[0]},${color[1]},${color[2]},${alpha})`;
+}
+function setFill(ctx, color, alpha = 1) {
+    ctx.fillStyle = rgba(color, alpha);
+}
+function setFont(ctx, o) {
+    ctx.font = `${o.bold ? 700 : 400} ${o.size}px ${o.mono ? MONO : SANS}`;
+    ctx.textAlign = o.align ?? 'left';
+    ctx.textBaseline = 'alphabetic';
+    ctx.letterSpacing = `${o.tracking ?? 0}px`;
+}
+function drawText(ctx, str, x, y, o) {
+    setFont(ctx, o);
+    setFill(ctx, o.color, o.alpha ?? 1);
+    ctx.fillText(str, x, y);
+    if (o.tracking)
+        ctx.letterSpacing = '0px';
+}
+/** 0..1, periodic in `t`, so every animated value loops seamlessly. */
+function wave(t, cycles, off) {
+    return 0.5 + 0.5 * Math.sin(TAU * (t * cycles + off));
+}
+/** One text row of the paper, in strip coordinates. */
+function drawLine(ctx, line, top, p) {
+    if (!line.left && !line.right && !line.center)
+        return;
+    const color = line.faded ? p.fadedInk : p.ink;
+    ctx.font = `400 ${PAPER.size}px ${MONO}`;
+    ctx.textBaseline = 'middle';
+    ctx.letterSpacing = '0px';
+    if (line.double) {
+        // The thermal double-height mode: the same glyphs, vertically scaled.
+        ctx.save();
+        ctx.translate(0, top);
+        ctx.scale(1, 2);
+        setFill(ctx, color, line.density);
+        ctx.textAlign = 'center';
+        ctx.fillText(line.center ?? '', PAPER.width / 2, line.h / 4);
+        ctx.restore();
+        return;
+    }
+    setFill(ctx, color, line.density);
+    if (line.left) {
+        ctx.textAlign = 'left';
+        ctx.fillText(line.left, PAPER.margin, top + line.h / 2);
+    }
+    if (line.right) {
+        ctx.textAlign = 'right';
+        ctx.fillText(line.right, PAPER.width - PAPER.margin, top + line.h / 2);
+    }
+    if (line.center) {
+        ctx.textAlign = 'center';
+        ctx.fillText(line.center, PAPER.width / 2, top + line.h / 2);
+    }
+}
+/** The paper: everything the printer prints, one receipt per period. */
+function renderStrip(p, model) {
+    const P = model.palette;
+    const strip = p.createGraphics(PAPER.width, model.length);
+    const ctx = strip.drawingContext;
+    setFill(ctx, P.paper);
+    ctx.fillRect(0, 0, PAPER.width, model.length);
+    let y = 0;
+    for (const line of model.lines) {
+        drawLine(ctx, line, y, P);
+        y += line.h;
+    }
+    // Barcode: one bar per week, centered, 2 px between bars.
+    const bars = model.barcode.filter((w) => w > 0);
+    const barsTop = y + TAIL.gapAboveBars;
+    if (bars.length > 0) {
+        const total = bars.reduce((s, w) => s + w, 0) + (bars.length - 1) * 2;
+        let x = (PAPER.width - total) / 2;
+        ctx.fillStyle = rgba(P.ink, 0.95);
+        for (const w of model.barcode) {
+            if (w > 0) {
+                ctx.fillRect(Math.round(x), barsTop, w, PAPER.bars);
+                x += w + 2;
+            }
+        }
+    }
+    // Human-readable text under the barcode.
+    const footerTop = barsTop + PAPER.bars + TAIL.gapBelowBars;
+    ctx.font = `400 14px ${MONO}`;
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.letterSpacing = '2px';
+    ctx.fillStyle = rgba(P.ink, 0.9);
+    ctx.fillText(model.footer, PAPER.width / 2, footerTop + TAIL.footer / 2);
+    ctx.letterSpacing = '0px';
+    // Tear line: a perforation between receipts, with edge notches.
+    const tearY = footerTop + TAIL.footer + TAIL.gapBelowFooter + TAIL.tear / 2;
+    ctx.strokeStyle = rgba(P.fadedInk, 0.85);
+    ctx.lineWidth = 1.5;
+    ctx.setLineDash([5, 4]);
+    ctx.beginPath();
+    ctx.moveTo(8, tearY);
+    ctx.lineTo(PAPER.width - 8, tearY);
+    ctx.stroke();
+    ctx.setLineDash([]);
+    ctx.globalCompositeOperation = 'destination-out';
+    for (const cx of [0, PAPER.width]) {
+        ctx.beginPath();
+        ctx.arc(cx, tearY, 6, 0, TAU);
+        ctx.fill();
+    }
+    ctx.globalCompositeOperation = 'source-over';
+    if (P.paperBorder) {
+        ctx.strokeStyle = rgba(P.paperBorder, 0.09);
+        ctx.lineWidth = 1;
+        ctx.strokeRect(0.5, 0.5, PAPER.width - 1, model.length - 1);
+    }
+    return strip;
+}
+export function createReceiptSketch(model, identity) {
+    const P = model.palette;
+    const fitted = fitIdentity({
+        name: identity.name.toUpperCase(),
+        tagline: identity.tagline,
+        website: identity.website && `↗ ${displayUrl(identity.website)}`,
+    }, IDENTITY_COLUMN);
+    // --- static layers --------------------------------------------------------
+    /** The counter and the identity column, beneath the paper. */
+    function renderChrome(p) {
+        const chrome = p.createGraphics(W, H);
+        const ctx = chrome.drawingContext;
+        setFill(ctx, P.counter);
+        ctx.fillRect(0, 0, W, H);
+        // Soft shadow around the paper, light theme only.
+        if (P.shadow > 0) {
+            for (const [x0, x1, peak] of [
+                [PAPER_X + PAPER.width, PAPER_X + PAPER.width + 10, P.shadow],
+                [PAPER_X - 10, PAPER_X, P.shadow * 0.6],
+            ]) {
+                const grad = ctx.createLinearGradient(x0, 0, x1, 0);
+                grad.addColorStop(0, rgba(P.paperBorder, peak));
+                grad.addColorStop(1, rgba(P.paperBorder, 0));
+                ctx.fillStyle = grad;
+                ctx.fillRect(x0, 0, x1 - x0, SLOT_Y);
+            }
+        }
+        const x = 48;
+        drawText(ctx, PROMPT, x, 58, { size: 13, mono: true, color: P.accent });
+        drawText(ctx, fitted.name.text, x, 116, {
+            size: fitted.name.size,
+            bold: true,
+            color: P.identityInk,
+            tracking: 3,
+        });
+        if (fitted.tagline) {
+            drawText(ctx, fitted.tagline.text, x, 146, {
+                size: fitted.tagline.size,
+                color: P.accent,
+            });
+        }
+        drawText(ctx, model.total.toLocaleString('en-US'), x, 218, {
+            size: 34,
+            bold: true,
+            color: P.identityInk,
+        });
+        drawText(ctx, 'contributions · last 12 months', x, 240, {
+            size: 11,
+            mono: true,
+            color: P.identityMuted,
+        });
+        if (fitted.website) {
+            drawText(ctx, fitted.website.text, x, 350, {
+                size: fitted.website.size,
+                mono: true,
+                color: P.accent,
+            });
+        }
+        return chrome;
+    }
+    /** The printer, drawn over the paper's lower edge. */
+    function renderPrinter(p) {
+        const printer = p.createGraphics(W, H);
+        const ctx = printer.drawingContext;
+        setFill(ctx, P.body);
+        ctx.fillRect(PRINTER.left, SLOT_Y, PRINTER.right - PRINTER.left, PRINTER.bottom - SLOT_Y);
+        // Bevel on the body's top edge.
+        setStroke(ctx, P.bevel, 0.7);
+        ctx.lineWidth = 1.5;
+        ctx.beginPath();
+        ctx.moveTo(PRINTER.left + 8, SLOT_Y + 1);
+        ctx.lineTo(PRINTER.right - 8, SLOT_Y + 1);
+        ctx.stroke();
+        // The slot: a dark mouth with a serrated tear bar biting the paper.
+        setFill(ctx, P.slot);
+        ctx.fillRect(SLOT.left, SLOT_Y, SLOT.right - SLOT.left, SLOT.bottom - SLOT_Y);
+        setFill(ctx, P.slot);
+        ctx.beginPath();
+        for (let x = SLOT.left + 4; x < SLOT.right - 2; x += 12) {
+            ctx.moveTo(x, SLOT_Y + 1);
+            ctx.lineTo(x + 6, SLOT_Y - 5);
+            ctx.lineTo(x + 12, SLOT_Y + 1);
+            ctx.closePath();
+        }
+        ctx.fill();
+        return printer;
+    }
+    function setStroke(ctx, color, alpha = 1) {
+        ctx.strokeStyle = rgba(color, alpha);
+    }
+    let chrome;
+    let printer;
+    let strip;
+    function setup(p) {
+        chrome = renderChrome(p);
+        printer = renderPrinter(p);
+        strip = renderStrip(p, model);
+    }
+    function draw(p, _frame, t) {
+        const ctx = p.drawingContext;
+        if (chrome)
+            p.image(chrome, 0, 0);
+        // The paper, one whole receipt per period, wrapped at the strip's length.
+        const { offset, led } = feedAt(model.feed, t);
+        const L = model.length;
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(PAPER_X, 0, PAPER.width, SLOT_Y);
+        ctx.clip();
+        if (strip) {
+            p.image(strip, PAPER_X, SLOT_Y - offset);
+            p.image(strip, PAPER_X, SLOT_Y - offset - L);
+        }
+        ctx.restore();
+        if (P.paperBorder) {
+            setStroke(ctx, P.paperBorder, 0.09);
+            ctx.lineWidth = 1;
+            ctx.strokeRect(PAPER_X + 0.5, 0.5, PAPER.width - 1, SLOT_Y - 1);
+        }
+        if (printer)
+            p.image(printer, 0, 0);
+        // Status LED: blinks once per text step, lit while feeding and holding.
+        if (led) {
+            ctx.save();
+            setFill(ctx, P.accent);
+            ctx.shadowColor = rgba(P.accent, 0.8);
+            ctx.shadowBlur = 7;
+            ctx.beginPath();
+            ctx.arc(LED.x, LED.y, 4.5, 0, TAU);
+            ctx.fill();
+            ctx.restore();
+            ctx.shadowBlur = 0;
+            ctx.shadowColor = 'transparent';
+        }
+        else {
+            setFill(ctx, P.accent, 0.16);
+            ctx.beginPath();
+            ctx.arc(LED.x, LED.y, 4.5, 0, TAU);
+            ctx.fill();
+        }
+        // Prompt cursor, blinking 3 times per loop.
+        if (wave(t, 3, 0) > 0.5) {
+            setFont(ctx, { size: 13, mono: true });
+            setFill(ctx, P.accent);
+            ctx.fillRect(48 + ctx.measureText(PROMPT).width + 4, 47, 7, 13);
+        }
+    }
+    return { setup, draw };
+}
+/** "https://www.example.com/" -> "www.example.com" */
+function displayUrl(url) {
+    return url.replace(/^[a-z]+:\/\//i, '').replace(/\/+$/, '');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "headreel",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Animated GitHub profile banner made from your GitHub activity, with a GitHub Action or CLI.",
   "keywords": [
     "github",