@hajimism/dek 0.4.0 → 0.5.0

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

@@ -5,6 +5,7 @@ import { type Diagnostic, diag } from "../diagnostic.ts";
 import { isPlainWord } from "../escape.ts";
 import type { HtmlRef } from "../html-scan.ts";
 import { isInside } from "../path.ts";
+import { trimUrl } from "../url-attributes.ts";
 
 /**
  * DEK020 to DEK023 for one reference, whether it comes from a slide's markup
@@ -56,9 +57,9 @@ export function assetRefDiagnostics(
   if (kind === "missing") {
     return [
       diag("DEK021", {
-        message: `missing ${ref.tag === "img" ? "image" : "file"} "${ref.value}"`,
+        message: `missing ${ref.tag === "img" ? "image" : "file"} "${visibleSpaces(ref.value)}"`,
         ...location,
-        ...missingImageHint(ref.value, deckDir),
+        ...(strayedSpaceHint(ref.value, deckDir, from) ?? missingImageHint(ref.value, deckDir)),
         data: { src: ref.value },
       }),
     ];
@@ -66,7 +67,7 @@ export function assetRefDiagnostics(
   if (!isCanonicalAssetPath(ref.value)) {
     return [
       diag("DEK023", {
-        message: `asset "${ref.value}" must be referenced as assets/${posix.basename(ref.value.trim())}`,
+        message: `asset "${ref.value}" must be referenced as assets/${posix.basename(trimUrl(ref.value))}`,
         ...location,
         data: { src: ref.value },
       }),
@@ -76,19 +77,56 @@ export function assetRefDiagnostics(
 }
 
 function leavesFromEither(value: string, deckDir: string, from: string): boolean {
-  const path = value.trim().split(/[?#]/)[0] ?? "";
+  const path = trimUrl(value).split(/[?#]/)[0] ?? "";
   return (
     path !== "" &&
     [resolve(deckDir, path), resolve(from, path)].some((target) => !isInside(target, deckDir))
   );
 }
 
+/** `value` with each space but the plain one written as `\uXXXX`, so a message shows it. */
+function visibleSpaces(value: string): string {
+  return value.replace(
+    /[^\S ]/g,
+    (char) => `\\u${char.charCodeAt(0).toString(16).toUpperCase().padStart(4, "0")}`,
+  );
+}
+
+/**
+ * The hint for a path that names a deck file once the spaces outside ASCII at its ends are gone,
+ * as ` assets/a.png` does: the browser keeps those spaces, so the path names nothing.
+ */
+function strayedSpaceHint(
+  value: string,
+  deckDir: string,
+  from: string,
+): { hint: string } | undefined {
+  const url = trimUrl(value);
+  const bare = url.trim();
+  if (bare === url || classifyAssetRef(bare, { deckDir, from }).kind !== "file") {
+    return undefined;
+  }
+  const at = url.indexOf(bare);
+  const before = url.slice(0, at);
+  const after = url.slice(at + bare.length);
+  const where = before && after ? "around" : before ? "before" : "after";
+  const spaces = [...new Set(before + after)].map((char) => {
+    const point = `U+${char.charCodeAt(0).toString(16).toUpperCase().padStart(4, "0")}`;
+    return char === "\u00A0" ? `no-break space (${point})` : `space (${point})`;
+  });
+  // The path is the slide's text: one that is no plain word is left out of the hint.
+  const path = isPlainWord(bare) ? bare : "the path";
+  return {
+    hint: `remove the ${spaces.join(" and the ")} ${where} ${path}: the browser keeps ${spaces.length > 1 ? "them" : "it"} as part of the path, which then names no file`,
+  };
+}
+
 /**
  * Decks copy what they use from the project's `assets/` (so a deck stays whole when moved);
  * when the project has the file, the fix is that copy.
  */
 function missingImageHint(value: string, deckDir: string): { hint?: string } {
-  const name = value.trim().split(/[?#]/)[0] ?? "";
+  const name = trimUrl(value).split(/[?#]/)[0] ?? "";
   if (!name.startsWith("assets/")) {
     return {};
   }
@@ -104,7 +142,7 @@ function missingImageHint(value: string, deckDir: string): { hint?: string } {
 function remoteHint(value: string): string {
   let name = "";
   try {
-    name = posix.basename(new URL(value.trim(), "https://dek.invalid").pathname);
+    name = posix.basename(new URL(trimUrl(value), "https://dek.invalid").pathname);
   } catch {}
   // The name is the remote URL's: one that is no plain word is left out of the hint.
   return name && isPlainWord(name)

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

@@ -1,6 +1,13 @@
+import { attributeTokens } from "../attribute-value.ts";
 import { type Diagnostic, diag } from "../diagnostic.ts";
 import { isPlainWord } from "../escape.ts";
-import type { HtmlAttribute, HtmlScan, Picture, SourceSpot } from "../html-scan.ts";
+import {
+  type HtmlAttribute,
+  type HtmlScan,
+  isName,
+  type Picture,
+  type SourceSpot,
+} from "../html-scan.ts";
 import type { Section } from "../schema.ts";
 import { beatAt, formatStepChoices, resolveStep, stepChoices } from "../step.ts";
 import { suggest } from "../suggest.ts";
@@ -368,24 +375,22 @@ const EVENT_HANDLER_RE = /^on[a-z]+$/;
 /** Tags that load a URL as a document of its own, so an SVG there runs its scripts. */
 const DOCUMENT_TAGS = new Set(["iframe", "frame", "object", "embed"]);
 
+/** What a relative URL resolves against; only a URL's own scheme can run script. */
+const SOME_PAGE = "https://dek.invalid/";
+
 /**
  * The scheme of a URL that runs script, or undefined: `javascript:` and `vbscript:` always, and a
  * `data:` URL holding HTML, or SVG where a tag loads it as a document. An image's `data:` stays.
- * Read the way the URL parser reads it: tabs and newlines dropped, leading space trimmed, any case.
+ * The value comes decoded, and the URL parser reads it as the browser's does: C0 controls and
+ * spaces trimmed, tabs and newlines dropped anywhere, the scheme in any case.
  */
 function scriptUrlScheme(tag: string, value: string): string | undefined {
-  const url = value
-    .replace(/[\t\n\r]/g, "")
-    .trimStart()
-    .toLowerCase();
-  if (url.startsWith("javascript:")) {
-    return "javascript:";
-  }
-  if (url.startsWith("vbscript:")) {
-    return "vbscript:";
+  const url = URL.parse(value, SOME_PAGE);
+  if (url?.protocol === "javascript:" || url?.protocol === "vbscript:") {
+    return url.protocol;
   }
-  if (url.startsWith("data:")) {
-    const type = url.slice("data:".length).split(/[;,]/, 1)[0]?.trim();
+  if (url?.protocol === "data:") {
+    const type = url.href.slice("data:".length).split(/[;,]/, 1)[0]?.trim().toLowerCase();
     const runs =
       type === "text/html" ||
       type === "application/xhtml+xml" ||
@@ -478,14 +483,12 @@ function unnamedPicture({
 }: Picture): { message: string; hint: string; data: Record<string, string> } | undefined {
   const value = (name: string): string | undefined =>
     element.attributes.find((attribute) => attribute.name === name)?.value;
-  const named = [value("aria-label"), value("aria-labelledby"), value("title")].some(
-    (name) => name !== undefined && name.trim() !== "",
-  );
+  const named = [value("aria-label"), value("aria-labelledby"), value("title")].some(isName);
   const { tag } = element;
   if (named || (tag === "img" && value("alt") !== undefined)) {
     return undefined;
   }
-  if ((value("role") ?? "").trim().toLowerCase().split(/\s+/)[0] === "img") {
+  if (attributeTokens(value("role"))[0]?.toLowerCase() === "img") {
     if (titled) {
       return undefined;
     }
@@ -543,7 +546,7 @@ function unknownClassDiagnostics(
       : `define it in slides/${section.slug}.css, or use one of: ${shown.join(", ")}${scriptHint}`;
   const unknown = new Map<string, HtmlAttribute>();
   for (const attribute of attributesNamed(scan, "class")) {
-    for (const name of attribute.value.split(/\s+/).filter(Boolean)) {
+    for (const name of attributeTokens(attribute.value)) {
       if (!classes.has(name) && !unknown.has(name)) {
         unknown.set(name, attribute);
       }

package/src/core/mv.ts

@@ -1,4 +1,5 @@
-import { existsSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+// biome-ignore lint/style/noRestrictedImports: renameSync and unlinkSync, for mv's steps, each undone on failure; safe-fs does not rename.
+import { existsSync, renameSync, unlinkSync } from "node:fs";
 import { basename } from "node:path";
 import { deckPaths } from "./deck-paths.ts";
 import { DekError } from "./error.ts";
@@ -11,6 +12,7 @@ import {
   requireSection,
   SLIDE_SIDECARS,
 } from "./resolve.ts";
+import { writeInside } from "./safe-fs.ts";
 import { Id } from "./schema.ts";
 import { deckLayouts, skeletonHtml } from "./skeleton.ts";
 import { skeletonRecord } from "./skeleton-record.ts";
@@ -22,11 +24,11 @@ export function renameSection(input: string | ResolvedDeck, from: string, to: st
   if (!Id.safeParse(to).success) {
     throw new DekError(`invalid id "${to}"`, { hint: "use [a-z0-9-] with at least one letter" });
   }
-  const { deck } = asResolvedDeck(input);
+  const { project, deck } = asResolvedDeck(input);
   const has = (slug: string): boolean => deck.deck.sections.some((entry) => entry.slug === slug);
   if (!has(from) && has(to)) {
     // script.md was edited first; only the files still carry the old id.
-    const steps = slideFileSteps(deck, from, to);
+    const steps = slideFileSteps(project.root, deck, from, to);
     if (steps.length === 0 && !existsSync(deckPaths(deck.dir).slide(to, ".html"))) {
       throw new DekError(`slide "${from}" not found`, {
         path: deckPaths(deck.dir).slide(from, ".html"),
@@ -56,8 +58,8 @@ export function renameSection(input: string | ResolvedDeck, from: string, to: st
   }
   lines[headingIndex] = rewriteHeadingId(heading, from, to);
   applySteps([
-    writeStep(deck.scriptPath, source, joinLines(source, lines)),
-    ...slideFileSteps(deck, from, to),
+    writeStep(project.root, deck.scriptPath, source, joinLines(source, lines)),
+    ...slideFileSteps(project.root, deck, from, to),
   ]);
 }
 
@@ -69,7 +71,12 @@ export function renameSection(input: string | ResolvedDeck, from: string, to: st
  * the author wrote, one under each id, stop the rename; everything that could stop it is worked
  * out before any file changes.
  */
-function slideFileSteps(deck: ResolvedDeck["deck"], from: string, to: string): FileStep[] {
+function slideFileSteps(
+  root: string,
+  deck: ResolvedDeck["deck"],
+  from: string,
+  to: string,
+): FileStep[] {
   const paths = deckPaths(deck.dir);
   const layouts = deckLayouts(deck.dir);
   const record = skeletonRecord(deck.dir);
@@ -100,16 +107,16 @@ function slideFileSteps(deck: ResolvedDeck["deck"], from: string, to: string): F
   const kept = source && (source.authored || !target) ? source : target;
   if (source && kept === source) {
     steps.push(
-      target ? writeStep(toPath, target.html, source.html) : renameStep(source.path, toPath),
+      target ? writeStep(root, toPath, target.html, source.html) : renameStep(source.path, toPath),
     );
   }
   if (source && target) {
-    steps.push(removeStep(source.path, source.html));
+    steps.push(removeStep(root, source.path, source.html));
   }
   if (kept) {
     const next = relabel(kept.html, from, to);
     if (next !== kept.html) {
-      steps.push(writeStep(toPath, kept.html, next));
+      steps.push(writeStep(root, toPath, kept.html, next));
     }
   }
   for (const ext of SLIDE_SIDECARS) {
@@ -119,7 +126,7 @@ function slideFileSteps(deck: ResolvedDeck["deck"], from: string, to: string): F
     }
   }
   if (voice) {
-    steps.push(writeStep(voice.path, voice.source, voice.next));
+    steps.push(writeStep(root, voice.path, voice.source, voice.next));
   }
   return steps;
 }
@@ -155,19 +162,22 @@ function again(from: string, to: string): string {
   return `\`dekc mv ${end}${source} ${target}\` again`;
 }
 
-/** One file change `dekc mv` makes, with how to take it back. */
+/**
+ * One file change `dekc mv` makes, with how to take it back. A write goes to a new file renamed
+ * into place, so a crash part way leaves the old file or the new one, never half of one.
+ */
 type FileStep = { path: string; apply: () => void; undo: () => void };
 
-function writeStep(path: string, before: string, after: string): FileStep {
+function writeStep(root: string, path: string, before: string, after: string): FileStep {
   return {
     path,
-    apply: () => writeFileSync(path, after),
-    undo: () => writeFileSync(path, before),
+    apply: () => writeInside(path, after, root),
+    undo: () => writeInside(path, before, root),
   };
 }
 
-function removeStep(path: string, before: string): FileStep {
-  return { path, apply: () => unlinkSync(path), undo: () => writeFileSync(path, before) };
+function removeStep(root: string, path: string, before: string): FileStep {
+  return { path, apply: () => unlinkSync(path), undo: () => writeInside(path, before, root) };
 }
 
 function renameStep(from: string, to: string): FileStep {
@@ -268,7 +278,7 @@ export function reorderSection(
   place: SectionPlace,
 ): void {
   const target = "before" in place ? place.before : place.after;
-  const { deck } = asResolvedDeck(input);
+  const { project, deck } = asResolvedDeck(input);
   const sections = deck.deck.sections;
   const fromIndex = sections.findIndex((entry) => entry.slug === slug);
   if (fromIndex < 0) {
@@ -301,7 +311,7 @@ export function reorderSection(
   });
   const insertAt = "before" in place ? remainingTarget : remainingTarget + 1;
   chunks.splice(insertAt, 0, moved);
-  writeFileSync(deck.scriptPath, joinLines(source, [...head, ...chunks.flat()]));
+  writeInside(deck.scriptPath, joinLines(source, [...head, ...chunks.flat()]), project.root);
 }
 
 function rewriteHeadingId(heading: string, from: string, to: string): string {

package/src/core/order.ts

@@ -0,0 +1,14 @@
+/**
+ * Orders two strings by their UTF-16 code units, as `Array.prototype.sort` does with no
+ * comparator, so every list dek sorts comes out in one order, the same on every machine.
+ *
+ * `localeCompare` with no locale follows the machine's, so a teammate set to Swedish or Turkish
+ * would write dict.toml in another order. A fixed locale is no cure: its collation comes from
+ * the ICU the runtime has, which Bun takes from the system on macOS and bundles on Linux, and it
+ * counts a precomposed `ä` and an `a` with a combining mark as equal, leaving their order to
+ * whichever came first. Code units cost a dictionary's order: `B` comes before `a`, `ä` after
+ * `z`, and Japanese reads hiragana, then katakana, then kanji by code point.
+ */
+export function compareCodeUnits(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/core/path.ts

@@ -1,5 +1,6 @@
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { holdsHidden } from "./foreign-text.ts";
 
 export function moduleFilePath(url: string | URL): string {
   return fileURLToPath(url);
@@ -16,8 +17,12 @@ export function deckProjectRoot(deckDir: string): string {
 }
 
 export const DECK_NAME_HINT =
-  'use a plain name like 2026-10-talk: no "/" or "\\", no control characters, no leading "-"';
+  'use a plain name like 2026-10-talk: no "/" or "\\", no control character or one a person cannot see, no leading "-"';
 
+/**
+ * A name `dekc new` and `dekc init` may give a deck. A pack's ref takes its deck's name, so, as
+ * `dekc pack` does, these refuse a control character and one a person cannot see.
+ */
 export function isDeckName(name: string): boolean {
   return (
     name.length > 0 &&
@@ -28,7 +33,8 @@ export function isDeckName(name: string): boolean {
     // A leading "-" reads as a flag to every tool the name is passed to.
     !name.startsWith("-") &&
     // biome-ignore lint/suspicious/noControlCharactersInRegex: a control in a name is the problem.
-    !/[\x00-\x1f\x7f]/.test(name)
+    !/[\x00-\x1f\x7f-\x9f]/.test(name) &&
+    !holdsHidden(name)
   );
 }
 

package/src/core/playwright-module.d.ts

@@ -27,6 +27,11 @@ declare module "playwright" {
     }): Promise<Buffer>;
     close(): Promise<void>;
     context(): BrowserContext;
+    mainFrame(): Frame;
+    frames(): Frame[];
+  };
+  export type Frame = {
+    url(): string;
   };
   /** A DevTools protocol session: Chromium's own answers, for what the page does not expose. */
   export type CDPSession = {
@@ -44,10 +49,16 @@ declare module "playwright" {
       viewport?: Viewport;
       deviceScaleFactor?: number;
       offline?: boolean;
+      httpCredentials?: { username: string; password: string };
     }): Promise<BrowserContext>;
+    newBrowserCDPSession(): Promise<CDPSession>;
     close(): Promise<void>;
   };
   export const chromium: {
-    launch(options?: { headless?: boolean; chromiumSandbox?: boolean }): Promise<Browser>;
+    launch(options?: {
+      headless?: boolean;
+      chromiumSandbox?: boolean;
+      executablePath?: string;
+    }): Promise<Browser>;
   };
 }

package/src/core/playwright-motion.ts

@@ -1,3 +1,4 @@
+// biome-ignore lint/style/noRestrictedImports: mkdirSync, in a worker, for the folder its parent chose in dek's cache, which Chromium writes into.
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import type { Page } from "playwright";

package/src/core/playwright-sheet.ts

@@ -1,3 +1,4 @@
+// biome-ignore lint/style/noRestrictedImports: mkdirSync, in a worker, for the folder its parent chose in dek's cache, which Chromium writes into.
 import { mkdirSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Page } from "playwright";

package/src/core/playwright-visual.ts

@@ -581,13 +581,18 @@ async function visitPage(
  * measuring again: first what the slide's script drew, then the slide's own CSS. A text that
  * clears its threshold, or an element that no longer crosses an edge, once a layer is gone is
  * that layer's to fix. With both gone, a text that still fails is the theme's, and an element that
- * still overflows is its content's: too much for the theme's sizes. The page is not put back.
+ * still overflows is its content's: too much for the theme's sizes. A text that shows no glyph
+ * once a layer is gone is no longer measured as the audience sees it: one the slide's CSS alone
+ * shows is marked so, and one the draw alone shows is no layer's unless it still fails with both
+ * gone. The page is not put back.
  */
 async function attributeFindings(
   page: Page,
   pending: { failing: Failing[]; crossing: Crossing[] },
 ): Promise<void> {
   let { failing, crossing } = pending;
+  // Texts that showed no glyph the last time they were measured.
+  const unseen = new Set<Failing>();
   for (const layer of LAYERS) {
     if (failing.length === 0 && crossing.length === 0) {
       return;
@@ -615,20 +620,32 @@ async function attributeFindings(
     const texts = await pageTexts(page, measured);
     const contrasts = await textContrasts(page, texts);
     const now = new Map(texts.map((text, at) => [text.key, { text, contrast: contrasts[at] }]));
-    failing = failing.filter(({ finding, key }) => {
-      const measuredText = now.get(key);
-      if (
-        measuredText?.contrast &&
-        measuredText.contrast.ratio >= contrastThreshold(measuredText.text)
-      ) {
-        finding.origin = layer.origin;
+    failing = failing.filter((entry) => {
+      const measuredText = now.get(entry.key);
+      const seen = !unseen.has(entry);
+      if (!measuredText?.contrast) {
+        if (layer.origin === "slide" && seen) {
+          entry.finding.onlyWithSlideCss = true;
+          return false;
+        }
+        unseen.add(entry);
+        return true;
+      }
+      if (measuredText.contrast.ratio >= contrastThreshold(measuredText.text)) {
+        // Hidden with the layer before gone, it may owe its low contrast to that layer as well.
+        if (seen) {
+          entry.finding.origin = layer.origin;
+        }
         return false;
       }
+      unseen.delete(entry);
       return true;
     });
   }
-  for (const { finding } of failing) {
-    finding.origin = "theme";
+  for (const entry of failing) {
+    if (!unseen.has(entry)) {
+      entry.finding.origin = "theme";
+    }
   }
   for (const { finding } of crossing) {
     finding.origin = "content";

package/src/core/playwright.ts

@@ -10,8 +10,9 @@ import { type Collision, EDGES, type Overflow } from "./overflow.ts";
 import { moduleFilePath } from "./path.ts";
 import type { PptxFill, PptxLayer, PptxTextBox } from "./pptx-package.ts";
 import type { PptxPageTheme } from "./pptx-theme.ts";
+import { chromiumFailure, launchFailure, runDrawingWorker, type SandboxMode } from "./sandbox.ts";
 import type { MotionBeat, SheetSpec } from "./sheet.ts";
-import { exitWorker, readWorkerRequest, runJsonWorker, workerCommand } from "./spawn.ts";
+import { exitWorker, readWorkerRequest, workerCommand } from "./spawn.ts";
 import type { Position } from "./step.ts";
 
 /** One slide page to measure; a page that names a `screenshotPath` is shot there too. */
@@ -136,9 +137,15 @@ export type ContrastFinding = {
   /**
    * For text below its threshold, which stylesheet draws it so: "theme" when it stays below
    * with the slide's own CSS taken away, "slide" when that CSS brings it there. Absent when the
-   * text passes, or shows no glyph without the slide's CSS.
+   * text passes, or shows no glyph without the slide's CSS. Absent too when it shows none with the
+   * slide script's draw undone and clears without the slide's CSS: either may have drawn it so.
    */
   origin?: ContrastOrigin;
+  /**
+   * For text below its threshold that shows with the slide's own CSS and no glyph without it: the
+   * theme alone was never measured, so either stylesheet may hold its colors.
+   */
+  onlyWithSlideCss?: true;
 };
 
 export type ContrastOrigin = "theme" | "slide" | "script";
@@ -231,6 +238,11 @@ type SpawnTimeoutOptions = {
   timeoutMs?: number;
 };
 
+type RunnerOptions = SpawnTimeoutOptions & {
+  /** The pages hold a ref's deck: Chromium's sandbox only, unless the user accepted otherwise. */
+  ref?: boolean;
+};
+
 const requireFromDek = createRequire(import.meta.url);
 
 export function resolvePlaywrightModule(): string | undefined {
@@ -293,49 +305,85 @@ export async function importPlaywright(): Promise<typeof import("playwright")> {
   return import(pathToFileURL(spec).href) as Promise<typeof import("playwright")>;
 }
 
+/** Playwright's Chromium, or what stands in for it in tests. */
+type Chromium = typeof import("playwright").chromium;
+
 /**
  * A Playwright worker's whole life: load Playwright, read the request, launch Chromium, answer
  * with what `handle` returns, and close the browser. Any failure exits with its reason on stderr.
+ * Where Chromium's sandbox did not start, the answer says why in `unsandboxed`, and is only that
+ * when the request's `sandbox` required it, or with why Chromium did not start without it either
+ * in `failed`. `chromium` stands in for Playwright's in tests.
  */
 export async function runPlaywrightWorker<Request, Response>(
   handle: (browser: Browser, request: Request) => Promise<Response>,
+  chromium?: Chromium,
 ): Promise<void> {
-  let playwright: Awaited<ReturnType<typeof importPlaywright>>;
+  let launcher: Chromium;
   try {
-    playwright = await importPlaywright();
+    launcher = chromium ?? (await importPlaywright()).chromium;
   } catch {
     exitWorker(`playwright not found; ${PLAYWRIGHT_INSTALL}`);
   }
-  const request = await readWorkerRequest<Request>();
+  const request = await readWorkerRequest<Request & { sandbox?: unknown }>();
   try {
-    const browser = await launchChromium(playwright.chromium);
+    // Anything but "preferred", or nothing, requires the sandbox.
+    const sandbox = request.sandbox === "preferred" ? "preferred" : "required";
+    const launched = await launchChromium(launcher, sandbox);
+    if (!launched.browser) {
+      const { browser: _none, ...said } = launched;
+      process.stdout.write(`${JSON.stringify(said)}\n`);
+      return;
+    }
+    const { browser, unsandboxed } = launched;
     try {
       const response = await handle(browser, request);
-      process.stdout.write(`${JSON.stringify(response)}\n`);
+      const answer = unsandboxed === undefined ? response : { ...response, unsandboxed };
+      process.stdout.write(`${JSON.stringify(answer)}\n`);
     } finally {
       await browser.close();
     }
   } catch (error) {
-    exitWorker(error);
+    // The parent's hint keeps the start of stderr, and Playwright's opens with a command line.
+    exitWorker(chromiumFailure(error) ?? error);
   }
 }
 
+/**
+ * Chromium with its sandbox, or without it and why; or none: where the sandbox was required, or
+ * where Chromium did not start without it either.
+ */
+type Launched =
+  | { browser: Browser; unsandboxed?: string }
+  | { browser?: never; unsandboxed: string; failed?: string };
+
 /**
  * Headless Chromium with its sandbox, which Playwright leaves off by default: slide scripts run in
- * it, a ref's included. Where the sandbox cannot start, as in a container running as root, it
- * runs without one rather than not at all.
+ * it, a ref's included. When that launch fails, as in a container running as root, it launches
+ * again without one only when `sandbox` is "preferred", and says why in Chromium's words, whether
+ * or not they name the sandbox; when that fails too, it says both.
  */
-async function launchChromium(chromium: typeof import("playwright").chromium): Promise<Browser> {
+export async function launchChromium(chromium: Chromium, sandbox: SandboxMode): Promise<Launched> {
+  let first: unknown;
   try {
-    return await chromium.launch({ headless: true, chromiumSandbox: true });
-  } catch {
-    return await chromium.launch({ headless: true });
+    return { browser: await chromium.launch({ headless: true, chromiumSandbox: true }) };
+  } catch (error) {
+    first = error;
+  }
+  const unsandboxed = launchFailure(first);
+  if (sandbox !== "preferred") {
+    return { unsandboxed };
+  }
+  try {
+    return { browser: await chromium.launch({ headless: true }), unsandboxed };
+  } catch (second) {
+    return { unsandboxed, failed: launchFailure(second) };
   }
 }
 
 export async function defaultPlaywrightRunner(
   request: VisualRequest,
-  options: SpawnTimeoutOptions = {},
+  options: RunnerOptions = {},
 ): Promise<VisualResponse | null> {
   if (!playwrightResolved()) {
     return null;
@@ -343,6 +391,14 @@ export async function defaultPlaywrightRunner(
   return spawnRunner(workerCommand(process.env.DEK_PLAYWRIGHT || workerPath()), request, options);
 }
 
+/**
+ * The default runner for a ref's pages: someone else's slide scripts, which Chromium runs only in
+ * its sandbox unless the user set DEK_ALLOW_UNSANDBOXED=1 (ADR 29).
+ */
+export function refPlaywrightRunner(request: VisualRequest): Promise<VisualResponse | null> {
+  return defaultPlaywrightRunner(request, { ref: true });
+}
+
 function workerPath(): string {
   return moduleFilePath(new URL("./playwright-worker.ts", import.meta.url));
 }
@@ -350,12 +406,13 @@ function workerPath(): string {
 function spawnRunner(
   cmd: string[],
   request: VisualRequest,
-  options: SpawnTimeoutOptions,
+  options: RunnerOptions,
 ): Promise<VisualResponse> {
-  return runJsonWorker(cmd, request, (text) => parseVisualResponse(text, request.kind), {
+  return runDrawingWorker(cmd, request, (text) => parseVisualResponse(text, request.kind), {
     label: "Playwright worker failed",
     hint: `${PLAYWRIGHT_INSTALL} or check DEK_PLAYWRIGHT`,
     ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    ...(options.ref ? { ref: true } : {}),
   });
 }
 
@@ -524,14 +581,15 @@ function isContrastFinding(value: unknown): value is ContrastFinding {
   if (!isFinding(value)) {
     return false;
   }
-  const { ratio, fg, bg, fontSize, fontWeight, origin } = value;
+  const { ratio, fg, bg, fontSize, fontWeight, origin, onlyWithSlideCss } = value;
   return (
     isNumber(ratio) &&
     isString(fg) &&
     isString(bg) &&
     isNumber(fontSize) &&
     isNumber(fontWeight) &&
-    (origin === undefined || origin === "theme" || origin === "slide" || origin === "script")
+    (origin === undefined || origin === "theme" || origin === "slide" || origin === "script") &&
+    (onlyWithSlideCss === undefined || onlyWithSlideCss === true)
   );
 }
 

package/src/core/pptx.ts

@@ -1,3 +1,4 @@
+// biome-ignore lint/style/noRestrictedImports: mkdtempSync and rmSync, for a folder of the shots' own in the system's temp folder, removed after.
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";