caracms 0.0.0-stage → 0.2.0

package/src/live/status.ts

@@ -0,0 +1,109 @@
+/**
+ * What's waiting, and whether a publish went live (M4 Decisions 5, 8, 12), as pure
+ * functions over facts read from git and GitHub, so they can be tested from
+ * fixtures. git.ts gathers the facts.
+ */
+import type { CommitSummary } from './backend.ts';
+import { parseMessage, type Person } from './messages.ts';
+
+// ── Waiting ───────────────────────────────────────────────────────────────────
+
+export interface WaitingFile {
+	/** Site-relative path. */
+	file: string;
+	/** Who changed it since the last publish, most recent first, each once. */
+	editors: { person: Person; at: string }[];
+	/** The newest of those changes (ISO); null when no commit names an editor (a push straight to drafts). */
+	changedAt: string | null;
+	/** A merge or a commit decided a key or the file for the draft: the merge notice's data (Decision 7). */
+	keptDraft: boolean;
+}
+
+/**
+ * The waiting list from git alone: `files` are the files that differ between `main`
+ * and `drafts`, `commits` the commits on `drafts` since `main` (oldest first), whose
+ * messages (messages.ts) say who changed what. Newest change first.
+ */
+export function waitingFromCommits(files: Iterable<string>, commits: CommitSummary[]): WaitingFile[] {
+	const out = new Map<string, WaitingFile>();
+	for (const file of files) out.set(file, { file, editors: [], changedAt: null, keptDraft: false });
+	for (const commit of commits) {
+		const parsed = parseMessage(commit.message);
+		for (const edit of parsed.edits) {
+			for (const file of edit.files) {
+				const w = out.get(file);
+				if (!w) continue;
+				const email = edit.person.email.toLowerCase();
+				w.editors = [{ person: edit.person, at: commit.date }, ...w.editors.filter((e) => e.person.email.toLowerCase() !== email)];
+				if (!w.changedAt || commit.date >= w.changedAt) w.changedAt = commit.date;
+			}
+		}
+		for (const file of parsed.keptDraft) {
+			const w = out.get(file);
+			if (w) w.keptDraft = true;
+		}
+	}
+	return [...out.values()].sort((a, b) => (b.changedAt ?? '').localeCompare(a.changedAt ?? '') || a.file.localeCompare(b.file));
+}
+
+// ── Publish status ────────────────────────────────────────────────────────────
+
+/** The newest publish, kept in Redis so a server replaced mid-publish still knows it (Watch-outs). */
+export interface PublishRecord {
+	/** The squashed commit on `main`. */
+	commit: string;
+	by: Person;
+	/** ISO. */
+	at: string;
+	/** Site-relative paths published. */
+	files: string[];
+	titles: string[];
+	/** When Try again last redeployed (ISO): deployments older than this don't count. */
+	tryAgainAt: string | null;
+}
+
+export type PublishState = 'publishing' | 'live' | 'failed';
+
+/** One GitHub Deployment and its newest status (null: no status yet). */
+export interface DeploymentFact {
+	sha: string;
+	createdAt: string;
+	state: string | null;
+}
+
+/** Statuses that are an answer. `in_progress`, `queued` and `pending` aren't: Railway leaves skipped deploys `in_progress` for good. */
+const FINAL = new Set(['success', 'failure', 'error', 'inactive']);
+
+export interface PublishFacts {
+	record: PublishRecord;
+	/** The running server's commit (RAILWAY_GIT_COMMIT_SHA / CARACMS_RUNNING_COMMIT), or null with no deploy pipeline. */
+	running: string | null;
+	/** Is `running` the publish commit or a descendant of it? null when not known (not asked). */
+	runningIncludesPublish: boolean | null;
+	/** Commits on `main` after the publish commit. */
+	laterOnMain: ReadonlySet<string>;
+	/** The repo's deployments, any order. */
+	deployments: DeploymentFact[];
+}
+
+/**
+ * Decision 12:
+ * - **live**: the running server's commit is the publish commit or after it; or, on a
+ *   server with no running commit at all (no deploy pipeline), once the refs moved,
+ *   which they had for a publish record to exist.
+ * - **failed**: the newest deployment that has *answered*, for the publish commit or
+ *   a later commit on `main` (since the last Try again), says `failure` or `error`.
+ *   A deployment stuck `in_progress` is never read as finished or failed.
+ * - **publishing**: otherwise.
+ */
+export function publishState(f: PublishFacts): { state: PublishState; assumed: boolean } {
+	if (f.running === null) return { state: 'live', assumed: true };
+	if (f.running === f.record.commit || f.runningIncludesPublish) return { state: 'live', assumed: false };
+	const since = f.record.tryAgainAt ?? '';
+	const answered = f.deployments
+		.filter((d) => (d.sha === f.record.commit || f.laterOnMain.has(d.sha)) && d.createdAt >= since && d.state !== null && FINAL.has(d.state))
+		.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+	const newest = answered[0];
+	if (newest && (newest.state === 'failure' || newest.state === 'error')) return { state: 'failed', assumed: false };
+	return { state: 'publishing', assumed: false };
+}

