@hajimism/dek 0.4.0 → 0.5.1

package/src/core/tar.ts

@@ -0,0 +1,315 @@
+/**
+ * dek's reader for a tar from someone else, a pack or GitHub's tarball of a repository (ADR 27).
+ * It reads the tar where it lies in memory, and each file is a copy of the bytes the tar stores
+ * for it, so nothing comes out larger than the tar that was counted on the way in. It reads what
+ * git, GNU tar, bsdtar, and Bun write: ustar headers, POSIX or GNU, with pax `x` and `g` headers
+ * and GNU `L` and `K` long names before an entry. Anything else, a sparse file, a device, a header
+ * that does not add up, or a second archive after the first, is refused rather than guessed at.
+ */
+
+const BLOCK = 512;
+
+// A byte order mark at the start of a name is part of the name, as Bun.Archive kept it.
+const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+
+/** The longest name dek reads, from a GNU long-name header or a pax record: PATH_MAX. */
+const MAX_NAME_BYTES = 4096;
+
+/** Headers that describe the entry after them, or the whole archive, rather than an entry. */
+const META_TYPES = new Set(["x", "g", "L", "K"]);
+
+/** Regular files: `0`, the old `\0`, and `7`, which tar writes and reads as a regular file. */
+const FILE_TYPES = new Set(["0", "\0", "7"]);
+
+/** Folders and links, which hold no data; Bun leaves links out, and so does dek. */
+const EMPTY_TYPES = new Set(["5", "1", "2"]);
+
+/** pax keys that make an entry a sparse file, whose bytes are not the ones the tar stores. */
+const SPARSE_KEY = /^(?:GNU\.sparse\.|SCHILY\.realsize$|SUN\.holesdata$)/;
+
+/**
+ * Why dek will not read a tar: its entries declare more than it may hold, it is not a tar at all,
+ * or it `holds` something dek does not read, named so its sender can find it, such as "a sparse
+ * file (`t/big`)".
+ */
+export type TarRefusal =
+  | { kind: "too large" }
+  | { kind: "not a tar" }
+  | { kind: "holds"; what: string };
+
+/**
+ * The regular files of `tar` by the path it gives them, or why there are none. It may hold
+ * `maxEntries` headers at most, and its entries may declare `maxBytes` in all. The tar must end
+ * with a block of zeros, and only zeros may follow it, so a second archive after the first is
+ * refused rather than half read. A file whose name's last segment starts with `._`, the
+ * AppleDouble file in which macOS's tar keeps another file's extended attributes, is left out,
+ * so dek does not read `slides/._intro.html` as a slide.
+ */
+export function readTar(
+  tar: Uint8Array<ArrayBuffer>,
+  { maxBytes, maxEntries }: { maxBytes: number; maxEntries: number },
+): Map<string, Blob> | TarRefusal {
+  // A first block that is no tar header at all, rather than a damaged one, is not a tar.
+  if (tar.byteLength < BLOCK || parseHeader(tar.subarray(0, BLOCK)) === NOT_USTAR) {
+    return { kind: "not a tar" };
+  }
+  const files = new Map<string, Blob>();
+  let declared = 0;
+  let entries = 0;
+  // What the headers before an entry say about it; they apply to that entry and no other.
+  let pending: Pending = NOTHING_PENDING;
+  let offset = 0;
+  while (offset + BLOCK <= tar.byteLength) {
+    const block = tar.subarray(offset, offset + BLOCK);
+    if (isZero(block)) {
+      if (pending !== NOTHING_PENDING) {
+        return holds("a pax or long-name header with no entry after it");
+      }
+      return afterEnd(tar.subarray(offset)) ?? files;
+    }
+    entries += 1;
+    if (entries > maxEntries) {
+      return holds(`more than ${maxEntries.toLocaleString("en-US")} entries`);
+    }
+    const header = parseHeader(block);
+    if (typeof header === "string") {
+      return holds(header);
+    }
+    const meta = META_TYPES.has(header.type);
+    const paxSize = meta ? undefined : pending.pax?.get("size");
+    const size = paxSize === undefined ? header.size : decimal(paxSize);
+    // The last of a pax path and a GNU long name names the entry; an empty one leaves the header's.
+    const path = meta ? header.name : pending.name || header.name;
+    if (size === undefined) {
+      return holds(`a pax size that does not read (${shown(path)})`);
+    }
+    // Short of what it declares before larger than the limit: a kilobyte that declares 200 MB is cut
+    // short, not 200 MB.
+    const start = offset + BLOCK;
+    if (start + size > tar.byteLength) {
+      return holds(`an entry cut short (${shown(path)})`);
+    }
+    declared += size;
+    if (declared > maxBytes) {
+      return { kind: "too large" };
+    }
+    const data = tar.subarray(start, start + size);
+    offset = start + Math.ceil(size / BLOCK) * BLOCK;
+
+    if (meta) {
+      const read = readMeta(header, data, pending);
+      if (typeof read === "string") {
+        return holds(read);
+      }
+      pending = read;
+      continue;
+    }
+    pending = NOTHING_PENDING;
+    if (path.includes("\0")) {
+      return holds(`a name with a NUL in it (${shown(path)})`);
+    }
+    if (FILE_TYPES.has(header.type)) {
+      if (path.endsWith("/")) {
+        return holds(`a file named like a folder (${shown(path)})`);
+      }
+      if (!path.slice(path.lastIndexOf("/") + 1).startsWith("._")) {
+        files.set(path, new Blob([data]));
+      }
+    } else if (!EMPTY_TYPES.has(header.type)) {
+      return holds(
+        `${KIND_OF[header.type] ?? `an entry of type ${shown(header.type)}`} (${shown(path)})`,
+      );
+    } else if (size !== 0) {
+      return holds(
+        `${header.type === "5" ? "a folder" : "a link"} that declares data (${shown(path)})`,
+      );
+    }
+  }
+  return holds("a tar with no end");
+}
+
+/** The entry types dek names when it refuses one; any other is named by its type. */
+const KIND_OF: Record<string, string> = {
+  S: "a sparse file",
+  "3": "a device",
+  "4": "a device",
+  "6": "a FIFO",
+};
+
+function holds(what: string): TarRefusal {
+  return { kind: "holds", what };
+}
+
+/** What follows the end of the tar, when it is not only zeros: another archive, or other data. */
+function afterEnd(rest: Uint8Array): TarRefusal | undefined {
+  const start = rest.findIndex((byte) => byte !== 0);
+  if (start < 0) {
+    return undefined;
+  }
+  const block = rest.subarray(start - (start % BLOCK), start - (start % BLOCK) + BLOCK);
+  return holds(
+    typeof parseHeader(block) === "string"
+      ? "data after the end of the tar"
+      : "a second archive after the first",
+  );
+}
+
+/**
+ * A name from the tar as dek may print it: on one line, with no control or format character, such
+ * as one that moves the cursor or turns text around, no longer than 80 characters, in backticks.
+ * It is cut before anything else, so a long name costs no more than a short one.
+ */
+function shown(name: string): string {
+  const head = Array.from(name.slice(0, 200));
+  const cut = head.length > 80 ? `${head.slice(0, 79).join("")}…` : head.join("");
+  return `\`${cut.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}`]/gu, "\uFFFD")}\``;
+}
+
+/** What the pax and GNU headers before an entry said: its pax records, its name, which were seen. */
+type Pending = {
+  pax?: Map<string, string>;
+  name?: string;
+  longName?: true;
+  longLink?: true;
+};
+
+const NOTHING_PENDING: Pending = {};
+
+/**
+ * What a pax or GNU header adds to what is pending for the next entry, or what is wrong with it:
+ * it does not read, names a path too long or repeats one already pending, or marks a sparse file.
+ * A global `g` header applies to nothing dek reads; it may come only between entries.
+ */
+function readMeta(header: Header, data: Uint8Array, pending: Pending): Pending | string {
+  const twice = `two pax or long-name headers before one entry (${shown(header.name)})`;
+  if (header.type === "L" || header.type === "K") {
+    const end = data.indexOf(0);
+    if ((end < 0 ? data.byteLength : end) > MAX_NAME_BYTES) {
+      return tooLong(data);
+    }
+    if (header.type === "K") {
+      return pending.longLink ? twice : { ...pending, longLink: true };
+    }
+    const name = text(data);
+    return pending.longName ? twice : { ...pending, longName: true, name: name || pending.name };
+  }
+  const records = paxRecords(data);
+  if (typeof records === "string") {
+    return records || `pax records that do not read (${shown(header.name)})`;
+  }
+  if ([...records.keys()].some((key) => SPARSE_KEY.test(key))) {
+    const name = records.get("GNU.sparse.name") ?? records.get("path") ?? header.name;
+    return `a sparse file (${shown(name)})`;
+  }
+  if (header.type === "g") {
+    return pending === NOTHING_PENDING
+      ? pending
+      : "a pax global header between a header and its entry";
+  }
+  if (pending.pax) {
+    return twice;
+  }
+  return { ...pending, pax: records, name: records.get("path") || pending.name };
+}
+
+/** A name longer than dek reads, shown by its start. */
+function tooLong(bytes: Uint8Array): string {
+  return `a name longer than ${MAX_NAME_BYTES} bytes (${shown(decoder.decode(bytes.subarray(0, 400)))})`;
+}
+
+type Header = { type: string; name: string; size: number };
+
+const NOT_USTAR = "a header that is neither ustar nor GNU tar";
+
+/**
+ * A header block, or what is wrong with it, unless it is a ustar header as POSIX (`ustar\0`
+ * `00`) or GNU (`ustar  \0`) writes it, with a checksum that adds up and a size in octal. A
+ * POSIX header's prefix goes before its name; a GNU header keeps other fields there.
+ */
+function parseHeader(block: Uint8Array): Header | string {
+  const magic = decoder.decode(block.subarray(257, 265));
+  const posix = magic === "ustar\u000000";
+  if (!posix && magic !== "ustar  \u0000" && !isZero(block)) {
+    return NOT_USTAR;
+  }
+  const name = text(block.subarray(0, 100));
+  const prefix = posix ? text(block.subarray(345, 500)) : "";
+  const path = prefix === "" ? name : `${prefix}/${name}`;
+  if (!checksumHolds(block)) {
+    return `a header whose checksum does not add up (${shown(path)})`;
+  }
+  const size = octal(block.subarray(124, 136));
+  if (size === undefined) {
+    return `a header whose size does not read (${shown(path)})`;
+  }
+  return { type: String.fromCharCode(block[156] ?? 0), name: path, size };
+}
+
+/** An octal field: digits, after spaces if any, then only NULs or spaces. */
+function octal(field: Uint8Array): number | undefined {
+  const digits = /^ *([0-7]+)[ \0]*$/.exec(decoder.decode(field))?.[1];
+  return digits === undefined ? undefined : Number.parseInt(digits, 8);
+}
+
+/** A pax number: decimal digits and nothing else. */
+function decimal(value: string): number | undefined {
+  return /^\d+$/.test(value) ? Number(value) : undefined;
+}
+
+/** The header's checksum against its bytes, summed as unsigned or as signed, as tar allows. */
+function checksumHolds(block: Uint8Array): boolean {
+  const stored = octal(block.subarray(148, 156));
+  let unsigned = 0;
+  let signed = 0;
+  for (let index = 0; index < BLOCK; index++) {
+    const value = index >= 148 && index < 156 ? 0x20 : (block[index] ?? 0);
+    unsigned += value;
+    signed += value > 127 ? value - 256 : value;
+  }
+  return stored === unsigned || stored === signed;
+}
+
+/** The pax records that name a path, which may be `MAX_NAME_BYTES` long at most. */
+const NAME_KEYS = new Set(["path", "linkpath"]);
+
+/**
+ * pax records, `<length> <key>=<value>\n` each with the length in decimal digits, filling `data`
+ * exactly, by key; otherwise what is wrong, a path too long or, as "", a record that does not read.
+ */
+function paxRecords(data: Uint8Array): Map<string, string> | string {
+  const records = new Map<string, string>();
+  let offset = 0;
+  while (offset < data.byteLength) {
+    const space = data.indexOf(0x20, offset);
+    const digits = space < 0 ? "" : decoder.decode(data.subarray(offset, space));
+    if (!/^[1-9]\d*$/.test(digits)) {
+      return "";
+    }
+    const end = offset + Number(digits);
+    if (end <= space + 1 || end > data.byteLength || data[end - 1] !== 0x0a) {
+      return "";
+    }
+    const equals = data.subarray(0, end - 1).indexOf(0x3d, space + 1);
+    if (equals <= space + 1) {
+      return "";
+    }
+    const key = decoder.decode(data.subarray(space + 1, equals));
+    const value = data.subarray(equals + 1, end - 1);
+    if (NAME_KEYS.has(key) && value.byteLength > MAX_NAME_BYTES) {
+      return tooLong(value);
+    }
+    records.set(key, decoder.decode(value));
+    offset = end;
+  }
+  return records;
+}
+
+/** A field's text up to its first NUL. */
+function text(field: Uint8Array): string {
+  const end = field.indexOf(0);
+  return decoder.decode(end < 0 ? field : field.subarray(0, end));
+}
+
+function isZero(bytes: Uint8Array): boolean {
+  return bytes.every((byte) => byte === 0);
+}

