@liebstoeckel/engine 0.3.5

package/src/QrOverlay.tsx

@@ -0,0 +1,133 @@
+import { useEffect, useState } from "react";
+import { AnimatePresence, motion } from "motion/react";
+import QRCode from "qrcode";
+
+/** Generate a QR data-URL for `url` while `enabled` (no work when closed). */
+function useQrDataUrl(url: string | undefined, enabled: boolean): string {
+  const [src, setSrc] = useState("");
+  useEffect(() => {
+    if (enabled && url) {
+      QRCode.toDataURL(url, { margin: 1, width: 420, color: { dark: "#0b0c10", light: "#ffffff" } })
+        .then(setSrc)
+        .catch(() => setSrc(""));
+    }
+  }, [enabled, url]);
+  return src;
+}
+
+/** Close on Escape while `open`. */
+function useEscToClose(open: boolean, onClose: () => void) {
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, onClose]);
+}
+
+export type QrItem = { url?: string; label: string; sub?: string };
+
+/** A labelled QR + the URL underneath. Renders nothing without a url. */
+function QrCard({ url, label, sub, enabled, size }: { url?: string; label: string; sub?: string; enabled: boolean; size: number }) {
+  const src = useQrDataUrl(url, enabled);
+  if (!url) return null;
+  return (
+    <div className="flex flex-col items-center gap-4">
+      {label && <div className="font-mono text-xs uppercase tracking-[0.3em] text-accent">{label}</div>}
+      {src && (
+        <motion.img
+          src={src}
+          alt={label || "QR code"}
+          width={size}
+          height={size}
+          className="rounded-2xl border border-border shadow-2xl"
+          initial={{ scale: 0.92 }}
+          animate={{ scale: 1 }}
+          transition={{ type: "spring", stiffness: 220, damping: 20 }}
+        />
+      )}
+      {sub && <div className="max-w-[18rem] break-all text-center font-mono text-[11px] text-muted">{sub}</div>}
+    </div>
+  );
+}
+
+/** The one QR-share surface: a full-screen, blurred, dismissable overlay (Esc /
+ *  backdrop tap / ✕) showing one or more labelled QRs. A single QR renders big
+ *  (the audience "scan to follow along"); several render as a row (presenter share).
+ *  `QrOverlay` and `PresenterShare` are thin wrappers so behaviour can't drift. */
+export function QrShare({ open, items, title, onClose }: { open: boolean; items: QrItem[]; title?: string; onClose: () => void }) {
+  useEscToClose(open, onClose);
+  const visible = items.filter((i) => i.url);
+  const big = visible.length <= 1;
+  return (
+    <AnimatePresence>
+      {open && visible.length > 0 && (
+        <motion.div
+          className="fixed inset-0 z-50 flex flex-col items-center justify-center gap-10 overflow-y-auto p-6 backdrop-blur-2xl"
+          style={{ background: "color-mix(in srgb, var(--brand-bg) 80%, transparent)" }}
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          exit={{ opacity: 0 }}
+          onClick={onClose}
+        >
+          <button
+            onClick={onClose}
+            aria-label="Close"
+            className="fixed right-4 flex h-10 w-10 items-center justify-center rounded-full border border-border text-muted transition hover:border-text hover:text-text"
+            style={{ top: "calc(1rem + env(safe-area-inset-top))" }}
+          >
+            ✕
+          </button>
+          {title && (
+            <div className="flex items-center gap-3 font-mono text-sm uppercase tracking-[0.35em] text-accent">
+              <span className="h-px w-8 bg-accent" />
+              {title}
+              <span className="h-px w-8 bg-accent" />
+            </div>
+          )}
+          <div className="flex flex-wrap items-start justify-center gap-14" onClick={(e) => e.stopPropagation()}>
+            {visible.map((it) => (
+              <QrCard key={it.label} url={it.url} label={it.label} sub={it.sub} enabled={open} size={big ? 300 : 240} />
+            ))}
+          </div>
+          <div className="font-mono text-xs text-muted">tap outside, ✕, or press Q / Esc to close</div>
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}
+
+/** Audience: a single big "follow along" QR (the read-only link). Toggled with Q in
+ *  the Deck during a live session. */
+export function QrOverlay({ open, url, onClose }: { open: boolean; url?: string; onClose: () => void }) {
+  return <QrShare open={open} onClose={onClose} items={[{ url, label: "Scan to follow along", sub: url }]} />;
+}
+
+/** Presenter: BOTH links, "Follow along" (read-only viewer) and "Drive from your
+ *  phone" (presenter; scanning joins as a second driver). Q / header button in the
+ *  presenter view. (DESIGN §QR & handoff.) */
+export function PresenterShare({
+  open,
+  viewerUrl,
+  presenterUrl,
+  onClose,
+}: {
+  open: boolean;
+  viewerUrl?: string;
+  presenterUrl?: string;
+  onClose: () => void;
+}) {
+  return (
+    <QrShare
+      open={open}
+      onClose={onClose}
+      title="share this session"
+      items={[
+        { url: viewerUrl, label: "Follow along", sub: viewerUrl },
+        { url: presenterUrl, label: "Drive from your phone", sub: presenterUrl },
+      ]}
+    />
+  );
+}

package/src/Stage.tsx

@@ -0,0 +1,82 @@
+import { createContext, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { motion } from "motion/react";
+import { Atmosphere } from "@liebstoeckel/components";
+
+// Logical canvas. Everything is authored at this size and scaled to fit, so the
+// audience view and presenter thumbnails are pixel-identical (just different scale).
+export const STAGE_W = 1280;
+export const STAGE_H = 720;
+
+/** The factor the canvas is scaled by to fit its parent (1 = unscaled). Consumers
+ *  (e.g. plugins) read it to decide when inline controls are too small to tap. */
+export const StageScaleContext = createContext(1);
+
+/** Fits a fixed STAGE_W×STAGE_H canvas into its parent, centered + letterboxed.
+ *  The fit transform is expressed as **Motion values**, `scale` + a centering
+ *  `x`/`y` translate, about a **top-left** origin, not a CSS `transform` string and
+ *  not a center `transform-origin`. Motion's layout-projection tree only accounts
+ *  for transforms it owns and assumes a top-left origin, so this is what keeps
+ *  `layoutId`/`layout` morphs (`Magic`, `CodeMagic`) correct under the scaled stage
+ *  (Motion #3356/#874). The outer div must be a positioned containing block for the
+ *  absolute canvas (all consumers pass `absolute`/`fixed inset-0`). */
+export function ScaledStage({ children, className }: { children: ReactNode; className?: string }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [fit, setFit] = useState({ scale: 0, x: 0, y: 0 });
+
+  useLayoutEffect(() => {
+    const el = ref.current!;
+    const measure = () => {
+      const { width, height } = el.getBoundingClientRect();
+      const scale = Math.min(width / STAGE_W, height / STAGE_H);
+      setFit({ scale, x: (width - STAGE_W * scale) / 2, y: (height - STAGE_H * scale) / 2 });
+    };
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  return (
+    <div ref={ref} className={`overflow-hidden bg-bg ${className ?? ""}`}>
+      <StageScaleContext.Provider value={fit.scale || 1}>
+        <motion.div
+          style={{
+            position: "absolute",
+            top: 0,
+            left: 0,
+            width: STAGE_W,
+            height: STAGE_H,
+            originX: 0,
+            originY: 0,
+            scale: fit.scale || 0.0001,
+            x: fit.x,
+            y: fit.y,
+            visibility: fit.scale ? "visible" : "hidden",
+          }}
+        >
+          {children}
+        </motion.div>
+      </StageScaleContext.Provider>
+    </div>
+  );
+}
+
+/** The visual frame of a slide: brand background + atmosphere + a padded content
+ *  area. Slides can break out with absolute positioning for full-bleed charts.
+ *  `still` renders the motionless atmosphere (thumbnails / capture). */
+export function SlideFrame({
+  children,
+  atmosphere = true,
+  still = false,
+}: {
+  children: ReactNode;
+  atmosphere?: boolean;
+  still?: boolean;
+}) {
+  return (
+    <div className="absolute inset-0 overflow-hidden bg-bg">
+      {atmosphere && <Atmosphere still={still} />}
+      <div className="absolute inset-0 flex flex-col justify-center px-24 py-20">{children}</div>
+    </div>
+  );
+}

package/src/Thumb.tsx

@@ -0,0 +1,36 @@
+import type { ComponentType } from "react";
+import { MDXProvider } from "@mdx-js/react";
+import { mdxComponents } from "@liebstoeckel/components";
+import { ScaledStage, SlideFrame } from "./Stage";
+import { PersistentProvider } from "./PersistentLayer";
+
+/** A scaled, non-interactive thumbnail of a slide (overview + presenter).
+ *
+ *  Prefers a pre-rendered image (`src`, from the build-time thumbnails manifest), *  a cheap `<img>` instead of a live React subtree. With no `src` it falls back to
+ *  rendering the slide **statically** (atmosphere frozen, no persistent layer);
+ *  Slots register harmlessly. */
+export function DeckThumb({ Component, src, alt }: { Component?: ComponentType; src?: string; alt?: string }) {
+  if (src) {
+    return (
+      <img
+        src={src}
+        alt={alt ?? ""}
+        loading="lazy"
+        decoding="async"
+        draggable={false}
+        className="h-full w-full object-cover"
+      />
+    );
+  }
+  return (
+    <div className="relative h-full w-full overflow-hidden bg-bg">
+      <MDXProvider components={mdxComponents}>
+        <PersistentProvider>
+          <ScaledStage className="absolute inset-0">
+            <SlideFrame still>{Component ? <Component /> : null}</SlideFrame>
+          </ScaledStage>
+        </PersistentProvider>
+      </MDXProvider>
+    </div>
+  );
+}

package/src/build/buildDeck.ts

@@ -0,0 +1,321 @@
+import { rm } from "node:fs/promises";
+import { basename, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import tailwind from "bun-plugin-tailwind";
+import { discoverFromPackageJson } from "@liebstoeckel/plugin-sdk/discovery";
+import {
+  embedManifest,
+  encodeServerBundle,
+  type PluginManifest,
+  type PluginManifestEntry,
+} from "@liebstoeckel/plugin-sdk/manifest";
+import mdx from "./mdx-plugin";
+import visxEsmInterop from "./visx-esm-plugin";
+import {
+  createLicenseCollector,
+  renderNotices,
+  embedLicenses,
+  formatFirstPartyConflicts,
+  type LicenseReport,
+} from "./licenses";
+
+// The single-copy guard primitives are part of the public build surface (the e2e
+// upgrade tier reduces over a real installed tree with them; ADR 0093).
+export { firstPartyVersionConflicts, formatFirstPartyConflicts, type FirstPartyConflict } from "./licenses";
+
+/** The plugins every deck build runs (Tailwind CSS gen, MDX compile, visx ESM
+ *  interop). Shared so the license collector and any collect-only build resolve
+ *  the exact same module graph as a real build. */
+const DECK_PLUGINS = [tailwind, mdx, visxEsmInterop];
+
+/** Default first-party notice embedded alongside the third-party block, the
+ *  MPL-2.0 line + public source pointer that MPL §3.2(b)/§3.4 require to travel
+ *  with the inlined engine code. */
+const DEFAULT_SELF_NOTICE =
+  "This presentation embeds the liebstoeckel presentation engine, licensed under\n" +
+  "the Mozilla Public License 2.0. Source code for the covered files is available\n" +
+  "at https://github.com/liebstoeckel/liebstoeckel, you may obtain it at no charge.";
+
+/** Bundle a plugin's server entry into a self-contained, base64-encoded ESM module
+ *  (target:"bun"). It externalizes nothing host-specific because the host injects
+ *  `ctx`, so it rehydrates with no node_modules resolution. */
+export async function buildServerBundle(entry: string): Promise<string> {
+  const built = await Bun.build({ entrypoints: [entry], target: "bun", format: "esm", minify: true });
+  if (!built.success) {
+    for (const log of built.logs) console.error(log);
+    throw new Error(`Failed to build server plugin bundle: ${entry}`);
+  }
+  return encodeServerBundle(await built.outputs[0]!.text());
+}
+
+/** Discover the deck's plugins (from package.json deps) and build a manifest:
+ *  every plugin listed; server entries embedded as base64. */
+export async function buildPluginManifest(pkgJsonPath: string): Promise<PluginManifest | null> {
+  let plugins;
+  try {
+    plugins = await discoverFromPackageJson(pkgJsonPath);
+  } catch {
+    return null; // no package.json / unreadable → no plugins
+  }
+  if (plugins.length === 0) return null;
+
+  const entries: PluginManifestEntry[] = [];
+  for (const p of plugins) {
+    const server = p.serverEntry ? await buildServerBundle(p.serverEntry) : undefined;
+    entries.push({
+      name: p.name,
+      version: p.version,
+      hasServer: !!server,
+      server,
+      id: p.id,
+      audienceWrites: p.audienceWrites,
+    });
+  }
+  return { v: 1, plugins: entries };
+}
+
+/** The deck's own package name (so the license report can exclude it, a deck never
+ *  lists itself). Best-effort: a missing/unreadable package.json just yields undefined. */
+async function readPkgName(pkgJsonPath: string): Promise<string | undefined> {
+  try {
+    return (await Bun.file(pkgJsonPath).json()).name;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Bun inlines the JS bundle as `<script type="module">…</script>`, but does NOT escape
+ *  `</script>` sequences that occur inside JS string literals (e.g. a deck embedding HTML
+ *  through an iframe `srcdoc`). The HTML parser would close the inline script at the first
+ *  such `</script>`, dumping the rest of the bundle as text. Escape every `</script` →
+ *  `<\/script` inside the module body (a no-op for the JS string value, but no longer a
+ *  tag terminator). Runs on Bun's fresh output, where the module bundle is the document's
+ *  last element, so its real terminator is the final `</script>`. */
+export function escapeInlineModuleScript(html: string): string {
+  const open = '<script type="module">';
+  const start = html.indexOf(open);
+  if (start < 0) return html;
+  const contentStart = start + open.length;
+  const close = html.lastIndexOf("</script>");
+  if (close <= contentStart) return html;
+  const body = html.slice(contentStart, close).replace(/<\/script/gi, "<\\/script");
+  return html.slice(0, contentStart) + body + html.slice(close);
+}
+
+/** Identifies the tool that drove the build (e.g. the CLI), stamped alongside the
+ *  engine version so a built deck records what produced it. */
+export interface Generator {
+  name: string;
+  version: string;
+}
+
+const ENGINE_PKG = fileURLToPath(new URL("../../package.json", import.meta.url));
+
+/** The engine's own version, read from its package.json. Best-effort: a build must
+ *  never fail because a version string couldn't be read. */
+async function engineVersion(): Promise<string> {
+  try {
+    return ((await Bun.file(ENGINE_PKG).json()) as { version?: string }).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/** Stamp the build's provenance into the document head: a human-readable comment
+ *  right after the doctype (the first thing in "view source") and a standard
+ *  `<meta name="generator">` that tooling can parse. Records the engine version
+ *  (always) and the invoking tool's version (e.g. the CLI) when the caller passes
+ *  one. Versions only, no timestamp, so the same deck still builds to the same
+ *  bytes (the source-package embed is byte-deterministic). */
+export function stampGenerator(html: string, parts: { engine: string; generator?: Generator }): string {
+  const tools = [`engine ${parts.engine}`];
+  if (parts.generator) tools.push(`${parts.generator.name} ${parts.generator.version}`);
+  const summary = `liebstoeckel ${tools.join(", ")}`;
+  return html
+    .replace(/<!doctype html>/i, (m) => `${m}\n<!-- Generated by ${summary} · https://liebstoeckel.app -->`)
+    .replace(/<head[^>]*>/i, (m) => `${m}\n    <meta name="generator" content="${summary}" />`);
+}
+
+// Bundles a deck into a single self-contained .html, the browser-free build
+// primitive (no Chromium). Plugins (Tailwind, MDX) only run via the Bun.build()
+// JS API, NOT the `bun build` CLI. `compile:true` + target:"browser" inline
+// JS/CSS and base64 the assets. Verified on Bun 1.3.
+//
+// For the batteries-included default (this + slide thumbnails) use `buildDeck`
+// from `@liebstoeckel/thumbnails/build`, which wraps this. Kept here, dependency-
+// free, so engine never pulls in the headless-browser capturer (playwright-core).
+export async function bundleDeck({
+  entry = "./index.html",
+  outdir = "./dist",
+  outfile = "index.html",
+  minify = true,
+  pkgJson = "./package.json",
+  inlinePackage = true,
+  inlineLicenses = true,
+  selfNotice = DEFAULT_SELF_NOTICE,
+  allowSecret = false,
+  generator,
+}: {
+  entry?: string;
+  outdir?: string;
+  /** Final artifact name within `outdir` (default `index.html`; the user-facing
+   *  `buildDeck` wrapper passes the deck slug, e.g. `poll-demo.html`, ADR 0068). */
+  outfile?: string;
+  minify?: boolean;
+  pkgJson?: string;
+  /** Embed the deck's own source as a recoverable package so the .html is ejectable (ADR 0039). */
+  inlinePackage?: boolean;
+  /** Embed a THIRD-PARTY-NOTICES block computed from the bundle's real module graph.
+   *  Minify strips license comments, so we re-add the required notices. */
+  inlineLicenses?: boolean;
+  /** First-party notice prepended to the notices block (default: the MPL line). */
+  selfNotice?: string;
+  /** Force the source-embed past its secret gate (loud, explicit). */
+  allowSecret?: boolean;
+  /** The tool driving the build (e.g. the CLI), recorded in the generator stamp
+   *  next to the engine version. Omit when the engine builds on its own behalf. */
+  generator?: Generator;
+} = {}) {
+  // The collector always runs (a pure onLoad observer): besides licenses it backs the
+  // single-copy guard below, which must hold whether or not we embed notices.
+  const licenses = createLicenseCollector({ selfName: await readPkgName(pkgJson) });
+  const result = await Bun.build({
+    entrypoints: [entry],
+    outdir,
+    minify,
+    target: "browser",
+    compile: true,
+    plugins: [...DECK_PLUGINS, licenses.plugin],
+  });
+
+  if (!result.success) {
+    for (const log of result.logs) console.error(log);
+    throw new Error("Deck build failed");
+  }
+
+  // Fail loud if the bundle pulled two versions of a liebstoeckel package — a deck is
+  // one inlined .html, so mixed framework versions ship duplicate, incompatible copies.
+  const conflicts = licenses.conflicts();
+  if (conflicts.length) throw new Error(formatFirstPartyConflicts(conflicts));
+
+  // Escape `</script>` inside the inlined bundle, then embed the plugin manifest
+  // (incl. base64 server bundles) into the single file. Bun.build names its output
+  // after the entry basename (`index.html`); we post-process that and ship it under
+  // `outfile` (the deck slug for the user-facing build, ADR 0068).
+  const built = join(outdir, basename(entry));
+  const outHtml = join(outdir, outfile);
+  let html = escapeInlineModuleScript(await Bun.file(built).text());
+  const manifest = await buildPluginManifest(pkgJson);
+  if (manifest) html = embedManifest(html, manifest);
+
+  // Re-add the third-party license notices that minify stripped, computed
+  // from the modules this build actually bundled, so it tracks font/lib swaps.
+  if (inlineLicenses) {
+    const report = licenses.report();
+    html = embedLicenses(html, renderNotices(report, { selfNotice }));
+    const flagged = report.flagged.length ? `, ⚠ ${report.flagged.length} non-standard license(s)` : "";
+    console.log(`✓ embedded license notices (${report.packages.length} third-party packages)${flagged}`);
+  }
+
+  // Embed the deck's own source so the compiled .html ejects back to an editable project.
+  if (inlinePackage) {
+    const { collectDeckTarball, embedSource } = await import("./source-package");
+    const { zstd, files } = await collectDeckTarball(dirname(pkgJson), { allowSecret });
+    html = embedSource(html, zstd);
+    console.log(`✓ embedded source package (${files.length} files, ${(zstd.length / 1024).toFixed(1)}KB)`);
+  }
+
+  // Stamp the build's provenance (engine + invoking-tool versions) into the head.
+  html = stampGenerator(html, { engine: await engineVersion(), generator });
+
+  await Bun.write(outHtml, html);
+  // Drop Bun's `index.html` emit when shipping under a different slug name.
+  if (built !== outHtml) await rm(built, { force: true });
+
+  return result;
+}
+
+/** Resolve a deck's third-party license report WITHOUT emitting an artifact, runs
+ *  the same plugin set as a real build so the module graph matches, then discards
+ *  the output. Backs `liebstoeckel licenses` over a deck directory. */
+export async function collectDeckLicenses({
+  entry = "./index.html",
+  pkgJson = "./package.json",
+}: { entry?: string; pkgJson?: string } = {}): Promise<LicenseReport> {
+  const licenses = createLicenseCollector({ selfName: await readPkgName(pkgJson) });
+  const result = await Bun.build({
+    entrypoints: [entry],
+    minify: false,
+    target: "browser",
+    plugins: [...DECK_PLUGINS, licenses.plugin],
+  });
+  if (!result.success) {
+    for (const log of result.logs) console.error(log);
+    throw new Error("Deck build failed");
+  }
+  return licenses.report();
+}
+
+/** A single build diagnostic, shaped for machine consumption (ADR 0045). */
+export interface DeckDiagnostic {
+  level: string;
+  message: string;
+  file?: string;
+  line?: number;
+  column?: number;
+}
+
+function toDiagnostic(log: unknown): DeckDiagnostic {
+  if (typeof log === "string") return { level: "error", message: log };
+  const l = log as { level?: string; message?: string; position?: { file?: string; line?: number; column?: number } | null };
+  const pos = l?.position ?? undefined;
+  const pos1 = (n?: number) => (typeof n === "number" && n > 0 ? n : undefined);
+  return {
+    level: l?.level ?? "error",
+    message: l?.message ?? String(log),
+    file: pos?.file || undefined,
+    line: pos1(pos?.line),
+    column: pos1(pos?.column),
+  };
+}
+
+/**
+ * Validate that a deck **bundles**, resolves, transforms (MDX/Tailwind), and the
+ * visx ESM-interop holds, without writing any artifact or capturing thumbnails
+ * (ADR 0045). Runs the same plugin pipeline as `bundleDeck` with `throw: false` and
+ * returns structured diagnostics for an agent's check → fix loop. It does **not**
+ * type-check (Bun.build doesn't); it answers "does this deck build?".
+ */
+export async function checkDeck({
+  entry = "./index.html",
+  pkgJson = "./package.json",
+}: { entry?: string; pkgJson?: string } = {}): Promise<{
+  ok: boolean;
+  diagnostics: DeckDiagnostic[];
+}> {
+  try {
+    const licenses = createLicenseCollector({ selfName: await readPkgName(pkgJson) });
+    const result = await Bun.build({
+      entrypoints: [entry],
+      target: "browser",
+      plugins: [...DECK_PLUGINS, licenses.plugin],
+      throw: false,
+    });
+    const diagnostics = result.logs.map(toDiagnostic);
+    let ok = result.success;
+    // Only meaningful on a graph that fully resolved; surface a duplicate liebstoeckel
+    // version as a loud diagnostic (ADR: the consumption-side single-copy guard).
+    if (ok) {
+      const conflicts = licenses.conflicts();
+      if (conflicts.length) {
+        ok = false;
+        diagnostics.push({ level: "error", message: formatFirstPartyConflicts(conflicts) });
+      }
+    }
+    return { ok, diagnostics };
+  } catch (err) {
+    // resolution / plugin failures can still throw (e.g. AggregateError)
+    const errs = err instanceof AggregateError ? err.errors : [err];
+    return { ok: false, diagnostics: errs.map(toDiagnostic) };
+  }
+}

package/src/build/capture-protocol.ts

@@ -0,0 +1,55 @@
+// The contract between the engine's CaptureView / PrintView and the
+// @liebstoeckel/thumbnails capturer (a headless browser). The capturer sets a flag
+// *before* the deck boots (so Present renders a static view, not the live Deck).
+//
+// Two static modes share this file:
+//  • Capture (thumbnails / PNG export): CAPTURE_FLAG → CaptureView. Reads
+//    SLIDE_COUNT, then for each slide dispatches CAPTURE_EVENT(index) and waits
+//    until CAPTURE_READY === index before screenshotting (one slide at a time).
+//  • Print (vector PDF export): PRINT_FLAG → PrintView, which stacks every slide
+//    onto its own print page so one `page.pdf()` yields a text-preserving,
+//    multi-page PDF. Reads SLIDE_COUNT, dispatches PRINT_SELECT_EVENT({indices,
+//    token}) to pick the slides, then waits until PRINT_READY === token.
+//
+// Pure (no React / DOM types beyond globalThis) so the capturer package can import
+// the names without pulling the engine's React tree.
+
+export const CAPTURE_FLAG = "__LIEBSTOECKEL_CAPTURE__";
+export const SLIDE_COUNT = "__LIEBSTOECKEL_SLIDE_COUNT__";
+export const CAPTURE_READY = "__LIEBSTOECKEL_CAPTURE_READY__";
+export const CAPTURE_EVENT = "liebstoeckel:capture";
+
+export const PRINT_FLAG = "__LIEBSTOECKEL_PRINT__";
+export const PRINT_READY = "__LIEBSTOECKEL_PRINT_READY__";
+export const PRINT_SELECT_EVENT = "liebstoeckel:print-select";
+
+export interface CaptureFlag {
+  /** slide to render first (the capturer then steps through the rest) */
+  index?: number;
+}
+
+export interface PrintFlag {
+  /** 0-based slides to lay out (default: every slide). The driver usually leaves
+   *  this empty and selects via PRINT_SELECT_EVENT once SLIDE_COUNT is known. */
+  indices?: number[];
+}
+
+/** The payload of a PRINT_SELECT_EVENT: which slides to render, plus a token the
+ *  view echoes into PRINT_READY once that selection has painted (so the driver
+ *  waits for the right frame, not a stale one). */
+export interface PrintSelect {
+  indices: number[];
+  token: number;
+}
+
+/** Read the capture request the capturer injects. Absent → normal deck. */
+export function captureRequest(): CaptureFlag | null {
+  const g = globalThis as Record<string, unknown>;
+  return (g[CAPTURE_FLAG] as CaptureFlag | undefined) ?? null;
+}
+
+/** Read the print request the exporter injects. Absent → not a print render. */
+export function printRequest(): PrintFlag | null {
+  const g = globalThis as Record<string, unknown>;
+  return (g[PRINT_FLAG] as PrintFlag | undefined) ?? null;
+}