headreel 1.0.0 → 1.2.0

package/README.md

@@ -1,53 +1,25 @@
 # headreel
 
 [![npm](https://img.shields.io/npm/v/headreel)](https://www.npmjs.com/package/headreel)
+[![GitHub Marketplace](https://img.shields.io/badge/marketplace-headreel-blue?logo=github)](https://github.com/marketplace/actions/headreel)
 [![CI](https://github.com/arifszn/headreel/actions/workflows/ci.yml/badge.svg)](https://github.com/arifszn/headreel/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-An animated banner for your GitHub profile, made from your own GitHub activity.
+An animated banner for your GitHub profile, made from your GitHub activity.
 
 ![Contribution City banner](https://raw.githubusercontent.com/arifszn/headreel/main/docs/samples/contribution-city.gif)
 
-headreel turns your contributions into a looping GIF. You can use it in two ways:
+Pick one way to make your banner:
 
-- **One command on your computer.** Run `npx headreel` and get your banner. You do not install or set up anything. It works on macOS, Windows, and Linux.
-- **A GitHub Action that keeps it current.** Add one workflow file, and your banner updates every day by itself.
+- [GitHub Action](#github-action): updates the banner every day. No setup on your computer.
+- [Command](#command): makes the banner once on your computer.
 
-Every style works on both light and dark GitHub themes.
+## GitHub Action
 
-## Make your banner now
+The Action is on the [GitHub Marketplace](https://github.com/marketplace/actions/headreel).
 
-Run this command. Replace `octocat` with your GitHub username.
-
-```bash
-npx headreel --style contribution-city --user octocat
-```
-
-The command saves your banner as `headreel.gif` in the current folder. The first run downloads headreel. After that, a banner takes a few seconds.
-
-Add your tagline and website:
-
-```bash
-npx headreel --style contribution-city --user octocat \
-  --tagline "Open source maintainer" \
-  --website https://example.com
-```
-
-You need [Node.js](https://nodejs.org) 22 (22.22.2 or later), 24 (24.15.0 or later), or 26 and later. You also need a GitHub token. If you use the [GitHub CLI](https://cli.github.com), log in with `gh auth login`, and headreel finds the token. For other ways, see [Command options](#command-options).
-
-To put the banner on your profile, add `headreel.gif` to your profile repository. Then add this line to its `README.md`:
-
-```markdown
-![My GitHub activity](headreel.gif)
-```
-
-## Keep it updated with the GitHub Action
-
-A banner that you make on your computer does not change. The Action makes a new banner every day.
-
-Your profile repository has the same name as your username, for example `octocat/octocat`. Do these steps in that repository.
-
-1. Create the file `.github/workflows/headreel.yml` with this content:
+1. Open your profile repository. This is the public repository with the same name as your username, for example `octocat/octocat`.
+2. Add `.github/workflows/headreel.yml`:
 
    ```yaml
    name: headreel
@@ -55,7 +27,7 @@ Your profile repository has the same name as your username, for example `octocat
    on:
      schedule:
        - cron: '0 0 * * *' # every day at 00:00 UTC
-     workflow_dispatch: # lets you run it from the Actions tab
+     workflow_dispatch:
 
    permissions:
      contents: write
@@ -68,107 +40,89 @@ Your profile repository has the same name as your username, for example `octocat
          - uses: arifszn/headreel@v1
            with:
              style: contribution-city
-             tagline: Senior Software Engineer · Distributed Systems
+             publish_mode: branch
+             tagline: Open source maintainer
              website: https://example.com
    ```
 
-2. Open the **Actions** tab of the repository. Select **headreel**, then select **Run workflow**.
-3. Wait for the run to finish. The workflow adds `headreel.gif` to the repository.
-4. Add this line to your `README.md`:
+3. Run the workflow once from the **Actions** tab. It adds `headreel.gif` to the `headreel` branch.
+4. Add the image line to your `README.md`. The workflow run page shows it, ready to copy. It looks like this:
 
    ```markdown
-   ![My GitHub activity](headreel.gif)
+   ![My GitHub activity](https://raw.githubusercontent.com/octocat/octocat/headreel/headreel.gif)
    ```
 
-> [!NOTE]
-> The workflow makes a commit only when the banner changes. Your contribution count changes most days, so expect about one commit each day.
+The workflow updates the banner only when it changes. After an update, the new banner can take up to 5 minutes to show. See [Settings](#settings) for all inputs.
 
-## Action inputs
+### Keep your repository small
 
-| Input            | Default                         | Description                                                        |
-| ---------------- | ------------------------------- | ------------------------------------------------------------------ |
-| `style`          | (required)                      | The banner style. See [Styles](#styles).                           |
-| `username`       | repository owner                | The GitHub user to show.                                           |
-| `tagline`        | empty                           | One line under your name. Empty means no tagline.                  |
-| `website`        | empty                           | Your website, for example `https://example.com`. Empty means none. |
-| `handle`         | empty                           | A handle, for styles that show one.                                |
-| `options`        | empty                           | Style settings, one `key: value` on each line.                     |
-| `output`         | `headreel.gif`                  | The path of the banner in your repository.                         |
-| `commit_to`      | the checked-out branch          | The branch that gets the banner.                                   |
-| `commit_message` | `chore: update headreel banner` | The commit message for each update.                                |
-| `token`          | `github.token`                  | The token that reads your contribution data.                       |
+The setup above uses `publish_mode: branch`. The banner lives on its own `headreel` branch, and each update replaces the old banner, so your repository does not grow.
 
-Your name comes from your GitHub profile. If your profile has no name, the banner shows your username.
+If you remove `publish_mode: branch`, each update adds a new commit to your main branch. Old banners stay in your history, and each one is a few MB.
 
-## Styles
+## Command
 
-### Contribution City
+Run this command. Replace `octocat` with your GitHub username.
+
+```bash
+npx headreel --style contribution-city --user octocat --tagline "Open source maintainer" --website https://example.com
+```
+
+The command saves `headreel.gif` in the current folder. Add the file to your profile repository, and add `![My GitHub activity](headreel.gif)` to its `README.md`.
 
-`style: contribution-city`
+You need:
 
-Each day of the last 12 months is one building. A taller building means more contributions on that day. A light beam moves across the city, and beacons glow on your busiest days.
+- A GitHub token. headreel uses `--token`, then `GITHUB_TOKEN`, then your [GitHub CLI](https://cli.github.com) login (`gh auth login`).
 
-The banner shows your name, your tagline, your total contributions, and your website.
+## Settings
+
+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.                                                        |
+
+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
+
+### 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. |
 
-Example:
+### Repo Galaxy
 
-```yaml
-- uses: arifszn/headreel@v1
-  with:
-    style: contribution-city
-    options: |
-      beacons: 5
-```
+`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.
 
-## Command options
-
-| Option                 | Description                                           |
-| ---------------------- | ----------------------------------------------------- |
-| `--style <id>`         | The banner style (required). See [Styles](#styles).   |
-| `--user <login>`       | Your GitHub username (required).                      |
-| `--out <file>`         | Where to save the GIF. The default is `headreel.gif`. |
-| `--tagline <text>`     | One line under your name.                             |
-| `--website <url>`      | Your website.                                         |
-| `--handle <text>`      | A handle, for styles that show one.                   |
-| `--option <key=value>` | A style setting. Use it again for each setting.       |
-| `--config <file>`      | A JSON file with your settings.                       |
-| `--token <token>`      | A GitHub token. See the token order below.            |
-
-headreel needs a GitHub token to read your contributions. It looks for a token in this order:
-
-1. The `--token` option.
-2. The `GITHUB_TOKEN` environment variable.
-3. The [GitHub CLI](https://cli.github.com), if you are logged in with `gh auth login`.
-
-You can keep your settings in a JSON file:
-
-```json
-{
-  "style": "contribution-city",
-  "user": "octocat",
-  "tagline": "Open source maintainer",
-  "website": "https://example.com",
-  "options": { "beacons": 5 }
-}
-```
+![Repo Galaxy banner](https://raw.githubusercontent.com/arifszn/headreel/main/docs/samples/repo-galaxy.gif)
 
-```bash
-npx headreel --config headreel.json
-```
+| Option          | Default | Description                                                           |
+| --------------- | ------- | --------------------------------------------------------------------- |
+| `max_repos`     | `20`    | The number of repositories to show, 5 to 30.                          |
+| `include_forks` | `false` | Show forked repositories too.                                         |
+| `labels`        | `top3`  | `top3` names the three most starred repositories. `none` hides names. |
 
-Options on the command line replace the values in the file. To see all options, run `npx headreel --help`.
+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
 
-**The workflow fails with "Permission denied" or a 403 error.**
-Make sure that the workflow file contains `permissions: contents: write`.
-
-**The workflow fails with "Could not resolve to a User".**
-Check the `username` input. It must be a GitHub username.
-
-**The command fails with "No GitHub token found".**
-Log in with `gh auth login`, or set the `GITHUB_TOKEN` environment variable.
+| Problem                          | Fix                                                      |
+| -------------------------------- | -------------------------------------------------------- |
+| "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`.              |

package/dist/core/data/repos.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+/** Most repos any style shows; each list below fetches this many. */
+export const MAX_REPOS = 30;
+const REPO_FIELDS = /* GraphQL */ `
+  nodes {
+    name
+    isFork
+    stargazerCount
+    pushedAt
+    primaryLanguage {
+      name
+      color
+    }
+  }
+`;
+// Two lists in one query: top own repos, and top repos including forks. Their
+// union holds the top MAX_REPOS for either `include_forks` setting.
+const QUERY = /* GraphQL */ `
+  query Repos($login: String!, $first: Int!) {
+    user(login: $login) {
+      own: repositories(
+        first: $first
+        ownerAffiliations: OWNER
+        privacy: PUBLIC
+        isFork: false
+        orderBy: { field: STARGAZERS, direction: DESC }
+      ) {
+        ${REPO_FIELDS}
+      }
+      all: repositories(
+        first: $first
+        ownerAffiliations: OWNER
+        privacy: PUBLIC
+        orderBy: { field: STARGAZERS, direction: DESC }
+      ) {
+        ${REPO_FIELDS}
+      }
+    }
+  }
+`;
+const repoSchema = z.object({
+    name: z.string().min(1),
+    fork: z.boolean(),
+    stars: z.number().int().min(0),
+    /** Primary language; `color` is the linguist color, null when it has none. */
+    language: z
+        .object({
+        name: z.string().min(1),
+        color: z
+            .string()
+            .regex(/^#[0-9a-fA-F]{6}$/)
+            .nullable(),
+    })
+        .nullable(),
+    /** Last push, YYYY-MM-DD. */
+    pushedAt: z.iso.date(),
+});
+export const reposSchema = z.object({
+    /** Fetch date, YYYY-MM-DD (UTC). Repo ages are measured from here, so renders stay stable. */
+    asOf: z.iso.date(),
+    /** Most starred first, ties by name. */
+    repos: z.array(repoSchema),
+});
+/** Stars descending, then name, so ties never depend on API order. */
+export function compareRepos(a, b) {
+    return b.stars - a.stars || a.name.localeCompare(b.name);
+}
+export async function fetchRepos(client, login, now) {
+    const { user } = await client(QUERY, { login, first: MAX_REPOS });
+    const byName = new Map();
+    for (const n of [...user.own.nodes, ...user.all.nodes]) {
+        byName.set(n.name, {
+            name: n.name,
+            fork: n.isFork,
+            stars: n.stargazerCount,
+            language: n.primaryLanguage
+                ? { name: n.primaryLanguage.name, color: n.primaryLanguage.color }
+                : null,
+            // A repo never pushed to has no pushedAt; it counts as the oldest.
+            pushedAt: (n.pushedAt ?? '1970-01-01').slice(0, 10),
+        });
+    }
+    return {
+        asOf: now.toISOString().slice(0, 10),
+        repos: [...byName.values()].sort(compareRepos),
+    };
+}

package/dist/core/pipeline.js

@@ -16,7 +16,13 @@ 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 sketch = style.createSketch({
+        login: input.login,
+        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/styles/contribution-city/index.js

@@ -6,7 +6,7 @@ export const contributionCity = {
     id: 'contribution-city',
     fps: 25,
     frames: 150,
-    data: { schema: contributionsSchema, fetch: fetchContributions },
+    data: { name: 'contributions', schema: contributionsSchema, fetch: fetchContributions },
     options,
     createSketch({ data, options, identity, rng }) {
         return createCitySketch(buildCity(data, rng, options.beacons), identity, rng);

package/dist/styles/index.js

@@ -1,5 +1,7 @@
 import { contributionCity } from './contribution-city/index.js';
+import { repoGalaxy } from './repo-galaxy/index.js';
 /** Built-in styles, keyed by id. */
 export const styles = {
     [contributionCity.id]: contributionCity,
+    [repoGalaxy.id]: repoGalaxy,
 };

package/dist/styles/repo-galaxy/galaxy.js

@@ -0,0 +1,149 @@
+import { compareRepos } from '../../core/data/repos.js';
+export const LAYOUT = {
+    width: 1280,
+    height: 400,
+    /** Sun, center of every orbit. */
+    cx: 872,
+    cy: 206,
+    /** Tilt of the orbital plane on screen, radians. */
+    tilt: -0.1,
+    /** Orbit ellipse height / width: how far the plane leans away from the viewer. */
+    aspect: 0.3,
+    /** Planet radius range, px, before depth scaling. */
+    minR: 3,
+    maxR: 13,
+    stars: 220,
+    dust: 2400,
+    grain: 2600,
+};
+/**
+ * Orbits by time since the last push: recent work circles close to the sun.
+ * `revs` are whole revolutions per loop, so every orbit closes seamlessly.
+ */
+export const RINGS = [
+    { label: '30 DAYS', maxDays: 30, rx: 132, revs: 3 },
+    { label: '6 MONTHS', maxDays: 183, rx: 206, revs: 2 },
+    { label: '2 YEARS', maxDays: 730, rx: 282, revs: 1 },
+    { label: 'OLDER', maxDays: Infinity, rx: 360, revs: 1 },
+];
+/** Planets without a language, and languages without a linguist color. */
+const NEUTRAL = [154, 163, 181];
+const DAY_MS = 86_400_000;
+/** Linguist colors include near-black ones; lift them so every planet reads on the night sky. */
+export function planetColor(hex) {
+    if (!hex)
+        return NEUTRAL;
+    const n = Number.parseInt(hex.slice(1), 16);
+    const rgb = [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+    const [h, s, l] = rgbToHsl(rgb);
+    return hslToRgb(h, Math.min(s, 0.85), Math.max(l, 0.52));
+}
+export function ringFor(pushedAt, asOf) {
+    const days = (Date.parse(`${asOf}T00:00:00Z`) - Date.parse(`${pushedAt}T00:00:00Z`)) / DAY_MS;
+    return RINGS.findIndex((r) => days <= r.maxDays);
+}
+export function selectRepos(data, options) {
+    return data.repos
+        .filter((r) => options.include_forks || !r.fork)
+        .sort(compareRepos)
+        .slice(0, options.max_repos);
+}
+export function buildGalaxy(data, rng, options) {
+    const repos = selectRepos(data, options);
+    const maxStars = Math.max(0, ...repos.map((r) => r.stars));
+    const scale = Math.log1p(maxStars);
+    const planets = repos.map((repo, rank) => ({
+        name: repo.name,
+        stars: repo.stars,
+        rank,
+        ring: ringFor(repo.pushedAt, data.asOf),
+        r: scale > 0
+            ? LAYOUT.minR + (LAYOUT.maxR - LAYOUT.minR) * (Math.log1p(repo.stars) / scale)
+            : LAYOUT.minR + 0.5,
+        color: planetColor(repo.language?.color),
+        angle: 0,
+        // A repo without stars is not among the most starred, whatever its rank.
+        label: options.labels === 'top3' && rank < 3 && repo.stars > 0,
+    }));
+    // Spread each ring's planets evenly from a seeded start, with a little jitter.
+    RINGS.forEach((_, ring) => {
+        const members = planets.filter((p) => p.ring === ring);
+        const start = rng() * Math.PI * 2;
+        const step = (Math.PI * 2) / Math.max(1, members.length);
+        members.forEach((p, i) => {
+            p.angle = start + i * step + (rng() - 0.5) * step * 0.3;
+        });
+    });
+    const languages = new Map();
+    for (const repo of repos) {
+        if (!repo.language)
+            continue;
+        const entry = languages.get(repo.language.name) ?? {
+            name: repo.language.name,
+            color: planetColor(repo.language.color),
+            count: 0,
+        };
+        entry.count++;
+        languages.set(entry.name, entry);
+    }
+    const stars = Array.from({ length: LAYOUT.stars }, () => ({
+        x: rng() * LAYOUT.width,
+        y: rng() * LAYOUT.height,
+        s: rng() < 0.07 ? 2 : 1,
+        a: 30 + rng() * 140,
+        cycles: 1 + Math.floor(rng() * 3),
+        off: rng(),
+    }));
+    // A faint band of dust crossing behind the orbits, bottom left to top right.
+    const dust = Array.from({ length: LAYOUT.dust }, () => {
+        const t = rng();
+        const spread = (rng() + rng() + rng() - 1.5) * 70;
+        return {
+            x: 380 + t * 960 + spread * 0.4,
+            y: 430 - t * 470 + spread,
+            a: 6 + rng() * 26,
+            warm: rng() < 0.35,
+        };
+    });
+    return {
+        planets,
+        totalStars: repos.reduce((sum, r) => sum + r.stars, 0),
+        languages: [...languages.values()]
+            .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name))
+            .slice(0, 3),
+        stars,
+        dust,
+    };
+}
+function rgbToHsl([r, g, b]) {
+    const [rn, gn, bn] = [r / 255, g / 255, b / 255];
+    const max = Math.max(rn, gn, bn);
+    const min = Math.min(rn, gn, bn);
+    const l = (max + min) / 2;
+    if (max === min)
+        return [0, 0, l];
+    const d = max - min;
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    const h = max === rn
+        ? (gn - bn) / d + (gn < bn ? 6 : 0)
+        : max === gn
+            ? (bn - rn) / d + 2
+            : (rn - gn) / d + 4;
+    return [h / 6, s, l];
+}
+function hslToRgb(h, s, l) {
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    const channel = (t) => {
+        const k = (t + 1) % 1;
+        const v = k < 1 / 6
+            ? p + (q - p) * 6 * k
+            : k < 1 / 2
+                ? q
+                : k < 2 / 3
+                    ? p + (q - p) * (2 / 3 - k) * 6
+                    : p;
+        return Math.round(v * 255);
+    };
+    return [channel(h + 1 / 3), channel(h), channel(h - 1 / 3)];
+}

package/dist/styles/repo-galaxy/index.js

@@ -0,0 +1,14 @@
+import { fetchRepos, reposSchema } from '../../core/data/repos.js';
+import { buildGalaxy } from './galaxy.js';
+import { options } from './options.js';
+import { createGalaxySketch } from './sketch.js';
+export const repoGalaxy = {
+    id: 'repo-galaxy',
+    fps: 25,
+    frames: 300,
+    data: { name: 'repos', schema: reposSchema, fetch: fetchRepos },
+    options,
+    createSketch({ login, data, options, identity, rng }) {
+        return createGalaxySketch(buildGalaxy(data, rng, options), identity, login, rng);
+    },
+};

package/dist/styles/repo-galaxy/options.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { MAX_REPOS } from '../../core/data/repos.js';
+export const options = z
+    .object({
+    /** Number of repositories shown, most starred first. */
+    max_repos: z.coerce.number().int().min(5).max(MAX_REPOS).default(20),
+    /** Include forked repositories. */
+    include_forks: z.stringbool().default(false),
+    /** Name the three most starred repositories. */
+    labels: z.enum(['top3', 'none']).default('top3'),
+})
+    .strict();

package/dist/styles/repo-galaxy/sketch.js

@@ -0,0 +1,407 @@
+import { LAYOUT, RINGS } from './galaxy.js';
+const PALETTE = {
+    skyTop: '#060914',
+    skyMid: '#0d1228',
+    skyFloor: '#0a0d1c',
+    /** Shadow side of planets. */
+    night: [6, 9, 20],
+    brass: [217, 178, 111],
+    sun: [255, 243, 214],
+    ink: '#f2ede3',
+    muted: '#8e93a8',
+};
+const SANS = 'Space Grotesk';
+const MONO = 'JetBrains Mono';
+const TEXT_X = 48;
+const PROMPT = '~/repos';
+/**
+ * Rays around the sun, long and short in turn. They rotate by one long-short
+ * pair (two spacings) per loop, so the loop closes.
+ */
+const RAYS = 12;
+/** Trail length along the orbit, px. */
+const TRAIL = 110;
+/** Where orbit names sit: the far side, left of the sun's crown. */
+const RING_LABEL_ANGLE = -Math.PI / 2 - 0.42;
+const { width: W, height: H, cx: CX, cy: CY, tilt: TILT, aspect: ASPECT } = LAYOUT;
+const COS_T = Math.cos(TILT);
+const SIN_T = Math.sin(TILT);
+/** 0..1, periodic in `phase`, so every animated value loops seamlessly. */
+function wave(phase, cycles, off) {
+    return 0.5 + 0.5 * Math.sin(Math.PI * 2 * (phase * cycles + off));
+}
+/** Screen position of angle `a` on an orbit of half-width `rx`. */
+function project(rx, a) {
+    const x = rx * Math.cos(a);
+    const y = rx * ASPECT * Math.sin(a);
+    return { x: CX + x * COS_T - y * SIN_T, y: CY + x * SIN_T + y * COS_T };
+}
+/** -1 at the far side of the plane, 1 at the near side. */
+const depthOf = (a) => Math.sin(a);
+function rgba([r, g, b], a) {
+    return `rgba(${r},${g},${b},${a.toFixed(3)})`;
+}
+/** 1234 -> "1.2k" */
+function compact(n) {
+    if (n < 1000)
+        return String(n);
+    const k = n / 1000;
+    return `${k >= 100 ? Math.round(k) : Number(k.toFixed(1))}k`;
+}
+/** "https://www.example.com/" -> "www.example.com" */
+function displayUrl(url) {
+    return url.replace(/^[a-z]+:\/\//i, '').replace(/\/+$/, '');
+}
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+export function createGalaxySketch(galaxy, identity, login, rng) {
+    const grainSeed = Math.floor(rng() * 2 ** 31);
+    let sky;
+    let grain;
+    function renderSky(p) {
+        const g = p.createGraphics(W, H);
+        g.pixelDensity(1);
+        const ctx = g.drawingContext;
+        const grad = ctx.createLinearGradient(0, 0, 0, H);
+        grad.addColorStop(0, PALETTE.skyTop);
+        grad.addColorStop(0.7, PALETTE.skyMid);
+        grad.addColorStop(1, PALETTE.skyFloor);
+        ctx.fillStyle = grad;
+        ctx.fillRect(0, 0, W, H);
+        // Cool haze on the far right, warm light around the sun.
+        const haze = ctx.createRadialGradient(1180, 60, 0, 1180, 60, 520);
+        haze.addColorStop(0, 'rgba(111,120,220,0.10)');
+        haze.addColorStop(1, 'rgba(111,120,220,0)');
+        ctx.fillStyle = haze;
+        ctx.fillRect(0, 0, W, H);
+        const warm = ctx.createRadialGradient(CX, CY, 0, CX, CY, 420);
+        warm.addColorStop(0, 'rgba(217,178,111,0.20)');
+        warm.addColorStop(0.35, 'rgba(217,178,111,0.06)');
+        warm.addColorStop(1, 'rgba(217,178,111,0)');
+        ctx.fillStyle = warm;
+        ctx.fillRect(0, 0, W, H);
+        for (const d of galaxy.dust) {
+            ctx.fillStyle = d.warm ? `rgba(240,214,170,${d.a / 255})` : `rgba(190,200,255,${d.a / 255})`;
+            ctx.fillRect(d.x, d.y, 1, 1);
+        }
+        return g;
+    }
+    function renderGrain(p) {
+        const g = p.createGraphics(W, H);
+        g.pixelDensity(1);
+        g.noStroke();
+        let s = grainSeed;
+        const next = () => {
+            s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
+            return s / 4294967296;
+        };
+        for (let i = 0; i < LAYOUT.grain; i++) {
+            g.fill(255, 4 + next() * 8);
+            g.rect(next() * W, next() * H, 1, 1);
+        }
+        return g;
+    }
+    function drawStars(p, phase) {
+        p.noStroke();
+        for (const s of galaxy.stars) {
+            p.fill(226, 232, 250, s.a * (0.3 + 0.7 * wave(phase, s.cycles, s.off)));
+            p.rect(s.x, s.y, s.s, s.s);
+        }
+    }
+    /** One half of every orbit: the far half (behind the sun) or the near half. */
+    function drawOrbits(ctx, near) {
+        const [start, end] = near ? [0, Math.PI] : [Math.PI, Math.PI * 2];
+        ctx.lineWidth = 0.8;
+        RINGS.forEach((ring, i) => {
+            const outer = i === RINGS.length - 1;
+            ctx.strokeStyle = rgba(PALETTE.brass, (near ? 0.42 : 0.2) + (outer ? 0.08 : 0));
+            ctx.setLineDash(outer ? [] : [1, 4]);
+            ctx.beginPath();
+            ctx.ellipse(CX, CY, ring.rx, ring.rx * ASPECT, TILT, start, end);
+            ctx.stroke();
+        });
+        ctx.setLineDash([]);
+        // Dial on the outer orbit: a tick every 6 degrees, a long one every 30.
+        const rx = RINGS[RINGS.length - 1].rx;
+        ctx.strokeStyle = rgba(PALETTE.brass, near ? 0.5 : 0.24);
+        ctx.lineWidth = 0.7;
+        ctx.beginPath();
+        for (let k = 0; k < 60; k++) {
+            const a = (k / 60) * Math.PI * 2;
+            if (depthOf(a) >= 0 !== near)
+                continue;
+            const inner = project(rx + 3, a);
+            const outerPt = project(rx + (k % 5 === 0 ? 11 : 6), a);
+            ctx.moveTo(inner.x, inner.y);
+            ctx.lineTo(outerPt.x, outerPt.y);
+        }
+        ctx.stroke();
+    }
+    function drawRingLabels(p) {
+        const ctx = p.drawingContext;
+        p.textFont(MONO);
+        p.textStyle(p.NORMAL);
+        p.textSize(9);
+        p.noStroke();
+        ctx.letterSpacing = '1.5px';
+        p.textAlign(p.CENTER, p.BASELINE);
+        for (const ring of RINGS) {
+            const at = project(ring.rx, RING_LABEL_ANGLE);
+            p.fill(217, 178, 111, 130);
+            p.text(ring.label, at.x, at.y - 5);
+        }
+        ctx.letterSpacing = '0px';
+    }
+    function place(planet, phase) {
+        const ring = RINGS[planet.ring];
+        const a = planet.angle + Math.PI * 2 * ring.revs * phase;
+        const { x, y } = project(ring.rx, a);
+        const depth = depthOf(a);
+        return { planet, a, x, y, depth, r: planet.r * (1 + 0.16 * depth) };
+    }
+    function drawTrail(ctx, pl, light) {
+        const rx = RINGS[pl.planet.ring].rx;
+        const span = TRAIL / rx;
+        const steps = 24;
+        ctx.lineCap = 'round';
+        let prev = project(rx, pl.a);
+        for (let k = 1; k <= steps; k++) {
+            const pt = project(rx, pl.a - (span * k) / steps);
+            const fade = 1 - k / steps;
+            ctx.strokeStyle = rgba(pl.planet.color, 0.45 * fade * fade * light);
+            ctx.lineWidth = Math.max(0.6, pl.r * 0.55 * fade);
+            ctx.beginPath();
+            ctx.moveTo(prev.x, prev.y);
+            ctx.lineTo(pt.x, pt.y);
+            ctx.stroke();
+            prev = pt;
+        }
+    }
+    /** A lit sphere: bright toward the sun, shadowed on the far side. */
+    function drawPlanet(ctx, pl) {
+        const { x, y, r, planet } = pl;
+        const light = 0.62 + 0.38 * ((pl.depth + 1) / 2);
+        drawTrail(ctx, pl, light);
+        // A soft glow on the larger planets only; small ones stay crisp.
+        if (r >= 7) {
+            const halo = ctx.createRadialGradient(x, y, r * 0.8, x, y, r * 2);
+            halo.addColorStop(0, rgba(planet.color, 0.2 * light));
+            halo.addColorStop(1, rgba(planet.color, 0));
+            ctx.fillStyle = halo;
+            ctx.fillRect(x - r * 2, y - r * 2, r * 4, r * 4);
+        }
+        const ring = planet.rank === 0 && planet.stars > 0;
+        if (ring)
+            drawPlanetRing(ctx, pl, false, light);
+        // Direction from the sun, for the shadow side.
+        const dx = x - CX;
+        const dy = y - CY;
+        const len = Math.hypot(dx, dy) || 1;
+        const ux = dx / len;
+        const uy = dy / len;
+        ctx.save();
+        ctx.beginPath();
+        ctx.arc(x, y, r, 0, Math.PI * 2);
+        ctx.fillStyle = rgba(planet.color, light);
+        ctx.fill();
+        ctx.clip();
+        ctx.fillStyle = rgba(PALETTE.night, 0.62);
+        ctx.beginPath();
+        ctx.arc(x + ux * r * 0.95, y + uy * r * 0.95, r * 1.08, 0, Math.PI * 2);
+        ctx.fill();
+        ctx.fillStyle = `rgba(255,255,255,${(0.35 * light).toFixed(3)})`;
+        ctx.beginPath();
+        ctx.arc(x - ux * r * 0.45, y - uy * r * 0.45, r * 0.32, 0, Math.PI * 2);
+        ctx.fill();
+        ctx.restore();
+        if (ring)
+            drawPlanetRing(ctx, pl, true, light);
+    }
+    /** The most starred repo wears a ring, split so the planet sits inside it. */
+    function drawPlanetRing(ctx, pl, near, light) {
+        const [start, end] = near ? [0, Math.PI] : [Math.PI, Math.PI * 2];
+        ctx.lineCap = 'butt';
+        for (const [scale, width, alpha] of [
+            [2.05, 1.6, 0.75],
+            [1.6, 0.8, 0.45],
+        ]) {
+            ctx.strokeStyle = rgba(PALETTE.brass, alpha * light);
+            ctx.lineWidth = width;
+            ctx.beginPath();
+            ctx.ellipse(pl.x, pl.y, pl.r * scale, pl.r * scale * 0.32, -0.32, start, end);
+            ctx.stroke();
+        }
+    }
+    function drawSun(p, phase) {
+        const ctx = p.drawingContext;
+        const pulse = wave(phase, 1, 0);
+        const corona = ctx.createRadialGradient(CX, CY, 8, CX, CY, 64 + pulse * 10);
+        corona.addColorStop(0, rgba(PALETTE.sun, 0.55));
+        corona.addColorStop(0.3, rgba(PALETTE.brass, 0.22));
+        corona.addColorStop(1, rgba(PALETTE.brass, 0));
+        ctx.fillStyle = corona;
+        ctx.fillRect(CX - 80, CY - 80, 160, 160);
+        ctx.strokeStyle = rgba(PALETTE.brass, 0.4);
+        ctx.lineWidth = 0.8;
+        ctx.beginPath();
+        const turn = (phase * Math.PI * 4) / RAYS;
+        for (let k = 0; k < RAYS; k++) {
+            const a = turn + (k / RAYS) * Math.PI * 2;
+            const len = k % 2 === 0 ? 20 : 11;
+            ctx.moveTo(CX + Math.cos(a) * 22, CY + Math.sin(a) * 22);
+            ctx.lineTo(CX + Math.cos(a) * (22 + len), CY + Math.sin(a) * (22 + len));
+        }
+        ctx.stroke();
+        const core = ctx.createRadialGradient(CX - 4, CY - 4, 1, CX, CY, 15);
+        core.addColorStop(0, '#ffffff');
+        core.addColorStop(0.6, rgba(PALETTE.sun, 1));
+        core.addColorStop(1, rgba([246, 206, 140], 1));
+        ctx.fillStyle = core;
+        ctx.beginPath();
+        ctx.arc(CX, CY, 15, 0, Math.PI * 2);
+        ctx.fill();
+        p.textFont(MONO);
+        p.textStyle(p.NORMAL);
+        p.textSize(10);
+        p.textAlign(p.CENTER, p.BASELINE);
+        p.noStroke();
+        p.fill(217, 178, 111, 200);
+        p.text(`@${login}`, CX, CY + 34);
+    }
+    function drawStarGlyph(ctx, x, y, r) {
+        ctx.beginPath();
+        for (let k = 0; k < 10; k++) {
+            const a = -Math.PI / 2 + (k * Math.PI) / 5;
+            const rr = k % 2 === 0 ? r : r * 0.45;
+            ctx.lineTo(x + Math.cos(a) * rr, y + Math.sin(a) * rr);
+        }
+        ctx.closePath();
+        ctx.fill();
+    }
+    /**
+     * Callout centered above the planet, clamped to the canvas. Its position is
+     * a continuous function of the planet's, so it never jumps between frames.
+     */
+    function drawLabel(p, pl) {
+        const ctx = p.drawingContext;
+        const light = 0.55 + 0.45 * ((pl.depth + 1) / 2);
+        const name = truncate(pl.planet.name, 22);
+        const count = compact(pl.planet.stars);
+        p.textFont(MONO);
+        p.textStyle(p.NORMAL);
+        p.textSize(11);
+        const nameW = p.textWidth(name);
+        const width = nameW + 17 + p.textWidth(count);
+        const ey = pl.y - pl.r - 16;
+        const tx = Math.min(Math.max(pl.x - width / 2, 20), W - 20 - width);
+        ctx.strokeStyle = rgba(PALETTE.brass, 0.6 * light);
+        ctx.lineWidth = 0.8;
+        ctx.beginPath();
+        ctx.moveTo(pl.x, pl.y - pl.r - 2);
+        ctx.lineTo(pl.x, ey + 8);
+        ctx.stroke();
+        // A dark tag behind the text keeps it legible when it crosses the sun.
+        ctx.fillStyle = rgba(PALETTE.night, 0.7 * light);
+        ctx.beginPath();
+        ctx.roundRect(tx - 4, ey - 8, width + 8, 16, 3);
+        ctx.fill();
+        p.textAlign(p.LEFT, p.BASELINE);
+        p.noStroke();
+        p.fill(242, 237, 227, 235 * light);
+        p.text(name, tx, ey + 4);
+        const sx = tx + nameW + 10;
+        ctx.fillStyle = rgba(PALETTE.brass, light);
+        drawStarGlyph(ctx, sx, ey + 0.5, 4.2);
+        p.fill(217, 178, 111, 255 * light);
+        p.text(count, sx + 7, ey + 4);
+    }
+    function drawText(p, phase) {
+        const x = TEXT_X;
+        const ctx = p.drawingContext;
+        const brass = PALETTE.brass;
+        p.noStroke();
+        p.textAlign(p.LEFT, p.BASELINE);
+        p.textFont(MONO);
+        p.textStyle(p.NORMAL);
+        p.textSize(13);
+        p.fill(...brass);
+        p.text(PROMPT, x, 58);
+        if (wave(phase, 3, 0) > 0.5) {
+            p.rect(x + p.textWidth(PROMPT) + 4, 47, 7, 13);
+        }
+        p.textFont(SANS);
+        p.textStyle(p.BOLD);
+        p.textSize(50);
+        ctx.letterSpacing = '3px';
+        p.fill(PALETTE.ink);
+        p.text(identity.name.toUpperCase(), x, 116);
+        ctx.letterSpacing = '0px';
+        if (identity.tagline) {
+            p.textStyle(p.NORMAL);
+            p.textSize(17);
+            p.fill(...brass);
+            p.text(identity.tagline, x, 146);
+        }
+        const count = galaxy.planets.length;
+        p.textFont(MONO);
+        p.textStyle(p.NORMAL);
+        p.textSize(11);
+        p.fill(PALETTE.muted);
+        p.text(count === 1 ? '1 REPOSITORY' : `${count} REPOSITORIES`, x, 206);
+        p.textFont(SANS);
+        p.textStyle(p.BOLD);
+        p.textSize(34);
+        p.fill(PALETTE.ink);
+        p.text(galaxy.totalStars.toLocaleString('en-US'), x, 244);
+        p.textFont(MONO);
+        p.textStyle(p.NORMAL);
+        p.textSize(11);
+        p.fill(PALETTE.muted);
+        p.text(galaxy.totalStars === 1 ? 'star' : 'stars', x, 262);
+        if (count === 0) {
+            p.text('no public repositories yet', x, 296);
+        }
+        let lx = x;
+        for (const lang of galaxy.languages) {
+            const label = truncate(lang.name, 14);
+            p.fill(...lang.color);
+            p.circle(lx + 4, 292, 7);
+            p.fill(PALETTE.muted);
+            p.text(label, lx + 14, 296);
+            lx += 14 + p.textWidth(label) + 18;
+        }
+        if (identity.website) {
+            p.textSize(12);
+            p.fill(...brass);
+            p.text(`↗ ${displayUrl(identity.website)}`, x, 350);
+        }
+    }
+    return {
+        setup(p) {
+            sky = renderSky(p);
+            grain = renderGrain(p);
+        },
+        draw(p, _frame, phase) {
+            const ctx = p.drawingContext;
+            const placed = galaxy.planets.map((pl) => place(pl, phase)).sort((a, b) => a.depth - b.depth);
+            p.image(sky, 0, 0);
+            drawStars(p, phase);
+            drawOrbits(ctx, false);
+            drawRingLabels(p);
+            for (const pl of placed)
+                if (pl.depth < 0)
+                    drawPlanet(ctx, pl);
+            drawSun(p, phase);
+            drawOrbits(ctx, true);
+            for (const pl of placed)
+                if (pl.depth >= 0)
+                    drawPlanet(ctx, pl);
+            for (const pl of placed)
+                if (pl.planet.label)
+                    drawLabel(p, pl);
+            drawText(p, phase);
+            p.image(grain, 0, 0);
+        },
+    };
+}

package/package.json

@@ -1,15 +1,24 @@
 {
   "name": "headreel",
-  "version": "1.0.0",
-  "description": "Animated GitHub profile banner, rendered from your GitHub data. GitHub Action and CLI.",
+  "version": "1.2.0",
+  "description": "Animated GitHub profile banner made from your GitHub activity, with a GitHub Action or CLI.",
   "keywords": [
     "github",
-    "profile",
+    "github-profile",
+    "github-profile-readme",
+    "profile-readme",
     "readme",
     "banner",
     "gif",
+    "animation",
     "github-action",
-    "contributions"
+    "github-actions",
+    "cli",
+    "npx",
+    "contributions",
+    "contribution-graph",
+    "generative-art",
+    "p5js"
   ],
   "homepage": "https://github.com/arifszn/headreel#readme",
   "bugs": {