@hajimism/dek 0.3.3 → 0.5.0

package/src/cli/scope.ts

@@ -1,25 +1,28 @@
-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 { foreignLine, type HiddenText, hiddenText, MESSAGE_MAX } from "../core/foreign-text.ts";
 import {
   isRefName,
   packFile,
   parseRefSource,
-  REF_MARKER,
-  readRefMeta,
+  type RefSource,
   refLicense,
+  refReadOnlyError,
   refState,
+  requireProject,
 } from "../core/ref.ts";
 import {
   locateDeck,
   type Project,
   type ProjectDeck,
+  readDeckFile,
   requireSection,
   resolveProject,
 } from "../core/resolve.ts";
 import { suggest } from "../core/suggest.ts";
 
-export { requireSection };
+export { requireProject, requireSection };
 
 export type Scope = {
   project: Project;
@@ -52,18 +55,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) {
@@ -139,9 +130,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: `start a deck on its theme with \`dekc new <name> --theme-from ${name}\`, or read it with \`dekc show ${name} <slug>\` and write what you need in your own deck's theme`,
-    });
+    throw refReadOnlyError(name);
   }
   const deck = project.decks.find((entry) => entry.name === name);
   if (!deck) {
@@ -149,10 +138,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`",
@@ -235,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
@@ -277,18 +286,16 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
       hint:
         source.kind === "file"
           ? "add it from the pack you were sent: `dekc ref <file>.tgz`"
-          : `run \`dekc ref ${arg}\``,
+          : `run \`dekc ref ${shellQuote(arg)}\``,
     });
   }
   // What adds the ref again: a pack's ref from its file, any other from its name.
-  const again =
-    source.kind === "file"
-      ? `dekc ref ${packFile(source.deck)}`
-      : `dekc ref ${source.name}@${pinned}`;
+  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) {
@@ -302,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,
@@ -311,7 +318,28 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
   }
   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) },
   };
 }
+
+/**
+ * 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,9 +1,15 @@
+import { basename, dirname, extname } from "node:path";
+import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.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 = {
@@ -12,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 = {
@@ -31,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": {
@@ -47,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 };
@@ -54,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 };
     }
   }
@@ -91,7 +163,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/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

@@ -1,6 +1,10 @@
 // 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 { 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";
 import type { AnnotationsCliResult } from "./annotations.ts";
@@ -16,6 +20,7 @@ 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";
@@ -50,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(", ")}`;
 }
@@ -66,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.
@@ -230,6 +268,27 @@ 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");
 }
@@ -258,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]);
@@ -304,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]),
@@ -346,6 +407,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(" ")}`,
@@ -360,7 +422,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");
 }
 
@@ -401,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],
@@ -411,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. */
@@ -437,7 +514,7 @@ export function formatRef(data: RefCliResult): string {
         head,
         ...data.warnings.map((warning) => `warning: ${warning}`),
         ...(data.pack ? [`commit ${data.pack}: a clone unpacks the ref from it`] : []),
-        `read it with \`dekc ls ${data.name}\` and \`dekc show ${data.name} <slug>\``,
+        `read it with \`dekc ls ${shellQuote(data.name)}\` and \`dekc show ${shellQuote(data.name)} <slug>\``,
       ].join("\n");
     }
     case "list":
@@ -449,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"],

package/src/cli/theme.ts

@@ -2,9 +2,12 @@ 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 { foreignList, type HiddenText, hiddenText } from "../core/foreign-text.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";
+import { hiddenField, type ReadableDeck, type RefInfo } from "./scope.ts";
 
 export type ThemeResult = {
   /** The deck's theme.css: the one lint and the slides use. */
@@ -15,11 +18,16 @@ 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. */
   ref?: RefInfo;
+  /** A ref's lines of theme.css that hold characters a person cannot see. */
+  hidden?: HiddenText[];
 };
 
 /** The deck's theme, or one layout's example markup when `name` is given. */
@@ -31,32 +39,72 @@ export function themeCommand({ deck, ref }: ReadableDeck, name?: string): ThemeR
       hint: "copy the project theme.css into the deck, or run `dekc new <name>` for a fresh deck",
     });
   }
-  const { classes, stateClasses, layouts, tokens } = themeFacts(
-    parseCss(readDeckFile(deck.dir, path) ?? ""),
-  );
+  const css = readDeckFile(deck.dir, path) ?? "";
+  const { classes, stateClasses, layouts, tokens } = themeFacts(parseCss(css));
+  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 } : {}),
+    ...hiddenField(ref, hiddenText(css, path)),
   };
   if (!name) {
     return result;
   }
   const layout = layouts.find((entry) => entry.name === name);
   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)"}`,
-    });
+    throw layoutNotFound(name, layouts, path, ref);
   }
   if (layout.example === undefined) {
     throw new DekError(`layout "${name}" has no example in theme.css`, {
       path,
-      hint: `add a /* @layout ${name} ... */ comment with its markup above .slide[data-layout="${name}"]`,
+      hint: ref
+        ? `a ref is read-only; read the markup of a slide that uses it with \`dekc show ${ref.name} <slug>\``
+        : `add a /* @layout ${name} ... */ comment with its markup above .slide[data-layout="${name}"]`,
     });
   }
   return { ...result, layout: { name, example: layout.example } };
 }
+
+/**
+ * A layout the theme does not define, named among the layouts whose names are plain words. A
+ * ref's layout names are its author's, so for a ref they go in the message, as foreignList shows
+ * them, and the hint is dek's words.
+ */
+function layoutNotFound(
+  name: string,
+  layouts: ThemeLayout[],
+  path: string,
+  ref: RefInfo | undefined,
+): DekError {
+  const names = layouts.map((entry) => entry.name);
+  if (!ref) {
+    return new DekError(`layout "${name}" is not defined in theme.css`, {
+      path,
+      hint: `use one of: ${listShown(names, isPlainWord, unprinted) || "(none)"}`,
+    });
+  }
+  const shown = names.filter(isPlainWord);
+  const left = names.length - shown.length;
+  const others = left > 0 ? unprinted(left) : "";
+  const defined =
+    shown.length === 0
+      ? others
+      : others
+        ? `${foreignList(shown)}, and ${others}`
+        : foreignList(shown);
+  return shown.length > 0
+    ? new DekError(`layout "${name}" is not defined in theme.css, which defines ${defined}`, {
+        path,
+        hint: `pass one of them: \`dekc theme ${ref.name} <layout>\``,
+      })
+    : new DekError(
+        `layout "${name}" is not defined in theme.css, which defines ${defined || "none"}`,
+        { path, hint: `read the markup of a slide with \`dekc show ${ref.name} <slug>\`` },
+      );
+}