@hajimism/dek 0.4.0 → 0.5.0

package/src/cli/ls.ts

@@ -1,11 +1,12 @@
 import type { Diagnostic } from "../core/diagnostic.ts";
+import type { HiddenText } from "../core/foreign-text.ts";
 import { lintDeck, lintProject } from "../core/lint.ts";
 import { listSlides, type Project, type ProjectDeck } from "../core/resolve.ts";
 import { slideVideoSeconds, timelineSeconds } from "../core/timeline.ts";
 import { sectionTiming } from "../core/timing.ts";
 import { tryLoadCachedTimeline } from "../core/voice.ts";
 import { type SkippedCheck, skippedChecks } from "./result.ts";
-import type { DecksTarget, RefInfo } from "./scope.ts";
+import { type DecksTarget, hiddenField, hiddenInFiles, type RefInfo } from "./scope.ts";
 
 export type LsListResult = {
   kind: "list";
@@ -46,6 +47,8 @@ export type LsDeckResult = {
   skipped?: SkippedCheck[];
   /** Set when the deck is a ref. */
   ref?: RefInfo;
+  /** A ref's lines of script.md that hold characters a person cannot see. */
+  hidden?: HiddenText[];
 };
 
 /** The one deck in scope, a ref included, or else every deck of the project. */
@@ -58,6 +61,7 @@ export function lsCommand(target: DecksTarget): LsListResult | LsDeckResult {
         { check: "lint", reason: "a ref is read-only; its problems are not yours to fix" },
       ]),
       ref,
