headreel 1.5.0 → 1.6.0

package/README.md

@@ -5,7 +5,7 @@
 [![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 GitHub activity.
+Animated banners for your GitHub profile, made from your GitHub activity.
 
 ![Contribution City banner](https://raw.githubusercontent.com/arifszn/headreel/main/docs/samples/contribution-city.gif)
 
@@ -18,8 +18,7 @@ Pick one way to make your banner:
 
 The Action is on the [GitHub Marketplace](https://github.com/marketplace/actions/headreel).
 
-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`:
+1. Add `.github/workflows/headreel.yml` to your repository:
 
    ```yaml
    name: headreel
@@ -45,8 +44,8 @@ The Action is on the [GitHub Marketplace](https://github.com/marketplace/actions
              website: https://example.com
    ```
 
-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:
+2. Run the workflow once from the **Actions** tab. It adds `headreel.gif` to the `headreel` branch.
+3. 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](https://raw.githubusercontent.com/octocat/octocat/headreel/headreel.gif)
@@ -68,7 +67,7 @@ Run this command. Replace `octocat` with your GitHub username.
 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`.
+The command saves `headreel.gif` in the current folder. Add the file to your repository, and add `![My GitHub activity](headreel.gif)` to its `README.md`.
 
 You need:
 
@@ -180,6 +179,24 @@ Set the style with `style: <name>` in the Action, or `--style <name>` in the com
 <tr>
 <td>
 
+### Trail Profile
+
+`trail-profile`: your last 12 months as a hiking trail's elevation profile on printed survey paper. Each week's contributions are the trail's elevation, drawn as a profile line with contour strata and engraved relief below it. A hiker marker walks the trail to your busiest week, the summit, and holds on its flag.
+
+![Trail Profile banner](https://raw.githubusercontent.com/arifszn/headreel/main/docs/samples/trail-profile.gif)
+
+| Option   | Default  | Description                                                                                    |
+| -------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `accent` | `sienna` | Profile line, strata and links: `sienna`, `cobalt`, `green` or `violet`. The paper stays buff. |
+
+</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.

package/dist/core/camera.js

@@ -0,0 +1,68 @@
+/**
+ * One camera over one world: a key list `{ frame, x, y, z }` interpolated with
+ * a single travel curve, so almost all motion happens in the middle third of a
+ * move (Highlights Reel's camera, shared with Trail Profile).
+ *
+ * Zoom travels in log space, so leaving a deep push-in pulls back as fast as it
+ * pans. A long move dips its zoom at the midpoint and pushes in to land; short
+ * hops stay flat. Held shots are still, and `frameFloat` wraps so `t = 1` snaps
+ * bitwise to `t = 0`, closing the loop to the pixel.
+ */
+/** The default travel curve: almost all motion happens in the middle third. */
+export const easeQuartic = (t) => t < 0.5 ? 8 * t ** 4 : 1 - (-2 * t + 2) ** 4 / 2;
+/** A gentler cruise, used for long flights: cubic in-out. */
+export const easeCubic = (t) => (t < 0.5 ? 4 * t ** 3 : 1 - (-2 * t + 2) ** 3 / 2);
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+/** The camera between keys: one curve, with a zoom dip on long moves. */
+export function shotAt(keys, frame, opts) {
+    const ease = opts.ease ?? easeQuartic;
+    if (frame <= keys[0].frame) {
+        return { x: keys[0].x, y: keys[0].y, z: keys[0].z };
+    }
+    const last = keys[keys.length - 1];
+    if (frame >= last.frame) {
+        return { x: last.x, y: last.y, z: last.z };
+    }
+    let index = 0;
+    while (index < keys.length - 2 && keys[index + 1].frame <= frame) {
+        index++;
+    }
+    const from = keys[index];
+    const to = keys[index + 1];
+    const t = clamp01((frame - from.frame) / (to.frame - from.frame));
+    const travelled = ease(t);
+    const distance = Math.hypot(to.x - from.x, to.y - from.y);
+    const dip = distance > opts.travel
+        ? 1 - 0.22 * Math.sin(Math.PI * t) * Math.min(1, distance / opts.span)
+        : 1;
+    return {
+        x: from.x + (to.x - from.x) * travelled,
+        y: from.y + (to.y - from.y) * travelled,
+        z: from.z * (to.z / from.z) ** travelled * dip,
+    };
+}
+/**
+ * The camera at a moment of the loop. Held shots are still: any drift, even in
+ * whole-pixel steps, reads as the scene stepping or the type vibrating.
+ */
+export function cameraAt(keys, frameFloat, frames, opts) {
+    // t = 1 snaps to 0, so the last frame is bit-identical to the first.
+    const t = frameFloat >= frames ? 0 : (((frameFloat / frames) % 1) + 1) % 1;
+    return shotAt(keys, t * frames, opts);
+}
+/** How fast the frame is moving, in screen pixels, zoom included. */
+export function speedAt(keys, frameFloat, frames, opts) {
+    const now = cameraAt(keys, frameFloat, frames, opts);
+    const before = cameraAt(keys, frameFloat - 1, frames, opts);
+    return ((Math.hypot(now.x - before.x, now.y - before.y) + Math.abs(now.z - before.z) * 700) * now.z);
+}
+/**
+ * Applies the world transform, snapped to whole screen pixels. At a fixed zoom
+ * the drift then moves the scene in 1 px steps instead of resampling every
+ * glyph each frame at a new sub-pixel offset, which reads as vibrating type.
+ * `(cx, cy)` is the viewport's centre in screen space.
+ */
+export function applyCamera(ctx, cam, cx, cy) {
+    ctx.translate(Math.round(cx - cam.x * cam.z), Math.round(cy - cam.y * cam.z));
+    ctx.scale(cam.z, cam.z);
+}

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

@@ -1,3 +1,4 @@
+import { applyCamera, cameraAt, speedAt } from '../../core/camera.js';
 import { fitIdentity } from '../../core/text.js';
 import { FRAMES, LAYOUT, plateAt, stationOf, } from './reel.js';
 /**
@@ -26,8 +27,8 @@ const TAU = Math.PI * 2;
 export const IDENTITY_COLUMN = 440 - 48;
 const clamp01 = (v) => Math.min(1, Math.max(0, v));
 const easeOutCubic = (t) => 1 - (1 - t) ** 3;
-/** The one travel curve: almost all motion happens in the middle third. */
-const travelEase = (t) => (t < 0.5 ? 8 * t ** 4 : 1 - (-2 * t + 2) ** 4 / 2);
+/** Camera tuning: moves longer than `travel` dip their zoom, scaled to `span`. */
+const CAMERA = { travel: LAYOUT.travel, span: 2400 };
 function smoothstep(e0, e1, x) {
     const t = clamp01((x - e0) / (e1 - e0));
     return t * t * (3 - 2 * t);
@@ -88,51 +89,10 @@ export function createReelSketch(reel, identity) {
         website: identity.website && `↗ ${displayUrl(identity.website)}`,
     }, IDENTITY_COLUMN);
     // --- camera ---------------------------------------------------------------
-    /** The camera between keys: one curve, with a zoom dip on long moves. */
-    function rawShot(frame) {
-        const keys = reel.plan.keys;
-        if (frame <= keys[0].frame) {
-            return { x: keys[0].x, y: keys[0].y, z: keys[0].z };
-        }
-        const last = keys[keys.length - 1];
-        if (frame >= last.frame) {
-            return { x: last.x, y: last.y, z: last.z };
-        }
-        let index = 0;
-        while (index < keys.length - 2 && keys[index + 1].frame <= frame) {
-            index++;
-        }
-        const from = keys[index];
-        const to = keys[index + 1];
-        const t = clamp01((frame - from.frame) / (to.frame - from.frame));
-        const travelled = travelEase(t);
-        const distance = Math.hypot(to.x - from.x, to.y - from.y);
-        // Zoom travels in log space, so leaving a deep push-in pulls back as fast
-        // as it pans. A long move also dips at its midpoint and pushes in to land.
-        const dip = distance > LAYOUT.travel
-            ? 1 - 0.22 * Math.sin(Math.PI * t) * Math.min(1, distance / 2400)
-            : 1;
-        return {
-            x: from.x + (to.x - from.x) * travelled,
-            y: from.y + (to.y - from.y) * travelled,
-            z: from.z * (to.z / from.z) ** travelled * dip,
-        };
-    }
-    /**
-     * The camera at a moment of the loop. Held shots are still: any drift, even
-     * in whole-pixel steps, reads as the cards stepping or the type vibrating.
-     */
-    function camera(frameFloat) {
-        // t = 1 snaps to 0, so the last frame is bit-identical to the first.
-        const t = frameFloat >= FRAMES ? 0 : (((frameFloat / FRAMES) % 1) + 1) % 1;
-        return rawShot(t * FRAMES);
-    }
+    /** The camera at a moment of the loop (see `core/camera.ts`). */
+    const camera = (frameFloat) => cameraAt(reel.plan.keys, frameFloat, FRAMES, CAMERA);
     /** How fast the frame is moving, in screen pixels, zoom included. */
-    function speedOf(frameFloat) {
-        const now = camera(frameFloat);
-        const before = camera(frameFloat - 1);
-        return ((Math.hypot(now.x - before.x, now.y - before.y) + Math.abs(now.z - before.z) * 700) * now.z);
-    }
+    const speedOf = (frameFloat) => speedAt(reel.plan.keys, frameFloat, FRAMES, CAMERA);
     /** A card builds while the camera arrives; an empty window means already finished. */
     function buildAt(window, frameFloat) {
         if (window.end <= window.start)
@@ -535,11 +495,10 @@ export function createReelSketch(reel, identity) {
         setFill(ctx, PALETTE.desk);
         ctx.fillRect(0, 0, W, H);
         ctx.save();
-        // Snap the world to whole screen pixels. At a fixed zoom the drift then
-        // moves the cards in 1 px steps instead of resampling every glyph each
-        // frame at a new sub-pixel offset, which reads as vibrating type.
-        ctx.translate(Math.round(W / 2 - cam.x * cam.z), Math.round(H / 2 - cam.y * cam.z));
-        ctx.scale(cam.z, cam.z);
+        // Snap the world to whole screen pixels (see `applyCamera`): at a fixed
+        // zoom the drift then moves the cards in 1 px steps instead of resampling
+        // every glyph each frame at a new sub-pixel offset.
+        applyCamera(ctx, cam, W / 2, H / 2);
         drawDots(ctx, cam, speed);
         for (let i = 0; i < reel.cards.length; i++)
             drawMarks(ctx, i);

package/dist/styles/index.js

@@ -3,6 +3,7 @@ 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';
+import { trailProfile } from './trail-profile/index.js';
 /** Built-in styles, keyed by id. */
 export const styles = {
     [contributionCity.id]: contributionCity,
@@ -10,4 +11,5 @@ export const styles = {
     [nowPlaying.id]: nowPlaying,
     [receipt.id]: receipt,
     [repoGalaxy.id]: repoGalaxy,
+    [trailProfile.id]: trailProfile,
 };

package/dist/styles/trail-profile/index.js

@@ -0,0 +1,16 @@
+import { contributionsSchema, fetchContributions, } from '../../core/data/contributions.js';
+import { buildTrail, FRAMES } from './trail.js';
+import { options } from './options.js';
+import { paletteOf, pinnedOf } from './palette.js';
+import { createTrailSketch } from './sketch.js';
+export const trailProfile = {
+    id: 'trail-profile',
+    fps: 25,
+    frames: FRAMES,
+    pinned: (o) => pinnedOf(paletteOf(o)),
+    data: { name: 'contributions', schema: contributionsSchema, fetch: fetchContributions },
+    options,
+    createSketch({ data, identity, options, rng }) {
+        return createTrailSketch(buildTrail(data, identity, paletteOf(options)), rng);
+    },
+};

package/dist/styles/trail-profile/options.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export const ACCENTS = ['sienna', 'cobalt', 'green', 'violet'];
+export const options = z
+    .object({
+    /** Color of the profile line, strata, tagline and website. */
+    accent: z.enum(ACCENTS).default('sienna'),
+})
+    .strict();

package/dist/styles/trail-profile/palette.js

@@ -0,0 +1,50 @@
+/** `over` at `alpha` over `base`, both opaque. */
+export function blend(over, base, alpha) {
+    return [
+        Math.round(over[0] * alpha + base[0] * (1 - alpha)),
+        Math.round(over[1] * alpha + base[1] * (1 - alpha)),
+        Math.round(over[2] * alpha + base[2] * (1 - alpha)),
+    ];
+}
+/** Survey-map contour brown, new to this style; the others keep shared names. */
+const ACCENT_VALUES = {
+    sienna: [138, 75, 34], // #8A4B22
+    cobalt: [47, 85, 212], // #2F55D4
+    green: [31, 107, 58], // #1F6B3A
+    violet: [106, 63, 200], // #6A3FC8
+};
+const BASE = {
+    paper: [243, 239, 227], // #F3EFE3
+    ink: [43, 38, 32], // #2B2620
+    muted: [107, 99, 88], // #6B6358
+    graticule: [47, 111, 168], // #2F6FA8
+    flag: [200, 16, 46], // #C8102E
+};
+export function paletteOf(options) {
+    const accent = ACCENT_VALUES[options.accent];
+    const paper = BASE.paper;
+    return {
+        ...BASE,
+        accent,
+        // Pre-blended solids, drawn opaque so the encoder can pin them: alpha
+        // strokes anti-alias into a ramp of near-identical colors that dithers
+        // and re-shuffles every frame the camera moves.
+        strata: blend(accent, paper, 0.6),
+        graticule: blend(BASE.graticule, paper, 0.35),
+        stipple: blend(BASE.ink, paper, 0.55),
+        grid: blend(BASE.ink, paper, 0.15),
+    };
+}
+/** Flat colors the encoder keeps exact and undithered. */
+export function pinnedOf(palette) {
+    return [
+        palette.paper,
+        palette.ink,
+        palette.accent,
+        palette.flag,
+        palette.strata,
+        palette.graticule,
+        palette.stipple,
+        palette.grid,
+    ];
+}

package/dist/styles/trail-profile/profile.js

@@ -0,0 +1,231 @@
+/**
+ * The contribution calendar as a trail profile: one column per week, each
+ * week's total the trail's elevation at that point of the year.
+ *
+ * Elevation is built so the busiest week is always the highest point, and the
+ * line never shows a peak the data does not have: weekly totals sit at their
+ * column centres and are joined with monotone cubic interpolation
+ * (Fritsch-Carlson), which never overshoots. The profile peaks at exactly the
+ * summit total at the busiest week (ties go to the latest week), and it stays
+ * on the ground line across empty weeks and the flat margins.
+ *
+ * Heights are in contributions per week. The profile is sampled once (every 4
+ * world units) and simplified (Ramer-Douglas-Peucker, epsilon 1); the strata
+ * spans, the x ranges where the trail is above each level, are computed once
+ * here. Nothing is derived per frame.
+ */
+/** One week column; one empty column flanks the calendar on each side. */
+export const CELL = 48;
+/** The sheet is 2.2:1, the viewport's aspect, so the wide shot fills the frame. */
+export const WORLD_H = 1200;
+/** World y of elevation 0, and of the summit (the busiest week). */
+export const GROUND_Y = 1080;
+export const SUMMIT_Y = 300;
+/** Profile sampling pitch and simplification, world units. */
+const SAMPLE = 4;
+const SPAN_SAMPLE = 2;
+const RDP_EPSILON = 1;
+export const MAX_LEVELS = 8;
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+/**
+ * The contour interval: the smallest of 1, 2, 5, 10, 20, 50, ... that gives at
+ * most `MAX_LEVELS` levels up to the summit, never below 1 contribution.
+ */
+export function contourInterval(summit) {
+    const series = [];
+    for (let pow = 1; pow <= 1e6; pow *= 10)
+        series.push(pow, pow * 2, pow * 5);
+    return series.find((step) => Math.floor(summit / step) <= MAX_LEVELS) ?? series.at(-1);
+}
+/**
+ * Fritsch-Carlson monotone cubic interpolation over uniformly spaced nodes:
+ * the curve never overshoots, so it stays 0 across a run of empty weeks and
+ * peaks at exactly the node value at a peak node.
+ */
+export function monotoneCubic(nodes, pitch, x0) {
+    const n = nodes.length;
+    const delta = [];
+    for (let i = 0; i < n - 1; i++)
+        delta.push((nodes[i + 1] - nodes[i]) / pitch);
+    const m = Array.from({ length: n });
+    m[0] = delta[0] ?? 0;
+    m[n - 1] = delta[n - 2] ?? 0;
+    for (let i = 1; i < n - 1; i++) {
+        if (delta[i - 1] * delta[i] <= 0) {
+            m[i] = 0;
+            continue;
+        }
+        // Weighted harmonic mean of the two segment slopes (equal pitches here),
+        // which never exceeds either in magnitude, so the curve stays monotone.
+        m[i] = (2 * delta[i - 1] * delta[i]) / (delta[i - 1] + delta[i]);
+    }
+    return (x) => {
+        if (n === 1)
+            return nodes[0];
+        const u = clamp((x - x0) / pitch, 0, n - 1);
+        const i = Math.min(Math.floor(u), n - 2);
+        const t = u - i;
+        const t2 = t * t;
+        const t3 = t2 * t;
+        return ((2 * t3 - 3 * t2 + 1) * nodes[i] +
+            (t3 - 2 * t2 + t) * pitch * m[i] +
+            (-2 * t3 + 3 * t2) * nodes[i + 1] +
+            (t3 - t2) * pitch * m[i + 1]);
+    };
+}
+/** Ramer-Douglas-Peucker, iterative. */
+function simplify(points, epsilon) {
+    if (points.length < 3)
+        return points;
+    const keep = new Uint8Array(points.length);
+    keep[0] = 1;
+    keep[points.length - 1] = 1;
+    const stack = [[0, points.length - 1]];
+    while (stack.length > 0) {
+        const [lo, hi] = stack.pop();
+        if (hi - lo < 2)
+            continue;
+        const [ax, ay] = points[lo];
+        const [bx, by] = points[hi];
+        const dx = bx - ax;
+        const dy = by - ay;
+        const len = Math.hypot(dx, dy) || 1;
+        let far = -1;
+        let dist = 0;
+        for (let i = lo + 1; i < hi; i++) {
+            const [px, py] = points[i];
+            const d = Math.abs((px - ax) * dy - (py - ay) * dx) / len;
+            if (d > dist) {
+                dist = d;
+                far = i;
+            }
+        }
+        if (dist > epsilon && far > 0) {
+            keep[far] = 1;
+            stack.push([lo, far], [far, hi]);
+        }
+    }
+    return points.filter((_, i) => keep[i]);
+}
+/** The x ranges where the trail is at or above `level` contributions. */
+function spansAbove(trail, level, x0, x1) {
+    const spans = [];
+    const f = (x) => trail(x) - level;
+    let start = null;
+    let prevX = x0;
+    let prevF = f(x0);
+    if (prevF >= 0)
+        start = x0;
+    for (let x = x0 + SPAN_SAMPLE; x <= x1 + 1e-9; x += SPAN_SAMPLE) {
+        const curF = f(x);
+        if (prevF < 0 && curF >= 0 && start === null) {
+            start = prevX + (SPAN_SAMPLE * -prevF) / (curF - prevF);
+        }
+        else if (prevF >= 0 && curF < 0 && start !== null) {
+            spans.push([start, prevX + (SPAN_SAMPLE * prevF) / (prevF - curF)]);
+            start = null;
+        }
+        prevX = x;
+        prevF = curF;
+    }
+    if (start !== null)
+        spans.push([start, x1]);
+    return spans;
+}
+export function buildProfile(contributions) {
+    const cols = contributions.weeks.length;
+    const world = { w: (cols + 2) * CELL, h: WORLD_H };
+    const mapArea = { x0: CELL, y0: 48, x1: world.w - CELL, y1: world.h - 48 };
+    const weekX = (i) => mapArea.x0 + (i + 0.5) * CELL;
+    // Weekly totals; days outside the window are skipped.
+    const weeks = contributions.weeks.map((week) => {
+        let total = 0;
+        for (const day of week) {
+            if (day.date < contributions.from || day.date > contributions.to)
+                continue;
+            total += day.count;
+        }
+        return { from: week[0].date, to: week.at(-1).date, total };
+    });
+    // The busiest week; ties go to the latest.
+    let summitWeek = -1;
+    let summitTotal = 0;
+    weeks.forEach(({ total }, i) => {
+        if (total >= summitTotal && total > 0) {
+            summitTotal = total;
+            summitWeek = i;
+        }
+    });
+    // Zero nodes in the margins keep the sheet's edges flat ground.
+    const trail = monotoneCubic([0, ...weeks.map((w) => w.total), 0], CELL, mapArea.x0 - CELL / 2);
+    const scale = (GROUND_Y - SUMMIT_Y) / (summitTotal || 1);
+    const profileY = (x) => GROUND_Y - trail(x) * scale;
+    const line = [];
+    for (let x = mapArea.x0; x <= mapArea.x1 + 1e-9; x += SAMPLE) {
+        line.push([Math.min(x, mapArea.x1), profileY(Math.min(x, mapArea.x1))]);
+    }
+    const summit = summitWeek >= 0
+        ? {
+            week: summitWeek,
+            total: summitTotal,
+            from: weeks[summitWeek].from,
+            to: weeks[summitWeek].to,
+            x: weekX(summitWeek),
+            y: profileY(weekX(summitWeek)),
+        }
+        : null;
+    const levels = [];
+    let interval = 0;
+    if (summit) {
+        interval = contourInterval(summit.total);
+        for (let k = 1; k * interval <= summit.total + 1e-9; k++) {
+            const height = k * interval;
+            levels.push({
+                height,
+                y: GROUND_Y - height * scale,
+                kind: k % 5 === 0 ? 'index' : 'intermediate',
+                spans: spansAbove(trail, height, mapArea.x0, mapArea.x1),
+            });
+        }
+    }
+    // Spot heights: the next 3 busiest weeks that are local maxima of the
+    // profile, at least 4 weeks from the summit and from each other.
+    const spots = [];
+    if (summit) {
+        const order = weeks
+            .map(({ total }, i) => ({ total, i }))
+            .filter(({ total, i }) => total > 0 && i !== summit.week)
+            .sort((a, b) => b.total - a.total || a.i - b.i);
+        const isPeak = (i) => {
+            const left = i > 0 ? weeks[i - 1].total : 0;
+            const right = i < weeks.length - 1 ? weeks[i + 1].total : 0;
+            const v = weeks[i].total;
+            return v >= left && v >= right && (v > left || v > right);
+        };
+        const taken = [summit.week];
+        for (const { total, i } of order) {
+            if (spots.length >= 3)
+                break;
+            if (!isPeak(i))
+                continue;
+            if (taken.some((w) => Math.abs(w - i) < 4))
+                continue;
+            taken.push(i);
+            spots.push({ week: i, total, x: weekX(i), y: profileY(weekX(i)) });
+        }
+    }
+    return {
+        cols,
+        world,
+        mapArea,
+        weeks,
+        interval,
+        levels,
+        line: simplify(line, RDP_EPSILON),
+        summit,
+        spots,
+        profileY,
+        weekX,
+        weekAt: (x) => clamp(Math.floor((x - mapArea.x0) / CELL), 0, cols - 1),
+    };
+}

package/dist/styles/trail-profile/sketch.js

@@ -0,0 +1,485 @@
+import { applyCamera, cameraAt } from '../../core/camera.js';
+import { altimeterLine, FRAMES, LAYOUT, markerAt, summitDates } from './trail.js';
+import { CELL, GROUND_Y } from './profile.js';
+import {} from './palette.js';
+/**
+ * A printed trail profile sheet, walked by one camera.
+ *
+ * Everything that covers area is flat and pinned (paper, collar), and the
+ * sheet's line work is rasterized like a plotter: the profile and the ground
+ * line as pure 1px pixel runs, the strata as horizontal spans, the relief as
+ * engraved stipple dots. This is not only the printed look the style wants -
+ * measured on the top-down draft this style replaces, anti-aliased strokes
+ * re-derive their fringes on every camera move, which dithers across a
+ * hundred colors and re-shuffles every frame, bloating the GIF to 20 MB;
+ * rasterized onto whole pixels the loop is a few MB.
+ *
+ * The collar, text, graticule, grid, spot heights, summit, marker and
+ * neatline stay vector through the raw context (style set right before each
+ * draw; see Highlights Reel's note on p5's cached fill state). Small type
+ * that would read as dithered noise at the wide shot (grid and month labels,
+ * spot figures, the summit label) fades in with zoom, as Highlights Reel's
+ * busiest-week rule does for its day cells.
+ */
+const SANS = '"Space Grotesk"';
+const MONO = '"JetBrains Mono"';
+const TAU = Math.PI * 2;
+const { width: W, height: H, viewport, collar: COLLAR } = LAYOUT;
+/** Camera dip tuning: moves longer than `travel` dip, scaled to `span`. */
+const CAMERA = { travel: LAYOUT.travel, span: LAYOUT.span };
+/** Hairline weights in screen px: the neatline's heavy rule. */
+const LINE = { neatHeavy: 2.4, neatThin: 1 };
+/** Small type appears as the camera closes in (zoom thresholds). */
+const LABEL_Z = { sheet: [0.36, 0.42], summit: [1.15, 1.5] };
+/** Screen size of the sheet's small type. */
+const LABEL_SIZE = 10;
+/** Stipple relief: engraving pitch, and the density under the profile line. */
+const STIPPLE_PITCH = 10;
+const STIPPLE_BASE = 0.05;
+const STIPPLE_MAX = 0.3;
+function viewOf(cam) {
+    return {
+        ox: Math.round(viewport.cx - cam.x * cam.z),
+        oy: Math.round(viewport.cy - cam.y * cam.z),
+        z: cam.z,
+    };
+}
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+function smoothstep(e0, e1, x) {
+    const t = clamp01((x - e0) / (e1 - e0));
+    return t * t * (3 - 2 * t);
+}
+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 setStroke(ctx, color, alpha = 1) {
+    ctx.strokeStyle = 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 = o.baseline ?? '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';
+}
+/**
+ * The relief, engraved: one stipple dot per jittered grid cell where a seeded
+ * draw falls under the cell's density. Density is highest just below the
+ * profile line and falls off with depth, so the silhouette reads at the wide
+ * shot; flat ground takes no dots, because there is nothing under it. Dots
+ * are placed once, in world space, and plotted as single pixels every frame.
+ */
+function stippleDots(model, next) {
+    const { mapArea, profileY } = model.profile;
+    const dots = [];
+    for (let y = STIPPLE_PITCH / 2; y < GROUND_Y; y += STIPPLE_PITCH) {
+        for (let x = STIPPLE_PITCH / 2; x < mapArea.x1; x += STIPPLE_PITCH) {
+            if (x < mapArea.x0)
+                continue;
+            const surface = profileY(x);
+            if (y <= surface)
+                continue;
+            const depth = (y - surface) / (GROUND_Y - surface);
+            const density = STIPPLE_BASE + STIPPLE_MAX * (1 - depth) ** 3;
+            if (next() >= density)
+                continue;
+            const jx = (next() - 0.5) * 0.8 * STIPPLE_PITCH;
+            const jy = (next() - 0.5) * 0.8 * STIPPLE_PITCH;
+            dots.push(x + jx, y + jy);
+        }
+    }
+    return dots;
+}
+/**
+ * A plotter hairline between two screen-integer points: Bresenham, batching
+ * pixels on the same row into one fillRect so a mostly-horizontal line is a
+ * few wide runs instead of one call per pixel. Segments that round to the
+ * same pixel are a single dot. `across` shifts the whole line one pixel
+ * sideways for the profile line's and the index strata's weight.
+ */
+function plotHairline(ctx, ax, ay, bx, by, across) {
+    const ox = across?.[0] ?? 0;
+    const oy = across?.[1] ?? 0;
+    let x = Math.round(ax) + ox;
+    let y = Math.round(ay) + oy;
+    const endX = Math.round(bx) + ox;
+    const endY = Math.round(by) + oy;
+    const dx = Math.abs(endX - x);
+    const dy = -Math.abs(endY - y);
+    if (dx === 0 && dy === 0) {
+        ctx.fillRect(x, y, 1, 1);
+        return;
+    }
+    const sx = x < endX ? 1 : -1;
+    const sy = y < endY ? 1 : -1;
+    let err = dx + dy;
+    let runX = x;
+    let runY = y;
+    for (;;) {
+        const lastX = x;
+        const e2 = 2 * err;
+        if (e2 >= dy) {
+            err += dy;
+            x += sx;
+        }
+        if (e2 <= dx) {
+            // The row changed: flush the run and start the next.
+            ctx.fillRect(Math.min(runX, lastX), runY, Math.abs(lastX - runX) + 1, 1);
+            err += dx;
+            y += sy;
+            runY = y;
+            runX = x;
+        }
+        if (x === endX && y === endY)
+            break;
+    }
+    ctx.fillRect(Math.min(runX, endX), runY, Math.abs(endX - runX) + 1, 1);
+}
+/** A hairline polyline, plotted with an optional second pass one pixel over. */
+function plotPolyline(ctx, view, line, across) {
+    for (let i = 1; i < line.length; i++) {
+        const ax = view.ox + line[i - 1][0] * view.z;
+        const ay = view.oy + line[i - 1][1] * view.z;
+        const bx = view.ox + line[i][0] * view.z;
+        const by = view.oy + line[i][1] * view.z;
+        plotHairline(ctx, ax, ay, bx, by, null);
+        if (across)
+            plotHairline(ctx, ax, ay, bx, by, across);
+    }
+}
+export function createTrailSketch(model, next) {
+    const P = model.palette;
+    const { profile } = model;
+    const { mapArea, world } = profile;
+    // Pure geometry, computed once.
+    let dots = [];
+    function setup(p) {
+        dots = stippleDots(model, next);
+        void p;
+    }
+    /** World point to screen integer, under the current view. */
+    const toScreen = (view, x, y) => [
+        Math.round(view.ox + x * view.z),
+        Math.round(view.oy + y * view.z),
+    ];
+    // --- world layers ---------------------------------------------------------
+    /**
+     * The elevation grid: a hairline at each index level across the sheet.
+     * Like the graticule, the lines are world-weight, so the resting wide sheet
+     * reads ruled but faint. Its labels are screen-space (`drawSheetLabels`).
+     */
+    function drawGrid(ctx) {
+        if (!profile.summit)
+            return;
+        const indexLevels = profile.levels.filter((l) => l.kind === 'index');
+        ctx.lineJoin = 'round';
+        setStroke(ctx, P.grid);
+        ctx.lineWidth = 1;
+        ctx.beginPath();
+        for (const level of indexLevels) {
+            ctx.moveTo(mapArea.x0, level.y);
+            ctx.lineTo(mapArea.x1, level.y);
+        }
+        ctx.stroke();
+    }
+    /** The graticule: a month line from the ground to the top neatline. */
+    function drawGraticule(ctx) {
+        ctx.lineJoin = 'round';
+        setStroke(ctx, P.graticule);
+        ctx.lineWidth = 1;
+        ctx.beginPath();
+        for (const mark of model.months) {
+            const x = mapArea.x0 + mark.week * CELL;
+            ctx.moveTo(x, GROUND_Y);
+            ctx.lineTo(x, mapArea.y0);
+        }
+        ctx.stroke();
+    }
+    /**
+     * The plotted sheet: strata, stipple, the ground line and the profile,
+     * rasterized in screen space and clipped to the map area, because printed
+     * sheets stop at the neatline. The dots and hairlines land on whole pixels
+     * at exact colors, so a still camera reproduces the sheet pixel for pixel
+     * and a moving one changes only the pixels a line actually crossed.
+     */
+    function drawRaster(ctx, cam, view) {
+        ctx.save();
+        ctx.setTransform(1, 0, 0, 1, 0, 0);
+        const [mx0, my0] = toScreen(view, mapArea.x0, mapArea.y0);
+        const [mx1, my1] = toScreen(view, mapArea.x1, mapArea.y1);
+        ctx.beginPath();
+        ctx.rect(mx0, my0, mx1 - mx0, my1 - my0);
+        ctx.clip();
+        const hw = (W - viewport.left) / 2 / cam.z + 8;
+        const hh = H / 2 / cam.z + 8;
+        const bounds = { x0: cam.x - hw, x1: cam.x + hw, y0: cam.y - hh, y1: cam.y + hh };
+        // Strata: the x spans where the trail is above each level, index levels
+        // plotted twice for their weight.
+        setFill(ctx, P.strata);
+        for (const level of profile.levels) {
+            if (level.y < bounds.y0 || level.y > bounds.y1)
+                continue;
+            const across = level.kind === 'index' ? [0, 1] : null;
+            for (const [x0, x1] of level.spans) {
+                if (x1 < bounds.x0 || x0 > bounds.x1)
+                    continue;
+                const ly = view.oy + level.y * view.z;
+                const ax = view.ox + x0 * view.z;
+                const bx = view.ox + x1 * view.z;
+                plotHairline(ctx, ax, ly, bx, ly, null);
+                if (across)
+                    plotHairline(ctx, ax, ly, bx, ly, across);
+            }
+        }
+        // Stipple relief. Close in, the world pitch would thin to specks, so the
+        // dots double with the summit zoom.
+        const dot = cam.z > 1.15 ? 2 : 1;
+        setFill(ctx, P.stipple);
+        for (let d = 0; d < dots.length; d += 2) {
+            const x = dots[d];
+            const y = dots[d + 1];
+            if (x < mapArea.x0 || x > mapArea.x1 || y < mapArea.y0 || y > mapArea.y1)
+                continue;
+            if (x < bounds.x0 || x > bounds.x1 || y < bounds.y0 || y > bounds.y1)
+                continue;
+            const [sx, sy] = toScreen(view, x, y);
+            ctx.fillRect(sx, sy, dot, dot);
+        }
+        // The ground line and the profile, plotted like the rest of the line work.
+        setFill(ctx, P.ink);
+        const gy = view.oy + GROUND_Y * view.z;
+        plotHairline(ctx, view.ox + mapArea.x0 * view.z, gy, view.ox + mapArea.x1 * view.z, gy, null);
+        if (profile.summit) {
+            setFill(ctx, P.accent);
+            plotPolyline(ctx, view, profile.line, [0, 1]);
+        }
+        ctx.restore();
+    }
+    /** The summit: survey triangle on the profile, flag on a pole, its figure. */
+    function drawSummit(ctx, cam, t, labelAlpha) {
+        const summit = profile.summit;
+        if (!summit)
+            return;
+        const poleTop = summit.y - 88;
+        // Survey triangle at the highest point.
+        setFill(ctx, P.ink);
+        ctx.beginPath();
+        ctx.moveTo(summit.x, summit.y - 7);
+        ctx.lineTo(summit.x + 8, summit.y + 6);
+        ctx.lineTo(summit.x - 8, summit.y + 6);
+        ctx.closePath();
+        ctx.fill();
+        setStroke(ctx, P.ink);
+        ctx.lineWidth = 2 / cam.z;
+        ctx.beginPath();
+        ctx.moveTo(summit.x, summit.y);
+        ctx.lineTo(summit.x, poleTop);
+        ctx.stroke();
+        // The flag waves only while the camera holds the summit, about one cycle
+        // per 40 frames (at least two), amplitude eased to 0 at both ends of the
+        // hold, so the wide shots at the seam match (the flag is always planted).
+        const { start, end } = model.plan.summitHold;
+        const u = end > start ? clamp01((t * FRAMES - start) / (end - start)) : 0;
+        const envelope = Math.sin(Math.PI * u);
+        const cycles = Math.max(2, Math.round((end - start) / 40));
+        const phase = cycles * TAU * u;
+        const tipX = 34 + 4 * Math.sin(phase) * envelope;
+        const sag = 3 * Math.sin(phase + 1) * envelope;
+        setFill(ctx, P.flag);
+        ctx.beginPath();
+        ctx.moveTo(summit.x, poleTop);
+        ctx.quadraticCurveTo(summit.x + tipX * 0.6, poleTop + 8 + sag, summit.x + tipX, poleTop + 8);
+        ctx.lineTo(summit.x, poleTop + 16);
+        ctx.closePath();
+        ctx.fill();
+        if (labelAlpha <= 0.02)
+            return;
+        // Beside the pole's lower half: at the hold zoom the figure's ascender
+        // would cross the frame's top edge if it sat at the flag.
+        drawText(ctx, String(summit.total), summit.x + 46, summit.y - 40, {
+            size: 30,
+            bold: true,
+            color: P.ink,
+            alpha: labelAlpha,
+        });
+        drawText(ctx, summitDates(summit.from, summit.to), summit.x + 46, summit.y - 18, {
+            size: 13,
+            mono: true,
+            color: P.muted,
+            alpha: labelAlpha,
+        });
+    }
+    /** Double frame around the map: thin inner, heavy outer. */
+    function drawNeatline(ctx, cam) {
+        ctx.lineJoin = 'miter';
+        const off = 7;
+        setStroke(ctx, P.ink);
+        ctx.lineWidth = LINE.neatHeavy / cam.z;
+        ctx.strokeRect(mapArea.x0 - off, mapArea.y0 - off, mapArea.x1 - mapArea.x0 + 2 * off, mapArea.y1 - mapArea.y0 + 2 * off);
+        ctx.lineWidth = LINE.neatThin / cam.z;
+        ctx.strokeRect(mapArea.x0, mapArea.y0, mapArea.x1 - mapArea.x0, mapArea.y1 - mapArea.y0);
+    }
+    // --- screen layers --------------------------------------------------------
+    /**
+     * The sheet's small type, at a fixed screen size so it reads at the walk
+     * zoom without swelling at the summit: elevation labels on the west
+     * neatline (or the viewport's edge), month labels under the ground line, and the spot heights (`×`
+     * and figure). Anchored to world points through the snapped view, so it
+     * moves with the sheet pixel for pixel.
+     */
+    function drawSheetLabels(ctx, view, alpha) {
+        if (alpha <= 0.02 || !profile.summit)
+            return;
+        const label = { size: LABEL_SIZE, mono: true, color: P.muted, alpha };
+        // Elevation labels ride the west neatline, or the viewport's left edge
+        // once the walk has panned the neatline out of view.
+        const wx = Math.max(toScreen(view, mapArea.x0, 0)[0], viewport.left + 4);
+        for (const level of profile.levels) {
+            if (level.kind !== 'index')
+                continue;
+            const [, y] = toScreen(view, 0, level.y);
+            drawText(ctx, String(level.height), wx + 4, y + 4, label);
+        }
+        const [, gy] = toScreen(view, 0, GROUND_Y);
+        drawText(ctx, '0', wx + 4, gy - 3, label);
+        for (const mark of model.months) {
+            const [x] = toScreen(view, mapArea.x0 + mark.week * CELL, 0);
+            drawText(ctx, mark.label, x + 3, gy + 13, label);
+        }
+        const r = 3.5;
+        ctx.lineJoin = 'round';
+        ctx.lineWidth = 1.2;
+        setStroke(ctx, P.ink, alpha);
+        ctx.beginPath();
+        for (const spot of profile.spots) {
+            const [x, y] = toScreen(view, spot.x, spot.y);
+            ctx.moveTo(x - r, y - r - 6);
+            ctx.lineTo(x + r, y + r - 6);
+            ctx.moveTo(x + r, y - r - 6);
+            ctx.lineTo(x - r, y + r - 6);
+        }
+        ctx.stroke();
+        for (const spot of profile.spots) {
+            const [x, y] = toScreen(view, spot.x, spot.y);
+            drawText(ctx, String(spot.total), x + 7, y - 3, { ...label, color: P.ink });
+        }
+    }
+    /**
+     * The hiker: an ink bead with a paper ring, centred on the profile line.
+     * Drawn in screen space at a fixed size, so the walker does not balloon
+     * with the zoom; it fades in on the descend and out on the summit arrival.
+     */
+    function drawMarker(ctx, view, marker) {
+        if (!marker || marker.alpha <= 0.02)
+            return;
+        const [sx, sy] = toScreen(view, marker.x, marker.y);
+        ctx.globalAlpha = marker.alpha;
+        setFill(ctx, P.paper);
+        ctx.beginPath();
+        ctx.arc(sx, sy, 7, 0, TAU);
+        ctx.fill();
+        setFill(ctx, P.ink);
+        ctx.beginPath();
+        ctx.arc(sx, sy, 5, 0, TAU);
+        ctx.fill();
+        ctx.globalAlpha = 1;
+    }
+    // --- collar ---------------------------------------------------------------
+    function drawScaleBar(ctx) {
+        const { px, segments } = model.collar.scale;
+        const x = COLLAR.left;
+        const y = 296;
+        const h = 5;
+        setFill(ctx, P.ink);
+        ctx.fillRect(x, y, px, h);
+        ctx.fillRect(x + 2 * px, y, px, h);
+        setStroke(ctx, P.ink);
+        ctx.lineWidth = 1;
+        ctx.strokeRect(x + 0.5, y + 0.5, segments * px - 1, h - 1);
+        for (let k = 0; k <= segments; k++) {
+            drawText(ctx, String(k * 4), x + k * px, y - 5, {
+                size: 9,
+                mono: true,
+                align: 'center',
+                color: P.muted,
+            });
+        }
+        drawText(ctx, 'WEEKS', x + segments * px + 8, y + 5, { size: 9, mono: true, color: P.muted });
+    }
+    function drawCollar(ctx, altimeter) {
+        const c = model.collar;
+        setFill(ctx, P.paper);
+        ctx.fillRect(0, 0, viewport.left, H);
+        // The double rule on the collar's right edge.
+        setFill(ctx, P.ink, 0.45);
+        ctx.fillRect(391, 0, 1, H);
+        setFill(ctx, P.ink);
+        ctx.fillRect(398, 0, 2, H);
+        const x = COLLAR.left;
+        drawText(ctx, 'TRAIL PROFILE · LAST 12 MONTHS', x, 58, {
+            size: 11,
+            mono: true,
+            tracking: 2,
+            color: P.muted,
+        });
+        drawText(ctx, c.name.text, x, 122, {
+            size: c.name.size,
+            bold: true,
+            tracking: 3,
+            color: P.ink,
+        });
+        if (c.tagline) {
+            drawText(ctx, c.tagline.text, x, 152, { size: c.tagline.size, color: P.accent });
+        }
+        drawText(ctx, c.total, x, 216, { size: 34, bold: true, color: P.ink });
+        drawText(ctx, 'contributions', x, 238, { size: 11, mono: true, color: P.muted });
+        if (altimeter) {
+            drawText(ctx, altimeter, x, 266, { size: 11, mono: true, color: P.ink });
+        }
+        drawScaleBar(ctx);
+        if (c.intervalText) {
+            drawText(ctx, c.intervalText, x, 328, { size: 10, mono: true, color: P.muted });
+        }
+        if (c.website) {
+            drawText(ctx, c.website.text, x, 352, { size: c.website.size, mono: true, color: P.accent });
+        }
+    }
+    // --- frame ----------------------------------------------------------------
+    function draw(p, _frame, t) {
+        const ctx = p.drawingContext;
+        const frameFloat = t * FRAMES;
+        const cam = cameraAt(model.plan.keys, frameFloat, FRAMES, CAMERA);
+        const view = viewOf(cam);
+        const sheetAlpha = smoothstep(LABEL_Z.sheet[0], LABEL_Z.sheet[1], cam.z);
+        const summitAlpha = smoothstep(LABEL_Z.summit[0], LABEL_Z.summit[1], cam.z);
+        setFill(ctx, P.paper);
+        ctx.fillRect(0, 0, W, H);
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(viewport.left, 0, W - viewport.left, H);
+        ctx.clip();
+        applyCamera(ctx, cam, viewport.cx, viewport.cy);
+        setFill(ctx, P.paper);
+        ctx.fillRect(0, 0, world.w, world.h);
+        drawGrid(ctx);
+        drawGraticule(ctx);
+        drawRaster(ctx, cam, view);
+        drawSummit(ctx, cam, t, summitAlpha);
+        drawNeatline(ctx, cam);
+        ctx.setTransform(1, 0, 0, 1, 0, 0);
+        drawSheetLabels(ctx, view, sheetAlpha);
+        drawMarker(ctx, view, markerAt(profile, model.plan, frameFloat));
+        ctx.restore();
+        drawCollar(ctx, altimeterLine(profile, model.plan, frameFloat));
+    }
+    return { setup, draw };
+}

package/dist/styles/trail-profile/trail.js

@@ -0,0 +1,278 @@
+import { canvasMeasure, fitLine } from '../../core/text.js';
+import { buildProfile, CELL } from './profile.js';
+/**
+ * The survey sheet as filmed: where the collar's type sits, and one walk from
+ * the year's first week to the summit and back (Highlights Reel's camera, in
+ * `core/camera.ts`). Everything here is a pure function of the data; the
+ * sketch only draws.
+ */
+export const FRAMES = 480;
+const W = 1280;
+const H = 400;
+/** The map's viewport: right of the collar. */
+const VIEWPORT_LEFT = 400;
+export const LAYOUT = {
+    width: W,
+    height: H,
+    viewport: { left: VIEWPORT_LEFT, cx: (VIEWPORT_LEFT + W) / 2, cy: H / 2 },
+    /** Margin around the sheet at the wide shot, screen px. */
+    wideMargin: 24,
+    /** The summit holds close. */
+    summitZ: 1.6,
+    /** Camera dip tuning: moves longer than `travel` dip, scaled to `span`. */
+    travel: 700,
+    span: 1600,
+    /** Collar text column. */
+    collar: { left: 48, right: 368 },
+    /**
+     * The walk. The camera frames the whole elevation band, from above the
+     * flag to the month labels, so it never chases the walker up and down: `y`
+     * and `z` are fixed and only `x` pans. The walker keeps one speed along the
+     * trail (screen px per frame, at `z`), eased in and out over `ramp` frames.
+     * A walk shorter than `max` frames gives its spare frames to the holds; a
+     * longer trail starts the walk that far before the summit.
+     */
+    walk: { z: 0.43, y: 660, speed: 7, ramp: 20, min: 60, max: 215 },
+    /** The walk's horizontal view keeps this margin past the map, world units. */
+    panMargin: 40,
+    /**
+     * Segment lengths, in frames, with the walk at `walk.max`; they add up to
+     * `FRAMES`. A shorter walk splits its spare frames between the two holds.
+     */
+    segments: { wideHold: 55, descend: 40, arrive: 40, summitHold: 80, pullBack: 50 },
+};
+const MONTHS = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'];
+/** "2026-03-12" .. "2026-03-18" -> "MAR 12 TO 18" (crossing months spells both). */
+export function summitDates(from, to) {
+    const [, fm, fd] = from.split('-').map(Number);
+    const [, tm, td] = to.split('-').map(Number);
+    return fm === tm
+        ? `${MONTHS[fm - 1]} ${fd} TO ${td}`
+        : `${MONTHS[fm - 1]} ${fd} TO ${MONTHS[tm - 1]} ${td}`;
+}
+/** The wide shot: the whole sheet in the viewport with `wideMargin` to spare. */
+export function wideShot(profile) {
+    const z = Math.min((W - VIEWPORT_LEFT - LAYOUT.wideMargin) / profile.world.w, (H - LAYOUT.wideMargin) / profile.world.h);
+    return { x: profile.world.w / 2, y: profile.world.h / 2, z };
+}
+/** Weeks the months start in, for the graticule and the labels under the ground. */
+export function monthMarks(contributions) {
+    const marks = [];
+    contributions.weeks.forEach((week, i) => {
+        for (const day of week) {
+            if (day.date < contributions.from || day.date > contributions.to)
+                continue;
+            const [, m, d] = day.date.split('-').map(Number);
+            if (d === 1) {
+                marks.push({ week: i, label: MONTHS[m - 1] });
+                break;
+            }
+        }
+    });
+    return marks;
+}
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+/**
+ * The walker at a loop frame: standing at the walk's start while it fades in,
+ * walking the baked path to the summit, then fading out as the camera pushes
+ * in, so the survey triangle takes over and the wide holds match.
+ */
+export function markerAt(profile, plan, frame) {
+    const { path, walk, fadeIn, fadeOut } = plan;
+    if (!profile.summit || path.length === 0)
+        return null;
+    const f = Math.floor(frame);
+    let x;
+    let alpha = 1;
+    let walking = false;
+    if (f < walk.start) {
+        x = path[0];
+        alpha = clamp01((frame - fadeIn.start) / (fadeIn.end - fadeIn.start));
+    }
+    else if (f < walk.end) {
+        x = path[f - walk.start];
+        walking = true;
+    }
+    else {
+        x = path.at(-1);
+        alpha = 1 - clamp01((frame - fadeOut.start) / (fadeOut.end - fadeOut.start));
+    }
+    return { x, y: profile.profileY(x), alpha, walking };
+}
+/**
+ * Distance along the trail at walk frame `f` of `n`, for a trail `length`
+ * long: a sine ramp up over `ramp` frames, a steady cruise, and the mirror
+ * ramp down, so velocity is continuous and the cruise is one speed.
+ */
+export function walkDistance(f, n, ramp, length) {
+    const v = length / (n - ramp);
+    const up = (g) => v * (g / 2 - (ramp / (2 * Math.PI)) * Math.sin((Math.PI * g) / ramp));
+    if (f <= 0)
+        return 0;
+    if (f >= n)
+        return length;
+    if (f < ramp)
+        return up(f);
+    if (f <= n - ramp)
+        return v * (ramp / 2 + (f - ramp));
+    return length - up(n - f);
+}
+/**
+ * The walker's path: its x at each walk frame, at one speed along the trail
+ * (arc length, so it slows on the climbs instead of shooting up them). The
+ * walk takes as many frames as the trail needs at `walk.speed`, within
+ * `walk.min` and `walk.max`; a trail too long for `walk.max` starts that far
+ * before the summit.
+ */
+function walkPath(profile) {
+    const { speed, ramp, min, max, z } = LAYOUT.walk;
+    const to = profile.summit.x;
+    // Cumulative arc length from the first week, sampled every world unit.
+    const xs = [];
+    const arc = [];
+    let s = 0;
+    let prevY = profile.profileY(profile.weekX(0));
+    for (let x = profile.weekX(0);; x = Math.min(x + 1, to)) {
+        const y = profile.profileY(x);
+        if (xs.length > 0)
+            s += Math.hypot(x - xs.at(-1), y - prevY);
+        xs.push(x);
+        arc.push(s);
+        prevY = y;
+        if (x >= to)
+            break;
+    }
+    const maxLength = ((max - ramp) * speed) / z;
+    const length = Math.min(s, maxLength);
+    const n = Math.min(max, Math.max(min, Math.round((length * z) / speed + ramp)));
+    const offset = s - length;
+    const path = [];
+    let i = 0;
+    for (let f = 0; f <= n; f++) {
+        const target = offset + walkDistance(f, n, ramp, length);
+        while (i < arc.length - 2 && arc[i + 1] < target)
+            i++;
+        const a = arc[i];
+        const b = arc[i + 1] ?? a;
+        const u = b > a ? clamp01((target - a) / (b - a)) : 0;
+        path.push(xs[i] + ((xs[i + 1] ?? xs[i]) - xs[i]) * u);
+    }
+    path[n] = to;
+    return path;
+}
+/**
+ * The walk's camera: fixed `y` and `z`, and an `x` that pans in step with
+ * the walker across the whole sheet, so the view's left edge sits at the
+ * map's west margin at the first week and its right edge at the east margin
+ * at the last. The pan is a straight line of the walker's x: no kinks.
+ */
+function walkCam(profile, x) {
+    const { z, y } = LAYOUT.walk;
+    const half = (W - VIEWPORT_LEFT) / 2 / z;
+    const lo = profile.mapArea.x0 - LAYOUT.panMargin + half;
+    const hi = profile.mapArea.x1 + LAYOUT.panMargin - half;
+    const first = profile.weekX(0);
+    const last = profile.weekX(profile.cols - 1);
+    const u = last > first ? clamp01((x - first) / (last - first)) : 0.5;
+    return { x: hi > lo ? lo + (hi - lo) * u : profile.world.w / 2, y, z };
+}
+const EMPTY = { start: 0, end: 0 };
+/**
+ * The camera plan. The walk is baked as one key per frame, so GIF frames
+ * sample it exactly and nothing re-eases.
+ */
+function buildPlan(profile) {
+    const wide = wideShot(profile);
+    if (!profile.summit) {
+        // The empty state: the camera holds the wide shot for the whole loop.
+        return {
+            keys: [
+                { frame: 0, ...wide },
+                { frame: FRAMES, ...wide },
+            ],
+            summitHold: EMPTY,
+            walk: EMPTY,
+            fadeIn: EMPTY,
+            fadeOut: EMPTY,
+            path: [],
+        };
+    }
+    const seg = LAYOUT.segments;
+    const path = walkPath(profile);
+    const walkFrames = path.length - 1;
+    const spare = LAYOUT.walk.max - walkFrames;
+    const wideHold = seg.wideHold + Math.floor(spare / 2);
+    const summitHold = seg.summitHold + Math.ceil(spare / 2);
+    const walkStart = wideHold + seg.descend;
+    const walkEnd = walkStart + walkFrames;
+    const holdStart = walkEnd + seg.arrive;
+    const holdEnd = holdStart + summitHold;
+    const keys = [
+        { frame: 0, ...wide },
+        { frame: wideHold, ...wide },
+    ];
+    path.forEach((x, f) => keys.push({ frame: walkStart + f, ...walkCam(profile, x) }));
+    const summit = { x: profile.summit.x, y: profile.summit.y + 30, z: LAYOUT.summitZ };
+    keys.push({ frame: holdStart, ...summit });
+    keys.push({ frame: holdEnd, ...summit });
+    keys.push({ frame: FRAMES, ...wide });
+    return {
+        keys,
+        summitHold: { start: holdStart, end: holdEnd },
+        walk: { start: walkStart, end: walkEnd },
+        fadeIn: { start: wideHold, end: walkStart },
+        fadeOut: { start: walkEnd, end: holdStart },
+        path,
+    };
+}
+/**
+ * The collar's altimeter line: the summit at rest, and the week under the
+ * walker (its total and dates) while it walks, switching back at arrival.
+ */
+export function altimeterLine(profile, plan, frame) {
+    const summit = profile.summit;
+    if (!summit)
+        return null;
+    const marker = markerAt(profile, plan, frame);
+    if (marker?.walking) {
+        const week = profile.weeks[profile.weekAt(marker.x)];
+        return `ALT ${week.total} · ${summitDates(week.from, week.to)}`;
+    }
+    return `SUMMIT ${summit.total} · ${summitDates(summit.from, summit.to)}`;
+}
+function buildCollar(profile, identity, zWide, total) {
+    const column = LAYOUT.collar.right - LAYOUT.collar.left;
+    return {
+        name: fitLine(identity.name.toUpperCase(), column, 44, 30, canvasMeasure('Space Grotesk', 700, 3)),
+        tagline: identity.tagline
+            ? fitLine(identity.tagline, column, 17, 17, canvasMeasure('Space Grotesk', 400))
+            : null,
+        website: identity.website
+            ? fitLine(`↗ ${displayUrl(identity.website)}`, column, 12, 12, canvasMeasure('JetBrains Mono', 400))
+            : null,
+        total: total.toLocaleString('en-US'),
+        ...(profile.summit
+            ? {
+                summitLine: `SUMMIT ${profile.summit.total} · ${summitDates(profile.summit.from, profile.summit.to)}`,
+                intervalText: `CONTOUR INTERVAL ${profile.interval} CONTRIBUTIONS`,
+            }
+            : { summitLine: null, intervalText: null }),
+        scale: { weeksPerSegment: 4, segments: 3, px: 4 * CELL * zWide },
+    };
+}
+/** "https://www.example.com/" -> "www.example.com" */
+function displayUrl(url) {
+    return url.replace(/^[a-z]+:\/\//i, '').replace(/\/+$/, '');
+}
+export function buildTrail(data, identity, palette) {
+    const profile = buildProfile(data);
+    const zWide = wideShot(profile).z;
+    return {
+        profile,
+        collar: buildCollar(profile, identity, zWide, data.total),
+        months: monthMarks(data),
+        plan: buildPlan(profile),
+        palette,
+        zWide,
+    };
+}

package/package.json

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