@hajimism/dek 0.3.2 → 0.4.0

package/src/core/line-break.ts

@@ -0,0 +1,275 @@
+/**
+ * One run of text as the page breaks it into lines: an element's own text with the text of the
+ * inline elements in it, as `<strong>` or `<a>`, which share its lines.
+ */
+export type TextFlow = {
+  /** Its element's index among the slide's elements, as `measureSlideInPage` lists them. */
+  element: number;
+  /** Its text as written, a `<br>` or a block inside it read as a newline. */
+  text: string;
+  /** Where each line starts in `text`, and whether a `<br>` or a block started it. */
+  lines: Array<{ start: number; forced: boolean }>;
+  /** Where each line would start, broken phrase by phrase; only where that is elsewhere. */
+  phrased?: number[];
+};
+
+/** What `measureTextFlowsInPage` finds: each text with more than one line, and how the slide breaks. */
+export type MeasuredFlows = {
+  /** The slide's own `word-break`, which every text inherits unless a rule sets its own. */
+  wordBreak: string;
+  flows: Array<TextFlow & { textWrap: string }>;
+};
+
+/**
+ * Lays each text on the first `.slide` out in lines, as `TextFlow` says. Where a line ends inside
+ * a phrase is what the page itself says: each text whose `word-break` is `normal` is laid out
+ * again beside itself with only `word-break: auto-phrase` changed, and where that puts its lines
+ * elsewhere, `phrased` says where. Chromium breaks by phrase only where the page's `lang` is one
+ * it knows phrases for, such as `ja`, so other text is never laid out elsewhere. The copies are
+ * taken away before it returns, so the page is as it was. It runs inside the page through
+ * `page.evaluate`, which serializes only this function, so it must not reference anything outside
+ * its own body.
+ */
+export function measureTextFlowsInPage(): MeasuredFlows {
+  const slide = document.querySelector(".slide");
+  if (!slide) {
+    return { wordBreak: "normal", flows: [] };
+  }
+  // Code keeps its own lines, and a drawing or a formula its own text.
+  const code = "pre, code, kbd, samp";
+  const drawings = new Set(["svg", "math"]);
+  // A text node, whose characters each take their place on a line, or an inline box such as an
+  // image or an inline-block, which takes its place whole.
+  type Piece = { at: number } & ({ node: Text } | { box: Element });
+  type Read = { text: string; pieces: Piece[]; forced: number[] };
+  // The text an element lays out in its own lines: its text nodes and those of the inline elements
+  // in it, and an inline box as the text it holds, or U+FFFC when it holds none. A <br>, a block
+  // between them, or a newline that white-space keeps, as pre-line does, starts a line.
+  const read = (root: Element): Read => {
+    const found: Read = { text: "", pieces: [], forced: [] };
+    const walk = (el: Element) => {
+      for (const child of el.childNodes) {
+        if (child instanceof Text) {
+          const at = found.text.length;
+          found.pieces.push({ at, node: child });
+          found.text += child.data;
+          if (/^(?:pre|pre-wrap|pre-line|break-spaces)$/.test(getComputedStyle(el).whiteSpace)) {
+            for (const kept of child.data.matchAll(/\n/g)) {
+              found.forced.push(at + kept.index);
+            }
+          }
+          continue;
+        }
+        if (!(child instanceof Element)) {
+          continue;
+        }
+        const display = getComputedStyle(child).display;
+        if (display === "none") {
+          continue;
+        }
+        const tag = child.tagName.toLowerCase();
+        if (tag === "br" || (!display.startsWith("inline") && display !== "contents")) {
+          found.forced.push(found.text.length);
+          found.text += "\n";
+        } else if ((display === "inline" || display === "contents") && !drawings.has(tag)) {
+          walk(child);
+        } else {
+          found.pieces.push({ at: found.text.length, box: child });
+          found.text += child.textContent?.trim() || "";
+        }
+      }
+    };
+    walk(root);
+    return found;
+  };
+  // What a piece draws, each with its place in the text: a text node's characters but its white
+  // space, which draws nothing of its own, or an inline box whole.
+  const drawn = (piece: Piece): Array<{ offset: number; rect: DOMRect }> => {
+    if ("box" in piece) {
+      return [{ offset: piece.at, rect: piece.box.getBoundingClientRect() }];
+    }
+    const { node, at } = piece;
+    const marks: Array<{ offset: number; rect: DOMRect }> = [];
+    for (let end = 0; end < node.data.length; ) {
+      const begin = end;
+      end += (node.data.codePointAt(begin) ?? 0) > 0xffff ? 2 : 1;
+      if (/\s/.test(node.data.slice(begin, end))) {
+        continue;
+      }
+      const range = document.createRange();
+      range.setStart(node, begin);
+      range.setEnd(node, end);
+      marks.push({ offset: at + begin, rect: range.getBoundingClientRect() });
+    }
+    return marks;
+  };
+  // Where each line starts: at the first thing drawn below the line before.
+  const lineStarts = ({ pieces, forced }: Read): Array<{ start: number; forced: boolean }> => {
+    const lines: Array<{ start: number; forced: boolean }> = [];
+    let bottom = Number.NEGATIVE_INFINITY;
+    let previous = -1;
+    for (const { offset, rect } of pieces.flatMap(drawn)) {
+      if (rect.width === 0 && rect.height === 0) {
+        continue;
+      }
+      if (rect.top >= bottom - 1) {
+        lines.push({
+          start: offset,
+          forced: lines.length > 0 && forced.some((at) => at > previous && at < offset),
+        });
+        bottom = rect.bottom;
+      } else {
+        bottom = Math.max(bottom, rect.bottom);
+      }
+      previous = offset;
+    }
+    return lines;
+  };
+
+  const all = [...slide.querySelectorAll("*")];
+  const measured = all.flatMap((el, element) => {
+    const display = getComputedStyle(el).display;
+    if (
+      !(el instanceof HTMLElement) ||
+      display === "inline" ||
+      display === "contents" ||
+      display === "none" ||
+      el.closest(code) !== null ||
+      el.closest("svg, math") !== null ||
+      el.closest('[aria-hidden="true"]') !== null
+    ) {
+      return [];
+    }
+    const flow = read(el);
+    const lines = lineStarts(flow);
+    if (lines.length < 2) {
+      return [];
+    }
+    const style = getComputedStyle(el);
+    const soft = lines.some(({ forced }, at) => at > 0 && !forced);
+    return [
+      {
+        el,
+        element,
+        flow,
+        lines,
+        textWrap: style.textWrap,
+        rewrap: soft && style.wordBreak === "normal",
+      },
+    ];
+  });
+  // Every line is read before any copy goes in, and every copy is in before any is read, so the
+  // page is laid out once for each. A copy sits where its text is, out of the flow, with only its
+  // word-break changed.
+  const copies = measured.map(({ el, rewrap }) => {
+    if (!rewrap) {
+      return undefined;
+    }
+    const copy = el.cloneNode(true) as HTMLElement;
+    Object.assign(copy.style, {
+      position: "absolute",
+      visibility: "hidden",
+      left: "0px",
+      top: "0px",
+      margin: "0px",
+      boxSizing: "border-box",
+      width: `${el.offsetWidth}px`,
+      minWidth: "0px",
+      maxWidth: "none",
+      wordBreak: "auto-phrase",
+    });
+    el.after(copy);
+    return copy;
+  });
+  const flows = measured.map(({ element, flow, lines, textWrap }, at) => {
+    const copy = copies[at];
+    const phrased = copy && lineStarts(read(copy)).map(({ start }) => start);
+    copy?.remove();
+    const moved =
+      phrased !== undefined &&
+      (phrased.length !== lines.length || phrased.some((start, at) => start !== lines[at]?.start));
+    return {
+      element,
+      text: flow.text,
+      lines,
+      ...(moved ? { phrased } : {}),
+      textWrap,
+    };
+  });
+  return { wordBreak: getComputedStyle(slide).wordBreak, flows };
+}
+
+/** What reads wrong about a text's line breaks. */
+export type LineBreakKind =
+  | {
+      /** A line ends inside a phrase. */
+      kind: "split";
+      /** The lines broken phrase by phrase. */
+      phrased: string[];
+    }
+  | {
+      /** A paragraph's last line holds two letters or fewer. */
+      kind: "short";
+      tail: string;
+    };
+
+/** A line break the audience trips over, in the flow of the element at `element`. */
+export type LineBreak = {
+  element: number;
+  /** Its lines as the audience reads them. */
+  lines: string[];
+} & LineBreakKind;
+
+/** A last line with no more letters or digits than this reads as a remnant. */
+const MAX_SHORT = 2;
+
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/** The letters and digits in `text`, an inline box that holds no text counted as one. */
+function letters(text: string): number {
+  return [...graphemes.segment(text)].filter(({ segment }) => /[\p{L}\p{N}]/u.test(segment))
+    .length;
+}
+
+/** The lines of `text` that start at `starts`, as read: white space collapsed. */
+function readLines(text: string, starts: number[]): string[] {
+  return starts.map((start, at) =>
+    text
+      .slice(start, starts[at + 1] ?? text.length)
+      .replace(/\s+/g, " ")
+      .trim(),
+  );
+}
+
+/**
+ * The line breaks in each flow that read wrong: a line that ends inside a phrase, which `phrased`
+ * shows where the page breaks it phrase by phrase, and a paragraph whose last line holds two
+ * letters or fewer. A short line a `<br>` or a block starts is the author's, and passes. Where a
+ * phrase is broken, every line after it moves once the text breaks by phrase, so that is all a
+ * flow reports.
+ */
+export function findLineBreaks(flows: TextFlow[]): LineBreak[] {
+  return flows.flatMap((flow): LineBreak[] => {
+    const lines = readLines(
+      flow.text,
+      flow.lines.map(({ start }) => start),
+    );
+    if (flow.phrased) {
+      return [
+        {
+          element: flow.element,
+          kind: "split",
+          lines,
+          phrased: readLines(flow.text, flow.phrased),
+        },
+      ];
+    }
+    return flow.lines.flatMap(({ forced }, at): LineBreak[] => {
+      const last = at === flow.lines.length - 1 || flow.lines[at + 1]?.forced === true;
+      const tail = lines[at] ?? "";
+      return at > 0 && !forced && last && letters(tail) <= MAX_SHORT
+        ? [{ element: flow.element, kind: "short", lines, tail }]
+        : [];
+    });
+  });
+}

