@hajimism/dek 0.1.0

package/src/core/schema.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+/** Section / beat ids. Digits-only values collide with numeric `data-step`. */
+export const Id = z
+  .string()
+  .regex(/^[a-z0-9-]+$/)
+  .refine((s) => /[a-z]/.test(s));
+
+export type Id = z.infer<typeof Id>;
+
+export const Beat = z.object({
+  id: Id.optional(),
+  title: z.string(),
+  body: z.string(),
+  line: z.number(),
+});
+
+export type Beat = z.infer<typeof Beat>;
+
+export const Section = z.object({
+  slug: Id,
+  title: z.string(),
+  body: z.string(),
+  beats: z.array(Beat),
+  line: z.number(),
+});
+
+export type Section = z.infer<typeof Section>;
+
+const Lang = z
+  .string()
+  .regex(/^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/, "write a BCP 47 tag, like en or ja");
+
+/** The page language when there is no script to read it from, such as the project index. */
+export const FALLBACK_LANG = "en";
+
+/**
+ * The language a script is written in, read from its writing system: kana means Japanese even
+ * among kanji, then Hangul, then Han. Anything else is taken as English. The frontmatter `lang`
+ * overrides it for every other language.
+ */
+export function inferLang(text: string): string {
+  if (/[\p{Script=Hiragana}\p{Script=Katakana}]/u.test(text)) {
+    return "ja";
+  }
+  if (/\p{Script=Hangul}/u.test(text)) {
+    return "ko";
+  }
+  if (/\p{Script=Han}/u.test(text)) {
+    return "zh";
+  }
+  return "en";
+}
+
+/** Frontmatter fields written to `.dek/schema.json` for yaml-language-server. */
+export const Frontmatter = z.object({
+  title: z.string(),
+  description: z
+    .string()
+    .optional()
+    .describe("One or two sentences a shared link shows under the title."),
+  event: z.string().optional(),
+  date: z.string().date("write a date, like 2026-04-18").optional(),
+  duration: z
+    .string("write minutes, like 10m")
+    .regex(/^\d+m$/, "write minutes, like 10m")
+    .optional(),
+  ratio: z.enum(["16:9", "4:3"]).default("16:9"),
+  lang: Lang.optional().describe(
+    "BCP 47 tag for the page. Omit it to follow the script: kana → ja, Hangul → ko, Han → zh, else en.",
+  ),
+});
+
+export type Frontmatter = z.infer<typeof Frontmatter>;
+
+export const Deck = Frontmatter.extend({
+  lang: Lang,
+  sections: z.array(Section).min(1, "add a ## heading; each one becomes a slide"),
+});
+
+export type Deck = z.infer<typeof Deck>;
+
+/**
+ * What a script may write, not what parsing returns: a field with a default is optional. Unknown
+ * keys stay flagged, as DEK008 flags them, although parsing drops them rather than failing.
+ */
+export function frontmatterJsonSchema(): unknown {
+  return { ...z.toJSONSchema(Frontmatter, { io: "input" }), additionalProperties: false };
+}

package/src/core/script-lines.ts

@@ -0,0 +1,53 @@
+import { splitLines } from "./lines.ts";
+
+/**
+ * One line of a script's body, and whether it is literal text no heading can start: `fenced` when
+ * that is because it belongs to a fenced code block, whose text the slide shows as written.
+ */
+export type ScriptLine = { text: string; literal: boolean; fenced: boolean };
+
+const FENCE_OPEN_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+
+/**
+ * The body's lines, each marked literal when it is part of a fenced code block, fences included,
+ * or lies inside an HTML comment. A `##` there is text the slide shows or the author hid, never a
+ * slide or a beat. Fences follow CommonMark: three or more backticks or tildes, indented at most
+ * three spaces, closed by a run of the same character at least as long.
+ */
+export function scriptLines(body: string): ScriptLine[] {
+  let fence: { char: string; length: number } | undefined;
+  let comment = false;
+  return splitLines(body).map((text) => {
+    if (fence) {
+      const close = new RegExp(`^ {0,3}${fence.char === "`" ? "`" : "~"}{${fence.length},}\\s*$`);
+      if (close.test(text)) {
+        fence = undefined;
+      }
+      return { text, literal: true, fenced: true };
+    }
+    const literal = comment;
+    const open = comment ? undefined : FENCE_OPEN_RE.exec(text);
+    // A backtick fence's info string may not hold a backtick; such a line is inline code.
+    if (open?.[1] && !(open[1].startsWith("`") && open[2]?.includes("`"))) {
+      fence = { char: open[1].charAt(0), length: open[1].length };
+      return { text, literal: true, fenced: true };
+    }
+    comment = commentOpenAfter(text, comment);
+    return { text, literal, fenced: false };
+  });
+}
+
+/** Whether an HTML comment is still open after `text`, given whether one was open before it. */
+function commentOpenAfter(text: string, open: boolean): boolean {
+  let inside = open;
+  let at = 0;
+  while (at < text.length) {
+    const next = text.indexOf(inside ? "-->" : "<!--", at);
+    if (next < 0) {
+      break;
+    }
+    at = next + (inside ? 3 : 4);
+    inside = !inside;
+  }
+  return inside;
+}

