@hajimism/dek 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [0.3.2](https://github.com/hajimism/dek/compare/v0.3.1...v0.3.2) (2026-10-20)
+
+
+### Bug Fixes
+
+* **pdf:** print each slide as a picture with its text laid over it ([02f49a8](https://github.com/hajimism/dek/commit/02f49a855209e1c4430613fd9358699305bcbb9b))
+* **pdf:** print each slide as a picture with its text laid over it ([b88259d](https://github.com/hajimism/dek/commit/b88259dbcc80ed0a1450cc6bf6422c71120c5802))
+
+
+### Performance
+
+* **pdf:** keep a slide of photographs as a JPEG ([19a9092](https://github.com/hajimism/dek/commit/19a909214b256c8bbcf66a443f00c54c2b43766e))
+
+
+### Documentation
+
+* record the PDF as pictures in ADR 14 and the presenting guide ([c889781](https://github.com/hajimism/dek/commit/c88978175a9b3812f611d8af4de94b2de57556c1))
+* say which slides the PDF keeps as JPEGs, in ADR 14 and the guide ([de733fb](https://github.com/hajimism/dek/commit/de733fb4589d5f6f45f6f9a83b60673d2feab706))
+
 ## [0.3.1](https://github.com/hajimism/dek/compare/v0.3.0...v0.3.1) (2026-10-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",
@@ -61,11 +61,11 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.14",
-    "@happy-dom/global-registrator": "20.14.5",
+    "@biomejs/biome": "2.5.15",
+    "@happy-dom/global-registrator": "21.0.1",
     "@types/bun": "^1.4.2",
-    "happy-dom": "20.14.5",
-    "knip": "6.38.0",
+    "happy-dom": "21.0.1",
+    "knip": "6.41.0",
     "playwright": "^1.63.0",
     "typescript": "^7.0.2",
     "vitepress": "^1.6.4"

package/src/cli/commands.ts

@@ -774,7 +774,8 @@ export const COMMANDS = {
     args: [],
     flags: ["root-dist"],
     usage: ["dekc pdf [deck] [--root-dist]"],
-    summary: "Write dist/<deck>.pdf, one page per slide at its last beat. Needs Playwright.",
+    summary:
+      "Write dist/<deck>.pdf, one page per slide at its last beat: a picture of it with its text\nlaid over it, unseen, to select and search. Needs Playwright.",
     group: "Output",
     overview: [["dekc pdf [--root-dist]", "write a PDF"]],
     agent: ["dekc pdf [--root-dist]"],

package/src/core/pdf-text.ts

@@ -0,0 +1,191 @@
+/// <reference lib="dom" />
+// What a PDF prints of a slide: a picture of the slide as the browser drew it, with its text laid
+// over it, unseen, so a reader can still select, search, and copy it. Chromium writes a blurred
+// box-shadow and `background-clip: text` into a PDF as soft masks, which Apple's viewers (Preview,
+// Quick Look, Safari, iOS) draw as flat boxes; a picture looks the same in every viewer.
+
+/** The slides of the print document, one PDF page each. */
+export const PDF_SLIDES = "#deck > .slide";
+
+/**
+ * Leaves each slide's text where it was laid out and paints nothing else: no color, no
+ * background, no border, no shadow, no picture. Only paint changes, never layout, so the text lies
+ * where the picture under it shows it. In a layer, so that these `!important` declarations win
+ * over any the theme or a slide writes, whatever their selectors weigh.
+ */
+export const PDF_TEXT_CSS = `@layer dek-pdf-text {
+  #deck > .slide,
+  #deck > .slide::before,
+  #deck > .slide::after,
+  #deck > .slide *,
+  #deck > .slide *::before,
+  #deck > .slide *::after,
+  #deck > .slide *::marker,
+  #deck > .slide *::first-letter,
+  #deck > .slide *::first-line {
+    color: transparent !important;
+    -webkit-text-fill-color: transparent !important;
+    -webkit-text-stroke-color: transparent !important;
+    text-decoration-color: transparent !important;
+    text-emphasis-color: transparent !important;
+    text-shadow: none !important;
+    border-color: transparent !important;
+    border-image: none !important;
+    outline-color: transparent !important;
+    column-rule-color: transparent !important;
+    box-shadow: none !important;
+    transition: none !important;
+  }
+  #deck > .slide::before,
+  #deck > .slide::after,
+  #deck > .slide *,
+  #deck > .slide *::before,
+  #deck > .slide *::after,
+  #deck > .slide *::first-letter,
+  #deck > .slide *::first-line {
+    background: none !important;
+  }
+  #deck > .slide {
+    opacity: 1 !important;
+    mix-blend-mode: normal !important;
+  }
+  #deck > .slide :is(img, video, canvas, iframe, embed, object, input, select, textarea, button, progress, meter),
+  #deck > .slide svg image {
+    opacity: 0 !important;
+  }
+  #deck > .slide svg * {
+    fill: transparent !important;
+    stroke: transparent !important;
+  }
+}`;
+
+/**
+ * Where each slide lies on the whole page, for its picture to be shot.
+ *
+ * Runs in the page, shipped by `page.evaluate`, so it references nothing outside itself.
+ */
+export function slideBoxesInPage(
+  selector: string,
+): { x: number; y: number; width: number; height: number }[] {
+  return [...document.querySelectorAll(selector)].map((slide) => {
+    const box = slide.getBoundingClientRect();
+    return {
+      x: box.left + window.scrollX,
+      y: box.top + window.scrollY,
+      width: box.width,
+      height: box.height,
+    };
+  });
+}
+
+/**
+ * Takes every paint but the text away from the page's slides, once their pictures are shot. A
+ * filter or a backdrop filter would draw over the picture, or turn the text under it into pixels,
+ * so each goes; `will-change` keeps the box it made for its positioned descendants, so they stay
+ * where they were laid out.
+ *
+ * Runs in the page, shipped by `page.evaluate`, so it references nothing outside itself.
+ */
+export function keepOnlyTextInPage({ selector, css }: { selector: string; css: string }): void {
+  for (const slide of document.querySelectorAll(selector)) {
+    for (const el of [slide, ...slide.querySelectorAll("*")]) {
+      if (!(el instanceof HTMLElement || el instanceof SVGElement)) {
+        continue;
+      }
+      const style = getComputedStyle(el);
+      const effects = (["filter", "backdrop-filter"] as const).filter(
+        (property) => style.getPropertyValue(property) !== "none",
+      );
+      if (effects.length === 0) {
+        continue;
+      }
+      const hints = style.willChange === "auto" ? [] : [style.willChange];
+      for (const property of effects) {
+        el.style.setProperty(property, "none", "important");
+      }
+      el.style.setProperty("will-change", [...hints, ...effects].join(", "), "important");
+    }
+  }
+  const sheet = document.createElement("style");
+  sheet.textContent = css;
+  document.head.append(sheet);
+}
+
+/** How good a JPEG a photograph's slide is kept as: near the PNG to the eye, at under half its size. */
+export const PDF_JPEG_QUALITY = 90;
+
+/** How much of a slide its photographs must cover for the slide to be kept as a JPEG. */
+const PHOTO_SHARE = 0.1;
+
+/**
+ * Which of a slide's two pictures the PDF keeps: the JPEG for a slide that shows photographs,
+ * where it is smaller, and the PNG for the rest. Type and flat shapes keep their edges in a PNG;
+ * a JPEG blurs them, so a slide of them is never kept as one, however much smaller it would be.
+ */
+export function pdfPictureType(
+  sizes: { png: number; jpeg: number },
+  photoShare: number,
+): "png" | "jpeg" {
+  return photoShare >= PHOTO_SHARE && sizes.jpeg < sizes.png ? "jpeg" : "png";
+}
+
+/**
+ * How much of each slide raster pictures cover, 0 to 1: images, video, and canvases, and
+ * backgrounds drawn from a picture's URL. SVG is shapes, not a photograph, and does not count.
+ *
+ * Runs in the page, shipped by `page.evaluate`, so it references nothing outside itself.
+ */
+export function photoSharesInPage(selector: string): number[] {
+  const vector = (url: string) => /^data:image\/svg|\.svg(?:[?#]|$)/i.test(url);
+  return [...document.querySelectorAll(selector)].map((slide) => {
+    const frame = slide.getBoundingClientRect();
+    let covered = 0;
+    for (const el of [slide, ...slide.querySelectorAll("*")]) {
+      const style = getComputedStyle(el);
+      if (style.visibility !== "visible" || style.display === "none") {
+        continue;
+      }
+      const raster =
+        el instanceof HTMLImageElement
+          ? !vector(el.currentSrc || el.src)
+          : el instanceof HTMLVideoElement ||
+            el instanceof HTMLCanvasElement ||
+            [...style.backgroundImage.matchAll(/url\("?([^")]*)"?\)/g)].some(
+              ([, url]) => url !== undefined && !vector(url),
+            );
+      if (!raster) {
+        continue;
+      }
+      const box = el.getBoundingClientRect();
+      const width = Math.min(box.right, frame.right) - Math.max(box.left, frame.left);
+      const height = Math.min(box.bottom, frame.bottom) - Math.max(box.top, frame.top);
+      covered += Math.max(0, width) * Math.max(0, height);
+    }
+    return Math.min(1, covered / (frame.width * frame.height));
+  });
+}
+
+/**
+ * Sets a slide's picture, a `data:` URL, under its text: the `index`th of the page's slides.
+ * One slide a call, so no message to the page carries more than one picture.
+ *
+ * Runs in the page, shipped by `page.evaluate`, so it references nothing outside itself.
+ */
+export function setSlidePictureInPage({
+  selector,
+  index,
+  picture,
+}: {
+  selector: string;
+  index: number;
+  picture: string;
+}): void {
+  const slide = document.querySelectorAll(selector)[index];
+  if (slide instanceof HTMLElement) {
+    slide.style.setProperty(
+      "background",
+      `url("${picture}") 0 0 / 100% 100% no-repeat border-box`,
+      "important",
+    );
+  }
+}

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

@@ -3,13 +3,18 @@ declare module "playwright" {
   export type Page = {
     goto(url: string): Promise<unknown>;
     setContent(html: string, options?: { waitUntil?: string }): Promise<void>;
-    emulateMedia(options: { reducedMotion?: "reduce" | "no-preference" }): Promise<void>;
+    emulateMedia(options: {
+      media?: "screen" | "print";
+      reducedMotion?: "reduce" | "no-preference";
+    }): Promise<void>;
     setViewportSize(size: Viewport): Promise<void>;
     evaluate<T, A = unknown>(fn: (arg: A) => T | Promise<T>, arg?: A): Promise<T>;
     screenshot(options: {
       path?: string;
       fullPage?: boolean;
+      clip?: { x: number; y: number; width: number; height: number };
       type?: "png" | "jpeg";
+      quality?: number;
     }): Promise<Buffer>;
     addScriptTag(options: { content: string }): Promise<unknown>;
     pdf(options: {

package/src/core/playwright-visual.ts

@@ -11,6 +11,16 @@ import {
   samePlace,
 } from "./overflow.ts";
 import { visitInPages } from "./page-pool.ts";
+import {
+  keepOnlyTextInPage,
+  PDF_JPEG_QUALITY,
+  PDF_SLIDES,
+  PDF_TEXT_CSS,
+  pdfPictureType,
+  photoSharesInPage,
+  setSlidePictureInPage,
+  slideBoxesInPage,
+} from "./pdf-text.ts";
 import type {
   ContrastFinding,
   ContrastOrigin,
@@ -50,12 +60,13 @@ export async function runVisualRequest<R extends VisualRequest>(
   browser: Browser,
   request: R,
 ): Promise<ResponseTo<R>> {
-  // A PPTX's pictures are shown full screen, so they are drawn at twice the slide's size. A deck is
-  // self-contained (DEK020), so the page needs no network, and a ref's slide scripts get none.
+  // A PPTX's and a PDF's pictures are shown full screen, so they are drawn at twice the slide's
+  // size. A deck is self-contained (DEK020), so the page needs no network, and a ref's slide
+  // scripts get none.
   const context = await browser.newContext({
     viewport: request.viewport,
     offline: true,
-    ...(request.kind === "pptx" ? { deviceScaleFactor: 2 } : {}),
+    ...(request.kind === "pptx" || request.kind === "pdf" ? { deviceScaleFactor: 2 } : {}),
   });
   try {
     return (await answer(context, request)) as ResponseTo<R>;
@@ -83,10 +94,35 @@ function answer(context: BrowserContext, request: VisualRequest) {
   }
 }
 
-/** The whole print document as one PDF, a page per slide. */
+/**
+ * The whole print document as one PDF, a page per slide: each slide shot as print draws it, then
+ * printed as that picture with its text laid over it, unseen.
+ */
 async function printPdf(context: BrowserContext, request: PdfRequest): Promise<DoneResponse> {
   const page = await context.newPage();
   await page.setContent(request.html, { waitUntil: "load" });
+  await page.evaluate(() => document.fonts.ready.then(() => undefined));
+  await page.emulateMedia({ media: "print" });
+  // A slide that shows photographs is shot as a JPEG too, and kept as one where it is smaller.
+  const shares = await page.evaluate(photoSharesInPage, PDF_SLIDES);
+  const pictures: string[] = [];
+  for (const [index, clip] of (await page.evaluate(slideBoxesInPage, PDF_SLIDES)).entries()) {
+    const share = shares[index] ?? 0;
+    const png = await page.screenshot({ clip, fullPage: true });
+    const jpeg =
+      pdfPictureType({ png: png.length, jpeg: 0 }, share) === "jpeg"
+        ? await page.screenshot({ clip, fullPage: true, type: "jpeg", quality: PDF_JPEG_QUALITY })
+        : undefined;
+    const kept =
+      jpeg && pdfPictureType({ png: png.length, jpeg: jpeg.length }, share) === "jpeg"
+        ? { type: "jpeg", data: jpeg }
+        : { type: "png", data: png };
+    pictures.push(`data:image/${kept.type};base64,${kept.data.toString("base64")}`);
+  }
+  await page.evaluate(keepOnlyTextInPage, { selector: PDF_SLIDES, css: PDF_TEXT_CSS });
+  for (const [index, picture] of pictures.entries()) {
+    await page.evaluate(setSlidePictureInPage, { selector: PDF_SLIDES, index, picture });
+  }
   await page.pdf({
     path: request.pdfPath,
     width: `${request.viewport.width}px`,

package/src/core/playwright.ts

@@ -55,7 +55,10 @@ export type PagesRequest = {
   sheets?: SheetSpec[];
 };
 
-/** One page printed to `pdfPath`, a PDF page per slide. */
+/**
+ * One page printed to `pdfPath`, a PDF page per slide: each slide a picture at twice its size,
+ * with its text laid over it, unseen, to select and search.
+ */
 export type PdfRequest = {
   kind: "pdf";
   viewport: Viewport;