+      ...hiddenField(ref, hiddenInFiles(deck.dir, [deck.scriptPath])),
     };
   }
   if (deck) {

package/src/cli/main.ts

@@ -1,8 +1,12 @@
+import { parseCss } from "../core/css.ts";
+import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
 import { shellQuote } from "../core/escape.ts";
 import { either } from "../core/prose.ts";
 import { isRefName } from "../core/ref-name.ts";
-import { resolveProject } from "../core/resolve.ts";
+import { type ProjectDeck, readDeckFile, resolveProject } from "../core/resolve.ts";
+import { takeUnsandboxed } from "../core/sandbox.ts";
+import { themeFacts } from "../core/theme-facts.ts";
 import { addressHint, deckWord, type HintDeck, withPlaceholderNote } from "./address.ts";
 import {
   type AnySpec,
@@ -158,7 +162,7 @@ async function run(cwd: string, line: CommandLine): Promise<void> {
   }
   const scope = spec.scope;
   const target = scope
-    ? retypedWithDeck(line, cwd, () =>
+    ? retypedWithDeck(line, cwd, call, () =>
         resolveTarget(cwd, scope, {
           deck: call.deck,
           refs: spec.refs === true,
@@ -170,10 +174,13 @@ async function run(cwd: string, line: CommandLine): Promise<void> {
   const ctx = { cwd, flags: line.values, args: call.args, target };
   const data = await form.run?.(ctx);
   if (spec.kind === "result") {
-    writeSuccess({ command: call.name, data } as CliResult, {
+    // Said on stderr as Chromium drew without its sandbox, and kept here for --json.
+    const drawn = { ...(data as object), ...takeUnsandboxed() };
+    writeSuccess({ command: call.name, data: drawn } as CliResult, {
       json: line.values.json === true,
       format: line.values.format,
       cwd,
+      flags: line.values,
       ...(target?.deck && {
         deck: { name: target.ref?.name ?? target.deck.name, dir: target.deck.dir },
       }),
@@ -186,9 +193,10 @@ const NAMED_DECKS = 3;
 
 /**
  * `resolve`, with a missing deck hinted as the line that was typed, the deck named where the
- * command takes it: one command per deck of the project, so the hint runs as written.
+ * command takes it: one command per deck of the project that has what the line names, so the
+ * hint runs as written.
  */
-function retypedWithDeck<T>(line: CommandLine, cwd: string, resolve: () => T): T {
+function retypedWithDeck<T>(line: CommandLine, cwd: string, call: Call, resolve: () => T): T {
   try {
     return resolve();
   } catch (error) {
@@ -196,18 +204,43 @@ function retypedWithDeck<T>(line: CommandLine, cwd: string, resolve: () => T): T
       throw error;
     }
     const typed = `\`dekc ${line.typed.map(shellQuote).join(" ")}\``;
-    const [first] = error.decks;
+    const decks = error.decks.filter((deck) => runsIn(call, deck));
+    const [first] = decks;
     // Each command is retyped for one deck; where to find a name left as <deck> is said once.
     const retyped = (deck: HintDeck) => addressHint(typed, deck, cwd, { note: false });
-    const hint = !first
-      ? "run `dekc new <name>` to make a deck"
-      : error.decks.length > NAMED_DECKS
-        ? `run ${retyped(first)}, or name another deck in place of ${deckWord(first.name)}; \`dekc ls\` lists them`
-        : `run ${either(error.decks.map(retyped))}`;
+    const hint =
+      error.decks.length === 0
+        ? "run `dekc new <name>` to make a deck"
+        : !first
+          ? "run `dekc ls`"
+          : decks.length > NAMED_DECKS
+            ? `run ${retyped(first)}, or name another deck in place of ${deckWord(first.name)}; \`dekc ls\` lists them`
+            : `run ${either(decks.map(retyped))}`;
     throw new DekError(error.message, { hint: withPlaceholderNote(hint), cause: error });
   }
 }
 
+/**
+ * Whether `call` finds in `deck` what it names: a section, the one `dekc mv` renames or the name
+ * script.md already gives it, and a layout of the deck's theme.
+ */
+function runsIn(call: Call, deck: ProjectDeck): boolean {
+  const { slug, old, layout } = call.args;
+  const has = (name: string | undefined) =>
+    deck.deck.sections.some((section) => section.slug === name);
+  return (
+    (slug === undefined || has(slug)) &&
+    (old === undefined || has(old) || has(call.args.new)) &&
+    (layout === undefined || themeLayouts(deck).includes(layout))
+  );
+}
+
+/** The layouts a deck's theme defines; none when it has no theme.css. */
+function themeLayouts(deck: ProjectDeck): string[] {
+  const css = readDeckFile(deck.dir, deckPaths(deck.dir).theme) ?? "";
+  return themeFacts(parseCss(css)).layouts.map((entry) => entry.name);
+}
+
 /** A session prints no result, so --json has nothing to shape, and a reader would wait forever. */
 function sessionJsonError(name: string): DekError {
   return new DekError(`${name} keeps running until stopped and prints no JSON`, {
@@ -220,6 +253,8 @@ function sessionJsonError(name: string): DekError {
  * prints once, here: as JSON when the line asks for it, even a line too broken to parse.
  */
 export async function main(argv: string[], cwd: string): Promise<void> {
+  // What a run before this one in the process drew is its own, even one that failed.
+  takeUnsandboxed();
   let json = wantsJson(argv);
   try {
     const line = parseCommandLine(argv);

package/src/cli/new.ts

@@ -3,13 +3,20 @@ import { join } from "node:path";
 import { loadConfig } from "../core/config.ts";
 import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
+import { type HiddenText, hiddenText } from "../core/foreign-text.ts";
 import { DECK_NAME_HINT, isDeckName } from "../core/path.ts";
 import { isRefName } from "../core/ref-name.ts";
 import { readDeckFile } from "../core/resolve.ts";
 import { readSourceIfExists } from "../core/safe-fs.ts";
 import { syncDeck } from "../core/sync.ts";
 import { applyPlan, deckPlan, nextSteps } from "./files.ts";
-import { type RefInfo, requireDeckFromCwd, requireProject, resolveTarget } from "./scope.ts";
+import {
+  hiddenField,
+  type RefInfo,
+  requireDeckFromCwd,
+  requireProject,
+  resolveTarget,
+} from "./scope.ts";
 
 export type NewResult = {
   name: string;
@@ -21,6 +28,11 @@ export type NewResult = {
   next: string[];
   /** Set when the theme came from a ref with no license. */
   warnings: string[];
+  /**
+   * A ref's theme's lines, now the new deck's theme.css, that hold characters a person cannot
+   * see: the copy is the deck's own, so they are its author's to remove.
+   */
+  hidden?: HiddenText[];
 };
 
 export function newCommand(options: { cwd: string; name: string; themeFrom?: string }): NewResult {
@@ -87,6 +99,7 @@ export function newCommand(options: { cwd: string; name: string; themeFrom?: str
             `${ref.name} has no license; ask its author before you present or share a deck built on its theme`,
           ]
         : [],
+    ...hiddenField(ref, ref ? hiddenText(theme, deckPaths(dir).theme) : []),
   };
 }
 

package/src/cli/ref.ts

@@ -1,3 +1,4 @@
+// biome-ignore lint/style/noRestrictedImports: rmdirSync, which takes packs/ and refs/ folders only while empty; removeInside would take what is in them.
 import { existsSync, lstatSync, readdirSync, readFileSync, rmdirSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { loadConfig } from "../core/config.ts";

package/src/cli/result.ts

@@ -1,10 +1,12 @@
 import type { Diagnostic, SkippedCheck } from "../core/diagnostic.ts";
 import { DekError } from "../core/error.ts";
+import { revealHidden } from "../core/foreign-text.ts";
 import { PLAYWRIGHT_INSTALL, type PlaywrightRunner, playwrightReady } from "../core/playwright.ts";
 import { addressHint, deckAround, type HintDeck } from "./address.ts";
 import { type CliResult, outputOf } from "./commands.ts";
+import type { FlagValues } from "./flags.ts";
 import { displayPath, formatError, formatErrorText } from "./format.ts";
-import { shouldColor, terminalSafe } from "./tty.ts";
+import { plainText, shouldColor, terminalSafe } from "./tty.ts";
 
 export type { CliResult, SkippedCheck };
 
@@ -41,6 +43,8 @@ export type WriteSuccessOptions = {
   cwd?: string;
   /** The one deck the command worked on, which hints that name no path are about. */
   deck?: HintDeck;
+  /** The flags it ran with, which a failure's rerun repeats where they change what is checked. */
+  flags?: FlagValues;
 };
 
 /** Where a run's hints are read: the directory it ran in, and the deck it worked on, if one. */
@@ -86,7 +90,7 @@ export function writeSuccess(original: CliResult, options: WriteSuccessOptions):
   const { cwd } = options;
   const addressed = cwd === undefined ? original : addressResult(original, { cwd, ...options });
   const result = cwd === undefined ? addressed : displayPaths(addressed, cwd);
-  const failed = output.failure?.(result.data);
+  const failed = output.failure?.(result.data, options.flags ?? {});
   const failure =
     failed?.hint === undefined || cwd === undefined
       ? failed
@@ -98,9 +102,13 @@ export function writeSuccess(original: CliResult, options: WriteSuccessOptions):
     const data = output.json ? output.json(result.data) : (result.data as object);
     process.stdout.write(`${JSON.stringify({ ...envelope, ...data })}\n`);
   } else {
-    const text = formatText(result, shouldColor(process.stdout));
+    const plain = {
+      ...result,
+      data: plainStrings(result.data, isAboutRef(result.data)),
+    } as CliResult;
+    const text = formatText(plain, shouldColor(process.stdout));
     process.stdout.write(`${terminalSafe(text)}\n`);
-    const notes = output.notes?.(result.data, shouldColor(process.stderr));
+    const notes = output.notes?.(plain.data, shouldColor(process.stderr));
     if (notes) {
       process.stderr.write(`${terminalSafe(notes)}\n`);
     }
@@ -126,6 +134,36 @@ export function displayPaths(result: CliResult, cwd: string): CliResult {
   return { ...result, data: paths(result.data, (path) => displayPath(path, cwd)) } as CliResult;
 }
 
+/** A result that read a ref, as `ls`, `show`, and `theme` mark theirs. */
+function isAboutRef(data: unknown): boolean {
+  return typeof data === "object" && data !== null && "ref" in data && data.ref !== undefined;
+}
+
+/**
+ * Every string in a result as plainText, so the text a deck or a ref wrote reaches the terminal
+ * with no escape of its own; the text formatters paint dek's colors after. In a result about a
+ * ref, each character a person cannot see shows as `⟨U+XXXX⟩` too.
+ */
+function plainStrings<T>(value: T, reveal: boolean): T {
+  if (typeof value === "string") {
+    const plain = plainText(value);
+    return (reveal ? revealHidden(plain) : plain) as T;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => plainStrings(entry, reveal)) as T;
+  }
+  if (
+    value !== null &&
+    typeof value === "object" &&
+    Object.getPrototypeOf(value) === Object.prototype
+  ) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, plainStrings(entry, reveal)]),
+    ) as T;
+  }
+  return value;
+}
+
 /** A result as text, without what did not run; see writeSuccess. */
 export function formatText(result: CliResult, color = false): string {
   return outputOf(result.command).text(result.data, color);

package/src/cli/scope.ts

@@ -1,10 +1,12 @@
 import { join, relative } from "node:path";
 import { DekError } from "../core/error.ts";
 import { shellName, shellQuote } from "../core/escape.ts";
+import { foreignLine, type HiddenText, hiddenText, MESSAGE_MAX } from "../core/foreign-text.ts";
 import {
   isRefName,
   packFile,
   parseRefSource,
+  type RefSource,
   refLicense,
   refReadOnlyError,
   refState,
@@ -14,6 +16,7 @@ import {
   locateDeck,
   type Project,
   type ProjectDeck,
+  readDeckFile,
   requireSection,
   resolveProject,
 } from "../core/resolve.ts";
@@ -222,6 +225,25 @@ export type RefInfo = {
 /** One deck to read: the project's own, or a ref. */
 export type ReadableDeck = DeckTarget & { ref?: RefInfo };
 
+/**
+ * `{ hidden }` when a ref's files hold characters a person cannot see, nothing otherwise. Only a
+ * ref's are reported: a deck of the project's own is its author's, emoji joiners and all.
+ */
+export function hiddenField(
+  ref: RefInfo | undefined,
+  found: HiddenText[],
+): { hidden?: HiddenText[] } {
+  return ref && found.length > 0 ? { hidden: found } : {};
+}
+
+/** What the files at `paths` in the deck hold that a person cannot see, file by file. */
+export function hiddenInFiles(deckDir: string, paths: string[]): HiddenText[] {
+  return paths.flatMap((path) => {
+    const text = readDeckFile(deckDir, path);
+    return text === undefined ? [] : hiddenText(text, path);
+  });
+}
+
 /**
  * What a command declares it works on, resolved: one deck or the decks in scope. Only a command
  * whose spec says `refs` reads a ref; it never writes, so a ref cannot reach a command that
@@ -287,7 +309,7 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
   if (!found) {
     const failed = snapshot.failed.find((entry) => entry.name === source.deck);
     if (failed) {
-      throw failed.error;
+      throw unreadableRef(failed.error, source);
     }
     throw new DekError(`ref "${source.name}" has no deck "${source.deck}"`, {
       path: dir,
@@ -304,3 +326,20 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
     ref: { name: source.name, rev: pinned, dir, license: refLicense(dir) },
   };
 }
+
+/**
+ * A ref whose script.md cannot be read. The error's hint would say how to fix the file, quoting
+ * it, and a ref is not the reader's to fix: the message stays, on one line, and the hint is dek's.
+ */
+function unreadableRef(error: Error, source: RefSource): DekError {
+  const fields = error instanceof DekError ? error : undefined;
+  return new DekError(foreignLine(error.message, MESSAGE_MAX), {
+    ...(fields?.path !== undefined ? { path: fields.path } : {}),
+    ...(fields?.line !== undefined ? { line: fields.line } : {}),
+    hint:
+      source.kind === "file"
+        ? "a ref is read-only, so its script.md is its author's to fix; ask them for a pack that reads, and add it with `dekc ref <file>.tgz`"
+        : `a ref is read-only, so its script.md is its author's to fix; pin a commit where it reads with \`dekc ref ${source.name}@<rev>\``,
+    cause: error,
+  });
+}

package/src/cli/shot.ts

@@ -1,10 +1,15 @@
+import { basename, dirname, extname } from "node:path";
+import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
-import { shellQuote } from "../core/escape.ts";
+import { shellName, shellQuote } from "../core/escape.ts";
+import { foreignLine, type HiddenText, MESSAGE_MAX } from "../core/foreign-text.ts";
+import { refPlaywrightRunner } from "../core/playwright.ts";
+import { SLIDE_SIDECARS } from "../core/resolve.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";
 import { playerScript } from "../runtime/player.ts";
-import type { ReadableDeck } from "./scope.ts";
+import { hiddenField, hiddenInFiles, type ReadableDeck } from "./scope.ts";
 import { usageError } from "./usage.ts";
 
 export type ShotCliResult = {
@@ -13,6 +18,11 @@ export type ShotCliResult = {
   sheets?: string[];
   /** With --motion, each beat's frames and the ms into its go each shows. */
   motion?: ShotMotion["beats"];
+  /**
+   * A ref's lines, in the files of the slides drawn and in its theme, that hold characters a
+   * person cannot see.
+   */
+  hidden?: HiddenText[];
 };
 
 type ShotCommandOptions = {
@@ -32,13 +42,64 @@ export type ShotMode =
   | { kind: "morph"; from: string; to: string; at: number };
 
 export async function shotCommand(
-  { project, deck }: ReadableDeck,
+  target: ReadableDeck,
   options: ShotCommandOptions,
 ): Promise<ShotCliResult> {
   const mode = parseShotMode(options);
+  try {
+    const result = await shoot(target, mode);
+    return target.ref
+      ? { ...result, ...hiddenField(target.ref, drawnHidden(target, mode)) }
+      : result;
+  } catch (error) {
+    throw refShotError(error, target);
+  }
+}
+
+/** What the files of the slides a shot drew, and its theme, hold that a person cannot see. */
+function drawnHidden({ deck }: ReadableDeck, mode: ShotMode): HiddenText[] {
+  const all = deck.deck.sections.map((section) => section.slug);
+  const slugs =
+    mode.kind === "sheet"
+      ? all
+      : mode.kind === "morph"
+        ? [mode.from, mode.to]
+        : mode.slug === undefined
+          ? all
+          : [mode.slug];
+  const paths = deckPaths(deck.dir);
+  const files = slugs.flatMap((slug) =>
+    ([".html", ...SLIDE_SIDECARS] as const).map((ext) => paths.slide(slug, ext)),
+  );
+  return hiddenInFiles(deck.dir, [...new Set(files), paths.theme]);
+}
+
+/**
+ * A ref's slide script that does not compile stops its slide's shot, as one of the project's
+ * would; Bun's message quotes the ref's source, so it is one foreignLine, and the fix is not lint,
+ * which refuses a ref, but its author's.
+ */
+function refShotError(error: unknown, { deck, ref }: ReadableDeck): unknown {
+  if (!ref || !(error instanceof DekError) || error.path === undefined) {
+    return error;
+  }
+  const path = error.path;
+  if (extname(path) !== ".ts" || dirname(path) !== deckPaths(deck.dir).slides) {
+    return error;
+  }
+  return new DekError(foreignLine(error.message, MESSAGE_MAX), {
+    path,
+    hint: `a ref's slide scripts are its author's to fix; \`dekc shot ${ref.name} <slug>\` still draws each of its other slides, and \`dekc show ${ref.name} ${shellName(basename(path, ".ts")) ?? "<slug>"}\` prints this one's`,
+    cause: error,
+  });
+}
+
+async function shoot({ project, deck, ref }: ReadableDeck, mode: ShotMode): Promise<ShotCliResult> {
+  // A ref's slide scripts are someone else's: Chromium runs them only in its sandbox (ADR 29).
+  const runner = ref ? { runner: refPlaywrightRunner } : {};
   switch (mode.kind) {
     case "sheet": {
-      const { sheets, shots } = await shotSheet({ project, deck });
+      const { sheets, shots } = await shotSheet({ project, deck }, runner);
       return { shots, sheets };
     }
     case "motion": {
@@ -48,6 +109,7 @@ export async function shotCommand(
           slug: mode.slug,
           ...(mode.step === undefined ? {} : { step: mode.step }),
           playerScript: await playerScript(),
+          ...runner,
         },
       );
       return { shots: [], sheets, motion: beats };
@@ -55,12 +117,21 @@ export async function shotCommand(
     case "morph": {
       const shots = await shotMorph(
         { project, deck },
-        { from: mode.from, to: mode.to, at: mode.at, playerScript: await playerScript() },
+        {
+          from: mode.from,
+          to: mode.to,
+          at: mode.at,
+          playerScript: await playerScript(),
+          ...runner,
+        },
       );
       return { shots };
     }
     case "still": {
-      const shots = await shotDeck({ project, deck }, { slug: mode.slug, step: mode.step });
+      const shots = await shotDeck(
+        { project, deck },
+        { slug: mode.slug, step: mode.step, ...runner },
+      );
       return { shots };
     }
   }

package/src/cli/show.ts

@@ -1,12 +1,13 @@
 import { classifyAssetRef } from "../core/assets.ts";
 import { cssUrls, parseCss } from "../core/css.ts";
 import { deckPaths } from "../core/deck-paths.ts";
+import { type HiddenText, hiddenText } from "../core/foreign-text.ts";
 import { type HtmlScan, scanSlideHtml } from "../core/html-scan.ts";
 import { sectionChunks, splitLines } from "../core/lines.ts";
 import { readDeckFile } from "../core/resolve.ts";
 import type { Section } from "../core/schema.ts";
 import { themeExcerpt } from "../core/theme-excerpt.ts";
-import { type ReadableDeck, type RefInfo, requireSection } from "./scope.ts";
+import { hiddenField, type ReadableDeck, type RefInfo, requireSection } from "./scope.ts";
 
 /**
  * Everything one slide is made of, read in one call: enough to learn how it is
@@ -34,6 +35,8 @@ export type ShowResult = {
   assets: string[];
   /** Set when the deck is a ref. */
   ref?: RefInfo;
+  /** A ref's lines, in the files show read, that hold characters a person cannot see. */
+  hidden?: HiddenText[];
 };
 
 export function showCommand({ deck, ref }: ReadableDeck, slug: string): ShowResult {
@@ -64,11 +67,14 @@ export function showCommand({ deck, ref }: ReadableDeck, slug: string): ShowResu
     ...(scan?.refs.map((ref) => ref.value) ?? []),
     ...(sheet ? cssUrls(sheet).map((url) => url.value) : []),
   ];
+  const script = sectionSource(deck, section);
+  const hiddenIn = (path: string, text: string | null) =>
+    text === null ? [] : hiddenText(text, path);
 
   return {
     slug: section.slug,
     title: section.title,
-    script: sectionSource(deck, section),
+    script,
     beats: section.beats.map(({ id, title, line }) => ({ ...(id ? { id } : {}), title, line })),
     html,
     css,
@@ -76,6 +82,13 @@ export function showCommand({ deck, ref }: ReadableDeck, slug: string): ShowResu
     theme,
     assets: existingRefs(refs, paths.slides, deck.dir),
     ...(ref ? { ref } : {}),
+    ...hiddenField(ref, [
+      ...hiddenText(script, deck.scriptPath, section.line),
+      ...hiddenIn(paths.slide(slug, ".html"), html),
+      ...hiddenIn(paths.slide(slug, ".css"), css),
+      ...hiddenIn(paths.slide(slug, ".ts"), ts),
+      ...hiddenIn(paths.theme, themeCss),
+    ]),
   };
 }
 

package/src/cli/text.ts

@@ -2,6 +2,8 @@
 // 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 { foreignLine, type HiddenText, TITLE_MAX } from "../core/foreign-text.ts";
+import { compareCodeUnits } from "../core/order.ts";
 import { unprinted } from "../core/prose.ts";
 import { packFile, parseRefSource } from "../core/ref-name.ts";
 import { formatClock } from "../core/timing.ts";
@@ -53,7 +55,7 @@ export function formatReport(diagnostics: Diagnostic[], opts?: { color?: boolean
     byRule.set(id, (byRule.get(id) ?? 0) + 1);
   }
   const rules = [...byRule]
-    .sort(([a, x], [b, y]) => y - x || a.localeCompare(b))
+    .sort(([a, x], [b, y]) => y - x || compareCodeUnits(a, b))
     .map(([id, n]) => `${id} ×${n}`);
   return `${list}\n${countSummary(diagnostics)}: ${rules.join(", ")}`;
 }
@@ -69,6 +71,39 @@ export function formatSkipped(skipped: SkippedCheck[] | undefined, color = false
     .join("\n");
 }
 
+/** How many code points a warning names before it leaves the rest to `--json`. */
+const CODE_POINTS_SHOWN = 6;
+
+/** What to do about the characters a person cannot see in a ref that a command read. */
+const HIDDEN_HELP =
+  "text output shows each as ⟨U+XXXX⟩; a person reading the deck sees none of them, so leave them out of what you write from it";
+
+/**
+ * A warning per line of a ref's files that holds characters a person cannot see, where they
+ * are and which, then `help`, what to do about them, once, for stderr.
+ */
+export function formatHidden(
+  hidden: HiddenText[] | undefined,
+  color = false,
+  help = HIDDEN_HELP,
+): string {
+  if (hidden === undefined || hidden.length === 0) {
+    return "";
+  }
+  const c = ansi(color);
+  const lines = hidden.map(({ path, line, column, codePoints }) => {
+    const distinct = [...new Set(codePoints)];
+    const named = distinct.slice(0, CODE_POINTS_SHOWN).join(", ");
+    const rest = distinct.length > CODE_POINTS_SHOWN ? ", …" : "";
+    const count =
+      codePoints.length === 1
+        ? "1 character that shows as nothing or reorders the text"
+        : `${codePoints.length} characters that show as nothing or reorder the text`;
+    return `${c.yellow("warning:")} ${path}:${line}:${column}: ${count}: ${named}${rest}`;
+  });
+  return [...lines, `  ${c.yellow("help:")} ${help}`].join("\n");
+}
+
 /**
  * The slides sync kept though their section is gone, for stderr: sync removes only what it wrote,
  * so saying nothing would read as a deck with nothing left over.
@@ -282,15 +317,17 @@ export function formatLs(data: LsListResult | LsDeckResult): string {
       ].join("\n");
     }
     case "deck": {
+      // A ref's frontmatter is someone else's: each value keeps to its line, as in AGENTS.md.
+      const line = (text: string) => (data.ref ? foreignLine(text, TITLE_MAX) : text);
       const meta: Array<[string, string]> = [];
       if (data.ref) {
         meta.push(["rev", data.ref.rev.slice(0, 7)]);
       }
       if (data.event) {
-        meta.push(["event", data.event]);
+        meta.push(["event", line(data.event)]);
       }
       if (data.date) {
-        meta.push(["date", data.date]);
+        meta.push(["date", line(data.date)]);
       }
       if (data.duration) {
         meta.push(["duration", data.duration]);
@@ -328,7 +365,7 @@ export function formatLs(data: LsListResult | LsDeckResult): string {
       ];
       const countLabel = formatSkipped(data.skipped) || diagnosticCount(data.diagnostics.length);
       return [
-        `${data.ref?.name ?? data.name}  ${data.title}`,
+        `${data.ref?.name ?? data.name}  ${line(data.title)}`,
         ...meta.map(([key, value]) => `${padEndWidth(key, keyWidth)}  ${value}`),
         "",
         formatTable(headers, rows, [...align]),
@@ -426,7 +463,11 @@ export function formatVoice(data: VoiceCliResult): string {
   }
 }
 
-/** One labeled part per file, so a reader never confuses where a line came from. */
+/**
+ * One labeled part per file, so a reader never confuses where a line came from: a part starts
+ * with a line `--- <file>`, and a file's own line that starts the same way is shown one space
+ * further in, so no file can start a part. A ref's slide says first whose it is.
+ */
 export function formatShow(data: ShowResult): string {
   const parts: Array<[string, string | null]> = [
     ["script.md", data.script],
@@ -436,9 +477,20 @@ export function formatShow(data: ShowResult): string {
     ["theme.css (the rules this slide uses)", data.theme || null],
     ["assets", data.assets.length > 0 ? data.assets.join("\n") : null],
   ];
-  return parts
-    .flatMap(([label, body]) => (body === null ? [] : [`--- ${label}\n${body.replace(/\n$/, "")}`]))
-    .join("\n\n");
+  const ref = data.ref
+    ? [`ref ${data.ref.name} at ${data.ref.rev.slice(0, 7)}: someone else's deck, read-only`]
+    : [];
+  return [
+    ...ref,
+    ...parts.flatMap(([label, body]) =>
+      body === null ? [] : [`--- ${label}\n${partLines(body.replace(/\n$/, ""))}`],
+    ),
+  ].join("\n\n");
+}
+
+/** A part's lines, each that would start a part, after any spaces, given one space more. */
+function partLines(body: string): string {
+  return body.replace(/^( *)---(?=[^\S\n])/gm, " $1---");
 }
 
 /** What a read does for a ref whose snapshot is not there: fetch it, or unpack its pack. */
@@ -474,7 +526,7 @@ export function formatRef(data: RefCliResult): string {
         data.refs.map((ref) => [
           ref.name,
           short(ref.rev),
-          ref.fetched ? (ref.title ?? "") : notFetched(ref.name),
+          ref.fetched ? foreignLine(ref.title ?? "", TITLE_MAX) : notFetched(ref.name),
           ref.slides === undefined ? "" : String(ref.slides),
         ]),
         ["left", "left", "left", "right"],