@hajimism/dek 0.3.2 → 0.4.0

package/src/cli/scope.ts

@@ -1,13 +1,14 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { DekError } from "../core/error.ts";
+import { shellName, shellQuote } from "../core/escape.ts";
 import {
   isRefName,
+  packFile,
   parseRefSource,
-  REF_MARKER,
-  readRefMeta,
   refLicense,
+  refReadOnlyError,
   refState,
+  requireProject,
 } from "../core/ref.ts";
 import {
   locateDeck,
@@ -18,7 +19,7 @@ import {
 } from "../core/resolve.ts";
 import { suggest } from "../core/suggest.ts";
 
-export { requireSection };
+export { requireProject, requireSection };
 
 export type Scope = {
   project: Project;
@@ -51,18 +52,6 @@ export type DecksTarget = {
   ref?: RefInfo;
 };
 
-export function requireProject(cwd: string): Project {
-  const project = resolveProject(cwd);
-  if (existsSync(join(project.root, REF_MARKER))) {
-    const name = readRefMeta(project.root)?.name ?? "<ref>";
-    throw new DekError("this directory is inside a ref; refs are read-only", {
-      path: project.root,
-      hint: `run dek from your own project instead: \`dekc show ${name} <slug>\``,
-    });
-  }
-  return project;
-}
-
 export function inferDeckName(project: Project, cwd: string): string | undefined {
   const located = locateDeck(project.root, cwd);
   if (!located) {
@@ -138,9 +127,7 @@ export function resolveScope(cwd: string, options: { deck?: string } = {}): Scop
     return { project };
   }
   if (isRefName(name)) {
-    throw new DekError(`"${name}" is a ref; refs are read-only`, {
-      hint: `read it with \`dekc show ${name} <slug>\`, then copy what you need into your own deck and rewrite it in your theme`,
-    });
+    throw refReadOnlyError(name);
   }
   const deck = project.decks.find((entry) => entry.name === name);
   if (!deck) {
@@ -148,10 +135,11 @@ export function resolveScope(cwd: string, options: { deck?: string } = {}): Scop
     if (failed) {
       throw failed.error;
     }
-    const guess = suggest(name, [
+    const near = suggest(name, [
       ...project.decks.map((entry) => entry.name),
       ...project.failed.map((entry) => entry.name),
     ]);
+    const guess = near === undefined ? undefined : shellName(near);
     throw new DekError(`deck "${name}" not found`, {
       path: join(project.root, "decks", name),
       hint: guess ? `did you mean \`${guess}\`? run \`dekc ls\` for every deck` : "run `dekc ls`",
@@ -273,19 +261,25 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
   if (pinned === undefined) {
     throw new DekError(`ref "${source.name}" is not added`, {
       path: project.configPath,
-      hint: `run \`dekc ref ${arg}\``,
+      hint:
+        source.kind === "file"
+          ? "add it from the pack you were sent: `dekc ref <file>.tgz`"
+          : `run \`dekc ref ${shellQuote(arg)}\``,
     });
   }
-  if (source.rev !== undefined && source.rev !== pinned) {
+  // What adds the ref again: a pack's ref from its file, any other from its name.
+  const added = source.kind === "file" ? packFile(source.deck) : `${source.name}@${pinned}`;
+  const again = `dekc ref ${shellQuote(added)}`;
+  if (source.kind === "github" && source.rev !== undefined && source.rev !== pinned) {
     throw new DekError(`"${arg}" is not the pinned version, ${pinned.slice(0, 7)}`, {
       path: project.configPath,
-      hint: `run \`dekc ref ${arg}\` to pin that version, or drop @${source.rev}`,
+      hint: `run \`dekc ref ${shellQuote(arg)}\` to pin that version, or drop @${source.rev}`,
     });
   }
   if (!fetched) {
     throw new DekError(`ref "${source.name}" is not fetched`, {
       path: dir,
-      hint: `run \`dekc ref ${source.name}@${pinned}\``,
+      hint: `run \`${again}\``,
     });
   }
   const snapshot = resolveProject(dir);
@@ -297,12 +291,16 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
     }
     throw new DekError(`ref "${source.name}" has no deck "${source.deck}"`, {
       path: dir,
-      hint: `run \`dekc ref ${source.name}@${pinned}\` to fetch it again`,
+      hint: `run \`${again}\` to fetch it again`,
     });
   }
   return {
     project: snapshot,
-    deck: found,
+    // Read where it is, but cached in this project: nothing is written in a snapshot.
+    deck: {
+      ...found,
+      cache: { dir: join(project.root, ".cache", relative(project.root, dir)), root: project.root },
+    },
     ref: { name: source.name, rev: pinned, dir, license: refLicense(dir) },
   };
 }

package/src/cli/shot.ts

@@ -1,4 +1,5 @@
 import { DekError } from "../core/error.ts";
+import { shellQuote } from "../core/escape.ts";
 import { parseMorphAt, shotMorph } from "../core/shot/morph.ts";
 import { type ShotMotion, shotMotion } from "../core/shot/motion.ts";
 import { type ShotFile, shotDeck, shotSheet } from "../core/shot/still.ts";
@@ -91,7 +92,7 @@ export function parseShotMode(options: ShotCommandOptions): ShotMode {
     if (slug) {
       refuse(
         "--sheet with a slug",
-        `--sheet tiles every slide; for one slide's beats, run \`dekc shot ${slug} --motion\``,
+        `--sheet tiles every slide; for one slide's beats, run \`dekc shot ${shellQuote(slug)} --motion\``,
       );
     }
     return { kind: "sheet" };

package/src/cli/text.ts

@@ -1,6 +1,9 @@
 // How each command's result reads as text; commands.ts says which command prints which.
 // The pieces the dev server's log shares, such as diagnostics and tables, are in format.ts.
 import type { Diagnostic, SkippedCheck } from "../core/diagnostic.ts";
+import { shellQuote } from "../core/escape.ts";
+import { unprinted } from "../core/prose.ts";
+import { packFile, parseRefSource } from "../core/ref-name.ts";
 import { formatClock } from "../core/timing.ts";
 import type { AnnotationsCliResult } from "./annotations.ts";
 import type { BuildCliResult } from "./build.ts";
@@ -13,7 +16,9 @@ import type { LsDeckResult, LsListResult } from "./ls.ts";
 import type { MarksCliResult } from "./marks.ts";
 import type { MvResult } from "./mv.ts";
 import type { NewResult } from "./new.ts";
+import type { PackCliResult } from "./pack.ts";
 import type { PdfCliResult } from "./pdf.ts";
+import type { PptxCliResult } from "./pptx.ts";
 import type { RefCliResult } from "./ref.ts";
 import type { ShotCliResult } from "./shot.ts";
 import type { ShowResult } from "./show.ts";
@@ -130,7 +135,8 @@ export function formatInit(data: InitResult): string {
 /** The deck, and any of dek's own files it brought up to date: the rest is the deck's, and new. */
 export function formatNew(data: NewResult): string {
   const updated = data.updated.map((path) => `  ${path} (updated)`);
-  return withNext([`created deck ${data.name}`, ...updated].join("\n"), data.next);
+  const warnings = data.warnings.map((warning) => `warning: ${warning}`);
+  return withNext([`created deck ${data.name}`, ...updated, ...warnings].join("\n"), data.next);
 }
 
 export function formatMv(data: MvResult): string {
@@ -227,6 +233,31 @@ export function formatPdf(data: PdfCliResult): string {
   return data.outs.map((path) => `wrote ${path}`).join("\n");
 }
 
+/**
+ * Each file written, and what it laid over its pictures, naming the slides that kept everything
+ * in the picture, which are the ones to rewrite toward shapes.
+ */
+export function formatPptx(data: PptxCliResult): string {
+  return data.outs
+    .flatMap((path, index) => {
+      const lifted = data.lifted?.[index];
+      if (!lifted) {
+        return [`wrote ${path}`];
+      }
+      const none = lifted.untouched.length > 0 ? `; nothing on ${lifted.untouched.join(", ")}` : "";
+      const count = (n: number, one: string) => `${n} ${one}${n === 1 ? "" : "s"}`;
+      return [
+        `wrote ${path}`,
+        `  laid ${count(lifted.shapes, "shape")} and ${count(lifted.pictures, "picture")} over the picture${none}`,
+      ];
+    })
+    .join("\n");
+}
+
+export function formatPack(data: PackCliResult): string {
+  return [formatPdf(data), ...data.warnings.map((warning) => `warning: ${warning}`)].join("\n");
+}
+
 export function formatLs(data: LsListResult | LsDeckResult): string {
   switch (data.kind) {
     case "list": {
@@ -339,6 +370,7 @@ export function formatTheme(data: ThemeResult): string {
     ...data.layouts.map(
       (layout) => `  ${layout.name}${layout.example === undefined ? "  (no example)" : ""}`,
     ),
+    ...(data.unprintedLayouts ? [`  and ${unprinted(data.unprintedLayouts)}`] : []),
     "",
     "CLASSES",
     `  ${data.classes.join(" ")}`,
@@ -353,7 +385,7 @@ export function formatTheme(data: ThemeResult): string {
     "TOKENS",
     ...data.tokens.map((token) => `  ${token.name.padEnd(width)}  ${token.value}`),
     "",
-    "Markup for a layout: dekc theme <layout>",
+    `Markup for a layout: dekc theme ${data.ref ? `${shellQuote(data.ref.name)} ` : ""}<layout>`,
   ].join("\n");
 }
 
@@ -409,6 +441,14 @@ export function formatShow(data: ShowResult): string {
     .join("\n\n");
 }
 
+/** What a read does for a ref whose snapshot is not there: fetch it, or unpack its pack. */
+function notFetched(name: string): string {
+  const source = parseRefSource(name);
+  return source.kind === "file"
+    ? `(not unpacked; a read unpacks ${packFile(source.deck)})`
+    : "(not fetched; a read fetches it)";
+}
+
 export function formatRef(data: RefCliResult): string {
   const short = (rev: string) => rev.slice(0, 7);
   switch (data.action) {
@@ -421,7 +461,8 @@ export function formatRef(data: RefCliResult): string {
       return [
         head,
         ...data.warnings.map((warning) => `warning: ${warning}`),
-        `read it with \`dekc ls ${data.name}\` and \`dekc show ${data.name} <slug>\``,
+        ...(data.pack ? [`commit ${data.pack}: a clone unpacks the ref from it`] : []),
+        `read it with \`dekc ls ${shellQuote(data.name)}\` and \`dekc show ${shellQuote(data.name)} <slug>\``,
       ].join("\n");
     }
     case "list":
@@ -433,7 +474,7 @@ export function formatRef(data: RefCliResult): string {
         data.refs.map((ref) => [
           ref.name,
           short(ref.rev),
-          ref.fetched ? (ref.title ?? "") : "(not fetched; a read fetches it)",
+          ref.fetched ? (ref.title ?? "") : notFetched(ref.name),
           ref.slides === undefined ? "" : String(ref.slides),
         ]),
         ["left", "left", "left", "right"],

package/src/cli/theme.ts

@@ -2,6 +2,8 @@ import { existsSync } from "node:fs";
 import { type CssToken, parseCss } from "../core/css.ts";
 import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
+import { isPlainWord } from "../core/escape.ts";
+import { listShown, unprinted } from "../core/prose.ts";
 import { readDeckFile } from "../core/resolve.ts";
 import { type ThemeLayout, themeFacts } from "../core/theme-facts.ts";
 import type { ReadableDeck, RefInfo } from "./scope.ts";
@@ -15,7 +17,10 @@ export type ThemeResult = {
   stateClasses: string[];
   /** The tokens every slide can `var()`. */
   tokens: CssToken[];
+  /** The layouts whose names are plain words. A name is the theme's text, maybe a pack's. */
   layouts: ThemeLayout[];
+  /** How many layouts the theme has whose names are no plain word, left out of `layouts`. */
+  unprintedLayouts?: number;
   /** Set when one layout was asked for; text output prints its example alone. */
   layout?: { name: string; example: string };
   /** Set when the deck is a ref. */
@@ -34,12 +39,15 @@ export function themeCommand({ deck, ref }: ReadableDeck, name?: string): ThemeR
   const { classes, stateClasses, layouts, tokens } = themeFacts(
     parseCss(readDeckFile(deck.dir, path) ?? ""),
   );
+  const printed = layouts.filter((layout) => isPlainWord(layout.name));
+  const left = layouts.length - printed.length;
   const result: ThemeResult = {
     path,
     classes: [...classes].sort(),
     stateClasses: [...stateClasses].sort(),
     tokens,
-    layouts,
+    layouts: printed,
+    ...(left > 0 ? { unprintedLayouts: left } : {}),
     ...(ref ? { ref } : {}),
   };
   if (!name) {
@@ -49,7 +57,13 @@ export function themeCommand({ deck, ref }: ReadableDeck, name?: string): ThemeR
   if (!layout) {
     throw new DekError(`layout "${name}" is not defined in theme.css`, {
       path,
-      hint: `use one of: ${layouts.map((entry) => entry.name).join(", ") || "(none)"}`,
+      hint: `use one of: ${
+        listShown(
+          layouts.map((entry) => entry.name),
+          isPlainWord,
+          unprinted,
+        ) || "(none)"
+      }`,
     });
   }
   if (layout.example === undefined) {

package/src/cli/voice.ts

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { DekError } from "../core/error.ts";
 import { deckProjectRoot } from "../core/path.ts";
-import { isCachedFile, writeInside } from "../core/safe-fs.ts";
+import { isCachedFile, requireInside, writeInside } from "../core/safe-fs.ts";
 import { loadVoiceDict, loadVoiceSettings, voiceCacheFile, writeVoiceDict } from "../core/voice.ts";
 import {
   engineBaseUrl,
@@ -91,8 +91,9 @@ export function pinVoice({ deck }: DeckTarget): VoiceCliResult {
   const pinDir = join(deck.dir, "voice", "pin");
   const pinTimeline = join(pinDir, "timeline.json");
   const pinAudio = join(pinDir, "master.wav");
-  writeInside(pinTimeline, readFileSync(timelinePath), root);
-  writeInside(pinAudio, readFileSync(audioPath), root);
+  // The folders on the way may be links too; what is pinned comes from inside the project.
+  writeInside(pinTimeline, readFileSync(requireInside(timelinePath, root)), root);
+  writeInside(pinAudio, readFileSync(requireInside(audioPath, root)), root);
   return { action: "pin", timelinePath: pinTimeline, audioPath: pinAudio };
 }
 

package/src/core/alignment.ts

@@ -0,0 +1,320 @@
+import type { Box, MeasuredElement } from "./slide-measure.ts";
+
+/** What lining up needs to know of an element. */
+export type AlignedElement = Pick<
+  MeasuredElement,
+  | "box"
+  | "parent"
+  | "rect"
+  | "textRects"
+  | "baseline"
+  | "opacity"
+  | "decorative"
+  | "inline"
+  | "tilted"
+  | "paints"
+  | "picture"
+  | "fontSize"
+>;
+
+/** An edge items side by side share (`top`, `middle`, `bottom`), or items stacked (`left`, …). */
+export type AlignedEdge = "top" | "middle" | "bottom" | "left" | "center" | "right";
+
+/**
+ * Two items that nearly line up and do not: `element` is the one off the line, `other` the one it
+ * misses, both indices into the elements measured. `of` says whether their boxes miss each other
+ * or the text that starts inside them.
+ */
+export type Misalignment = {
+  element: number;
+  other: number;
+  edge: AlignedEdge;
+  of: "box" | "text";
+  /** How far apart, in the slide's own pixels. */
+  by: number;
+};
+
+/** Edges this close are one line; layout rounds to fractions of a pixel nobody sees. */
+const SAME = 0.5;
+/** Edges closer than this look like one, on a projector as on a laptop. */
+const SEEN = 1.5;
+/** Edges this far apart, or farther, read as a choice; nearer, as a mistake. */
+const NEAR = 8;
+
+type Side = "start" | "center" | "end";
+const SIDES: Side[] = ["start", "center", "end"];
+type Axis = Record<Side, AlignedEdge>;
+/** Items side by side, compared down the slide. */
+const ROW: Axis = { start: "top", center: "middle", end: "bottom" };
+/** Items stacked, compared across it. */
+const COLUMN: Axis = { start: "left", center: "center", end: "right" };
+
+function along(rect: Box, axis: Axis): Record<Side, number> {
+  return axis === ROW
+    ? { start: rect.top, center: (rect.top + rect.bottom) / 2, end: rect.bottom }
+    : { start: rect.left, center: (rect.left + rect.right) / 2, end: rect.right };
+}
+
+/** Side by side when only their heights overlap, stacked when only their widths do. */
+function relation(a: Box, b: Box): Axis | undefined {
+  const across = Math.min(a.right, b.right) - Math.max(a.left, b.left);
+  const down = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
+  if (down > 0 && across <= 0) {
+    return ROW;
+  }
+  if (across > 0 && down <= 0) {
+    return COLUMN;
+  }
+  return undefined;
+}
+
+function union(rects: Box[]): Box {
+  return {
+    left: Math.min(...rects.map((rect) => rect.left)),
+    top: Math.min(...rects.map((rect) => rect.top)),
+    right: Math.max(...rects.map((rect) => rect.right)),
+    bottom: Math.max(...rects.map((rect) => rect.bottom)),
+  };
+}
+
+const near = (apart: number): boolean => Math.abs(apart) >= SEEN && Math.abs(apart) <= NEAR;
+
+/** What an item is, as its tag and first class say, whatever beat it shows at or id it has. */
+const kindOf = (box: string): string => box.replace(/#[^.[]+|\[data-step="[^"]*"\]/g, "");
+
+/** An item compared: one element, or the row or the stack several form beside another item. */
+type Group = {
+  members: number[];
+  rect: Box;
+  line: FirstLine | undefined;
+  /** Whether every member paints its box or is a picture, so its edges show. */
+  framed: boolean;
+  kind: string | undefined;
+};
+
+/**
+ * The items on a slide that nearly line up and do not. Items are compared within one parent, and
+ * only when they sit side by side, compared by top, middle, and bottom, or stacked, compared by
+ * left, center, and right. Several items in a row under one item, or stacked beside it, are
+ * compared with it as the row or the stack they form, by the member at that edge. An item lines
+ * up when it shares one of those edges, or, side by side, a baseline: a heading over a wider list,
+ * an icon centered beside a line of text, and a number on its unit's baseline all pass. Where
+ * nothing is shared and the nearest edge is two pixels to eight away, it reads as a mistake; so
+ * does a start, top or left, that nearly meets where the end meets, between items that hold text.
+ * Items of one kind whose box the audience sees, as a row of cards, are held to more: one that
+ * shares its top and nearly its bottom with the others is a little shorter, and ones that start
+ * on one line should start their text on one line too.
+ *
+ * Inline boxes, which sit on a line of text, decoration, what the beat has not shown, what a
+ * transform turns, and the parts of a picture, such as an SVG's shapes, are not items. Of two
+ * items that miss each other, the one fewer others line up with is off the line, and of two alike
+ * the later; each is named once for each of its edges.
+ */
+export function findMisalignments(elements: AlignedElement[]): Misalignment[] {
+  const inPicture = (index: number): boolean => {
+    for (let at = elements[index]?.parent ?? -1; at >= 0; at = elements[at]?.parent ?? -1) {
+      if (elements[at]?.picture) {
+        return true;
+      }
+    }
+    return false;
+  };
+  const items = elements.flatMap((element, index) =>
+    element.opacity >= 0.01 &&
+    !element.decorative &&
+    !element.inline &&
+    !element.tilted &&
+    element.rect.right > element.rect.left &&
+    element.rect.bottom > element.rect.top &&
+    !inPicture(index)
+      ? [index]
+      : [],
+  );
+  const lines = firstLines(elements);
+  const rectOf = (index: number): Box => elements[index]?.rect ?? union([]);
+
+  // The row or the stack `item` forms beside `other`: the items `other` relates to as it does to
+  // `item`, which sit across that from `item` or from one another.
+  const groupOf = (item: number, other: number, axis: Axis, siblings: number[]): Group => {
+    const across = axis === ROW ? COLUMN : ROW;
+    const members = [item];
+    for (let at = 0; at < members.length; at++) {
+      const member = members[at] ?? item;
+      for (const candidate of siblings) {
+        if (
+          !members.includes(candidate) &&
+          candidate !== other &&
+          relation(rectOf(candidate), rectOf(other)) === axis &&
+          relation(rectOf(candidate), rectOf(member)) === across
+        ) {
+          members.push(candidate);
+        }
+      }
+    }
+    members.sort((a, b) => a - b);
+    const kinds = new Set(members.map((member) => kindOf(elements[member]?.box ?? "")));
+    const memberLines = members.flatMap((member) => lines[member] ?? []);
+    return {
+      members,
+      rect: union(members.map(rectOf)),
+      line: memberLines.reduce<FirstLine | undefined>(
+        (first, line) => (!first || earlier(line.rect, first.rect) ? line : first),
+        undefined,
+      ),
+      framed: members.every(
+        (member) => elements[member]?.paints === true || elements[member]?.picture === true,
+      ),
+      kind: kinds.size === 1 ? [...kinds][0] : undefined,
+    };
+  };
+  // The member whose edge is the group's on that side.
+  const at = (group: Group, axis: Axis, side: Side): number =>
+    side === "center"
+      ? (group.members[0] ?? -1)
+      : group.members.reduce((best, member) => {
+          const value = along(rectOf(member), axis)[side];
+          const kept = along(rectOf(best), axis)[side];
+          return (side === "start" ? value < kept : value > kept) ? member : best;
+        });
+
+  type Miss = Misalignment & { key: string };
+  const misses: Miss[] = [];
+  // How many items each one lines up with, edge by edge.
+  const support = new Map<string, number>();
+  const lineUp = (index: number, key: string) => {
+    support.set(`${index}\0${key}`, (support.get(`${index}\0${key}`) ?? 0) + 1);
+  };
+  const compare = (
+    [a, b]: [number, number],
+    edge: AlignedEdge,
+    of: Miss["of"],
+    apart: number,
+  ): void => {
+    const key = `${of}\0${edge}`;
+    if (Math.abs(apart) < SAME) {
+      lineUp(a, key);
+      lineUp(b, key);
+    } else if (near(apart)) {
+      misses.push({ element: b, other: a, edge, of, by: Math.round(Math.abs(apart)), key });
+    }
+  };
+
+  const siblings = Map.groupBy(items, (index) => elements[index]?.parent ?? -1);
+  for (const group of siblings.values()) {
+    for (const [index, a] of group.entries()) {
+      for (const b of group.slice(index + 1)) {
+        const axis = relation(rectOf(a), rectOf(b));
+        if (!axis) {
+          continue;
+        }
+        const one = groupOf(a, b, axis, group);
+        const two = groupOf(b, a, axis, group);
+        // A row or a stack is compared once, as its first member.
+        if (one.members[0] !== a || two.members[0] !== b) {
+          continue;
+        }
+        const from = along(one.rect, axis);
+        const to = along(two.rect, axis);
+        const apart = (side: Side) => to[side] - from[side];
+        const shared = (side: Side) => Math.abs(apart(side)) < SAME;
+        const pair = (side: Side): [number, number] => [at(one, axis, side), at(two, axis, side)];
+        for (const side of SIDES.filter(shared)) {
+          compare(pair(side), axis[side], "box", 0);
+        }
+        const texts = one.line !== undefined && two.line !== undefined;
+        const cards =
+          one.framed && two.framed && texts && one.kind !== undefined && one.kind === two.kind;
+        // Text set on one baseline lines up, whatever boxes that do not show do. A baseline is
+        // worked out from the font's ascent, which layout may round where a canvas does not, so
+        // two that look like one count as one.
+        const baseline =
+          axis === ROW &&
+          !(one.framed && two.framed) &&
+          one.line?.baseline !== undefined &&
+          two.line?.baseline !== undefined &&
+          Math.abs(one.line.baseline - two.line.baseline) < SEEN;
+        if (baseline) {
+          // Nothing more to compare.
+        } else if (shared("center")) {
+          // Centered on one line, whatever their sizes.
+        } else if (shared("start") || shared("end")) {
+          // Side by side, text starts at the top, so a top a few pixels off reads where the
+          // bottoms meet; and a row of cards is one height, so one that shares its top and nearly
+          // its bottom is a little shorter. Stacked, items take the width their words give them,
+          // as tags set flush right do, and only an edge none of them shares can be off.
+          if (axis === ROW && shared("end") && texts) {
+            compare(pair("start"), axis.start, "box", apart("start"));
+          } else if (axis === ROW && shared("start") && cards) {
+            compare(pair("end"), axis.end, "box", apart("end"));
+          }
+        } else {
+          const nearest = SIDES.reduce((best, side) =>
+            Math.abs(apart(side)) < Math.abs(apart(best)) ? side : best,
+          );
+          compare(pair(nearest), axis[nearest], "box", apart(nearest));
+        }
+        // Text in cards off the line moved with them, and is named by their edge. Text centered
+        // in its card lines up by its middle, whatever its length.
+        if (cards && shared("start") && one.line && two.line) {
+          const [from, to] = [along(one.line.rect, axis), along(two.line.rect, axis)];
+          const centered = Math.abs(to.center - from.center) < SAME;
+          if (axis === COLUMN || one.line.fontSize === two.line.fontSize) {
+            compare([a, b], axis.start, "text", centered ? 0 : to.start - from.start);
+          }
+        }
+      }
+    }
+  }
+
+  const named = new Set<string>();
+  return misses.flatMap(({ key, ...miss }) => {
+    const ofOther = support.get(`${miss.other}\0${key}`) ?? 0;
+    const ofElement = support.get(`${miss.element}\0${key}`) ?? 0;
+    const found =
+      ofElement > ofOther ? { ...miss, element: miss.other, other: miss.element } : miss;
+    const id = `${found.element}\0${key}`;
+    if (named.has(id)) {
+      return [];
+    }
+    named.add(id);
+    return [found];
+  });
+}
+
+/** The first line of text in an element: where it is drawn, its baseline, and its size. */
+type FirstLine = { rect: Box; baseline?: number; fontSize: number };
+
+/** Whether `a` comes before `b` in reading order: higher, or as high and further left. */
+function earlier(a: Box, b: Box): boolean {
+  return a.top < b.top - SAME || (Math.abs(a.top - b.top) < SAME && a.left < b.left);
+}
+
+/**
+ * Each element's first line of text, its own or a descendant's, in reading order. Decoration and
+ * what the beat has not shown have none.
+ */
+function firstLines(elements: AlignedElement[]): Array<FirstLine | undefined> {
+  const first: Array<FirstLine | undefined> = elements.map(() => undefined);
+  // A parent comes before its children, so walking back reaches every child before its parent.
+  for (let index = elements.length - 1; index >= 0; index--) {
+    const element = elements[index];
+    if (!element || element.decorative || element.opacity < 0.01) {
+      continue;
+    }
+    const [own] = element.textRects;
+    const kept = first[index];
+    if (own && (!kept || earlier(own, kept.rect))) {
+      first[index] = {
+        rect: own,
+        fontSize: element.fontSize,
+        ...(element.baseline !== undefined ? { baseline: element.baseline } : {}),
+      };
+    }
+    const mine = first[index];
+    const parent = first[element.parent];
+    if (mine && element.parent >= 0 && (!parent || earlier(mine.rect, parent.rect))) {
+      first[element.parent] = mine;
+    }
+  }
+  return first;
+}