package/src/live/sweep.ts

@@ -0,0 +1,228 @@
+/**
+ * The sweep (M4 Decisions 5 and 6): it carries autosaves from Redis into `drafts`.
+ *
+ * - **A document's autosave is committed once it has been idle for `sweepIdleMs`**, and
+ *   at least every `sweepCapMs` while someone keeps typing (measured from the first
+ *   write since its last commit). **One marked `sweepAtOnce`** (Site Settings', M5a
+ *   Decision 10) is ready on the next tick, with no idle wait.
+ * - **One commit per tick for everything ready** (`git.commitDrafts`), never one per
+ *   editor or per document (M1 → G4). Each autosave is merged with `drafts` (Decision
+ *   6); its ancestor is the session's last commit, else its base (autosaves.ts).
+ * - **It ticks every `sweepTickMs`, but only while something is pending**: from the
+ *   first autosave this server sees until nothing is left. **With nothing pending it
+ *   makes no Redis call at all**, so Railway's Redis can sleep (Decision 17, M1 → R1).
+ *   One check at startup (`start`) picks up what a previous server left behind; the
+ *   status route `poke`s it when a poll sees autosaves, in case they came in on the
+ *   other server during a deploy and that server went away.
+ * - **Each tick takes a short Redis lock first**: during a deploy two servers sweep.
+ * - `commitAll` commits everything pending now, idle or not: Publish's step 1
+ *   (Decision 10) through `git.commitPending`, and Decision 8's merge.
+ * - After a commit an autosave is deleted only if no newer write replaced it (a
+ *   compare-and-delete); a newer one stays, with its cap restarted. Then a lock whose
+ *   only reason to hold was that autosave is dropped (Decision 9: commit, then release).
+ * - **New and deleted documents** (M5a) are autosaves like any other: a new one's text
+ *   is committed as an added file (its ancestor is what `drafts` had there, autosaves.ts
+ *   → `ancestorFor`), a "gone" one as a removed file (git.ts → `commitDrafts`). A newer
+ *   write that came in while a new document was being committed is no longer a new
+ *   document: its `created` mark is dropped (retried if a write beats the swap), so its ancestor is that commit.
+ */
+import { randomBytes } from 'node:crypto';
+import type { DraftEntry, LiveGit } from './git.ts';
+import type { Autosaves, Read, Autosave } from './autosaves.ts';
+import type { Locks } from './locks.ts';
+import type { RedisClient } from './redis.ts';
+import type { LiveTimings } from './timings.ts';
+
+export type Schedule = (fn: () => void, ms: number) => () => void;
+
+const defaultSchedule: Schedule = (fn, ms) => {
+	const t = setTimeout(fn, ms);
+	t.unref?.();
+	return () => clearTimeout(t);
+};
+
+export interface SweepOptions {
+	redis: RedisClient;
+	git: Pick<LiveGit, 'commitDrafts'>;
+	autosaves: Autosaves;
+	locks: Locks;
+	timings: LiveTimings;
+	now: () => number;
+	schedule?: Schedule;
+	sleep?: (ms: number) => Promise<void>;
+	log?: (line: string) => void;
+	prefix?: string;
+}
+
+export interface SweepResult {
+	commit: string | null;
+	/** Files committed (or found already in `drafts`). */
+	files: string[];
+	/** False when another server held the sweep's lock and this tick did nothing. */
+	ran: boolean;
+}
+
+type Select = 'ready' | 'all' | { files: string[] };
+
+/** Is an autosave ready for a tick: marked to go at once, idle long enough, or past the cap? */
+export function ready(a: Autosave, now: number, timings: Pick<LiveTimings, 'sweepIdleMs' | 'sweepCapMs'>): boolean {
+	return a.sweepAtOnce === true || now - a.updatedAt >= timings.sweepIdleMs || now - a.firstAt >= timings.sweepCapMs;
+}
+
+export class Sweep {
+	/** Ticking: something is (or may be) pending. */
+	active = false;
+	/** Bumped by every poke, so a run that found nothing doesn't stop a sweep a write started meanwhile. */
+	private pokes = 0;
+	private cancel: (() => void) | null = null;
+	private running: Promise<unknown> = Promise.resolve();
+	private readonly o: SweepOptions;
+	private readonly schedule: Schedule;
+	private readonly sleep: (ms: number) => Promise<void>;
+	private readonly log: (line: string) => void;
+	private readonly lockKey: string;
+
+	constructor(options: SweepOptions) {
+		this.o = options;
+		this.schedule = options.schedule ?? defaultSchedule;
+		this.sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+		this.log = options.log ?? ((line) => console.log(`[caracms] ${line}`));
+		this.lockKey = `${options.prefix ?? 'caracms:'}sweep:lock`;
+	}
+
+	/** The startup check: anything a previous server left behind starts the ticking. */
+	async start(): Promise<void> {
+		const pending = await this.o.autosaves.all();
+		if (pending.length) {
+			this.log(`sweep: ${pending.length} autosave(s) waiting from before this server started`);
+			this.poke();
+		}
+	}
+
+	/** An autosave arrived (or was seen): tick until nothing is pending. */
+	poke(): void {
+		this.pokes++;
+		if (this.active) return;
+		this.active = true;
+		this.arm();
+	}
+
+	/** Stop ticking (tests, shutdown). */
+	stop(): void {
+		this.cancel?.();
+		this.cancel = null;
+		this.active = false;
+	}
+
+	private arm() {
+		this.cancel?.();
+		this.cancel = this.schedule(() => {
+			this.cancel = null;
+			void this.tick().catch((error: unknown) => this.log(`sweep: ${error instanceof Error ? error.message : String(error)}`));
+		}, this.o.timings.sweepTickMs);
+	}
+
+	/** One tick: commit what's ready. Keeps ticking while anything is left; goes quiet when nothing is. */
+	async tick(): Promise<SweepResult> {
+		let left = true;
+		const pokes = this.pokes;
+		try {
+			const r = await this.run('ready');
+			left = r.left;
+			return r.result;
+		} finally {
+			if (this.active) {
+				if (left || this.pokes !== pokes) this.arm();
+				else this.stop();
+			}
+		}
+	}
+
+	/** Commit every pending autosave now (Publish's step 1, Decision 8's merge). */
+	async commitAll(): Promise<SweepResult> {
+		const pokes = this.pokes;
+		const r = await this.run('all');
+		if (!r.left && this.active && this.pokes === pokes) this.stop();
+		return r.result;
+	}
+
+	/** Commit these files' autosaves now (a lock moved under an autosave from another tab). */
+	async commitFiles(files: string[]): Promise<SweepResult> {
+		return (await this.run({ files })).result;
+	}
+
+	/** Runs one at a time in this process; the Redis lock keeps two servers apart. */
+	private run(select: Select): Promise<{ result: SweepResult; left: boolean }> {
+		const next = this.running.then(
+			() => this.once(select),
+			() => this.once(select),
+		);
+		this.running = next.catch(() => {});
+		return next;
+	}
+
+	private async once(select: Select): Promise<{ result: SweepResult; left: boolean }> {
+		const { redis, autosaves, timings, now } = this.o;
+		const token = randomBytes(9).toString('base64url');
+		const lockMs = Math.max(30_000, timings.sweepTickMs);
+		let locked = await redis.set(this.lockKey, token, { nx: true, px: lockMs });
+		if (!locked) {
+			// Another server is sweeping. A tick leaves it to them; a commit-everything waits briefly, then goes anyway (commits are compare-and-swap).
+			if (select === 'ready') return { result: { commit: null, files: [], ran: false }, left: true };
+			for (let i = 0; i < 20 && !locked; i++) {
+				await this.sleep(250);
+				locked = await redis.set(this.lockKey, token, { nx: true, px: lockMs });
+			}
+		}
+		try {
+			const all = await autosaves.all();
+			const t = now();
+			const chosen =
+				select === 'all'
+					? all
+					: select === 'ready'
+						? all.filter((a) => ready(a.value, t, timings))
+						: all.filter((a) => select.files.includes(a.value.file));
+			if (chosen.length === 0) return { result: { commit: null, files: [], ran: true }, left: all.length > 0 };
+			const result = await this.commit(chosen);
+			return { result, left: all.length > result.removed };
+		} finally {
+			if (locked) await redis.compareAndDelete(this.lockKey, token).catch(() => false);
+		}
+	}
+
+	private async commit(chosen: Read<Autosave>[]): Promise<SweepResult & { removed: number }> {
+		const { autosaves, locks, git, now } = this.o;
+		// (M5a) `text` is null for a deletion, which commitDrafts commits as a removed file.
+		const entries: DraftEntry[] = [];
+		for (const a of chosen) {
+			const ancestor = await autosaves.ancestorFor(a.value);
+			// Worth a line when an editing session's record exists but wasn't used whole: the "kept draft" notice turns on it.
+			if (ancestor.from !== 'session' && ancestor.from !== 'base') this.log(`sweep: ${a.value.file} merged against ${ancestor.from}`);
+			entries.push({ file: a.value.file, base: ancestor.text, text: a.value.text, editor: a.value.editor });
+		}
+		const r = await git.commitDrafts(entries);
+		let removed = 0;
+		const at = now();
+		for (const a of chosen) {
+			const { file, tab, base, text, editor } = a.value;
+			await autosaves.setCommitted(file, { tab, base, text, at, editor: editor.email.toLowerCase() });
+			if (await autosaves.removeIf(a)) {
+				removed++;
+				await locks.dropIfFree(file);
+				continue;
+			}
+			// A newer write came in while committing: it stays, and its cap starts again from this commit.
+			// A document this commit created isn't new any more (M5a): the commit is the newer write's ancestor
+			// (so is any `ancestor` it carried from before the commit).
+			// A write can land between the get and the replaceIf (it copies `created` forward again), so look again until it takes or the autosave is gone.
+			for (let attempt = 0; attempt < 8; attempt++) {
+				const newer = await autosaves.get(file);
+				if (!newer) break;
+				const { created: _created, ancestor: _ancestor, ...rest } = newer.value;
+				if (await autosaves.replaceIf(newer, { ...rest, firstAt: at })) break;
+			}
+		}
+		return { commit: r.commit, files: chosen.map((a) => a.value.file), ran: true, removed };
+	}
+}

