@hajimism/dek 0.3.3 → 0.4.0

package/src/core/shot-cache.ts

@@ -3,6 +3,7 @@ import { readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { escapeRegExp } from "./escape.ts";
 import { cacheDir, deckProjectRoot } from "./path.ts";
+import type { ProjectDeck } from "./resolve.ts";
 import { isCachedFile, outputDir } from "./safe-fs.ts";
 import type { Section } from "./schema.ts";
 import { lastStop, stepKey } from "./step.ts";
@@ -26,12 +27,22 @@ export type CacheEntry = {
 /** A cached folder of files, such as a set of contact sheets. */
 type CacheBundle = {
   dir: string;
+  /** The project the folder is in, for what a capture writes inside it. */
+  root: string;
   commit(): void;
 };
 
-/** `.cache/shots`, made if missing, where it really is; a link out of the project is an error. */
-function shotsDir(deckDir: string): string {
-  return outputDir(cacheDir(deckDir, "shots"), deckProjectRoot(deckDir));
+/** The deck a capture is of: its folder, and for a ref, where its cache is instead. */
+type ShotDeck = Pick<ProjectDeck, "dir" | "cache">;
+
+/**
+ * `.cache/shots`, made if missing, where it really is, and the project it is in; a link out of
+ * the project is an error. A ref's shots go in the cache of the project that reads it.
+ */
+function shotsDir(deck: ShotDeck): { dir: string; root: string } {
+  const root = deck.cache?.root ?? deckProjectRoot(deck.dir);
+  const dir = deck.cache ? join(deck.cache.dir, "shots") : cacheDir(deck.dir, "shots");
+  return { dir: outputDir(dir, root), root };
 }
 
 function contentHash(text: string): string {
@@ -52,7 +63,7 @@ export function shotName(parts: string[], content: string): string {
  * `--step 2` and a still at the last beat, `dekc build`'s link preview included, are one file.
  */
 export function stillEntry(
-  deckDir: string,
+  deck: ShotDeck,
   section: Section,
   beatIndex: number,
   html: string,
@@ -64,18 +75,18 @@ export function stillEntry(
     `${section.slug}-${step}`,
     `${section.slug}-${beatIndex}`,
   ];
-  return fileEntry(deckDir, [section.slug, step], html, legacy);
+  return fileEntry(deck, [section.slug, step], html, legacy);
 }
 
 /** The frame `at` of the move from `from` into `to`. */
 export function morphEntry(
-  deckDir: string,
+  deck: ShotDeck,
   from: string,
   to: string,
   at: number,
   html: string,
 ): CacheEntry {
-  return fileEntry(deckDir, [from, to, String(at)], `${at}\0${html}`, [`${from}-to-${to}-${at}`]);
+  return fileEntry(deck, [from, to, String(at)], `${at}\0${html}`, [`${from}-to-${to}-${at}`]);
 }
 
 /**
@@ -83,29 +94,26 @@ export function morphEntry(
  * folder, so runs of different captures neither evict nor race each other.
  */
 export function bundleEntry(
-  deckDir: string,
+  deck: ShotDeck,
   kind: "sheets" | "motion",
   parts: string[],
   content: string,
 ): CacheBundle {
-  const root = deckProjectRoot(deckDir);
-  const parent = outputDir(join(shotsDir(deckDir), kind), root);
+  const shots = shotsDir(deck);
+  const { root } = shots;
+  const parent = outputDir(join(shots.dir, kind), root);
   const base = parts.join(SEPARATOR);
   const name = base ? `${base}.${contentHash(content)}` : contentHash(content);
   const pattern = new RegExp(`^${base ? `${escapeRegExp(base)}\\.` : ""}${HASH}$`);
   return {
     dir: outputDir(join(parent, name), root),
+    root,
     commit: () => prune(parent, [pattern], name, { recursive: true }),
   };
 }
 
-function fileEntry(
-  deckDir: string,
-  parts: string[],
-  content: string,
-  legacy: string[],
-): CacheEntry {
-  const dir = shotsDir(deckDir);
+function fileEntry(deck: ShotDeck, parts: string[], content: string, legacy: string[]): CacheEntry {
+  const { dir } = shotsDir(deck);
   const name = shotName(parts, content);
   const path = join(dir, name);
   const patterns = [

package/src/core/slide-measure.ts

@@ -45,6 +45,22 @@ export type MeasuredElement = {
   picture: boolean;
   /** Whether it paints its own box: a background, or a border in a color that shows. */
   paints: boolean;
+  /**
+   * Whether it is laid out on a line of text, as `<strong>` or an inline-block chip is, rather
+   * than as a box of its own: it sits on the line's baseline.
+   */
+  inline: boolean;
+  /**
+   * Whether a transform turns or skews it, its own or an ancestor's: its box is then the box
+   * around its shape, not the shape the audience sees.
+   */
+  tilted: boolean;
+  /**
+   * Where the first line of its own text sits, in viewport pixels from the top: the baseline of
+   * its first text node's first line, which is not its first line when an inline element such as
+   * `<strong>` opens it.
+   */
+  baseline?: number;
   /**
    * What an ancestor inside the slide cuts it to, with `overflow` other than `visible`: the
    * nearest such ancestor, and the box every one of them leaves visible. `intended` when the cut is
@@ -196,6 +212,35 @@ export function measureSlideInPage(): SlideMeasure {
         .map(toBox);
     });
 
+  // Turned or skewed, by its own transform or rotate, or an ancestor's.
+  const tilts = new Map<Element, boolean>();
+  const tilted = (el: Element | null): boolean => {
+    if (!el || el === slide) {
+      return false;
+    }
+    const known = tilts.get(el);
+    if (known !== undefined) {
+      return known;
+    }
+    const style = getComputedStyle(el);
+    const matrix = style.transform === "none" ? undefined : new DOMMatrixReadOnly(style.transform);
+    const own =
+      (matrix !== undefined && (matrix.b !== 0 || matrix.c !== 0)) ||
+      (style.rotate !== "none" && style.rotate !== "");
+    const found = own || tilted(el.parentElement);
+    tilts.set(el, found);
+    return found;
+  };
+  // A line's baseline sits the font's ascent below the top of the box its text is drawn in.
+  const metrics = document.createElement("canvas").getContext("2d");
+  const baselineOf = (style: CSSStyleDeclaration, line: Box | undefined): number | undefined => {
+    if (!line || !metrics) {
+      return undefined;
+    }
+    metrics.font = `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+    return line.top + metrics.measureText("x").fontBoundingBoxAscent;
+  };
+
   const all = [...slide.querySelectorAll("*")];
   const indexOf = new Map(all.map((el, index) => [el, index]));
   const elements = all.map((el): MeasuredElement => {
@@ -209,19 +254,24 @@ export function measureSlideInPage(): SlideMeasure {
     const whole = el instanceof HTMLElement ? el.innerText : el.textContent;
     const text = own || squash(whole ?? "");
     const parentEl = el.parentElement;
+    const textRects = lineBoxes(textNodes);
+    const baseline = baselineOf(style, textRects[0]);
     return {
       box: describe(el),
       parent: parentEl ? (indexOf.get(parentEl) ?? -1) : -1,
       rect: extent(el, textNodes),
       ...(text ? { text } : {}),
       ownText: own !== "",
-      textRects: lineBoxes(textNodes),
+      textRects,
+      ...(baseline !== undefined ? { baseline } : {}),
       opacity: opacityOf(el),
       fontSize: Number.parseFloat(style.fontSize),
       fontWeight: Number(style.fontWeight) || 400,
       decorative: el.closest('[aria-hidden="true"]') !== null,
       picture: pictures.has(el.tagName.toLowerCase()) || style.backgroundImage.includes("url("),
       paints: paints(style),
+      inline: style.display.startsWith("inline"),
+      tilted: tilted(el),
       ...clipped(clipOf(el)),
     };
   });

package/src/core/slide-script-eval.ts

@@ -6,6 +6,7 @@ import {
   lineMatching,
   type SlideScriptProblem,
   staticProblems,
+  withoutImports,
 } from "./slide-script.ts";
 import { BUN_FLAGS } from "./spawn.ts";
 import { suggest } from "./suggest.ts";
@@ -77,13 +78,6 @@ type PendingScript = {
   withoutImports: boolean;
 };
 
-const IMPORT_RE = /^[ \t]*import\s+(?:type\s+)?(?:[\s\S]*?\sfrom\s*)?["'][^"'\n]+["'][ \t]*;?/gm;
-
-/** The code with its import declarations blanked out, lines kept in place. */
-function withoutImports(code: string): string {
-  return code.replace(IMPORT_RE, (match) => match.replace(/[^\n]/g, " "));
-}
-
 function prepareScripts(scripts: ScriptInput[]): {
   results: SlideScriptProblem[][];
   pending: PendingScript[];
@@ -97,7 +91,15 @@ function prepareScripts(scripts: ScriptInput[]): {
     const source = importsOnly ? withoutImports(script.code) : script.code;
     const compiled =
       problems.length > 0 && !importsOnly ? undefined : compileSlideScript(source, "slide");
-    if (compiled && "problem" in compiled) {
+    // The blanked code can fail for the blanking's sake: an import it left is refused again, and
+    // already reported, and a syntax error is its own, since the script as written parsed.
+    const blanking =
+      importsOnly &&
+      compiled &&
+      "problem" in compiled &&
+      (compiled.problem.message === IMPORTS_MESSAGE ||
+        compiled.problem.message.startsWith("syntax error: "));
+    if (compiled && "problem" in compiled && !blanking) {
       problems.push(compiled.problem);
     }
     results.push(problems);

package/src/core/slide-script.ts

@@ -4,8 +4,35 @@ import { escapeRegExp } from "./escape.ts";
 import { listSlideFiles } from "./resolve.ts";
 import { stillDrawScript } from "./slide-draw.ts";
 
-/** Slide scripts are `slides/<slug>.ts`; plain JavaScript is valid TypeScript. */
-const transpiler = new Bun.Transpiler({ loader: "ts" });
+/** Thrown in place of reading a script that imports; see `transpiler`. */
+class ImportsRefused extends Error {}
+
+/** A first `#!` line, a comment that `scanImports` rejects; Bun ends it at any line terminator. */
+const HASHBANG_RE = /^#![^\n\r\u2028\u2029]*/;
+
+/**
+ * Bun's transpiler, which nothing else in dek holds. Bun's own `scan` and `transformSync` run a
+ * macro, an import marked `type: "macro"`, in this process while they read the code, so a ref's
+ * slide script or a cloned project's would run inside dek. `scanImports` runs none: both methods
+ * here ask it first, and throw `ImportsRefused` for code that imports anything.
+ * Slide scripts are `slides/<slug>.ts`; plain JavaScript is valid TypeScript.
+ */
+const transpiler = (() => {
+  const bun = new Bun.Transpiler({ loader: "ts" });
+  /** The code to read, once it imports nothing; a syntax error throws as Bun reports it. */
+  function importFree(code: string): string {
+    const source = code.replace(HASHBANG_RE, "");
+    // A `require(…)` calls a function a page does not have, and Bun reads nothing for it.
+    if (bun.scanImports(source).some((found) => found.kind !== "require-call")) {
+      throw new ImportsRefused();
+    }
+    return source;
+  }
+  return {
+    scan: (code: string) => bun.scan(importFree(code)),
+    transformSync: (code: string) => bun.transformSync(importFree(code)),
+  };
+})();
 
 const DEFAULT_EXPORT_RE = /\bexport\s+default\b/;
 /** In transpiled output, comments are gone and each statement starts a line. */
@@ -35,30 +62,94 @@ function withLine(problem: SlideScriptProblem, line: number | undefined): SlideS
   return line === undefined ? problem : { ...problem, line };
 }
 
+function importsProblem(code: string): SlideScriptProblem {
+  return withLine(
+    {
+      message: IMPORTS_MESSAGE,
+      hint: "remove the import and write what it gave in this file; DekSlide is global, from .dek/slide.d.ts",
+    },
+    lineMatching(code, /^\s*import\b/),
+  );
+}
+
+/** A string literal, which can hold a quote, a brace, or a semicolon. */
+const STRING = String.raw`"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'`;
+/**
+ * A name's character. Each part below takes only what it can hold, and none starts with a space
+ * where the part before it ends with any, so no text is read more than once from each place.
+ */
+const NAME = String.raw`[\p{ID_Continue}$]`;
+/** A specifier, then `with { … }` or the older `assert { … }`, to the end of the statement. */
+const SOURCE = String.raw`(?:${STRING})(?:\s*(?:with|assert)\s*\{(?:${NAME}|[\s,:]|${STRING})*\})?[ \t]*;?`;
+/** Where a statement can start: a line's start, or after a statement or a comment on its line. */
+const STATEMENT = String.raw`(?<=^|[;}]|\*\/)[ \t]*`;
+/** What an import declaration binds, up to its `from`, which no other import comes before. */
+const BINDINGS = String.raw`(?:(?!\bimport\b)(?:${NAME}|[\s,*{}])|${STRING})*?\bfrom\s*`;
+/** An `export { … }` clause, or the name of an `export * as`, captured. */
+const EXPORT_NAMES = String.raw`export\s*(?:\{((?:${NAME}|[\s,]|${STRING})*)\}|\*\s*as\s+(${NAME}+|${STRING}))`;
+
+/**
+ * What `scanImports` counts as an import, as the text shows it: an import declaration, an
+ * `export … from`, and the `import` of an `import(…)`.
+ */
+const IMPORT_RE = new RegExp(
+  String.raw`${STATEMENT}(?:import(?!${NAME})\s*(?:type\b\s*)?(?:(?=\S)${BINDINGS})?|(?:${EXPORT_NAMES}|export\s*\*)\s*from\s*)${SOURCE}|(?<!${NAME}|\.)import(?=\s*\()`,
+  "gmu",
+);
+const EXPORT_NAMES_RE = new RegExp(STATEMENT + EXPORT_NAMES, "gmu");
+
+/** The code with its imports blanked out, attributes included, lines kept in place. */
+export function withoutImports(code: string): string {
+  return code.replace(IMPORT_RE, (match) => match.replace(/[^\n]/g, " "));
+}
+
+/**
+ * The names `export { … }` and `export * as` give the module: what follows `as`, or the name
+ * itself. Bun leaves out of a scan one whose binding, or whose `from`, the blanking took.
+ */
+function exportedNames(code: string): string[] {
+  return [...code.matchAll(EXPORT_NAMES_RE)].flatMap(([, clause = "", star]) =>
+    (star === undefined ? clause.split(",") : [star])
+      .map((item) => item.trim())
+      .filter((item) => item !== "" && !/^type\s+(?!as\b)/.test(item))
+      .map((item) => (item.split(/\s+as\s+/).at(-1) ?? item).replace(/^(["'])(.*)\1$/, "$2")),
+  );
+}
+
 /**
  * What stops a script from being one self-contained module whose only export is the default
  * object, found without running it.
  */
 export function staticProblems(code: string): SlideScriptProblem[] {
-  let scan: ReturnType<Bun.Transpiler["scan"]>;
+  const problems: SlideScriptProblem[] = [];
+  let exports: string[] | undefined;
   try {
-    scan = transpiler.scan(code);
+    const scan = transpiler.scan(code);
+    // `require.resolve(…)` is the import scanImports does not report; nothing runs for it.
+    if (scan.imports.length > 0) {
+      problems.push(importsProblem(code));
+    }
+    exports = scan.exports;
   } catch (error) {
-    return [syntaxProblem(error)];
-  }
-  const problems: SlideScriptProblem[] = [];
-  if (scan.imports.length > 0) {
-    problems.push(
-      withLine(
-        {
-          message: IMPORTS_MESSAGE,
-          hint: "remove the import and write what it gave in this file; DekSlide is global, from .dek/slide.d.ts",
-        },
-        lineMatching(code, /^\s*import\b/),
-      ),
-    );
+    if (!(error instanceof ImportsRefused)) {
+      return [syntaxProblem(error)];
+    }
+    // Imports alone do not stop the rest of the checks, which read the script without them.
+    problems.push(importsProblem(code));
+    const blanked = withoutImports(code);
+    try {
+      // In Bun's order, which sorts the names.
+      exports = [...new Set([...transpiler.scan(blanked).exports, ...exportedNames(code)])].sort();
+    } catch (blankedError) {
+      // An error on a line the blanking left alone is the script's own, and all Bun said before.
+      const own = blankedError instanceof ImportsRefused ? undefined : syntaxProblem(blankedError);
+      const at = own?.line === undefined ? undefined : own.line - 1;
+      if (own && at !== undefined && code.split("\n")[at] === blanked.split("\n")[at]) {
+        return [own];
+      }
+    }
   }
-  for (const name of scan.exports.filter((entry) => entry !== "default")) {
+  for (const name of (exports ?? []).filter((entry) => entry !== "default")) {
     problems.push(
       withLine(
         {
@@ -72,7 +163,8 @@ export function staticProblems(code: string): SlideScriptProblem[] {
       ),
     );
   }
-  if (!scan.exports.includes("default") || !DEFAULT_EXPORT_RE.test(code)) {
+  // Exports the blanking left unreadable leave the source to say whether one is the default.
+  if (!(exports?.includes("default") ?? true) || !DEFAULT_EXPORT_RE.test(code)) {
     problems.push({
       message: "missing export default",
       hint: "end the script with export default { draw(slide, { t }) {} } satisfies DekSlide",
@@ -116,7 +208,9 @@ export function compileSlideScript(
   try {
     js = transpiler.transformSync(code);
   } catch (error) {
-    return { problem: syntaxProblem(error) };
+    return {
+      problem: error instanceof ImportsRefused ? importsProblem(code) : syntaxProblem(error),
+    };
   }
   let firstError: unknown;
   for (const match of js.matchAll(EXPORT_DEFAULT_LINE_RE)) {

package/src/core/sync.ts

@@ -132,7 +132,7 @@ export function syncDeck(input: string | ResolvedDeck): SyncResult {
     const skeleton = sectionSkeleton(deck.deck, index, layouts);
     const current = existing.get(section.slug);
     if (current) {
-      const html = readFileSync(current, "utf8");
+      const html = readSourceIfExists(current, project.root) ?? "";
       if (!record.owns(html, skeleton)) {
         continue;
       }
@@ -170,7 +170,7 @@ function removeOrphanSkeletons(
   const removed: string[] = [];
   const kept: string[] = [];
   for (const [slug, path] of orphans) {
-    const html = readFileSync(path, "utf8");
+    const html = readSourceIfExists(path, root) ?? "";
     const beside = ([...SLIDE_SIDECARS, ".js"] as const).some((ext) =>
       existsSync(paths.slide(slug, ext)),
     );

package/src/core/visual-cache.ts

@@ -19,10 +19,12 @@ export type PageFindings = Required<PagesResponse>;
  * its source is part of every key, and a cache written by another dek is never read.
  */
 const MEASURERS = [
+  "alignment.ts",
   "playwright-visual.ts",
   "slide-measure.ts",
   "text-contrast.ts",
   "fill.ts",
+  "line-break.ts",
   "overflow.ts",
   "pseudo-text.ts",
   "finish-beat.ts",

package/src/core/visual.ts

@@ -83,7 +83,7 @@ async function visualDeck(
     return { diagnostics: [], fills: [] };
   }
 
-  const actions: PageAction[] = ["overflow", "contrast", "fill"];
+  const actions: PageAction[] = ["overflow", "contrast", "fill", "breaks", "alignment"];
   const viewport = logicalSize(deck.deck.ratio);
   const cache = visualCache(deck.dir, { viewport, actions });
   const keyed = pages.map((page) => {
@@ -137,6 +137,8 @@ async function visualDeck(
         contrasts: all.flatMap((page) => page.contrasts),
         drawErrors: all.flatMap((page) => page.drawErrors),
         collisions: all.flatMap((page) => page.collisions ?? []),
+        lineBreaks: all.flatMap((page) => page.lineBreaks ?? []),
+        misalignments: all.flatMap((page) => page.misalignments ?? []),
       },
       deck.dir,
     ),
@@ -147,13 +149,20 @@ async function visualDeck(
   };
 }
 
-const NOTHING_FOUND: PageFindings = {
-  overflows: [],
-  contrasts: [],
-  drawErrors: [],
-  collisions: [],
-  fills: [],
-};
+/** A page's findings before any is found, each list its own to push to. */
+function noFindings(): PageFindings {
+  return {
+    overflows: [],
+    contrasts: [],
+    drawErrors: [],
+    collisions: [],
+    fills: [],
+    lineBreaks: [],
+    misalignments: [],
+  };
+}
+
+const NOTHING_FOUND: PageFindings = noFindings();
 
 /** A page's findings name its slide and step, which no two pages of one run share. */
 function pageId(page: { slug: string; step: string }): string {
@@ -165,13 +174,7 @@ function findingsByPage(response: PagesResponse): Map<string, PageFindings> {
   const pages = new Map<string, PageFindings>();
   const of = (finding: { slug: string; step: string }): PageFindings => {
     const id = pageId(finding);
-    const found = pages.get(id) ?? {
-      overflows: [],
-      contrasts: [],
-      drawErrors: [],
-      collisions: [],
-      fills: [],
-    };
+    const found = pages.get(id) ?? noFindings();
     pages.set(id, found);
     return found;
   };
@@ -190,6 +193,12 @@ function findingsByPage(response: PagesResponse): Map<string, PageFindings> {
   for (const finding of response.fills ?? []) {
     of(finding).fills.push(finding);
   }
+  for (const finding of response.lineBreaks ?? []) {
+    of(finding).lineBreaks.push(finding);
+  }
+  for (const finding of response.misalignments ?? []) {
+    of(finding).misalignments.push(finding);
+  }
   return pages;
 }
 
@@ -352,9 +361,139 @@ function visualDiagnostics(response: PagesResponse, deckDir: string): Diagnostic
     ...groupBySteps(response.collisions ?? [], collisionKey).map((group) =>
       collisionDiagnostic(group, paths),
     ),
+    ...groupBySteps(response.lineBreaks ?? [], lineBreakKey).map((group) =>
+      lineBreakDiagnostic(group, paths),
+    ),
+    ...groupBySteps(response.misalignments ?? [], misalignmentKey).map((group) =>
+      misalignmentDiagnostic(group, paths),
+    ),
   ];
 }
 
+type MisalignmentSample = NonNullable<PagesResponse["misalignments"]>[number];
+
+function misalignmentKey(m: MisalignmentSample): string {
+  return [m.slug, m.box, m.text ?? "", m.other, m.otherText ?? "", m.edge, m.of].join("\0");
+}
+
+/** How the message names an edge two items share. */
+const EDGE_NAMES: Record<MisalignmentSample["edge"], string> = {
+  top: "tops",
+  middle: "middles",
+  bottom: "bottoms",
+  left: "left edges",
+  center: "centers",
+  right: "right edges",
+};
+
+/**
+ * Two items that nearly line up and do not. The fix depends on the edge: a start lines up with
+ * the same space before it, an end with one size, a middle with one way of centering, and text in
+ * cards that line up with one padding.
+ */
+function misalignmentDiagnostic(
+  { first, items, steps }: StepGroup<MisalignmentSample>,
+  paths: DeckPaths,
+): Diagnostic {
+  // By the most they miss at any step, so the fix covers the worst beat.
+  const by = Math.max(...items.map((item) => item.by));
+  const pair = `${describeTarget(first.box, first.text)}and ${describeTarget(first.other, first.otherText).trimEnd()}`;
+  const where =
+    first.of === "text"
+      ? `almost start their text ${first.edge === "left" ? "at one left edge" : "on one line"}`
+      : `almost line up at their ${EDGE_NAMES[first.edge]}`;
+  const css = `slides/${first.slug}.css`;
+  const both = `${first.box} and ${first.other}`;
+  const why = "an edge a few pixels off reads as a mistake, not a choice";
+  const hint =
+    first.of === "text"
+      ? `give ${both} the same padding in ${css}, so their text starts on one line`
+      : first.edge === "top" || first.edge === "left"
+        ? `line ${first.box} up with ${first.other} in ${css}, with the same margin, padding, or alignment: ${why}`
+        : first.edge === "bottom" || first.edge === "right"
+          ? `give ${both} one ${first.edge === "bottom" ? "height" : "width"} in ${css}, with align-items: stretch or the same size: ${why}`
+          : `center ${both} on one line in ${css}, with align-items: center or the same margins: ${why}`;
+  return diag("DEK036", {
+    message: `${pair} ${where}, ${by}px apart, ${atSteps(steps)}`,
+    path: paths.slide(first.slug, ".html"),
+    slug: first.slug,
+    hint,
+    data: {
+      box: first.box,
+      ...(first.text ? { text: first.text } : {}),
+      other: first.other,
+      ...(first.otherText ? { otherText: first.otherText } : {}),
+      edge: first.edge,
+      of: first.of,
+      by,
+      steps,
+    },
+  });
+}
+
+type LineBreakSample = NonNullable<PagesResponse["lineBreaks"]>[number];
+
+function lineBreakKey(b: LineBreakSample): string {
+  return [b.slug, b.box, b.text ?? "", b.kind, ...b.lines].join("\0");
+}
+
+/** Where a line ends: the end of one line and the start of the next, as far as either reads. */
+function breakAt(lines: string[], phrased: string[]): string {
+  const differs = lines.findIndex((line, at) => line !== phrased[at]);
+  const at = Math.max(0, Math.min(differs, lines.length - 2));
+  const end = [...(lines[at] ?? "")];
+  const start = [...(lines[at + 1] ?? "")];
+  const half = SNIPPET_CHARS / 2;
+  const before = end.length > half ? `…${end.slice(-half).join("")}` : end.join("");
+  const after = start.length > half ? `${start.slice(0, half).join("")}…` : start.join("");
+  return `${before} / ${after}`;
+}
+
+/**
+ * A line break the audience trips over. One inside a phrase is fixed where Japanese is told to
+ * break by phrase: on `.slide` in theme.css, for every slide, unless a rule takes it away from
+ * this text. A remnant on a last line is the text's own to fix, or the theme's text-wrap.
+ */
+function lineBreakDiagnostic(
+  { first, steps }: StepGroup<LineBreakSample>,
+  paths: DeckPaths,
+): Diagnostic {
+  const target = describeTarget(first.box, first.text);
+  const css = `slides/${first.slug}.css`;
+  const yourself = "break the line yourself with <br>";
+  const common = {
+    slug: first.slug,
+    data: {
+      kind: first.kind,
+      box: first.box,
+      ...(first.text ? { text: first.text } : {}),
+      lines: first.lines,
+      ...(first.kind === "split" ? { phrased: first.phrased } : { tail: first.tail }),
+      steps,
+    },
+  };
+  if (first.kind === "split") {
+    const theme = first.wordBreak !== "auto-phrase";
+    return diag("DEK035", {
+      message: `${target}breaks a line inside a phrase, at "${breakAt(first.lines, first.phrased)}", ${atSteps(steps)}`,
+      path: theme ? paths.theme : paths.slide(first.slug, ".html"),
+      hint: theme
+        ? `add word-break: auto-phrase to .slide in theme.css, so Japanese breaks between phrases on every slide; or ${yourself} where its sense breaks`
+        : `a rule gives it word-break: normal where .slide breaks by phrase: remove it from ${css} or theme.css, or ${yourself} where its sense breaks`,
+      ...common,
+    });
+  }
+  const evened = first.textWrap === "pretty" || first.textWrap === "balance";
+  return diag("DEK035", {
+    message: `${target}leaves "${first.tail}" alone on its last line ${atSteps(steps)}`,
+    path: paths.slide(first.slug, ".html"),
+    hint: evened
+      ? `reword it so its last line holds more, or ${yourself} earlier`
+      : `even out its lines with text-wrap: pretty, or balance for a heading, in ${css} or for every slide in theme.css; or reword it, or ${yourself}`,
+    ...common,
+  });
+}
+
 type CollisionSample = NonNullable<PagesResponse["collisions"]>[number];
 
 function collisionKey(c: CollisionSample): string {

package/src/core/voice.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { z } from "zod";
 import type { VoiceDict } from "./cue.ts";
@@ -269,10 +269,8 @@ export function parseTimelineJson(text: string, path?: string): Timeline {
 
 export function loadCachedTimeline(deckDir: string): Timeline | undefined {
   const path = voiceCacheFile(deckDir, "timeline.json");
-  if (!existsSync(path)) {
-    return undefined;
-  }
-  return parseTimelineJson(readFileSync(path, "utf8"), path);
+  const source = readDeckFile(deckDir, path);
+  return source === undefined ? undefined : parseTimelineJson(source, path);
 }
 
 export function tryLoadCachedTimeline(deckDir: string): Timeline | undefined {