headreel 1.2.0 → 1.3.0

package/README.md

@@ -78,32 +78,47 @@ You need:
 
 The Action and the command use the same settings.
 
-| Action input     | Command flag           | Default                         | Description                                                                                                       |
-| ---------------- | ---------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `style`          | `--style`              | (required)                      | The banner style. See [Styles](#styles).                                                                          |
-| `username`       | `--user`               | repository owner                | The GitHub user to show. The command requires it.                                                                 |
-| `tagline`        | `--tagline`            | empty                           | One line under your name.                                                                                         |
-| `website`        | `--website`            | empty                           | Your website.                                                                                                     |
-| `handle`         | `--handle`             | empty                           | A handle, for styles that show one.                                                                               |
-| `options`        | `--option <key=value>` | empty                           | Style options. Action: one `key: value` on each line. Command: repeat the flag, for example `--option beacons=5`. |
-| `output`         | `--out`                | `headreel.gif`                  | The path of the banner.                                                                                           |
-| `token`          | `--token`              | `github.token`                  | The token that reads your GitHub data.                                                                            |
-| `publish_mode`   | -                      | `commit`                        | `commit` adds a commit on every update. `branch` keeps one commit on its own branch, replaced on every update.    |
-| `commit_to`      | -                      | checked-out branch / `headreel` | The branch that gets the banner. The default is `headreel` in `branch` mode.                                      |
-| `commit_message` | -                      | `chore: update headreel banner` | The commit message.                                                                                               |
-| -                | `--config <file>`      | -                               | A JSON file with these settings. Flags replace its values.                                                        |
+| Action input     | Command flag           | Default                         | Description                                                                                                          |
+| ---------------- | ---------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `style`          | `--style`              | (required)                      | The banner style. See [Styles](#styles).                                                                             |
+| `username`       | `--user`               | repository owner                | The GitHub user to show. The command requires it.                                                                    |
+| `tagline`        | `--tagline`            | empty                           | One line under your name.                                                                                            |
+| `website`        | `--website`            | empty                           | Your website.                                                                                                        |
+| `handle`         | `--handle`             | empty                           | A handle, for styles that show one.                                                                                  |
+| `options`        | `--option <key=value>` | empty                           | Style options. Action: one `key: value` on each line. Command: repeat the flag, for example `--option accent=green`. |
+| `output`         | `--out`                | `headreel.gif`                  | The path of the banner.                                                                                              |
+| `token`          | `--token`              | `github.token`                  | The token that reads your GitHub data.                                                                               |
+| `publish_mode`   | -                      | `commit`                        | `commit` adds a commit on every update. `branch` keeps one commit on its own branch, replaced on every update.       |
+| `commit_to`      | -                      | checked-out branch / `headreel` | The branch that gets the banner. The default is `headreel` in `branch` mode.                                         |
+| `commit_message` | -                      | `chore: update headreel banner` | The commit message.                                                                                                  |
+| -                | `--config <file>`      | -                               | A JSON file with these settings. Flags replace its values.                                                           |
 
 Empty settings do not show on the banner. Your name comes from your GitHub profile. If your profile has no name, the banner shows your username.
 
 ## Styles
 
+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.
+
 ### 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.
 
-| Option    | Default | Description                                        |
-| --------- | ------- | -------------------------------------------------- |
-| `beacons` | `8`     | The number of busiest days with a beacon, 0 to 10. |
+![Contribution City banner](https://raw.githubusercontent.com/arifszn/headreel/main/docs/samples/contribution-city.gif)
+
+| Option   | Default | Description                                                                                   |
+| -------- | ------- | --------------------------------------------------------------------------------------------- |
+| `accent` | `cyan`  | Color of the roofs, windows, lights and links: `cyan`, `cobalt`, `green`, `violet` or `pink`. |
+
+### 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.
+
+![Highlights Reel banner](https://raw.githubusercontent.com/arifszn/headreel/main/docs/samples/highlights-reel.gif)
+
+| Option   | Default  | Description                                                                            |
+| -------- | -------- | -------------------------------------------------------------------------------------- |
+| `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`. |
 
 ### Repo Galaxy
 
@@ -117,8 +132,6 @@ Empty settings do not show on the banner. Your name comes from your GitHub profi
 | `include_forks` | `false` | Show forked repositories too.                                         |
 | `labels`        | `top3`  | `top3` names the three most starred repositories. `none` hides names. |
 
-Set an option with `options: 'beacons: 5'` in the Action, or `--option beacons=5` in the command. For more than one option in the Action, put each on its own line.
-
 ## Troubleshooting
 
 | Problem                          | Fix                                                      |
@@ -126,3 +139,11 @@ Set an option with `options: 'beacons: 5'` in the Action, or `--option beacons=5
 | "Permission denied" or 403 error | Add `permissions: contents: write` to the workflow file. |
 | "Could not resolve to a User"    | Set `username` to a valid GitHub username.               |
 | "No GitHub token found"          | Run `gh auth login`, or set `GITHUB_TOKEN`.              |
+
+## Support
+
+If headreel is useful to you, please [star the repository](https://github.com/arifszn/headreel). It helps other people find it.
+
+## License
+
+[MIT License](./LICENSE).

package/dist/core/data/contributions.js

@@ -32,6 +32,17 @@ export const contributionsSchema = z.object({
     /** Calendar columns, oldest first. First and last weeks may be partial. */
     weeks: z.array(z.array(daySchema)),
 });
+/** Normalizes the GraphQL contribution calendar into the stored shape. */
+export function normalizeCalendar(calendar, from, to) {
+    return {
+        from,
+        to,
+        total: calendar.totalContributions,
+        weeks: calendar.weeks.map((week) => week.contributionDays
+            .map((d) => ({ date: d.date, weekday: d.weekday, count: d.contributionCount }))
+            .sort((a, b) => a.date.localeCompare(b.date))),
+    };
+}
 const DAY_MS = 86_400_000;
 /**
  * The 365 days ending on `now` (UTC), matching GitHub's profile calendar.
@@ -51,13 +62,5 @@ export async function fetchContributions(client, login, now) {
         from: `${from}T00:00:00Z`,
         to: `${to}T23:59:59Z`,
     });
-    const calendar = user.contributionsCollection.contributionCalendar;
-    return {
-        from,
-        to,
-        total: calendar.totalContributions,
-        weeks: calendar.weeks.map((week) => week.contributionDays
-            .map((d) => ({ date: d.date, weekday: d.weekday, count: d.contributionCount }))
-            .sort((a, b) => a.date.localeCompare(b.date))),
-    };
+    return normalizeCalendar(user.contributionsCollection.contributionCalendar, from, to);
 }

package/dist/core/data/highlights.js

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+import { contributionWindow, contributionsSchema, normalizeCalendar } from './contributions.js';
+import { MAX_REPOS } from './repos.js';
+// One query for the whole reel: the same 365-day window as Contribution City,
+// the most starred owned public repos (the first is the top repo, the set
+// counts the top languages and the total stars), and all-time merged pull
+// requests.
+const QUERY = /* GraphQL */ `
+  query Highlights($login: String!, $first: Int!, $from: DateTime!, $to: DateTime!) {
+    user(login: $login) {
+      contributionsCollection(from: $from, to: $to) {
+        contributionCalendar {
+          totalContributions
+          weeks {
+            contributionDays {
+              date
+              weekday
+              contributionCount
+            }
+          }
+        }
+      }
+      repos: repositories(
+        first: $first
+        ownerAffiliations: OWNER
+        privacy: PUBLIC
+        isFork: false
+        orderBy: { field: STARGAZERS, direction: DESC }
+      ) {
+        nodes {
+          name
+          stargazerCount
+          forkCount
+          primaryLanguage {
+            name
+            color
+          }
+        }
+      }
+      pullRequests(states: MERGED) {
+        totalCount
+      }
+    }
+  }
+`;
+const topRepoSchema = z.object({
+    name: z.string().min(1),
+    stars: z.number().int().min(0),
+    forks: z.number().int().min(0),
+    language: 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(),
+});
+/** Repos shown as pseudo cards around the top repo, most starred first. */
+export const STARRED_REPOS = 6;
+export const highlightsSchema = z.object({
+    contributions: contributionsSchema,
+    topRepo: topRepoSchema.nullable(),
+    /** Stars summed over the fetched repos. */
+    totalStars: z.number().int().min(0),
+    /** The most starred repos, top repo first, for the pseudo cards. */
+    starredRepos: z
+        .array(z.object({
+        name: z.string().min(1),
+        stars: z.number().int().min(0),
+        /** Linguist color of the primary language; null when none. */
+        color: z
+            .string()
+            .regex(/^#[0-9a-fA-F]{6}$/)
+            .nullable(),
+    }))
+        .max(STARRED_REPOS),
+    mergedPullRequests: z.number().int().min(0),
+    /** Top three languages by repo count over the fetched repos, most first. */
+    languages: z
+        .array(z.object({
+        name: z.string().min(1),
+        /** Linguist color; null when no repo sets one. */
+        color: z
+            .string()
+            .regex(/^#[0-9a-fA-F]{6}$/)
+            .nullable(),
+        count: z.number().int().min(1),
+    }))
+        .max(3),
+});
+export async function fetchHighlights(client, login, now) {
+    const { from, to } = contributionWindow(now);
+    const { user } = await client(QUERY, {
+        login,
+        first: MAX_REPOS,
+        from: `${from}T00:00:00Z`,
+        to: `${to}T23:59:59Z`,
+    });
+    const nodes = user.repos.nodes;
+    // Languages by repo count, ties by name; repos without a language are skipped.
+    const counts = new Map();
+    for (const n of nodes) {
+        if (!n.primaryLanguage)
+            continue;
+        const entry = counts.get(n.primaryLanguage.name) ?? {
+            color: n.primaryLanguage.color,
+            count: 0,
+        };
+        entry.count++;
+        counts.set(n.primaryLanguage.name, entry);
+    }
+    const languages = [...counts.entries()]
+        .sort((a, b) => b[1].count - a[1].count || a[0].localeCompare(b[0]))
+        .slice(0, 3)
+        .map(([name, { color, count }]) => ({ name, color, count }));
+    const top = nodes[0];
+    return {
+        contributions: normalizeCalendar(user.contributionsCollection.contributionCalendar, from, to),
+        topRepo: top
+            ? {
+                name: top.name,
+                stars: top.stargazerCount,
+                forks: top.forkCount,
+                language: top.primaryLanguage
+                    ? { name: top.primaryLanguage.name, color: top.primaryLanguage.color }
+                    : null,
+            }
+            : null,
+        totalStars: nodes.reduce((sum, n) => sum + n.stargazerCount, 0),
+        starredRepos: nodes.slice(0, STARRED_REPOS).map((n) => ({
+            name: n.name,
+            stars: n.stargazerCount,
+            color: n.primaryLanguage?.color ?? null,
+        })),
+        mergedPullRequests: user.pullRequests.totalCount,
+        languages,
+    };
+}

package/dist/core/encode/gif.js

@@ -4,7 +4,7 @@ import * as gifencModule from 'gifenc';
 const gifenc = typeof gifencModule.quantize === 'function'
     ? gifencModule
     : gifencModule.default;
-const { GIFEncoder, quantize, applyPalette } = gifenc;
+const { GIFEncoder, quantize } = 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. */
@@ -33,12 +33,13 @@ const BAYER = (() => {
  * that does not change between frames dithers identically, which keeps the
  * frame deltas small and avoids shimmer.
  */
-function dither(rgba, width) {
+function dither(rgba, width, pinned) {
     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;
+        const exact = pinned.size > 0 && pinned.has((rgba[i] << 16) | (rgba[i + 1] << 8) | rgba[i + 2]);
+        const offset = exact ? 0 : 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;
@@ -46,12 +47,48 @@ function dither(rgba, width) {
     }
     return out;
 }
-function buildPalette(frames, frameBytes) {
+/**
+ * Maps pixels to their nearest palette index, memoized per exact color.
+ * gifenc's `applyPalette` memoizes per rgb565 bucket instead, so the first pixel
+ * of a bucket in scan order picks the index for the whole bucket. Near-white
+ * pixels then land on white in one frame and on a pale grey in the next, and a
+ * flat card flickers. An exact memo is a pure function of the color.
+ */
+function createMapper(palette) {
+    const memo = new Int16Array(1 << 24).fill(-1);
+    const nearest = (r, g, b) => {
+        let best = 0;
+        let bestDist = Infinity;
+        for (let k = 0; k < palette.length; k++) {
+            const c = palette[k];
+            const d = (c[0] - r) ** 2 + (c[1] - g) ** 2 + (c[2] - b) ** 2;
+            if (d < bestDist) {
+                bestDist = d;
+                best = k;
+            }
+        }
+        return best;
+    };
+    return (rgba) => {
+        const out = new Uint8Array(rgba.length / 4);
+        for (let i = 0, p = 0; i < rgba.length; i += 4, p++) {
+            const key = (rgba[i] << 16) | (rgba[i + 1] << 8) | rgba[i + 2];
+            let index = memo[key];
+            if (index < 0) {
+                index = nearest(rgba[i], rgba[i + 1], rgba[i + 2]);
+                memo[key] = index;
+            }
+            out[p] = index;
+        }
+        return out;
+    };
+}
+function buildPalette(frames, frameBytes, colors) {
     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);
+    return quantize(sample, colors);
 }
 /**
  * Encodes RGBA frames into a looping GIF: one global palette, ordered
@@ -59,16 +96,22 @@ function buildPalette(frames, frameBytes) {
  */
 export function encodeGif(frames, spec) {
     const { width, height } = spec;
-    const palette = buildPalette(frames, width * height * 4);
+    const pinnedColors = spec.pinned ?? [];
+    const palette = [
+        ...buildPalette(frames, width * height * 4, COLORS - pinnedColors.length),
+        ...pinnedColors.map((c) => [...c]),
+    ];
+    const pinned = new Set(pinnedColors.map(([r, g, b]) => (r << 16) | (g << 8) | b));
     const globalPalette = [...palette];
     while (globalPalette.length < TRANSPARENT)
         globalPalette.push([0, 0, 0]);
     globalPalette.push([0, 0, 0]);
+    const toIndex = createMapper(palette);
     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);
+        const index = toIndex(dither(data, width, pinned));
         let pixels = index;
         if (previous) {
             pixels = new Uint8Array(index);

package/dist/core/pipeline.js

@@ -24,5 +24,9 @@ export async function renderBanner(style, input) {
         rng,
     });
     const frames = await renderFrames(sketch, { ...CANVAS, frames: style.frames });
-    return encodeGif(frames, { ...CANVAS, fps: style.fps });
+    return encodeGif(frames, {
+        ...CANVAS,
+        fps: style.fps,
+        ...(style.pinned ? { pinned: style.pinned(options) } : {}),
+    });
 }

package/dist/core/text.js

@@ -0,0 +1,72 @@
+import { createCanvas } from '@napi-rs/canvas';
+import { registerFonts } from './fonts.js';
+const ELLIPSIS = '…';
+/**
+ * Fits one line of text into `maxWidth`. It first shrinks from `size` toward
+ * `minSize` (pass `minSize === size` to keep the size), then cuts the text
+ * with an ellipsis. The result is never wider than `maxWidth`, so no line can
+ * leave the canvas or run into the scene.
+ */
+export function fitLine(text, maxWidth, size, minSize, measure) {
+    if (measure(text, size) <= maxWidth)
+        return { text, size };
+    // Width scales about linearly with size; step down until it fits.
+    let fitted = Math.max(minSize, Math.floor((size * maxWidth) / measure(text, size)));
+    while (fitted > minSize && measure(text, fitted) > maxWidth)
+        fitted--;
+    if (measure(text, fitted) <= maxWidth)
+        return { text, size: fitted };
+    // Longest prefix that fits with the ellipsis.
+    const chars = [...text];
+    let lo = 0;
+    let hi = chars.length;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        const candidate = `${chars.slice(0, mid).join('').trimEnd()}${ELLIPSIS}`;
+        if (measure(candidate, minSize) <= maxWidth)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    const cut = chars.slice(0, lo).join('').trimEnd();
+    return { text: cut ? `${cut}${ELLIPSIS}` : '', size: minSize };
+}
+let scratch;
+/**
+ * Measures with the bundled fonts on a private canvas, so fitting never
+ * touches a sketch's own drawing state (p5 caches font and fill state).
+ * `tracking` is letter spacing in px, as the sketch draws it.
+ */
+export function canvasMeasure(family, weight, tracking = 0) {
+    registerFonts();
+    scratch ??= createCanvas(1, 1).getContext('2d');
+    const ctx = scratch;
+    return (text, size) => {
+        ctx.font = `${weight} ${size}px "${family}"`;
+        ctx.letterSpacing = `${tracking}px`;
+        return ctx.measureText(text).width;
+    };
+}
+/** The identity column's lines, shared by every style (same fonts and sizes). */
+export const IDENTITY_TYPE = {
+    name: { family: 'Space Grotesk', weight: 700, size: 50, minSize: 30, tracking: 3 },
+    tagline: { family: 'Space Grotesk', weight: 400, size: 17 },
+    website: { family: 'JetBrains Mono', weight: 400, size: 12 },
+};
+/**
+ * Fits the identity column: `name` shrinks then cuts, `tagline` and `website`
+ * cut. `column` bounds name and tagline; `websiteColumn` bounds the website,
+ * which some styles draw beside the scene rather than above it.
+ */
+export function fitIdentity(lines, column, websiteColumn = column) {
+    const { name, tagline, website } = IDENTITY_TYPE;
+    return {
+        name: fitLine(lines.name, column, name.size, name.minSize, canvasMeasure(name.family, name.weight, name.tracking)),
+        tagline: lines.tagline
+            ? fitLine(lines.tagline, column, tagline.size, tagline.size, canvasMeasure(tagline.family, tagline.weight))
+            : null,
+        website: lines.website
+            ? fitLine(lines.website, websiteColumn, website.size, website.size, canvasMeasure(website.family, website.weight))
+            : null,
+    };
+}

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

@@ -31,7 +31,9 @@ export function tileAt(weeks, w, d) {
     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) {
+/** Busiest days marked with a beacon. */
+export const BEACONS = 8;
+export function buildCity(data, rng) {
     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));
@@ -73,7 +75,7 @@ export function buildCity(data, rng, beacons) {
     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))
+    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);

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

@@ -9,6 +9,6 @@ export const contributionCity = {
     data: { name: 'contributions', schema: contributionsSchema, fetch: fetchContributions },
     options,
     createSketch({ data, options, identity, rng }) {
-        return createCitySketch(buildCity(data, rng, options.beacons), identity, rng);
+        return createCitySketch(buildCity(data, rng), identity, rng, options.accent);
     },
 };

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

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+export const ACCENTS = ['cyan', 'cobalt', 'green', 'violet', 'pink'];
 export const options = z
     .object({
-    /** Number of busiest days marked with a beacon. */
-    beacons: z.coerce.number().int().min(0).max(10).default(8),
+    /** Color of the roofs, windows, glow, lines, scan beam and links. */
+    accent: z.enum(ACCENTS).default('cyan'),
 })
     .strict();