package/src/live/timings.ts

@@ -0,0 +1,47 @@
+/** Live mode's timings (M4 Phase 1). */
+
+/**
+ * Every timing live mode uses, in one place so tests shorten them (Decision 2). The
+ * sweep's and the locks' are Phase 2's; they're defined here so the runtime carries one set.
+ */
+export interface LiveTimings {
+	/** Decision 8: status reads check `main` at most this often. */
+	mainCheckMs: number;
+	/** Decision 13: the deployments are read at most this often while a publish is in flight. */
+	deploymentReadMs: number;
+	/** Decision 12: history is refreshed at most this often. */
+	historyMs: number;
+	/** How long the Publish lock lasts if its holder dies (Decision 10: one Publish at a time). */
+	publishLockMs: number;
+	/** Phase 2 (Decision 5): the sweep's tick. */
+	sweepTickMs: number;
+	/** Phase 2 (Decision 5): an autosave is committed once its document has been idle this long. */
+	sweepIdleMs: number;
+	/** Phase 2 (Decision 5): …and at least this often while someone keeps typing. */
+	sweepCapMs: number;
+	/** Phase 2 (Decision 9): a lock lapses this long after the last heartbeat (once committed). */
+	lockLapseMs: number;
+	/** Take over (2026-10-15): a tab renews its lock only while someone typed, clicked or scrolled in it this recently. */
+	lockIdleMs: number;
+	/** Phase 2 (Decision 9): someone is "on" a document while they polled with it this recently. */
+	presenceMs: number;
+	/** Decision 4: autosaves expire after this long, as a backstop. */
+	autosaveTtlMs: number;
+	/** Decision 13: each tab polls the status this often (the editor's POLL_MS; /admin passes it to the page). */
+	pollMs: number;
+}
+
+export const DEFAULT_TIMINGS: LiveTimings = {
+	mainCheckMs: 60_000,
+	deploymentReadMs: 10_000,
+	historyMs: 60_000,
+	publishLockMs: 120_000,
+	sweepTickMs: 30_000,
+	sweepIdleMs: 60_000,
+	sweepCapMs: 5 * 60_000,
+	lockLapseMs: 2 * 60_000,
+	lockIdleMs: 10 * 60_000,
+	presenceMs: 15_000,
+	autosaveTtlMs: 7 * 24 * 60 * 60_000,
+	pollMs: 5000,
+};