package/src/core/text-contrast.ts

@@ -255,6 +255,7 @@ async function sampleTextContrasts({
   texts,
 }: SamplerInput): Promise<Array<TextContrast | null>> {
   const decode = async (base64: string): Promise<Pixels> => {
+    // biome-ignore lint/style/noRestrictedGlobals: it runs in the page and decodes a data: URL, which reaches no network.
     const blob = await (await fetch(`data:image/png;base64,${base64}`)).blob();
     const bitmap = await createImageBitmap(blob);
     const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
@@ -419,6 +420,7 @@ ${
   }, GLYPHS_MARK);
   const found = await page.evaluate(async (input) => {
     const decode = async (base64: string) => {
+      // biome-ignore lint/style/noRestrictedGlobals: it runs in the page and decodes a data: URL, which reaches no network.
       const blob = await (await fetch(`data:image/png;base64,${base64}`)).blob();
       const bitmap = await createImageBitmap(blob);
       const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);

package/src/core/toml-keys.ts

@@ -17,7 +17,8 @@ export type TomlKey = {
 /**
  * Every key and table header in a TOML file, in order, with where each is written: the one reader
  * dek.toml lint, `dekc mv`, and `dekc ref` share. It reads `[table]`, `[[array]]`, (dotted) keys, and
- * one-line inline tables, and steps over comments and multi-line strings.
+ * inline tables, and steps over comments, multi-line strings, and arrays and inline tables written
+ * over several lines, as Bun's TOML parser reads them.
  */
 export function scanTomlKeys(source: string): TomlKey[] {
   const lines = source.split("\n");
@@ -38,10 +39,7 @@ export function scanTomlKeys(source: string): TomlKey[] {
     }
     const path = [...table, ...names(assignment.segments)];
     keys.push(keyAt("key", path, assignment.segments, index));
-    if (line[assignment.value] === "{") {
-      inlineKeys(line, assignment.value, path, index, keys);
-    }
-    index = valueLastLine(lines, index, assignment.value);
+    index = readValue(lines, { index, at: assignment.value }, path, keys).index;
   }
   return keys;
 }
@@ -82,64 +80,131 @@ function readAssignment(
   return { segments: path.segments, value: skipSpace(line, path.end + 1) };
 }
 
-/** The keys of the inline table opening at `open`, nested ones too; returns the index past it. */
-function inlineKeys(
-  line: string,
-  open: number,
-  prefix: string[],
-  index: number,
+/** A place in a file split into lines: the line's index, and the character's on it. */
+type Cursor = { index: number; at: number };
+
+const VALUE_ENDS = new Set([",", "#", "]", "}"]);
+
+/**
+ * The place past the value at `from`: a string, multi-line or not, an array, an inline table, or
+ * a bare word. An inline table's keys are recorded under `path`, nested ones too; one in an
+ * array is not, as no key path names it.
+ */
+function readValue(
+  lines: string[],
+  from: Cursor,
+  path: string[] | undefined,
   keys: TomlKey[],
-): number {
-  let i = skipSpace(line, open + 1);
-  while (i < line.length && line[i] !== "}") {
-    const assignment = readAssignment(line, i);
-    if (!assignment) {
-      return line.length;
+): Cursor {
+  const line = lines[from.index] ?? "";
+  const ch = line[from.at];
+  const delimiter = tripleQuote(line, from.at);
+  if (delimiter) {
+    return skipMultilineString(lines, from, delimiter);
+  }
+  if (isQuote(ch)) {
+    return { index: from.index, at: Math.min(skipString(line, from.at), lineEnd(line)) };
+  }
+  if (ch === "[" || ch === "{") {
+    return readItems(lines, { index: from.index, at: from.at + 1 }, ch, path, keys);
+  }
+  let at = from.at;
+  while (at < lineEnd(line) && !VALUE_ENDS.has(line[at] ?? "")) {
+    at++;
+  }
+  return { index: from.index, at };
+}
+
+/**
+ * The place past the array or inline table whose items start at `from`, which may run on over
+ * lines. A table's keys are recorded under `path`. One that breaks off, as at a key with no comma
+ * before it, ends with the line it broke off on, so what follows is read as the file's own.
+ */
+function readItems(
+  lines: string[],
+  from: Cursor,
+  open: "[" | "{",
+  path: string[] | undefined,
+  keys: TomlKey[],
+): Cursor {
+  const close = open === "[" ? "]" : "}";
+  let last = from;
+  let next = skipBlank(lines, from);
+  for (;;) {
+    const line = lines[next.index] ?? "";
+    const ch = line[next.at];
+    if (ch === close) {
+      return { index: next.index, at: next.at + 1 };
+    }
+    if (ch === undefined || next.at >= lineEnd(line)) {
+      return next;
     }
-    const path = [...prefix, ...names(assignment.segments)];
-    keys.push(keyAt("inline", path, assignment.segments, index));
-    const { value } = assignment;
-    i = skipSpace(
-      line,
-      line[value] === "{" ? inlineKeys(line, value, path, index, keys) : skipValue(line, value),
-    );
-    if (line[i] === ",") {
-      i = skipSpace(line, i + 1);
+    let valueAt = next;
+    let itemPath: string[] | undefined;
+    if (open === "{") {
+      const assignment = readAssignment(line, next.at);
+      if (!assignment) {
+        return { index: last.index, at: lineEnd(lines[last.index] ?? "") };
+      }
+      itemPath = path && [...path, ...names(assignment.segments)];
+      if (itemPath) {
+        keys.push(keyAt("inline", itemPath, assignment.segments, next.index));
+      }
+      valueAt = { index: next.index, at: assignment.value };
+    }
+    last = readValue(lines, valueAt, itemPath, keys);
+    next = skipBlank(lines, last);
+    const after = lines[next.index]?.[next.at];
+    if (after === ",") {
+      last = { index: next.index, at: next.at + 1 };
+      next = skipBlank(lines, last);
+    } else if (after !== close) {
+      return { index: last.index, at: lineEnd(lines[last.index] ?? "") };
     }
   }
-  return i + 1;
 }
 
-const NESTING: Record<string, number> = { "[": 1, "{": 1, "]": -1, "}": -1 };
-const VALUE_ENDS = new Set([",", "#", "]", "}"]);
+/** The place past the spaces, comments, and line breaks at `from`; the end of the file at most. */
+function skipBlank(lines: string[], from: Cursor): Cursor {
+  let { index, at } = from;
+  for (;;) {
+    const line = lines[index] ?? "";
+    at = skipSpace(line, at);
+    if ((at < lineEnd(line) && line[at] !== "#") || index >= lines.length - 1) {
+      return { index, at };
+    }
+    index++;
+    at = 0;
+  }
+}
 
-/** The index past one value on a line: a string, an array or inline table, or a bare word. */
-function skipValue(line: string, from: number): number {
-  let depth = 0;
-  let i = from;
-  while (i < line.length) {
-    const ch = line[i] ?? "";
-    if (depth === 0 && VALUE_ENDS.has(ch)) {
-      return i;
+/** The place past the multi-line string opening at `from`; an unclosed one runs to the end. */
+function skipMultilineString(lines: string[], from: Cursor, delimiter: string): Cursor {
+  let at = from.at + 3;
+  for (let index = from.index; index < lines.length; index++, at = 0) {
+    const line = lines[index] ?? "";
+    const close = line.indexOf(delimiter, at);
+    if (close !== -1) {
+      // Up to two quotes of the string's own may come right before its closing three.
+      let end = close + 3;
+      while (end < close + 5 && line[end] === delimiter[0]) {
+        end++;
+      }
+      return { index, at: end };
     }
-    depth += NESTING[ch] ?? 0;
-    i = isQuote(ch) ? skipString(line, i) : i + 1;
   }
-  return i;
+  const index = lines.length - 1;
+  return { index, at: lineEnd(lines[index] ?? "") };
 }
 
-/**
- * The line the value starting at `start` ends on: its own, unless it opens a multi-line string it
- * does not close there. An unclosed one runs to the end of the file.
- */
+/** Where a line's text ends, before the CR of a CRLF. */
+function lineEnd(line: string): number {
+  return line.endsWith("\r") ? line.length - 1 : line.length;
+}
+
+/** The line the value starting at `start` ends on, a later one when it runs on over lines. */
 function valueLastLine(lines: string[], index: number, start: number): number {
-  const line = lines[index] ?? "";
-  const delimiter = tripleQuote(line, start);
-  if (!delimiter || line.includes(delimiter, start + 3)) {
-    return index;
-  }
-  const close = lines.findIndex((next, i) => i > index && next.includes(delimiter));
-  return close === -1 ? lines.length - 1 : close;
+  return readValue(lines, { index, at: start }, undefined, []).index;
 }
 
 /** Reads `a . "b" . 'c'` from `from`; `end` is the first non-space after it. */

package/src/core/url-attributes.ts

@@ -2,6 +2,7 @@
  * Which attributes name a URL, and where in the value each URL is written. Lint checks exactly
  * these, and the build inlines exactly these, so a reference that passes one never breaks the other.
  */
+import { isAsciiWhitespace } from "./attribute-value.ts";
 
 /**
  * What the page does with a URL: a `resource` is loaded to draw the slide, so it must exist and
@@ -46,18 +47,18 @@ function urlAttribute(tag: string, attr: string): (typeof URL_ATTRIBUTES)[number
 
 /**
  * The URLs of a `srcset`, each with its offset in the value, parsed the way the HTML standard
- * does: a URL runs to the next whitespace, a trailing comma ends it, and the descriptors after it
- * run to the next comma. So `data:` URIs keep their commas.
+ * does: a URL runs to the next ASCII whitespace, a trailing comma ends it, and the descriptors
+ * after it run to the next comma. So `data:` URIs keep their commas.
  */
 export function srcsetUrls(value: string): Array<{ url: string; offset: number }> {
   const candidates: Array<{ url: string; offset: number }> = [];
   let index = 0;
   while (index < value.length) {
-    while (index < value.length && /[\s,]/.test(value[index] ?? "")) {
+    while (index < value.length && (value[index] === "," || isAsciiWhitespace(value[index]))) {
       index++;
     }
     const start = index;
-    while (index < value.length && !/\s/.test(value[index] ?? "")) {
+    while (index < value.length && !isAsciiWhitespace(value[index])) {
       index++;
     }
     let url = value.slice(start, index);
@@ -90,14 +91,31 @@ export function attributeUrls(
   value: string,
 ): { use: UrlUse; urls: Array<{ url: string; offset: number }> } | undefined {
   const entry = urlAttribute(tag, attr);
-  const url = value.trim();
-  if (!entry || !url) {
+  const { start, end } = urlBounds(value);
+  if (!entry || start === end) {
     return undefined;
   }
   return {
     use: entry.use,
-    urls: entry.list
-      ? srcsetUrls(value)
-      : [{ url, offset: value.length - value.trimStart().length }],
+    urls: entry.list ? srcsetUrls(value) : [{ url: value.slice(start, end), offset: start }],
   };
 }
+
+/** A URL without the C0 controls and spaces at its ends, which the URL parser strips. */
+export function trimUrl(url: string): string {
+  const { start, end } = urlBounds(url);
+  return url.slice(start, end);
+}
+
+/** Where `value` starts and ends past the C0 controls and spaces; a no-break space stays. */
+function urlBounds(value: string): { start: number; end: number } {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value.charCodeAt(start) <= 0x20) {
+    start++;
+  }
+  while (end > start && value.charCodeAt(end - 1) <= 0x20) {
+    end--;
+  }
+  return { start, end };
+}

package/src/core/visual.ts

@@ -4,7 +4,6 @@ import { EDGES, type Edge } from "./overflow.ts";
 import { renderPdfHtml } from "./pdf.ts";
 import {
   askPlaywright,
-  type ContrastOrigin,
   type FillFinding,
   type PageAction,
   type PagesResponse,
@@ -315,9 +314,14 @@ function groupBySteps<T extends { step: string }>(items: T[], key: (item: T) =>
 /**
  * Where to fix low contrast. Text the theme alone draws too faint is fixed once in theme.css
  * for every slide that uses the pair; a slide that fixed it in its own CSS would leave the rest.
+ * Text only the slide's CSS shows was never measured on the theme alone, so both are named.
  */
-function contrastHint(origin: ContrastOrigin | undefined, threshold: number, slug: string): string {
+function contrastHint(sample: ContrastSample, threshold: number): string {
+  const { origin, slug } = sample;
   const own = `slides/${slug}.css`;
+  if (sample.onlyWithSlideCss) {
+    return `without ${own} it does not show, so dek cannot tell whether theme.css alone draws it below ${threshold}:1: fix the pair in ${own}, or in theme.css if the colors are the theme's`;
+  }
   switch (origin) {
     case "theme":
       return `theme.css alone draws it below ${threshold}:1: fix the pair in theme.css, where one change reaches every slide that uses it`;
@@ -333,8 +337,17 @@ function contrastHint(origin: ContrastOrigin | undefined, threshold: number, slu
   }
 }
 
-/** The file to change: the one the origin names, or the slide itself when it is not known. */
-function contrastPath(origin: ContrastOrigin | undefined, slug: string, paths: DeckPaths): string {
+/**
+ * The file to change: the one the origin names, or the slide itself when it is not known. Text
+ * only the slide's CSS shows goes to that CSS, which the hint names first.
+ */
+function contrastPath(
+  { origin, slug, onlyWithSlideCss }: ContrastSample,
+  paths: DeckPaths,
+): string {
+  if (onlyWithSlideCss) {
+    return paths.slide(slug, ".css");
+  }
   switch (origin) {
     case "theme":
       return paths.theme;
@@ -583,9 +596,15 @@ function shownRatio(sample: ContrastSample): number {
 }
 
 function contrastKey(c: ContrastSample): string {
-  return [c.slug, c.box, c.text ?? "", shownRatio(c), contrastThreshold(c), c.origin ?? ""].join(
-    "\0",
-  );
+  return [
+    c.slug,
+    c.box,
+    c.text ?? "",
+    shownRatio(c),
+    contrastThreshold(c),
+    c.origin ?? "",
+    c.onlyWithSlideCss ?? "",
+  ].join("\0");
 }
 
 function overflowWhere(amounts: Partial<Record<Edge, number>>): string {
@@ -681,9 +700,9 @@ function contrastDiagnostic(
   const colors = fg && bg ? ` (${fg} on ${bg})` : "";
   return diag("DEK031", {
     message: `${describeTarget(first.box, first.text)}has contrast ${ratio}${colors}, below ${threshold}:1${size} ${atSteps(steps)}`,
-    path: contrastPath(first.origin, first.slug, paths),
+    path: contrastPath(first, paths),
     slug: first.slug,
-    hint: contrastHint(first.origin, threshold, first.slug),
+    hint: contrastHint(first, threshold),
     data: {
       box: first.box,
       ...(first.text ? { text: first.text } : {}),