package/src/core/sheet.ts

@@ -0,0 +1,223 @@
+import { escapeAttr, escapeHtml } from "./escape.ts";
+import type { Size } from "./size.ts";
+
+/**
+ * Contact sheets: many captures on one image, so an agent reads a deck, or a slide's motion, in
+ * one look instead of one file per frame. A sheet is laid out here, as boxes at pixel positions,
+ * and drawn by a browser from the HTML `sheetHtml` writes.
+ */
+
+/** The longest edge a vision model reads without scaling the image down. */
+export const SHEET_MAX_EDGE = 1568;
+/** The most pixels a vision model reads without scaling the image down. */
+export const SHEET_MAX_PIXELS = 1_150_000;
+/** Part of every cache key for a sheet: a change to how sheets look makes new ones. */
+export const SHEET_LAYOUT_VERSION = "1";
+
+export type SheetCell = { image: string; label: string };
+type SheetRow = { label?: string; cells: SheetCell[] };
+export type SheetSpec = {
+  path: string;
+  title: string;
+  tile: Size;
+  columns: number;
+  rows: SheetRow[];
+};
+
+type SheetBox = {
+  kind: "title" | "label" | "image" | "caption";
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  text?: string;
+  image?: string;
+};
+
+/** One capture of a slide in motion, `ms` into the go that began its beat. */
+export type MotionFrame = { ms: number; path: string; end?: true };
+export type MotionBeat = { label: string; frames: MotionFrame[] };
+
+type SheetOptions = { slide: Size; title: string; dir: string };
+
+const PAD = 16;
+const GAP = 12;
+const TITLE = 32;
+const LABEL = 24;
+const CAPTION = 20;
+/** Below this a tile shows too little to judge a slide by; a long deck takes more sheets instead. */
+const MIN_TILE_WIDTH = 240;
+
+/**
+ * Every slide as a tile, in order. The tiles are as large as they can be with the whole deck on one
+ * sheet a vision model reads as drawn; a deck too long for that goes on over more sheets.
+ */
+export function overviewSheets(
+  cells: SheetCell[],
+  options: SheetOptions & {
+    /** Fixes the column count instead of choosing it. */
+    columns?: number;
+  },
+): SheetSpec[] {
+  if (cells.length === 0) {
+    return [];
+  }
+  const columns = options.columns ?? overviewColumns(cells.length, options.slide);
+  const tile = tileFor(columns, options.slide);
+  const rows = chunk(cells, columns).map((row) => ({ cells: row }));
+  const pages = paginate(rows, columns, tile);
+  let first = 1;
+  return pages.map((page, index) => {
+    const count = page.reduce((sum, row) => sum + row.cells.length, 0);
+    const title = `${options.title} · slides ${first}–${first + count - 1} of ${cells.length}`;
+    first += count;
+    return { path: sheetPath(options.dir, index), title, tile, columns, rows: page };
+  });
+}
+
+/**
+ * A row for each beat, its frames left to right and its settled end last, captioned with the
+ * moment each shows. A beat that does not move is one frame, captioned as such.
+ */
+export function motionSheets(beats: MotionBeat[], options: SheetOptions): SheetSpec[] {
+  const columns = Math.max(1, ...beats.map((beat) => beat.frames.length));
+  const tile = tileFor(columns, options.slide);
+  const rows = beats.map((beat) => ({
+    label: beat.label,
+    cells: beat.frames.map((frame) => ({ image: frame.path, label: frameCaption(frame, beat) })),
+  }));
+  const pages = paginate(rows, columns, tile);
+  return pages.map((page, index) => ({
+    path: sheetPath(options.dir, index),
+    title: pages.length > 1 ? `${options.title} · ${index + 1}/${pages.length}` : options.title,
+    tile,
+    columns,
+    rows: page,
+  }));
+}
+
+/** Where each title, row label, image, and caption goes, and how large the sheet is. */
+export function sheetLayout(spec: SheetSpec): { size: Size; boxes: SheetBox[] } {
+  const width = PAD * 2 + spec.columns * spec.tile.width + (spec.columns - 1) * GAP;
+  const inner = width - PAD * 2;
+  const boxes: SheetBox[] = [
+    { kind: "title", x: PAD, y: PAD, width: inner, height: TITLE, text: spec.title },
+  ];
+  let y = PAD + TITLE;
+  spec.rows.forEach((row, index) => {
+    if (index > 0) {
+      y += GAP;
+    }
+    if (row.label !== undefined) {
+      boxes.push({ kind: "label", x: PAD, y, width: inner, height: LABEL, text: row.label });
+      y += LABEL;
+    }
+    row.cells.forEach((cell, column) => {
+      const x = PAD + column * (spec.tile.width + GAP);
+      boxes.push({ kind: "image", x, y, ...spec.tile, image: cell.image });
+      boxes.push({
+        kind: "caption",
+        x,
+        y: y + spec.tile.height,
+        width: spec.tile.width,
+        height: CAPTION,
+        text: cell.label,
+      });
+    });
+    y += spec.tile.height + CAPTION;
+  });
+  return { size: { width, height: y + PAD }, boxes };
+}
+
+/** The sheet as a page to screenshot at its own size; `src` turns an image path into a URL. */
+export function sheetHtml(spec: SheetSpec, src: (image: string) => string): string {
+  const { size, boxes } = sheetLayout(spec);
+  const drawn = boxes
+    .map((box) => {
+      const at = `left:${box.x}px;top:${box.y}px;width:${box.width}px;height:${box.height}px`;
+      return box.kind === "image"
+        ? `<img class="image" style="${at}" src="${escapeAttr(src(box.image ?? ""))}" alt="">`
+        : `<div class="${box.kind}" style="${at}">${escapeHtml(box.text ?? "")}</div>`;
+    })
+    .join("\n");
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><style>
+html, body { margin: 0; background: #262626; }
+.sheet { position: relative; overflow: hidden; }
+.sheet > * { position: absolute; box-sizing: border-box; }
+.title, .label, .caption { color: #d4d4d4; font: 12px/20px ui-monospace, SFMono-Regular, Menlo, monospace; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.title { font-size: 13px; color: #fafafa; }
+.label { line-height: 22px; color: #a3a3a3; }
+.caption { padding-top: 2px; }
+.image { display: block; outline: 1px solid #5c5c5c; }
+</style></head><body><div class="sheet" style="width:${size.width}px;height:${size.height}px">
+${drawn}
+</div></body></html>`;
+}
+
+/** The fewest columns, so the largest tiles, that fit the whole deck on one sheet. */
+function overviewColumns(count: number, slide: Size): number {
+  for (let columns = 1; columns <= count; columns++) {
+    const tile = tileFor(columns, slide);
+    if (tile.width < MIN_TILE_WIDTH) {
+      break;
+    }
+    const rows = chunk(Array.from({ length: count }), columns).map(() => ({ cells: [] }));
+    if (fits(rows, columns, tile)) {
+      return columns;
+    }
+  }
+  return Math.max(1, Math.floor((SHEET_MAX_EDGE - PAD * 2 + GAP) / (MIN_TILE_WIDTH + GAP)));
+}
+
+/** The tile for `columns` across the widest sheet, never larger than the slide itself. */
+function tileFor(columns: number, slide: Size): Size {
+  const across = Math.floor((SHEET_MAX_EDGE - PAD * 2 - (columns - 1) * GAP) / columns);
+  const width = Math.min(slide.width, across);
+  return { width, height: Math.round((width * slide.height) / slide.width) };
+}
+
+/** Rows split over as few sheets as keep each one within what a vision model reads as drawn. */
+function paginate(rows: SheetRow[], columns: number, tile: Size): SheetRow[][] {
+  const pages: SheetRow[][] = [];
+  let page: SheetRow[] = [];
+  for (const row of rows) {
+    if (page.length > 0 && !fits([...page, row], columns, tile)) {
+      pages.push(page);
+      page = [];
+    }
+    page.push(row);
+  }
+  if (page.length > 0) {
+    pages.push(page);
+  }
+  return pages;
+}
+
+function fits(rows: SheetRow[], columns: number, tile: Size): boolean {
+  const { size } = sheetLayout({ path: "", title: "", tile, columns, rows });
+  return (
+    size.width <= SHEET_MAX_EDGE &&
+    size.height <= SHEET_MAX_EDGE &&
+    size.width * size.height <= SHEET_MAX_PIXELS
+  );
+}
+
+function frameCaption(frame: MotionFrame, beat: MotionBeat): string {
+  if (!frame.end) {
+    return `${Math.round(frame.ms)} ms`;
+  }
+  return beat.frames.length === 1 ? "no motion" : `end · ${Math.round(frame.ms)} ms`;
+}
+
+function sheetPath(dir: string, index: number): string {
+  return `${dir}/sheet-${index + 1}.png`;
+}
+
+function chunk<T>(items: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    chunks.push(items.slice(i, i + size));
+  }
+  return chunks;
+}

package/src/core/shot/morph.ts

@@ -0,0 +1,80 @@
+import { DekError } from "../error.ts";
+import { type PlaywrightRunner, requirePlaywright } from "../playwright.ts";
+import { asResolvedDeck, type ResolvedDeck, requireSection } from "../resolve.ts";
+import { morphEntry } from "../shot-cache.ts";
+import { logicalSize } from "../size.ts";
+import { lastStop, stepKey } from "../step.ts";
+import { videoDocument } from "../video-document.ts";
+import type { ShotFile } from "./still.ts";
+
+export type ShotMorphOptions = {
+  from: string;
+  to: string;
+  /** Where in the transition, 0..1; `parseMorphAt` reads it from the command line. */
+  at: number;
+  /** The player runtime to embed; `playerScript()` from src/runtime. */
+  playerScript: string;
+  runner?: PlaywrightRunner;
+};
+
+/** `--at` as a number between 0 and 1; 0.5 when left out. */
+export function parseMorphAt(value: string | undefined): number {
+  if (value === undefined) {
+    return 0.5;
+  }
+  // Number("") is 0: an empty value would pass for the start of the transition.
+  return requireMorphAt(value.trim() === "" ? Number.NaN : Number(value), value);
+}
+
+function requireMorphAt(at: number, written: string = String(at)): number {
+  if (!Number.isFinite(at) || at < 0 || at > 1) {
+    throw new DekError(`invalid --at "${written}"`, {
+      hint: "use a number between 0 and 1, e.g. --at 0.5",
+    });
+  }
+  return at;
+}
+
+/**
+ * Screenshot the view transition from the last beat of `from` into beat 0 of
+ * `to`, frozen at `at`. The page is the video document (all slides plus the
+ * player runtime), so morphs and theme transitions run exactly as in `dekc video`.
+ */
+export async function shotMorph(dir: string, options: ShotMorphOptions): Promise<ShotFile[]>;
+export async function shotMorph(
+  source: ResolvedDeck,
+  options: ShotMorphOptions,
+): Promise<ShotFile[]>;
+export async function shotMorph(
+  input: string | ResolvedDeck,
+  options: ShotMorphOptions,
+): Promise<ShotFile[]> {
+  const resolved = asResolvedDeck(input);
+  const { deck } = resolved;
+  const at = requireMorphAt(options.at);
+  const fromSection = requireSection(deck, options.from);
+  const toSection = requireSection(deck, options.to);
+  const from = {
+    slideIndex: deck.deck.sections.indexOf(fromSection),
+    beatIndex: lastStop(fromSection.beats),
+  };
+  const to = { slideIndex: deck.deck.sections.indexOf(toSection), beatIndex: 0 };
+  const step = stepKey(fromSection.beats, from.beatIndex);
+
+  const html = videoDocument(resolved, options.playerScript);
+  const entry = morphEntry(deck.dir, options.from, options.to, at, html);
+  if (!entry.cached) {
+    await requirePlaywright(
+      {
+        kind: "morph",
+        viewport: logicalSize(deck.deck.ratio),
+        html,
+        screenshotPath: entry.path,
+        morph: { from, to, at },
+      },
+      options.runner,
+    );
+  }
+  entry.commit();
+  return [{ slug: options.from, step, path: entry.path, to: options.to, at }];
+}

package/src/core/shot/motion.ts

@@ -0,0 +1,187 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import pkg from "../../../package.json";
+import { DekError } from "../error.ts";
+import { deckProjectRoot } from "../path.ts";
+import { type PlaywrightRunner, requirePlaywright } from "../playwright.ts";
+import { deckStops, retreat } from "../position.ts";
+import { asResolvedDeck, type ResolvedDeck, requireSection } from "../resolve.ts";
+import { dropLinks, isCachedFile, outputDir, replaceFile } from "../safe-fs.ts";
+import type { Section } from "../schema.ts";
+import { type MotionFrame, SHEET_LAYOUT_VERSION } from "../sheet.ts";
+import { bundleEntry } from "../shot-cache.ts";
+import { logicalSize } from "../size.ts";
+import { beatAt, type Position, stepKey, stopCount } from "../step.ts";
+import { videoDocument } from "../video-document.ts";
+import { resolveBeat } from "./still.ts";
+
+export type ShotMotionOptions = {
+  slug: string;
+  /** One beat alone, played from the beat before it; every beat when left out. */
+  step?: string;
+  /** The player runtime to embed; `playerScript()` from src/runtime. */
+  playerScript: string;
+  runner?: PlaywrightRunner;
+};
+
+export type ShotMotion = {
+  slug: string;
+  /** The contact sheets: a row per beat, its moments left to right, its settled end last. */
+  sheets: string[];
+  beats: Array<{ step: string; frames: MotionFrame[] }>;
+};
+
+/** Where each go is held before its end, as a share of how long it runs. */
+const MOTION_FRACTIONS = [0, 0.25, 0.5, 0.75];
+
+type MotionPlan = {
+  /** Where the talk stands before the first beat plays; none at the start of the talk. */
+  from?: Position;
+  /** Each beat to play, in order, with its sheet row label and its step key. */
+  beats: Array<{ position: Position; label: string; step: string }>;
+};
+
+/**
+ * Which beats of `section` a motion plays, and from where: every beat from the slide before
+ * (or the start of the talk), or with `step` that beat alone, from the beat before it.
+ */
+export function planMotion(section: Section, sections: Section[], step?: string): MotionPlan {
+  const slideIndex = sections.indexOf(section);
+  const indices =
+    step === undefined
+      ? Array.from({ length: stopCount(section.beats) }, (_, i) => i)
+      : [resolveBeat(section, step).index];
+  const first = indices[0] ?? 0;
+  const from = retreat({ slideIndex, beatIndex: first }, deckStops(sections));
+  const previous = sections[slideIndex - 1];
+  const origin =
+    first > 1
+      ? `from beat ${first - 1}`
+      : first === 1
+        ? "from arrival"
+        : previous
+          ? `from ${previous.slug}`
+          : "from the start";
+  return {
+    ...(from ? { from } : {}),
+    beats: indices.map((beatIndex, i) => ({
+      position: { slideIndex, beatIndex },
+      label: [stopLabel(section, beatIndex), i === 0 ? origin : undefined]
+        .filter(Boolean)
+        .join(" · "),
+      step: stepKey(section.beats, beatIndex),
+    })),
+  };
+}
+
+/**
+ * A slide's beats in motion, each played the way the talk reaches it: the first from the slide
+ * before (or the beat before, with a step), each after from the one it follows. Every go is held
+ * at a few moments of everything it starts, the view transition, the slide's CSS animations and
+ * transitions, and its script, then ended as `dekc shot` ends it. The page is the video document,
+ * so this is the motion the talk and `dekc video` show.
+ */
+export async function shotMotion(dir: string, options: ShotMotionOptions): Promise<ShotMotion>;
+export async function shotMotion(
+  source: ResolvedDeck,
+  options: ShotMotionOptions,
+): Promise<ShotMotion>;
+export async function shotMotion(
+  input: string | ResolvedDeck,
+  options: ShotMotionOptions,
+): Promise<ShotMotion> {
+  const resolved = asResolvedDeck(input);
+  const { deck } = resolved;
+  const section = requireSection(deck, options.slug);
+  const plan = planMotion(section, deck.deck.sections, options.step);
+  const beats = plan.beats.map(({ position, label }) => ({ position, label }));
+  const first = plan.beats[0]?.position.beatIndex ?? 0;
+
+  const html = videoDocument(resolved, options.playerScript);
+  const title = `${section.slug} · motion`;
+  // The page holds the player, but not the worker code that holds and seeks it; the version does.
+  const key = `${JSON.stringify([pkg.version, SHEET_LAYOUT_VERSION, MOTION_FRACTIONS, plan.from, beats, title])}\0${html}`;
+  // Each step keeps its own entry, so runs of different steps neither evict nor race each other.
+  const capture = options.step === undefined ? [section.slug] : [section.slug, String(first)];
+  const bundle = bundleEntry(deck.dir, "motion", capture, key);
+  const manifest = join(bundle.dir, "motion.json");
+  const cached = readMotionManifest(manifest, bundle.dir);
+  if (cached) {
+    bundle.commit();
+    return cached;
+  }
+  // Chromium writes the frames and sheets by name, so no link may stand where one goes.
+  dropLinks(bundle.dir);
+  dropLinks(outputDir(join(bundle.dir, "frames"), deckProjectRoot(deck.dir)));
+
+  const response = await requirePlaywright(
+    {
+      kind: "motion",
+      viewport: logicalSize(deck.deck.ratio),
+      html,
+      motion: {
+        ...(plan.from ? { from: plan.from } : {}),
+        beats,
+        fractions: MOTION_FRACTIONS,
+        dir: bundle.dir,
+        title,
+      },
+    },
+    options.runner,
+  );
+  if (response.motion.length !== beats.length) {
+    throw new DekError("the Playwright worker returned the wrong number of beats", {
+      hint: `asked for ${beats.length}, got ${response.motion.length}; check DEK_PLAYWRIGHT`,
+    });
+  }
+  const result: ShotMotion = {
+    slug: section.slug,
+    sheets: response.sheets,
+    beats: response.motion.map((beat, i) => ({
+      step: plan.beats[i]?.step ?? "0",
+      frames: beat.frames,
+    })),
+  };
+  replaceFile(manifest, `${JSON.stringify(result)}\n`);
+  bundle.commit();
+  return result;
+}
+
+/**
+ * A motion answered before, while every file it names is still there. The cache is dek's own
+ * output, but a manifest that does not read back whole, or names a file outside its own folder,
+ * is taken again rather than trusted.
+ */
+function readMotionManifest(path: string, dir: string): ShotMotion | undefined {
+  if (!isCachedFile(path)) {
+    return undefined;
+  }
+  try {
+    const result = JSON.parse(readFileSync(path, "utf8")) as ShotMotion;
+    const files = [
+      ...result.sheets,
+      ...result.beats.flatMap((beat) => beat.frames.map((frame) => frame.path)),
+    ];
+    const inDir = (file: unknown): file is string => {
+      if (typeof file !== "string") {
+        return false;
+      }
+      const rel = relative(dir, file);
+      return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+    };
+    // Every path is checked to be in the folder before any is looked at, since a look removes a link.
+    return files.length > 0 && files.every(inDir) && files.every((file) => isCachedFile(file))
+      ? result
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** "arrival" for a slide as it arrives; "beat 2 · hook" at a beat. */
+function stopLabel(section: Section, beatIndex: number): string {
+  if (beatIndex === 0) {
+    return "arrival";
+  }
+  return [`beat ${beatIndex}`, beatAt(section.beats, beatIndex)?.id].filter(Boolean).join(" · ");
+}