package/src/live/webhook.ts

@@ -0,0 +1,39 @@
+/**
+ * GitHub's webhook, `POST /_caracms/github` (M4 Decisions 8 and 14). It takes no
+ * session; it checks GitHub's signature instead.
+ *
+ * - **No `GITHUB_WEBHOOK_SECRET`: 404**, as if the route didn't exist; the
+ *   once-a-minute check does the job.
+ * - **`X-Hub-Signature-256` must be the body's HMAC-SHA256 under the secret**,
+ *   compared in constant time, or it's 401 and nothing happens.
+ * - **Nothing in the body is trusted or even read**: a good signature only prompts
+ *   Decision 8's check, which asks GitHub itself what moved.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/** Largest body read. GitHub caps payloads at 25 MB; a push is far smaller, and it's never parsed. */
+const MAX_BODY_BYTES = 25 * 1024 * 1024;
+
+export function signatureMatches(secret: string, body: Buffer, header: string | null): boolean {
+	if (!header || !header.startsWith('sha256=')) return false;
+	const expected = Buffer.from(`sha256=${createHmac('sha256', secret).update(body).digest('hex')}`);
+	const given = Buffer.from(header.trim());
+	return given.length === expected.length && timingSafeEqual(given, expected);
+}
+
+const text = (status: number, body: string) => new Response(body, { status, headers: { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' } });
+
+/**
+ * The whole route. `trigger` starts the check and isn't awaited: GitHub wants an
+ * answer within ten seconds, and a merge can take longer.
+ */
+export async function handleGithubWebhook(request: Request, options: { secret: string | null; trigger: () => Promise<unknown> }): Promise<Response> {
+	if (!options.secret) return text(404, 'Not found');
+	if (request.method !== 'POST') return new Response('The webhook only takes POST.', { status: 405, headers: { Allow: 'POST' } });
+	if (Number(request.headers.get('content-length') ?? 0) > MAX_BODY_BYTES) return text(413, 'Too large.');
+	const body = Buffer.from(await request.arrayBuffer());
+	if (body.length > MAX_BODY_BYTES) return text(413, 'Too large.');
+	if (!signatureMatches(options.secret, body, request.headers.get('x-hub-signature-256'))) return text(401, 'Bad signature.');
+	void options.trigger().catch((error: unknown) => console.error('[caracms] the check after a webhook failed:', error));
+	return text(202, 'Checking.');
+}

package/src/lockup-css.ts

@@ -0,0 +1,58 @@
+/**
+ * The lockup's CSS, generated per site because the phone-lines switch is a media
+ * query at the site's configured width (Decision 11), and a media query can't read
+ * a custom property. Served as `virtual:caracms/lockup.css`, which Lockup.astro
+ * imports, so any page that renders a lockup gets it (inlined or linked by Astro).
+ *
+ * Structure (Lockup.astro):
+ *   <h1 class="cms-lockup [cms-lockup--has-phone]" style="--cms-size…">        one heading
+ *     <span class="cms-lockup-set cms-lockup-main" style="--longest-line: …">   a size container
+ *       <span class="cms-lockup-fit">                                            font-size: the fit
+ *         <span class="cms-lockup-line">…</span> <span class="cms-lockup-line">…</span>
+ *     <span class="cms-lockup-set cms-lockup-phone" style="--longest-line: …">  only with phone lines
+ *
+ * Each set is its own container with its own `--longest-line` (Decision 11; M1 →
+ * E5: `cqi` resolves against the nearest container ancestor, so the fit sits inside
+ * the set). The inactive set is `display: none`, so screen readers, copying and
+ * crawlers see one set of lines.
+ */
+export function lockupCss(phoneLinesWidth: number): string {
+	return `/* caracms: lockups (Spec → Text). Phone lines below ${phoneLinesWidth}px (Decision 11). */
+.cms-lockup {
+	margin: 0;
+}
+.cms-lockup-set {
+	display: block;
+	container-type: inline-size;
+}
+.cms-lockup-fit {
+	display: block;
+	font-family: var(--cms-family);
+	font-weight: var(--cms-weight);
+	font-variation-settings: var(--cms-variation);
+	font-optical-sizing: none;
+	font-kerning: normal;
+	letter-spacing: var(--cms-tracking);
+	line-height: var(--cms-leading);
+	text-transform: var(--cms-transform);
+	/* The fit. No floor, on purpose (Spec → Text). */
+	font-size: min(var(--cms-size), calc(100cqi / var(--longest-line)));
+}
+.cms-lockup-line {
+	display: block;
+	white-space: nowrap;
+	width: fit-content;
+}
+.cms-lockup-phone {
+	display: none;
+}
+@media (width < ${phoneLinesWidth}px) {
+	.cms-lockup-phone {
+		display: block;
+	}
+	.cms-lockup--has-phone > .cms-lockup-main {
+		display: none;
+	}
+}
+`;
+}

package/src/measure.ts

@@ -0,0 +1,145 @@
+/**
+ * Measure a lockup line's width in ems, from the font file, as the browser will
+ * draw it (Spec → Text → "What's measured"; lifted from M1, E4: within 0.064% of Chrome).
+ *
+ * - Shaped with HarfBuzz (harfbuzzjs), the shaper Chrome and Firefox use, so
+ *   kerning (GPOS) and substitutions (GSUB) match their defaults.
+ * - The style's text-transform is applied before shaping.
+ * - The style's variable axes are pinned (TextStyle.axes), as the CSS pins them.
+ * - Tracking is added once per grapheme cluster, including after the last one
+ *   (browsers draw that trailing letter-space).
+ * - With non-zero tracking, optional ligatures (`liga`, `clig`) are off, as CSS asks.
+ * - **Uncovered characters** (Decision 15): a character the font has no glyph for
+ *   shapes as `.notdef` (glyph 0) here, but the browser draws it from a system
+ *   font at an unknown width, so the fit can overflow. They're reported, per line,
+ *   as the graphemes as drawn (after the transform), so the editor can say
+ *   "“✨” isn't in this font, so this line may not fit".
+ *
+ * Synchronous after module load (harfbuzzjs initialises its wasm with a top-level
+ * await), so it runs inside an Astro component's frontmatter during render.
+ */
+import { readFileSync } from 'node:fs';
+import type * as Harfbuzz from 'harfbuzzjs';
+import type { TextStyle, TextTransform } from './text-styles.ts';
+import { normaliseLines } from './fields.ts';
+
+/** What measuring needs from a style: the measured font's absolute path, and how it's set. */
+export type MeasureStyle = Pick<TextStyle, 'axes' | 'trackingEm' | 'textTransform'> & {
+	resolvedFontFile: { measure: string };
+};
+
+/**
+ * harfbuzzjs, loaded at runtime from where it's installed. The integration sets
+ * `__CARACMS_HARFBUZZ__` (a Vite `define`) to its entry's file URL, because a
+ * built site can't bundle it (it reads its .wasm beside itself) and, under pnpm,
+ * can't resolve it from the site's own folder either (it's the package's
+ * dependency, not the site's). Outside Vite (node:test) it's a plain import.
+ */
+declare const __CARACMS_HARFBUZZ__: string | undefined;
+const hb: typeof Harfbuzz = await import(
+	/* @vite-ignore */ typeof __CARACMS_HARFBUZZ__ === 'string' ? __CARACMS_HARFBUZZ__ : 'harfbuzzjs'
+);
+
+interface LoadedFont {
+	font: Harfbuzz.Font;
+	upem: number;
+}
+
+// A cache of shaping fonts by file and axes: immutable, so safe to share between renders.
+const fonts = new Map<string, LoadedFont>();
+
+function fontFor(style: MeasureStyle): LoadedFont {
+	const path = style.resolvedFontFile.measure;
+	const key = `${path}|${JSON.stringify(style.axes)}`;
+	let loaded = fonts.get(key);
+	if (!loaded) {
+		const face = new hb.Face(new hb.Blob(readFileSync(path)));
+		const font = new hb.Font(face);
+		const axes = Object.entries(style.axes);
+		if (axes.length > 0) font.setVariations(axes.map(([tag, value]) => new hb.Variation(tag, value)));
+		loaded = { font, upem: face.upem };
+		fonts.set(key, loaded);
+	}
+	return loaded;
+}
+
+export function applyTransform(text: string, transform: TextTransform): string {
+	switch (transform) {
+		case 'uppercase':
+			return text.toLocaleUpperCase('en');
+		case 'lowercase':
+			return text.toLocaleLowerCase('en');
+		default:
+			return text;
+	}
+}
+
+const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
+
+export interface MeasuredLine {
+	text: string;
+	/** Width in em at the style's tracking, transform and axes. */
+	em: number;
+	/** Graphemes (as drawn, after the transform) the font has no glyph for, in order, without repeats. */
+	uncovered: string[];
+}
+
+/** Measure one line. Empty → 0 em. */
+export function measureLineDetail(line: string, style: MeasureStyle): MeasuredLine {
+	const text = applyTransform(line, style.textTransform);
+	if (text.length === 0) return { text: line, em: 0, uncovered: [] };
+
+	const { font, upem } = fontFor(style);
+	const buffer = new hb.Buffer();
+	buffer.addText(text);
+	buffer.guessSegmentProperties();
+	const features = style.trackingEm !== 0 ? [new hb.Feature('liga', 0), new hb.Feature('clig', 0)] : [];
+	hb.shape(font, buffer, features);
+
+	let advance = 0;
+	for (const p of buffer.getGlyphPositions()) advance += p.xAdvance;
+
+	// Graphemes by UTF-16 offset; a glyph's cluster is the offset of its first code unit.
+	const graphemes = [...segmenter.segment(text)];
+	const uncovered: string[] = [];
+	for (const info of buffer.getGlyphInfos()) {
+		if (info.codepoint !== 0) continue; // after shaping, `codepoint` is the glyph id; 0 is .notdef
+		const g = graphemes.findLast((s) => s.index <= info.cluster)?.segment;
+		if (g && !/^\s+$/.test(g) && !uncovered.includes(g)) uncovered.push(g);
+	}
+
+	return { text: line, em: advance / upem + graphemes.length * style.trackingEm, uncovered };
+}
+
+/** The line's width in ems. */
+export function measureLine(line: string, style: MeasureStyle): number {
+	return measureLineDetail(line, style).em;
+}
+
+/** Graphemes in a line the style's font doesn't cover (Decision 15). */
+export function uncoveredCharacters(line: string, style: MeasureStyle): string[] {
+	return measureLineDetail(line, style).uncovered;
+}
+
+export interface MeasuredLockup {
+	lines: MeasuredLine[];
+	/** The longest line's em width; drives `--longest-line`. */
+	longest: number;
+	/** Every uncovered grapheme across the lines, without repeats. */
+	uncovered: string[];
+}
+
+/** Measure a set of lines as the lockup renders them: trimmed, blank lines dropped. */
+export function measureLockup(lines: readonly string[], style: MeasureStyle): MeasuredLockup {
+	const measured = normaliseLines(lines).map((text) => measureLineDetail(text, style));
+	const uncovered = [...new Set(measured.flatMap((l) => l.uncovered))];
+	return { lines: measured, longest: Math.max(0, ...measured.map((l) => l.em)), uncovered };
+}
+
+/**
+ * The size a lockup computes at a given container width, in px, by the CSS fit:
+ * `min(size, width / longest)`. What the browser does; for tests and the demo's numbers.
+ */
+export function fittedSizePx(longestEm: number, containerPx: number, sizePx: number): number {
+	return longestEm > 0 ? Math.min(sizePx, containerPx / longestEm) : sizePx;
+}