package/src/core/lint/asset-refs.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { dirname, join, posix, resolve } from "node:path";
 import { classifyAssetRef, isCanonicalAssetPath } from "../assets.ts";
 import { type Diagnostic, diag } from "../diagnostic.ts";
+import { isPlainWord } from "../escape.ts";
 import type { HtmlRef } from "../html-scan.ts";
 import { isInside } from "../path.ts";
 
@@ -95,7 +96,9 @@ function missingImageHint(value: string, deckDir: string): { hint?: string } {
   if (!existsSync(projectFile)) {
     return {};
   }
-  return { hint: `the project has it: copy ../../${name} into the deck's assets/` };
+  // The name is the slide's text: one that is no plain word is left out of the hint.
+  const copy = isPlainWord(name) ? `../../${name}` : "it from the project's assets/";
+  return { hint: `the project has it: copy ${copy} into the deck's assets/` };
 }
 
 function remoteHint(value: string): string {
@@ -103,7 +106,8 @@ function remoteHint(value: string): string {
   try {
     name = posix.basename(new URL(value.trim(), "https://dek.invalid").pathname);
   } catch {}
-  return name
+  // The name is the remote URL's: one that is no plain word is left out of the hint.
+  return name && isPlainWord(name)
     ? `download it into assets/ and use assets/${name}`
     : "download it into assets/ and reference it from there";
 }

package/src/core/lint/files.ts

@@ -1,6 +1,8 @@
 import { type Diagnostic, diag } from "../diagnostic.ts";
+import { shellName } from "../escape.ts";
 import { either } from "../prose.ts";
 import { listSlideFiles, SLIDE_SIDECARS } from "../resolve.ts";
+import { Id } from "../schema.ts";
 import type { LintContext } from "./context.ts";
 
 /** DEK001 for a section without slides/<slug>.html; DEK002 for a slide file without its section. */
@@ -60,9 +62,13 @@ export function pairingDiagnostics(ctx: LintContext): Diagnostic[] {
 
 /**
  * What to do with a slide file the script does not name, when no rename explains it: give it a
- * section, or take it out of the talk. Which one is the author's call.
+ * section, or take it out of the talk. Which one is the author's call. A name that is no section
+ * id cannot head one, and is the file's text, so the hint names it nowhere.
  */
 function orphanHint(slug: string, file: string): string {
+  if (!Id.safeParse(slug).success) {
+    return "its name is no section id, which uses a-z, 0-9, and -: rename it to one and add that section to script.md, or remove it if the slide is gone from the talk";
+  }
   const title = slug.charAt(0).toUpperCase() + slug.slice(1).replaceAll("-", " ");
   return `add a section for it to script.md, like \`## ${title} {#${slug}}\`, or remove ${file} if the slide is gone from the talk`;
 }
@@ -91,10 +97,16 @@ export function suggestRename(diagnostics: Diagnostic[], ctx: LintContext): Diag
   }
   const [orphan] = orphans;
   const [target] = targets;
-  if (orphans.size === 1 && targets.length === 1 && orphan?.slug && target) {
+  if (
+    orphans.size === 1 &&
+    targets.length === 1 &&
+    orphan?.slug &&
+    target &&
+    movable(orphan.slug)
+  ) {
     // An orphan beside a section without its own slide is a rename, made in the script or in the
     // files: which one is the author's to say, and each command finishes it from this state.
-    const hint = `run \`dekc mv ${orphan.slug} ${target}\` to move the files to the script's id, or \`dekc mv ${target} ${orphan.slug}\` to give the section the files' id`;
+    const hint = `run ${mvCommand(orphan.slug, target)} to move the files to the script's id, or ${mvCommand(target, orphan.slug)} to give the section the files' id`;
     return diagnostics.map((diagnostic) =>
       diagnostic === orphan
         ? { ...diagnostic, hint, data: { ...diagnostic.data, renames: targets } }
@@ -104,10 +116,11 @@ export function suggestRename(diagnostics: Diagnostic[], ctx: LintContext): Diag
     );
   }
   return diagnostics.map((diagnostic) => {
-    if (!orphans.has(diagnostic) || !diagnostic.slug) {
+    const file = diagnostic.slug;
+    if (!orphans.has(diagnostic) || !file || !movable(file)) {
       return diagnostic;
     }
-    const commands = targets.map((slug) => `\`dekc mv ${diagnostic.slug} ${slug}\``);
+    const commands = targets.map((slug) => mvCommand(file, slug));
     return {
       ...diagnostic,
       hint: `run ${either(commands)} to move the files to the section they now belong to`,
@@ -115,3 +128,15 @@ export function suggestRename(diagnostics: Diagnostic[], ctx: LintContext): Diag
     };
   });
 }
+
+/** Whether a slide file's name can be written in a command: see `shellName`. */
+function movable(slug: string): boolean {
+  return shellName(slug) !== undefined;
+}
+
+/** `dekc mv from to`, with `--` first when a name starts with a dash, which would read as a flag. */
+function mvCommand(from: string, to: string): string {
+  const words = [from, to].map((slug) => shellName(slug) ?? slug);
+  const end = [from, to].some((slug) => slug.startsWith("-")) ? "-- " : "";
+  return `\`dekc mv ${end}${words.join(" ")}\``;
+}

package/src/core/lint/keys.ts

@@ -5,8 +5,10 @@ import {
   unknownTomlKeys,
 } from "../config-keys.ts";
 import { type Diagnostic, diag } from "../diagnostic.ts";
+import { isPlainWord } from "../escape.ts";
 import { readFrontmatterYaml } from "../parse.ts";
-import { type Project, readTextIfExists } from "../resolve.ts";
+import type { Project } from "../resolve.ts";
+import { readSourceIfExists } from "../safe-fs.ts";
 import type { DeckSettings } from "../schema.ts";
 import type { LintContext } from "./context.ts";
 
@@ -17,7 +19,7 @@ import type { LintContext } from "./context.ts";
 
 /** DEK008 for dek.toml: a project finding, the same for every deck. */
 export function tomlKeyDiagnostics(project: Project): Diagnostic[] {
-  return unknownTomlKeys(readTextIfExists(project.configPath) ?? "").map((key) =>
+  return unknownTomlKeys(readSourceIfExists(project.configPath, project.root) ?? "").map((key) =>
     unknownKeyDiagnostic(key, { file: "dek.toml", path: project.configPath }),
   );
 }
@@ -79,8 +81,10 @@ function unknownKeyDiagnostic(
     where.file === "dek.toml"
       ? `see ${REFERENCE_URL}#dek-toml`
       : `the keys are ${FRONTMATTER_KEYS.join(", ")}; see ${REFERENCE_URL}#frontmatter`;
+  // The key is the file's text, which a cloned project brings along: see formatZodIssues.
+  const shown = isPlainWord(key) ? key : "<key>";
   return diag("DEK008", {
-    message: `unknown key ${key} in ${place}; dek ignores it`,
+    message: `unknown key ${shown} in ${place}; dek ignores it`,
     path: where.path,
     line,
     hint: suggestion ? `did you mean ${suggestion}?` : known,

package/src/core/lint/slide-html.ts

@@ -1,4 +1,5 @@
 import { type Diagnostic, diag } from "../diagnostic.ts";
+import { isPlainWord } from "../escape.ts";
 import type { HtmlAttribute, HtmlScan, Picture, SourceSpot } from "../html-scan.ts";
 import type { Section } from "../schema.ts";
 import { beatAt, formatStepChoices, resolveStep, stepChoices } from "../step.ts";
@@ -159,7 +160,8 @@ function layoutDiagnostics({ section, path, scan }: SlideHtml, layouts: Set<stri
     return [];
   }
   const known = [...layouts].sort();
-  const guess = suggest(scan.layout, known);
+  // A layout's name is the theme's text: one that is no plain word is never a guess.
+  const guess = suggest(scan.layout, known.filter(isPlainWord));
   return [
     diag("DEK019", {
       message: `data-layout "${scan.layout}" is not a layout of the theme`,

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

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { type Diagnostic, diag } from "../diagnostic.ts";
+import { shellName } from "../escape.ts";
 import { listSlideFiles } from "../resolve.ts";
 import type { Section } from "../schema.ts";
 import type { SlideScriptProblem } from "../slide-script.ts";
@@ -54,15 +55,16 @@ export function slideScriptDiagnostics(
 
 /** DEK016 for a slides/<slug>.js, which dek does not load: motion is written in TypeScript. */
 export function javascriptDiagnostics(ctx: LintContext): Diagnostic[] {
-  return listSlideFiles(ctx.deck.dir, ".js").map((file) =>
-    diag("DEK016", {
+  return listSlideFiles(ctx.deck.dir, ".js").map((file) => {
+    const [from, to] = [`slides/${file.slug}.js`, `slides/${file.slug}.ts`].map(shellName);
+    return diag("DEK016", {
       message: `slide scripts are TypeScript; rename ${file.slug}.js to ${file.slug}.ts`,
       path: file.path,
       slug: file.slug,
-      hint: `run \`mv slides/${file.slug}.js slides/${file.slug}.ts\`; plain JavaScript is valid TypeScript`,
+      hint: `${from && to ? `run \`mv ${from} ${to}\`` : "rename it to .ts"}; plain JavaScript is valid TypeScript`,
       data: { file: `slides/${file.slug}.js` },
-    }),
-  );
+    });
+  });
 }
 
 export type SeekProblem = {

package/src/core/mv.ts

@@ -1,10 +1,16 @@
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { deckPaths } from "./deck-paths.ts";
 import { DekError } from "./error.ts";
-import { escapeRegExp } from "./escape.ts";
+import { escapeRegExp, isPlainWord, shellName } from "./escape.ts";
 import { joinLines, sectionChunks, splitLines } from "./lines.ts";
-import { asResolvedDeck, type ResolvedDeck, requireSection, SLIDE_SIDECARS } from "./resolve.ts";
+import {
+  asResolvedDeck,
+  type ResolvedDeck,
+  readDeckFile,
+  requireSection,
+  SLIDE_SIDECARS,
+} from "./resolve.ts";
 import { Id } from "./schema.ts";
 import { deckLayouts, skeletonHtml } from "./skeleton.ts";
 import { skeletonRecord } from "./skeleton-record.ts";
@@ -38,7 +44,7 @@ export function renameSection(input: string | ResolvedDeck, from: string, to: st
     });
   }
 
-  const source = readFileSync(deck.scriptPath, "utf8");
+  const source = readDeckFile(deck.dir, deck.scriptPath) ?? "";
   const lines = splitLines(source);
   const headingIndex = section.line - 1;
   const heading = lines[headingIndex];
@@ -69,10 +75,11 @@ function slideFileSteps(deck: ResolvedDeck["deck"], from: string, to: string): F
   const record = skeletonRecord(deck.dir);
   const read = (slug: string): SlideFile | undefined => {
     const path = paths.slide(slug, ".html");
-    if (!existsSync(path)) {
+    // What is read here may be written under the other id: a link out of the project is refused.
+    const html = readDeckFile(deck.dir, path);
+    if (html === undefined) {
       return undefined;
     }
-    const html = readFileSync(path, "utf8");
     return { path, html, authored: !record.owns(html, skeletonHtml(deck.deck, slug, layouts)) };
   };
   const source = read(from);
@@ -131,10 +138,23 @@ function bothHold(fromPath: string, toPath: string, from: string, to: string): D
   const what = fromPath.endsWith(".html") ? "hold a slide you wrote" : "exist";
   return new DekError(`${fromName} and ${toName} both ${what}`, {
     path: fromPath,
-    hint: `merge them into ${toName} and remove ${fromName}, then run \`dekc mv ${from} ${to}\` again`,
+    hint: `merge them into ${toName} and remove ${isPlainWord(from) ? fromName : "the other"}, then run ${again(from, to)}`,
   });
 }
 
+/**
+ * The rename to run again: as a command when each name has a word every shell reads alike, after
+ * `--` when one starts with a dash; else as the one that was run.
+ */
+function again(from: string, to: string): string {
+  const [source, target] = [shellName(from), shellName(to)];
+  if (source === undefined || target === undefined) {
+    return "that `dekc mv` again";
+  }
+  const end = from.startsWith("-") || to.startsWith("-") ? "-- " : "";
+  return `\`dekc mv ${end}${source} ${target}\` again`;
+}
+
 /** One file change `dekc mv` makes, with how to take it back. */
 type FileStep = { path: string; apply: () => void; undo: () => void };
 
@@ -192,10 +212,10 @@ function planVoiceBeatKeys(
   to: string,
 ): { path: string; source: string; next: string } | undefined {
   const path = deckPaths(deckDir).voiceToml;
-  if (!existsSync(path)) {
+  const source = readDeckFile(deckDir, path);
+  if (source === undefined) {
     return undefined;
   }
-  const source = readFileSync(path, "utf8");
   let parsed: Record<string, unknown>;
   try {
     parsed = Bun.TOML.parse(source) as Record<string, unknown>;
@@ -259,7 +279,7 @@ export function reorderSection(
     requireSection(deck, target);
   }
 
-  const source = readFileSync(deck.scriptPath, "utf8");
+  const source = readDeckFile(deck.dir, deck.scriptPath) ?? "";
   const lines = splitLines(source);
   const firstLine = sections[0]?.line;
   if (firstLine === undefined) {