@hajimism/dek 0.4.0 → 0.5.0

package/src/cli/theme.ts

@@ -3,10 +3,11 @@ 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. */
@@ -25,6 +26,8 @@ export type ThemeResult = {
   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. */
@@ -36,9 +39,8 @@ 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 = {
@@ -49,28 +51,60 @@ export function themeCommand({ deck, ref }: ReadableDeck, name?: string): ThemeR
     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: ${
-        listShown(
-          layouts.map((entry) => entry.name),
-          isPlainWord,
-          unprinted,
-        ) || "(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>\`` },
+      );
+}

package/src/cli/tty.ts

@@ -10,15 +10,29 @@ const codes = {
   bold: "\x1b[1m",
 } as const;
 
+/** The codes dek's own palette writes, which are all terminalSafe lets through. */
+const PALETTE = new Set<string>([reset, ...Object.values(codes)]);
+
+/**
+ * Text with no control character but a newline and a tab: each other shows as U+FFFD, the escape
+ * that starts a color code included. A result's and an error's text go through it before dek
+ * paints them, so what a deck or a ref wrote carries no color, conceal, or cursor move of its own.
+ */
+export function plainText(text: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point.
+  return text.replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, "\uFFFD");
+}
+
 /**
  * Text for a terminal: dek's own colors, newlines, and tabs pass, and every other control
  * character shows as U+FFFD. A deck title, a file name, or a ref's title fetched from GitHub
- * could otherwise set the window title, draw a fake link (OSC 8), or clear the screen.
+ * could otherwise set the window title, draw a fake link (OSC 8), clear the screen, or hide
+ * itself from a person while an agent reading the bytes sees it, as conceal (SGR 8) does.
  */
 export function terminalSafe(text: string): string {
   // biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point.
   return text.replace(/\x1b\[[0-9;]*m|[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, (match) =>
-    match.length > 1 ? match : "\uFFFD",
+    PALETTE.has(match) ? match : plainText(match),
   );
 }
 

package/src/cli/voice.ts

@@ -1,9 +1,9 @@
-import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { DekError } from "../core/error.ts";
 import { deckProjectRoot } from "../core/path.ts";
 import { isCachedFile, requireInside, writeInside } from "../core/safe-fs.ts";
+import { runPiped } from "../core/spawn.ts";
 import { loadVoiceDict, loadVoiceSettings, voiceCacheFile, writeVoiceDict } from "../core/voice.ts";
 import {
   engineBaseUrl,
@@ -97,6 +97,9 @@ export function pinVoice({ deck }: DeckTarget): VoiceCliResult {
   return { action: "pin", timelinePath: pinTimeline, audioPath: pinAudio };
 }
 
+/** A clip of a sentence or two plays well inside this. */
+const PLAY_TIMEOUT_MS = 5 * 60 * 1000;
+
 async function playWav(path: string): Promise<void> {
   if (process.env.DEK_VOICE_PLAY === "0") {
     return;
@@ -106,9 +109,11 @@ async function playWav(path: string): Promise<void> {
   if (!bin) {
     return;
   }
-  await new Promise<void>((resolve) => {
-    const child = spawn(bin, [path], { stdio: "ignore" });
-    child.on("exit", () => resolve());
-    child.on("error", () => resolve());
-  });
+  // Playing is a courtesy: the clip is written either way, so a player that is missing, fails,
+  // or hangs is let go.
+  await runPiped([bin, path], {
+    label: `${bin} failed`,
+    hint: `play ${path} yourself`,
+    timeoutMs: PLAY_TIMEOUT_MS,
+  }).catch(() => {});
 }

package/src/core/assets.ts

@@ -1,5 +1,6 @@
 import { readFileSync, realpathSync, statSync } from "node:fs";
 import { extname, relative, resolve, sep } from "node:path";
+import { decodeAttribute } from "./attribute-value.ts";
 import { parseCss } from "./css.ts";
 import {
   type CssEditor,
@@ -10,9 +11,10 @@ import {
   shareTokensWithTransitions,
 } from "./css-transform.ts";
 import { deckPaths } from "./deck-paths.ts";
+import { escapeAttr } from "./escape.ts";
 import { isInside } from "./path.ts";
 import { listSlideFiles, readDeckFile } from "./resolve.ts";
-import { attributeUrls } from "./url-attributes.ts";
+import { attributeUrls, trimUrl } from "./url-attributes.ts";
 
 /** Where one reference from a slide or a stylesheet points. */
 export type AssetRef =
@@ -35,13 +37,14 @@ const SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
  * Resolves a reference the one way lint, show, and the build agree on: the
  * deck root first, which is where the dev server and the build look for
  * `assets/`, then next to the file that names it, so `../assets/x` from
- * slides/ still resolves. A query string or fragment is not part of the path.
+ * slides/ still resolves. A query string or fragment is not part of the path, and only the C0
+ * controls and spaces at its ends are trimmed, as the URL parser trims them.
  */
 export function classifyAssetRef(
   raw: string,
   options: { deckDir: string; from: string },
 ): AssetRef {
-  const value = raw.trim().split(/[?#]/)[0] ?? "";
+  const value = trimUrl(raw).split(/[?#]/)[0] ?? "";
   if (!value) {
     return { kind: "skip" };
   }
@@ -93,7 +96,7 @@ export function fileInside(
 
 /** True when a reference is written as `assets/...` from the deck root, or is not a local path at all. */
 export function isCanonicalAssetPath(raw: string): boolean {
-  const value = raw.trim();
+  const value = trimUrl(raw);
   if (!value || value.startsWith("#") || SCHEME_RE.test(value) || REMOTE_RE.test(value)) {
     return true;
   }
@@ -118,8 +121,10 @@ export function inlineAssets(
 
 /**
  * The rewriter handler `inlineAssets` runs, for a pass that rewrites more than URLs. The URLs are
- * the ones lint checks, read by the same parser: every candidate of a `srcset` keeps its
- * descriptors, links and text stay as written.
+ * the ones lint checks, read by the same parser and decoded as the browser decodes them: every
+ * candidate of a `srcset` keeps its descriptors, links and text stay as written. The rewriter
+ * writes a value as it is given, escaping only `"`, so each data: URI goes in escaped, in place
+ * of the URL as written, and an attribute with nothing to inline is never written at all.
  */
 export function assetInliner(
   deckDir: string,
@@ -128,7 +133,8 @@ export function assetInliner(
   return {
     element(el) {
       const tag = el.tagName.toLowerCase();
-      for (const [name, value] of [...el.attributes]) {
+      for (const [name, written] of [...el.attributes]) {
+        const { value, writtenAt } = decodeAttribute(written);
         const named = attributeUrls(tag, name.toLowerCase(), value);
         if (named?.use !== "resource") {
           continue;
@@ -137,9 +143,11 @@ export function assetInliner(
           const uri = inlinedUri(url, deckDir, from);
           return uri === undefined
             ? rewritten
-            : rewritten.slice(0, offset) + uri + rewritten.slice(offset + url.length);
-        }, value);
-        if (inlined !== value) {
+            : rewritten.slice(0, writtenAt(offset)) +
+                escapeAttr(uri) +
+                rewritten.slice(writtenAt(offset + url.length));
+        }, written);
+        if (inlined !== written) {
           el.setAttribute(name, inlined);
         }
       }

package/src/core/attribute-value.ts

@@ -0,0 +1,188 @@
+/**
+ * An attribute's value as the browser reads it. Bun's HTMLRewriter gives each value as written,
+ * character references and all, so `assets/Q&A.png` would name a file the page never loads.
+ * Every value lint or the build reads off the rewriter goes through here first; a value written
+ * back into the markup is written from the one as written, never from this.
+ */
+import { LEGACY_REFERENCES, NAMED_REFERENCES } from "./html-entities.ts";
+
+/** A decoded value, and where in the value as written each of its UTF-16 units comes from. */
+export type DecodedAttribute = {
+  value: string;
+  /** The offset in the written value of the unit at `index`; `value.length` maps past the end. */
+  writtenAt(index: number): number;
+};
+
+/** The value of `name` on a rewriter's element as the browser reads it, or null when absent. */
+export function attributeOf(
+  element: { getAttribute(name: string): string | null },
+  name: string,
+): string | null {
+  const written = element.getAttribute(name);
+  return written === null ? null : decodeAttribute(written).value;
+}
+
+/**
+ * Whether `char` is ASCII whitespace, the only whitespace HTML splits a list of tokens on or trims
+ * a value of. A no-break space, written as itself or as ` `, is part of the value.
+ */
+export function isAsciiWhitespace(char: string | undefined): boolean {
+  return char === " " || char === "\t" || char === "\n" || char === "\f" || char === "\r";
+}
+
+/** The tokens of a value such as `class` or `role`, split on ASCII whitespace as HTML splits it. */
+export function attributeTokens(value: string | null | undefined): string[] {
+  return (value ?? "").split(/[\t\n\f\r ]+/).filter(Boolean);
+}
+
+/** `value` without the ASCII whitespace at its ends, as HTML trims a keyword or a name. */
+export function trimAsciiWhitespace(value: string): string {
+  return value.replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/g, "");
+}
+
+/**
+ * `written` read the way the HTML standard reads an attribute value: every numeric and named
+ * character reference decoded, a carriage return read as a line feed, and a NUL as U+FFFD. A
+ * name the standard allows without its `;` stays as written when a letter, a digit, or `=`
+ * follows it, so the `&copy` of `?a=1&copy=2` is left alone, as the browser leaves it.
+ */
+export function decodeAttribute(written: string): DecodedAttribute {
+  // Each replacement, where it is in the decoded value and where in the written one, in order.
+  const spans: Array<{ start: number; end: number; writtenStart: number; writtenEnd: number }> = [];
+  let shift = 0;
+  const value = written.replace(
+    REFERENCE_RE,
+    (match: string, hex?: string, decimal?: string, name?: string, semicolon?: string, at = 0) => {
+      const text = replacement(written, match, at, { hex, decimal, name, semicolon });
+      if (text !== match) {
+        const start = at - shift;
+        spans.push({
+          start,
+          end: start + text.length,
+          writtenStart: at,
+          writtenEnd: at + match.length,
+        });
+        shift += match.length - text.length;
+      }
+      return text;
+    },
+  );
+  return {
+    value,
+    writtenAt(index) {
+      let offset = index;
+      for (const span of spans) {
+        if (index < span.start) {
+          break;
+        }
+        if (index < span.end) {
+          return span.writtenStart;
+        }
+        offset = span.writtenEnd + (index - span.end);
+      }
+      return offset;
+    },
+  };
+}
+
+/**
+ * A character reference, with its parts as groups; a carriage return, which the input stream reads
+ * as a line feed; or a NUL, which the tokenizer reads as U+FFFD in a value.
+ */
+const REFERENCE_RE = /&(?:#(?:[xX]([0-9a-fA-F]+)|([0-9]+));?|([A-Za-z0-9]+)(;?))|\r\n?|\0/g;
+
+/** What one match of REFERENCE_RE reads as: itself, when the standard leaves it as written. */
+function replacement(
+  written: string,
+  match: string,
+  at: number,
+  parts: { hex?: string; decimal?: string; name?: string; semicolon?: string },
+): string {
+  if (match === "\0") {
+    return "\uFFFD";
+  }
+  if (match.startsWith("\r")) {
+    return "\n";
+  }
+  if (parts.hex !== undefined || parts.decimal !== undefined) {
+    return numericReference(
+      parts.hex === undefined
+        ? Number.parseInt(parts.decimal ?? "", 10)
+        : Number.parseInt(parts.hex, 16),
+    );
+  }
+  const name = parts.name ?? "";
+  if (parts.semicolon) {
+    return namedReferences().get(name) ?? match;
+  }
+  // The browser takes the longest name it knows. A legacy name shorter than the run of letters
+  // and digits is followed by one of them, which keeps it as written, so only the whole run can.
+  if (legacyReferences().has(name) && written[at + match.length] !== "=") {
+    return namedReferences().get(name) ?? match;
+  }
+  return match;
+}
+
+/**
+ * The character a numeric reference stands for: U+FFFD for NUL, a surrogate, or a number past
+ * Unicode, and for 0x80 to 0x9F the Windows-1252 character the standard reads it as.
+ */
+function numericReference(number: number): string {
+  if (number === 0 || number > 0x10ffff || (number >= 0xd800 && number <= 0xdfff)) {
+    return "\uFFFD";
+  }
+  return String.fromCodePoint(C1_REPLACEMENTS.get(number) ?? number);
+}
+
+/** The HTML standard's table for a numeric reference to a C1 control. */
+const C1_REPLACEMENTS: ReadonlyMap<number, number> = new Map([
+  [0x80, 0x20ac],
+  [0x82, 0x201a],
+  [0x83, 0x0192],
+  [0x84, 0x201e],
+  [0x85, 0x2026],
+  [0x86, 0x2020],
+  [0x87, 0x2021],
+  [0x88, 0x02c6],
+  [0x89, 0x2030],
+  [0x8a, 0x0160],
+  [0x8b, 0x2039],
+  [0x8c, 0x0152],
+  [0x8e, 0x017d],
+  [0x91, 0x2018],
+  [0x92, 0x2019],
+  [0x93, 0x201c],
+  [0x94, 0x201d],
+  [0x95, 0x2022],
+  [0x96, 0x2013],
+  [0x97, 0x2014],
+  [0x98, 0x02dc],
+  [0x99, 0x2122],
+  [0x9a, 0x0161],
+  [0x9b, 0x203a],
+  [0x9c, 0x0153],
+  [0x9e, 0x017e],
+  [0x9f, 0x0178],
+]);
+
+let named: Map<string, string> | undefined;
+let legacy: Set<string> | undefined;
+
+/** Each named reference, without its `;`, and the characters it stands for; read once. */
+function namedReferences(): Map<string, string> {
+  named ??= new Map(
+    NAMED_REFERENCES.split(" ").map((entry) => {
+      const [name = "", points = ""] = entry.split(":");
+      return [
+        name,
+        String.fromCodePoint(...points.split("+").map((point) => Number.parseInt(point, 16))),
+      ];
+    }),
+  );
+  return named;
+}
+
+function legacyReferences(): Set<string> {
+  legacy ??= new Set(LEGACY_REFERENCES.split(" "));
+  return legacy;
+}

package/src/core/build.ts

@@ -1,11 +1,11 @@
-import { copyFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { loadConfig } from "./config.ts";
 import { renderDeckDocument } from "./document.ts";
 import { type DistOptions, distFile } from "./path.ts";
 import type { PlaywrightRunner } from "./playwright.ts";
 import { asResolvedDeck, type ResolvedDeck } from "./resolve.ts";
-import { outputPath, removeInside, writeInside } from "./safe-fs.ts";
+import { removeInside, writeInside } from "./safe-fs.ts";
 import { coverShot } from "./shot/still.ts";
 import { logicalSize } from "./size.ts";
 
@@ -43,7 +43,7 @@ export async function buildDeck(
   const shot = baseUrl ? await coverShot(deck, options.runner) : undefined;
 
   if (shot) {
-    copyFileSync(shot, outputPath(imagePath, project.root));
+    writeInside(imagePath, readFileSync(shot), project.root);
   } else {
     // An image from an earlier build would outlive the tag that pointed at it.
     removeInside(imagePath, project.root);