@hajimism/dek 0.3.3 → 0.5.0

package/src/core/playwright.ts

@@ -2,13 +2,17 @@ import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 import type { Browser } from "playwright";
+import type { AlignedEdge, Misalignment } from "./alignment.ts";
 import { DekError } from "./error.ts";
 import type { Fill } from "./fill.ts";
+import type { LineBreakKind } from "./line-break.ts";
 import { type Collision, EDGES, type Overflow } from "./overflow.ts";
 import { moduleFilePath } from "./path.ts";
-import type { PptxTextBox } from "./pptx-package.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. */
@@ -41,7 +45,7 @@ export type MotionSpec = {
 };
 
 /** What to measure on each page; a screenshot is asked for by the page's `screenshotPath`. */
-export type PageAction = "overflow" | "contrast" | "fill";
+export type PageAction = "overflow" | "contrast" | "fill" | "breaks" | "alignment";
 
 type Viewport = { width: number; height: number };
 
@@ -84,8 +88,9 @@ export type MotionRequest = {
 };
 
 /**
- * Each slide's still page drawn for a PPTX, at twice its size: its text measured line by line,
- * then the page shot without it, to `screenshotPath`.
+ * Each slide's still page drawn for a PPTX, at twice its size: its text, boxes, and pictures
+ * measured, each picture drawn alone beside `screenshotPath`, then the page shot without what
+ * is laid over it, to `screenshotPath`.
  */
 export type PptxRequest = {
   kind: "pptx";
@@ -93,9 +98,22 @@ export type PptxRequest = {
   pages: Array<{ html: string; slug: string; screenshotPath: string }>;
 };
 
-/** Each page's text, in the order of the request's pages, with the font each run was drawn in. */
+/** A picture on its way to the package: the PNG the worker wrote, and the SVG it read. */
+export type PptxPictureFile = { png: string; svg?: string };
+
+/** Each page's layers, in the order of the request's pages, with the font each run was drawn in. */
 export type PptxResponse = {
-  slides: Array<{ slug: string; description: string; boxes: PptxTextBox[] }>;
+  slides: Array<{
+    slug: string;
+    description: string;
+    layers: PptxLayer<PptxPictureFile>[];
+    /** Whether anything is left in the slide's picture; false for nothing. */
+    picture?: boolean;
+    /** The slide's background, when PowerPoint paints it. */
+    background?: PptxFill;
+    /** What the slide says of the deck's theme. */
+    theme?: PptxPageTheme;
+  }>;
 };
 
 /** What the Playwright worker is asked; the kind says which payload comes with it. */
@@ -119,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";
@@ -144,6 +168,30 @@ type CollisionFinding = Collision & { slug: string; step: string };
 /** How much of the frame one page fills, and where. */
 export type FillFinding = Fill & { slug: string; step: string };
 
+/**
+ * A line break that reads wrong on one page, with what decides where the fix goes: the slide's own
+ * `word-break` and the text's `text-wrap`, as the page computes them.
+ */
+type LineBreakFinding = {
+  slug: string;
+  step: string;
+  box: string;
+  text?: string;
+  lines: string[];
+  wordBreak: string;
+  textWrap: string;
+} & LineBreakKind;
+
+/** Two items on one page that nearly line up and do not, each named as the page shows it. */
+type MisalignmentFinding = Omit<Misalignment, "element" | "other"> & {
+  slug: string;
+  step: string;
+  box: string;
+  text?: string;
+  other: string;
+  otherText?: string;
+};
+
 export type PagesResponse = {
   overflows: OverflowFinding[];
   contrasts: ContrastFinding[];
@@ -153,6 +201,10 @@ export type PagesResponse = {
   collisions?: CollisionFinding[];
   /** One for each page, when `fill` was asked for; absent from a runner that has none. */
   fills?: FillFinding[];
+  /** Absent from a runner that has none to report. */
+  lineBreaks?: LineBreakFinding[];
+  /** Absent from a runner that has none to report. */
+  misalignments?: MisalignmentFinding[];
 };
 
 export type MotionResponse = {
@@ -186,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 {
@@ -248,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;
@@ -298,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));
 }
@@ -305,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 } : {}),
   });
 }
 
