@liebstoeckel/thumbnails 0.3.5

package/src/capture.ts

@@ -0,0 +1,319 @@
+import { existsSync } from "node:fs";
+import { chromium, type Page } from "playwright-core";
+import {
+  CAPTURE_EVENT,
+  CAPTURE_FLAG,
+  CAPTURE_READY,
+  PRINT_FLAG,
+  PRINT_READY,
+  PRINT_SELECT_EVENT,
+  SLIDE_COUNT,
+} from "@liebstoeckel/engine/build/capture-protocol";
+import type { ThumbnailManifest } from "@liebstoeckel/engine/build/thumbnails";
+
+export type ThumbnailFormat = "webp" | "jpeg" | "png";
+
+/** Thumbnail capture options, the slide driver's options (ADR 0042) plus the
+ *  image-encoding policy specific to the thumbnail sink. Default width 640 ×
+ *  scale 2 = 1280×720, the native authoring canvas, so the overview is never
+ *  upscaled even on large/hi-dpi screens. Lower `width` to shrink a big deck. */
+export interface CaptureOptions extends RenderDriveOptions {
+  /** output image format (default "webp", ~half a JPEG, alpha, no extra deps) */
+  format?: ThumbnailFormat;
+  /** lossy quality 0-100 (ignored for png) */
+  quality?: number;
+}
+
+// Bun's built-in image codec (Bun.Image), not yet in @types/bun, so typed here.
+// Lets us transcode the browser's PNG screenshot to WebP natively (no `sharp`).
+interface BunImageChain {
+  webp(o?: { quality?: number }): BunImageChain;
+  jpeg(o?: { quality?: number }): BunImageChain;
+  png(): BunImageChain;
+  dataurl(): Promise<string>;
+}
+type BunImageCtor = new (data: Uint8Array | ArrayBuffer) => BunImageChain;
+const BunImage = (Bun as unknown as { Image: BunImageCtor }).Image;
+
+/** Transcode a PNG screenshot to a `data:` URI in the requested format. */
+function encodeDataUri(png: Uint8Array, format: ThumbnailFormat, quality: number): Promise<string> {
+  const img = new BunImage(png);
+  if (format === "png") return img.png().dataurl();
+  if (format === "jpeg") return img.jpeg({ quality }).dataurl();
+  return img.webp({ quality }).dataurl();
+}
+
+// Container-friendly flags. The full Chromium (not chrome-headless-shell, which
+// SIGSEGVs in some sandboxes) plus --single-process/--no-zygote launches cleanly
+// without a GPU or a user namespace.
+const DEFAULT_ARGS = [
+  "--no-sandbox",
+  "--disable-gpu",
+  "--disable-dev-shm-usage",
+  "--single-process",
+  "--no-zygote",
+];
+
+/** Resolve a Chromium binary: explicit → $LIEBSTOECKEL_CHROMIUM → Playwright's. */
+export function resolveChromium(opts: CaptureOptions = {}): string {
+  let candidate = opts.executablePath ?? process.env.LIEBSTOECKEL_CHROMIUM;
+  if (!candidate) {
+    try {
+      candidate = chromium.executablePath();
+    } catch {
+      candidate = undefined;
+    }
+  }
+  // executablePath() returns a computed path even when the browser isn't
+  // installed, verify the binary actually exists so hasChromium() stays honest
+  // (otherwise capture is attempted where no browser exists, e.g. CI).
+  if (candidate && existsSync(candidate)) return candidate;
+  throw new Error(
+    "No Chromium found for thumbnail capture. Run `bunx playwright install chromium`, " +
+      "or set LIEBSTOECKEL_CHROMIUM to a Chrome/Chromium binary.",
+  );
+}
+
+/** Whether a Chromium is available for capture (cheap, resolves a path, no launch). */
+export function hasChromium(opts: CaptureOptions = {}): boolean {
+  try {
+    resolveChromium(opts);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Decide whether to capture thumbnails: on by default, opt out with
+ *  `LIEBSTOECKEL_NO_THUMBS`, and skipped (not failed) when no Chromium is available.
+ *  Pure, `env`/`chromium` are injectable for tests. */
+export function thumbnailsEnabled(
+  env: Record<string, string | undefined> = process.env,
+  chromium = hasChromium(),
+): { enabled: boolean; reason?: string } {
+  if (env.LIEBSTOECKEL_NO_THUMBS) return { enabled: false, reason: "LIEBSTOECKEL_NO_THUMBS is set" };
+  if (!chromium) {
+    return { enabled: false, reason: "no Chromium (run `bunx playwright install chromium` or set LIEBSTOECKEL_CHROMIUM)" };
+  }
+  return { enabled: true };
+}
+
+/** Inject a static-mode flag as a classic (non-deferred) inline script so it runs
+ *  before the deck's deferred module bundle boots → Present renders the matching
+ *  static view (CaptureView / PrintView) instead of the live deck. */
+function injectFlag(html: string, global: string, value: unknown): string {
+  const tag = `<script>window.${global}=${JSON.stringify(value)};</script>`;
+  const head = html.match(/<head[^>]*>/i);
+  if (head) return html.replace(head[0], head[0] + tag);
+  const body = html.match(/<body[^>]*>/i);
+  if (body) return html.replace(body[0], body[0] + tag);
+  return tag + html;
+}
+
+const injectCaptureFlag = (html: string): string => injectFlag(html, CAPTURE_FLAG, { index: 0 });
+
+/** Options for the sink-agnostic slide driver (ADR 0042). The viewport/scale and
+ *  the per-slide wait policy live here; what the rendered frame *becomes* (a
+ *  data-URI thumbnail, a PNG file, a PDF page) is the caller's `onFrame`. */
+export interface RenderDriveOptions {
+  /** viewport width in CSS px (default 640). */
+  width?: number;
+  /** viewport height in CSS px (default 16:9 of width). */
+  height?: number;
+  /** device scale factor, renders at this multiple for crisp output (default 2). */
+  scale?: number;
+  /** explicit Chromium/Chrome binary; else $LIEBSTOECKEL_CHROMIUM, else Playwright's */
+  executablePath?: string;
+  /** override the launch flags (defaults are container-friendly) */
+  launchArgs?: string[];
+  /** extra settle time after a slide reports ready (late chart/font paints) */
+  settleMs?: number;
+  /** per-step timeout */
+  timeoutMs?: number;
+  /** 0-based slide indices to render, in order (default: every slide). Indices
+   *  outside `[0, count)` are skipped. The capture protocol can jump to any
+   *  index, so a subset is just a shorter list (ADR 0042 / 0043). */
+  indices?: number[];
+  /** Resolve the index list once the deck's slide count is known, for specs that
+   *  are open-ended (e.g. "from slide 3 to the end"). Overrides `indices`. */
+  selectIndices?(count: number): number[];
+  /** progress callback: (nth-rendered, total-to-render). */
+  onSlide?(index: number, total: number): void;
+}
+
+export interface RenderDriveResult {
+  /** total slides the deck reported (not necessarily how many were rendered). */
+  count: number;
+  /** intrinsic pixel size of each frame (`width*scale` × `height*scale`). */
+  w: number;
+  h: number;
+}
+
+/**
+ * The one headless drive loop (ADR 0042): launch a browser, load a built deck in
+ * capture mode, wait for fonts + the slide-count handshake, then step through the
+ * requested slide indices, calling `onFrame(index, page)` once each slide has
+ * painted and settled. Sink-agnostic: the callback decides what a frame becomes.
+ * Both `captureThumbnails` and `exportDeck` ride on this. The deck must render
+ * `Present`/`CaptureView`. **Loud**, throws if no Chromium / never enters capture.
+ */
+export async function renderDeckSlides(
+  html: string,
+  opts: RenderDriveOptions,
+  onFrame: (index: number, page: Page) => Promise<void>,
+): Promise<RenderDriveResult> {
+  const width = opts.width ?? 640;
+  const height = opts.height ?? Math.round((width * 9) / 16);
+  const scale = opts.scale ?? 2;
+  const settleMs = opts.settleMs ?? 250;
+  const timeout = opts.timeoutMs ?? 15000;
+
+  const browser = await chromium.launch({
+    headless: true,
+    executablePath: resolveChromium(opts),
+    args: opts.launchArgs ?? DEFAULT_ARGS,
+  });
+  try {
+    const page = await browser.newPage({ viewport: { width, height }, deviceScaleFactor: scale });
+    await page.setContent(injectCaptureFlag(html), { waitUntil: "load", timeout });
+    // fonts affect layout/metrics; wait once before stepping through slides
+    await page.evaluate(() => (document as unknown as { fonts?: { ready?: Promise<unknown> } }).fonts?.ready);
+    try {
+      await page.waitForFunction((key) => (window as unknown as Record<string, unknown>)[key] != null, SLIDE_COUNT, { timeout });
+    } catch {
+      throw new Error("deck never entered capture mode, ensure it renders <Present> (no __LIEBSTOECKEL_SLIDE_COUNT__)");
+    }
+    const count = (await page.evaluate((key) => (window as unknown as Record<string, unknown>)[key], SLIDE_COUNT)) as number;
+
+    // Resolve which slides to render: a count-aware resolver (open-ended specs)
+    // wins, else an explicit list, else every slide, always clamped to real slides.
+    const requested = opts.selectIndices
+      ? opts.selectIndices(count)
+      : (opts.indices ?? Array.from({ length: count }, (_, i) => i));
+    const indices = requested.filter((i) => Number.isInteger(i) && i >= 0 && i < count);
+
+    for (let n = 0; n < indices.length; n++) {
+      const i = indices[n]!;
+      opts.onSlide?.(n, indices.length);
+      // tell CaptureView to render slide i; it flips CAPTURE_READY to i when painted
+      await page.evaluate(
+        ([evt, idx]) => window.dispatchEvent(new CustomEvent(evt as string, { detail: idx })),
+        [CAPTURE_EVENT, i] as const,
+      );
+      await page.waitForFunction(
+        ([key, idx]) => (window as unknown as Record<string, unknown>)[key as string] === idx,
+        [CAPTURE_READY, i] as const,
+        { timeout },
+      );
+      if (settleMs > 0) await page.waitForTimeout(settleMs);
+      await onFrame(i, page);
+    }
+    return { count, w: Math.round(width * scale), h: Math.round(height * scale) };
+  } finally {
+    await browser.close();
+  }
+}
+
+/** Render a built single-file deck in a headless browser and screenshot each slide
+ *  as a data-URI (WebP by default, via Bun.Image). Returns a thumbnails manifest
+ *  (embed it with `embedThumbnails`). The deck must use `Present`/`CaptureView`. */
+export async function captureThumbnails(html: string, opts: CaptureOptions = {}): Promise<ThumbnailManifest> {
+  const format = opts.format ?? "webp";
+  const quality = opts.quality ?? 80;
+
+  const thumbs: Record<number, string> = {};
+  const { w, h } = await renderDeckSlides(html, opts, async (i, page) => {
+    // PNG (lossless) from the browser → transcode natively to the target format
+    const png = await page.screenshot({ type: "png" });
+    thumbs[i] = await encodeDataUri(png, format, quality);
+  });
+  return { v: 1, w, h, thumbs };
+}
+
+/** Options for the vector-PDF driver. The logical page is the authoring canvas
+ *  (STAGE_W×STAGE_H, 1280×720), selectable text, vector output, no raster. */
+export interface PrintDriveOptions {
+  /** logical page width in CSS px (default 1280, the authoring canvas). */
+  pageWidth?: number;
+  /** logical page height in CSS px (default 16:9 of pageWidth). */
+  pageHeight?: number;
+  /** explicit Chromium/Chrome binary; else $LIEBSTOECKEL_CHROMIUM, else Playwright's */
+  executablePath?: string;
+  /** override the launch flags (defaults are container-friendly) */
+  launchArgs?: string[];
+  /** settle time after the print selection paints (lets entrance motion finish).
+   *  More generous than capture's per-slide settle, every slide animates at once. */
+  settleMs?: number;
+  /** per-step timeout */
+  timeoutMs?: number;
+  /** resolve the 0-based slide indices once the count is known (open-ended specs). */
+  selectIndices?(count: number): number[];
+}
+
+export interface PrintDriveResult {
+  /** the produced PDF bytes. */
+  pdf: Uint8Array;
+  /** total slides the deck reported. */
+  count: number;
+  /** number of slides laid out (pages in the PDF). */
+  pages: number;
+}
+
+/**
+ * Render a built deck through `PrintView` and produce a **single, text-preserving**
+ * PDF (ADR 0043): every selected slide is stacked one-per-page in the DOM, so one
+ * `page.pdf()` yields a multi-page vector PDF with selectable text. `emulateMedia`
+ * keeps the deck's *screen* styles (not print CSS). **Loud**, throws if no Chromium.
+ */
+export async function printDeckPdf(html: string, opts: PrintDriveOptions = {}): Promise<PrintDriveResult> {
+  const pageWidth = opts.pageWidth ?? 1280;
+  const pageHeight = opts.pageHeight ?? Math.round((pageWidth * 9) / 16);
+  const settleMs = opts.settleMs ?? 700;
+  const timeout = opts.timeoutMs ?? 30000;
+
+  const browser = await chromium.launch({
+    headless: true,
+    executablePath: resolveChromium(opts),
+    args: opts.launchArgs ?? DEFAULT_ARGS,
+  });
+  try {
+    const page = await browser.newPage({ viewport: { width: pageWidth, height: pageHeight } });
+    // print with the deck's screen styling, not print-media CSS
+    await page.emulateMedia({ media: "screen" });
+    await page.setContent(injectFlag(html, PRINT_FLAG, {}), { waitUntil: "load", timeout });
+    await page.evaluate(() => (document as unknown as { fonts?: { ready?: Promise<unknown> } }).fonts?.ready);
+    try {
+      await page.waitForFunction((key) => (window as unknown as Record<string, unknown>)[key] != null, SLIDE_COUNT, { timeout });
+    } catch {
+      throw new Error("deck never entered print mode, ensure it renders <Present> (no __LIEBSTOECKEL_SLIDE_COUNT__)");
+    }
+    const count = (await page.evaluate((key) => (window as unknown as Record<string, unknown>)[key], SLIDE_COUNT)) as number;
+
+    const requested = opts.selectIndices ? opts.selectIndices(count) : Array.from({ length: count }, (_, i) => i);
+    const indices = requested.filter((i) => Number.isInteger(i) && i >= 0 && i < count);
+
+    // Hand PrintView the selection + a token it echoes into PRINT_READY once painted.
+    const token = 1;
+    await page.evaluate(
+      ([evt, payload]) => window.dispatchEvent(new CustomEvent(evt as string, { detail: payload })),
+      [PRINT_SELECT_EVENT, { indices, token }] as const,
+    );
+    await page.waitForFunction(
+      ([key, tok]) => (window as unknown as Record<string, unknown>)[key as string] === tok,
+      [PRINT_READY, token] as const,
+      { timeout },
+    );
+    if (settleMs > 0) await page.waitForTimeout(settleMs);
+
+    const pdf = await page.pdf({
+      width: `${pageWidth}px`,
+      height: `${pageHeight}px`,
+      printBackground: true,
+      margin: { top: "0", right: "0", bottom: "0", left: "0" },
+      preferCSSPageSize: false,
+    });
+    return { pdf: new Uint8Array(pdf), count, pages: indices.length };
+  } finally {
+    await browser.close();
+  }
+}

package/src/cli.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env bun
+import { defineCommand, runMain } from "citty";
+import { basename, join, resolve } from "node:path";
+import { mkdtempSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { addThumbnailsToFile, exportDeck } from "./index";
+import type { ExportFormat, ThumbnailFormat } from "./index";
+
+/** Parse a numeric flag value; undefined when absent or non-numeric (mirrors the
+ *  previous CLI's lenient handling). */
+function num(v: string | undefined): number | undefined {
+  const n = v == null ? NaN : Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/** Coerce a thumbnail format string, ignoring anything unrecognized. */
+function thumbFormat(v: string | undefined): ThumbnailFormat | undefined {
+  return v === "webp" || v === "jpeg" || v === "png" ? v : undefined;
+}
+
+export const thumbsCommand = defineCommand({
+  meta: {
+    name: "thumbs",
+    description: "(re)generate thumbnails for a built deck",
+  },
+  args: {
+    deck: {
+      type: "positional",
+      required: false,
+      description: "built deck .html",
+      valueHint: "deck.html",
+    },
+    format: { type: "string", description: "image format", valueHint: "webp|jpeg|png" },
+    width: { type: "string", description: "thumbnail width in px", valueHint: "640" },
+    quality: { type: "string", description: "image quality", valueHint: "80" },
+    scale: { type: "string", description: "device scale factor", valueHint: "2" },
+  },
+  async run({ args }) {
+    const file = args.deck;
+    if (!file) {
+      console.error("error: missing <deck.html>, the built deck to thumbnail");
+      process.exit(1);
+    }
+    const abs = resolve(file);
+    try {
+      if (!statSync(abs).isFile()) throw new Error("not a file");
+    } catch {
+      console.error(`cannot read deck: ${file}`);
+      process.exit(1);
+    }
+
+    process.stderr.write(`▶  capturing thumbnails for ${file}\n`);
+    try {
+      const manifest = await addThumbnailsToFile(abs, {
+        width: num(args.width),
+        quality: num(args.quality),
+        scale: num(args.scale),
+        format: thumbFormat(args.format),
+        onSlide: (i, n) => process.stderr.write(`\r   slide ${i + 1}/${n}   `),
+      });
+      process.stderr.write("\n");
+      const n = Object.keys(manifest.thumbs).length;
+      console.log(`✓ embedded ${n} thumbnail${n === 1 ? "" : "s"} (${manifest.w}×${manifest.h}) into ${file}`);
+    } catch (e) {
+      // Mirror `export`'s clean handling: a missing Chromium (the common case) should be a
+      // one-line actionable error, not an uncaught stack trace that leaks internal paths.
+      process.stderr.write("\n");
+      console.error(`✕ thumbnails failed: ${(e as Error).message}`);
+      process.exit(1);
+    }
+  },
+});
+
+/** Resolve the export format: an explicit `--format` wins, else infer from the
+ *  output extension, else PNG. */
+function inferFormat(explicit: string | undefined, out: string | undefined): ExportFormat {
+  if (explicit === "png" || explicit === "pdf") return explicit;
+  if (out && /\.pdf$/i.test(out)) return "pdf";
+  if (out && /\.png$/i.test(out)) return "png";
+  return "png";
+}
+
+/** A human-friendly base name for output files: a deck's `index.html` borrows its
+ *  directory's name, skipping a build dir (`dist`/`build`/`out`) so a deck built to
+ *  `foo/dist/index.html` is named "foo"; anything else uses its own filename stem. */
+function deckBaseName(target: string): string {
+  const stem = basename(target).replace(/\.html?$/i, "");
+  if (stem !== "index") return stem || "deck";
+  let dir = resolve(target, "..");
+  if (/^(dist|build|out)$/i.test(basename(dir))) dir = resolve(dir, "..");
+  return basename(dir) || "deck";
+}
+
+/** Resolve the export input to a built deck HTML string. A `.html` file is read
+ *  directly; a deck source directory is bundled to a temp dir first (thumbnails
+ *  skipped, export does its own rendering), so `export <dir>` works in one shot. */
+async function resolveDeckHtml(target: string): Promise<{ html: string; base: string }> {
+  const abs = resolve(target);
+  let isFile = false;
+  try {
+    isFile = statSync(abs).isFile();
+  } catch {
+    /* not a file */
+  }
+
+  if (isFile && /\.html?$/i.test(abs)) {
+    return { html: await Bun.file(abs).text(), base: deckBaseName(abs) };
+  }
+
+  // treat as a deck source directory → bundle it to a throwaway dir
+  const { bundleDeck } = await import("@liebstoeckel/engine/build");
+  const outdir = mkdtempSync(join(tmpdir(), "lst-export-"));
+  const prev = process.cwd();
+  process.chdir(abs);
+  try {
+    await bundleDeck({ entry: "./index.html", outdir, inlinePackage: false });
+  } finally {
+    process.chdir(prev);
+  }
+  return { html: await Bun.file(join(outdir, "index.html")).text(), base: basename(abs) };
+}
+
+export const exportCommand = defineCommand({
+  meta: {
+    name: "export",
+    description: "export slides to PNG or PDF",
+  },
+  args: {
+    deck: {
+      type: "positional",
+      required: false,
+      description: "deck .html or deck source dir (default: cwd)",
+      valueHint: "deck.html|deck-dir",
+    },
+    dir: { type: "string", description: "deck directory (alternative to the positional)", valueHint: "deck" },
+    format: { type: "string", description: "output format", valueHint: "png|pdf" },
+    slides: { type: "string", description: "slide selection, e.g. 1,3,5-7", valueHint: "1,3,5-7" },
+    out: {
+      type: "string",
+      alias: "o",
+      description: "PNG: output directory (one file per slide); PDF: the .pdf file",
+      valueHint: "path",
+    },
+    scale: { type: "string", description: "device scale factor", valueHint: "2" },
+    width: { type: "string", description: "render width in px", valueHint: "1280" },
+    quality: { type: "string", description: "image quality", valueHint: "92" },
+    raster: { type: "boolean", description: "PDF: rasterize pages instead of vector (selectable) text" },
+  },
+  async run({ args }) {
+    // Deck targeting (ADR 0050): a leading positional, else --dir, else cwd.
+    const target = args.deck ?? args.dir ?? ".";
+
+    const out = args.out;
+    const format = inferFormat(args.format, out);
+    // PNG writes one file per slide into a directory; a `.png`-looking `-o` is almost
+    // always a mistake (you'd get a directory literally named "foo.png"), warn (ticket 0030).
+    if (format === "png" && out && /\.png$/i.test(out)) {
+      process.stderr.write(
+        `⚠  --format png writes one file per slide into a DIRECTORY; "-o ${out}" will be a directory (created if needed), not a single PNG.\n`,
+      );
+    }
+    const slides = args.slides;
+    const width = num(args.width) ?? 1280;
+    const scale = num(args.scale);
+    const quality = num(args.quality);
+    // PDF text mode: vector (selectable text) by default; --raster forces image pages.
+    const pdfMode: "vector" | "raster" = args.raster ? "raster" : "vector";
+
+    let html: string;
+    let base: string;
+    try {
+      ({ html, base } = await resolveDeckHtml(target));
+    } catch (e) {
+      console.error(`✕ cannot prepare deck: ${(e as Error).message}`);
+      process.exit(1);
+      return;
+    }
+
+    const label = format === "pdf" ? `PDF (${pdfMode})` : "PNG";
+    process.stderr.write(`▶  exporting ${base} → ${label}\n`);
+    try {
+      const { written, pages, count } = await exportDeck(html, {
+        format,
+        slides,
+        width,
+        scale,
+        quality,
+        pdfMode,
+        baseName: base,
+        outDir: format === "png" ? out : undefined,
+        outFile: format === "pdf" ? out : undefined,
+        onSlide: (i, n) => process.stderr.write(`\r   slide ${i + 1}/${n}   `),
+      });
+      process.stderr.write("\n");
+      if (written.length === 0) {
+        console.error(`✕ no slides matched${slides ? ` "${slides}"` : ""} (deck has ${count} slide${count === 1 ? "" : "s"})`);
+        process.exit(1);
+      }
+      if (format === "pdf") {
+        console.log(`✓ exported ${pages} slide${pages === 1 ? "" : "s"} → ${written[0]}`);
+      } else {
+        console.log(`✓ exported ${pages} PNG${pages === 1 ? "" : "s"}:`);
+        for (const f of written) console.log(`   ${f}`);
+      }
+    } catch (e) {
+      console.error(`✕ export failed: ${(e as Error).message}`);
+      process.exit(1);
+    }
+  },
+});
+
+if (import.meta.main) void runMain(thumbsCommand);