@@ -318,13 +420,23 @@ function spawnRunner(
 const RESPONSE_PARSERS: {
   [K in keyof VisualResponses]: (fields: Record<string, unknown>) => VisualResponses[K] | null;
 } = {
-  pages: ({ overflows, contrasts, drawErrors = [], collisions = [], fills = [] }) =>
+  pages: ({
+    overflows,
+    contrasts,
+    drawErrors = [],
+    collisions = [],
+    fills = [],
+    lineBreaks = [],
+    misalignments = [],
+  }) =>
     isArrayOf(overflows, isOverflowFinding) &&
     isArrayOf(contrasts, isContrastFinding) &&
     isArrayOf(drawErrors, isDrawErrorFinding) &&
     isArrayOf(collisions, isCollisionFinding) &&
-    isArrayOf(fills, isFillFinding)
-      ? { overflows, contrasts, drawErrors, collisions, fills }
+    isArrayOf(fills, isFillFinding) &&
+    isArrayOf(lineBreaks, isLineBreakFinding) &&
+    isArrayOf(misalignments, isMisalignmentFinding)
+      ? { overflows, contrasts, drawErrors, collisions, fills, lineBreaks, misalignments }
       : null,
   pdf: () => ({}),
   morph: () => ({}),
@@ -401,6 +513,37 @@ function isFillFinding(value: unknown): value is FillFinding {
   );
 }
 
+function isLineBreakFinding(value: unknown): value is LineBreakFinding {
+  if (!isFinding(value)) {
+    return false;
+  }
+  const { kind, lines, phrased, tail, wordBreak, textWrap } = value;
+  return (
+    isArrayOf(lines, isString) &&
+    isString(wordBreak) &&
+    isString(textWrap) &&
+    ((kind === "split" && isArrayOf(phrased, isString)) || (kind === "short" && isString(tail)))
+  );
+}
+
+const ALIGNED_EDGES: ReadonlySet<unknown> = new Set<AlignedEdge>([
+  "top",
+  "middle",
+  "bottom",
+  "left",
+  "center",
+  "right",
+]);
+
+function isMisalignmentFinding(value: unknown): value is MisalignmentFinding {
+  // Both name two elements by their boxes and their texts, as a collision does.
+  if (!isCollisionFinding(value)) {
+    return false;
+  }
+  const { edge, of, by } = value as Record<string, unknown>;
+  return ALIGNED_EDGES.has(edge) && (of === "box" || of === "text") && isNumber(by);
+}
+
 function isDrawErrorFinding(value: unknown): value is DrawErrorFinding {
   if (!value || typeof value !== "object") {
     return false;
@@ -438,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)
   );
 }
 
@@ -453,34 +597,125 @@ function isPptxSlide(value: unknown): value is PptxResponse["slides"][number] {
   if (!value || typeof value !== "object") {
     return false;
   }
-  const { slug, description, boxes } = value as Record<string, unknown>;
-  return isString(slug) && isString(description) && isArrayOf(boxes, isPptxBox);
+  const { slug, description, layers, picture, background, theme } = value as Record<
+    string,
+    unknown
+  >;
+  return (
+    isString(slug) &&
+    isString(description) &&
+    isArrayOf(layers, isPptxLayer) &&
+    (picture === undefined || typeof picture === "boolean") &&
+    (background === undefined || isFill(background)) &&
+    (theme === undefined || (Boolean(theme) && typeof theme === "object"))
+  );
 }
 
-function isPptxBox(value: unknown): value is PptxTextBox {
+function isFill(value: unknown): value is PptxFill {
   if (!value || typeof value !== "object") {
     return false;
   }
-  const box = value as Record<string, unknown>;
+  const fill = value as Record<string, unknown>;
+  return fill.kind === "solid"
+    ? isPaint(fill.paint)
+    : fill.kind === "linear" &&
+        isNumber(fill.angle) &&
+        isArrayOf(
+          fill.stops,
+          (stop: unknown): stop is object =>
+            Boolean(stop) &&
+            typeof stop === "object" &&
+            isNumber((stop as Record<string, unknown>).at) &&
+            isPaint((stop as Record<string, unknown>).paint),
+        );
+}
+
+function isPptxLayer(value: unknown): value is PptxLayer<PptxPictureFile> {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const layer = value as Record<string, unknown>;
+  const at = ["x", "y", "width", "height"].every((key) => isNumber(layer[key]));
+  switch (layer.kind) {
+    case "text":
+      return isPptxBox(layer);
+    case "rule":
+      return (
+        ["x1", "y1", "x2", "y2", "width"].every((key) => isNumber(layer[key])) &&
+        isPaint(layer.paint)
+      );
+    case "picture":
+      return (
+        at &&
+        isString(layer.png) &&
+        isString(layer.description) &&
+        (layer.svg === undefined || isString(layer.svg))
+      );
+    case "shape":
+      return (
+        at &&
+        isNumber(layer.radius) &&
+        (layer.fill === undefined || isPaint(layer.fill)) &&
+        isArrayOf(layer.layers, isPptxLayer) &&
+        (layer.text === undefined || isShapeText(layer.text))
+      );
+    default:
+      return false;
+  }
+}
+
+function isPaint(value: unknown): boolean {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const { color, alpha } = value as Record<string, unknown>;
+  return isArrayOf(color, isNumber) && isNumber(alpha);
+}
+
+function isShapeText(value: unknown): boolean {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const { inset, paragraphs } = value as Record<string, unknown>;
   return (
-    ["x", "y", "width", "height", "lineHeight"].every((key) => isNumber(box[key])) &&
-    isArrayOf(box.runs, (run: unknown): run is PptxTextBox["runs"][number] => {
-      if (!run || typeof run !== "object") {
+    Boolean(inset) &&
+    typeof inset === "object" &&
+    isArrayOf(paragraphs, (paragraph: unknown): paragraph is object => {
+      if (!paragraph || typeof paragraph !== "object") {
         return false;
       }
-      const { text, size, alpha, letterSpacing, color, font } = run as Record<string, unknown>;
-      return (
-        isString(text) &&
-        isNumber(size) &&
-        isNumber(alpha) &&
-        isNumber(letterSpacing) &&
-        isArrayOf(color, isNumber) &&
-        (font === undefined || isString(font))
-      );
+      const { runs, lineHeight } = paragraph as Record<string, unknown>;
+      return isNumber(lineHeight) && isArrayOf(runs, isPptxRun);
     })
   );
 }
 
+function isPptxBox(value: unknown): value is PptxTextBox {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const box = value as Record<string, unknown>;
+  return (
+    ["x", "y", "width", "height", "lineHeight"].every((key) => isNumber(box[key])) &&
+    isArrayOf(box.runs, isPptxRun)
+  );
+}
+
+function isPptxRun(run: unknown): run is PptxTextBox["runs"][number] {
+  if (!run || typeof run !== "object") {
+    return false;
+  }
+  const { text, size, alpha, letterSpacing, color, font } = run as Record<string, unknown>;
+  return (
+    isString(text) &&
+    isNumber(size) &&
+    isNumber(alpha) &&
+    isNumber(letterSpacing) &&
+    isArrayOf(color, isNumber) &&
+    (font === undefined || isString(font))
+  );
+}
+
 function isMotionBeat(value: unknown): value is MotionBeat {
   if (!value || typeof value !== "object") {
     return false;