@hajimism/dek 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [0.3.1](https://github.com/hajimism/dek/compare/v0.3.0...v0.3.1) (2026-10-08)
+
+
+### Performance
+
+* **build:** leave the dev server's line out of built files ([1e74ba0](https://github.com/hajimism/dek/commit/1e74ba0fb2512eeecf8ca4ba13a747374b1a651c))
+* **build:** leave the dev server's line out of built files ([93bb4fc](https://github.com/hajimism/dek/commit/93bb4fc56105940cc5b19dc86f890dc9246df850))
+
+## [0.3.0](https://github.com/hajimism/dek/compare/v0.2.2...v0.3.0) (2026-10-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* a DEK_ variable kept in a project's .env, such as DEK_VOICE_URL, no longer applies; set it in the shell, or use `engine` in voice.toml.
+* reading a private ref needs GITHUB_TOKEN or GH_TOKEN; being signed in to gh is not enough, and DEK_GH is gone. `GITHUB_TOKEN=$(gh auth token) dekc ref ...` does what dek did before. No token is sent to DEK_GITHUB_API.
+
+### Bug Fixes
+
+* draw pages in Chromium's sandbox with the network off ([550cc3a](https://github.com/hajimism/dek/commit/550cc3ab1c44005d4ef89420d3bb92a44a7da3a9))
+* ignore what the .env.*.local files set, and NODE_TLS_REJECT_UNAUTHORIZED from any .env ([da02b7c](https://github.com/hajimism/dek/commit/da02b7c4375b41ddd9ea2d879714950e5017cbc2))
+* keep a ref's title to one line of AGENTS.md ([c1b0b60](https://github.com/hajimism/dek/commit/c1b0b609a8710985c32988cff19b8cb65a0e6bc6))
+* run dekc, and every bun it starts, without the working directory's bunfig.toml ([0418909](https://github.com/hajimism/dek/commit/04189098b6975ba37506f039e865388205c5817b))
+* ship tsconfig.json, so a project's paths cannot take over dek's imports ([3eed8f0](https://github.com/hajimism/dek/commit/3eed8f0961a232a48be1cb06cd08dc03e121d026))
+* stop asking gh for a token, and send one only to api.github.com ([62c896b](https://github.com/hajimism/dek/commit/62c896ba1b69424e5426534040a087a2d42bef1a))
+* take DEK_ variables only from the environment, never from a .env ([7f4629b](https://github.com/hajimism/dek/commit/7f4629b3099e23a4c46b6261fa95627659fbfe51))
+
+
+### Documentation
+
+* **adr:** number the GHSA-mj6q-67q7-q923 decision after the ones on main ([4a888b0](https://github.com/hajimism/dek/commit/4a888b06594c188bf0efa88fb9111f48f70263e9))
+* **adr:** take GitHub tokens and DEK_ variables only from what the user sets ([c07fa4c](https://github.com/hajimism/dek/commit/c07fa4ceb7e1df69fb184ee8955f1819ee58a069))
+* record the ref title and shot fixes in ADR 12 and the architecture guide ([a6bfb93](https://github.com/hajimism/dek/commit/a6bfb9383c9c614c5c39f0e2f6817db24dc83e06))
+* say what a project cannot set for the Bun that runs dek, and what stays out of scope ([632efbb](https://github.com/hajimism/dek/commit/632efbbe4697a2175bf9cd0c8b5db77e53dbfa17))
+
 ## [0.2.2](https://github.com/hajimism/dek/compare/v0.2.1...v0.2.2) (2026-10-06)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",
@@ -11,6 +11,7 @@
   "files": [
     "src",
     "skills",
+    "tsconfig.json",
     "LICENSE",
     "README.md",
     "README.ja.md",

package/src/cli/env-file.ts

@@ -0,0 +1,78 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ansi, shouldColor, terminalSafe } from "./tty.ts";
+
+/**
+ * The files Bun may read into process.env from the working directory before dek starts: `.env`,
+ * `.env.local`, and the two for NODE_ENV, plain and `.local`. All of them are read whatever
+ * NODE_ENV is, so a change in which ones Bun picks cannot let a variable through.
+ */
+const ENV_FILES = [
+  ".env",
+  ".env.local",
+  ...["development", "production", "test"].flatMap((mode) => [
+    `.env.${mode}`,
+    `.env.${mode}.local`,
+  ]),
+];
+
+/**
+ * Every name dek takes only from the environment that a file holds, however the line around it is
+ * written: `K=v`, `export K=v`, `K: v`. Besides DEK_ variables, NODE_TLS_REJECT_UNAUTHORIZED: Bun
+ * reads it on each request, and with it a proxy that a `.env` named could read the token `dekc ref`
+ * sends. Other variables Bun acts on, such as HTTPS_PROXY, take effect before dek starts, and
+ * deleting them changes nothing.
+ */
+const NAME_RE = /DEK_[A-Z0-9_]*|NODE_TLS_REJECT_UNAUTHORIZED/gi;
+
+/**
+ * Takes out of `env` every variable in NAME_RE that a `.env` file in `cwd` may have set, and
+ * returns their names. Bun loads those files before dek runs, so a repository someone else wrote
+ * could otherwise choose the programs dek runs and the host `dekc ref` calls. These variables come
+ * only from the environment dek was started in. Under `--no-env-file`, which the dekc bin passes,
+ * Bun loaded nothing, so every one there is the user's own.
+ */
+export function dropEnvFileVariables(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  execArgv: readonly string[] = process.execArgv,
+): string[] {
+  if (execArgv.includes("--no-env-file")) {
+    return [];
+  }
+  const names = new Set<string>();
+  for (const file of ENV_FILES) {
+    let text: string;
+    try {
+      text = readFileSync(join(cwd, file), "utf8");
+    } catch {
+      continue;
+    }
+    for (const [name] of text.matchAll(NAME_RE)) {
+      names.add(name.toUpperCase());
+    }
+  }
+  const dropped = [...names].filter((name) => env[name] !== undefined).sort();
+  for (const name of dropped) {
+    delete env[name];
+  }
+  return dropped;
+}
+
+/** What dek says on stderr about the variables `dropEnvFileVariables` took out. */
+export function envFileWarning(names: readonly string[], color = false): string {
+  const c = ansi(color);
+  const list = names.join(", ");
+  return [
+    `${c.yellow("warning:")} ignored ${list}: a .env file in this directory sets it, and dek takes it only from the environment`,
+    `  ${c.yellow("help:")} set it in the shell that runs dekc instead`,
+  ].join("\n");
+}
+
+/** The bin's first step: drop what a `.env` set, and say so. */
+export function ignoreEnvFileVariables(cwd: string): void {
+  const dropped = dropEnvFileVariables(cwd);
+  if (dropped.length > 0) {
+    process.stderr.write(`${terminalSafe(envFileWarning(dropped, shouldColor(process.stderr)))}\n`);
+  }
+}

package/src/cli.ts

@@ -1,4 +1,8 @@
-#!/usr/bin/env bun
+#!/usr/bin/env -S bun --no-env-file --config=/dev/null
+import { ignoreEnvFileVariables } from "./cli/env-file.ts";
 import { main } from "./cli/main.ts";
 
+// `bun ./node_modules/.bin/dekc` skips the line above and loads `.env` anyway. It reads
+// `bunfig.toml` too, and nothing here can undo a preload that has already run.
+ignoreEnvFileVariables(process.cwd());
 await main(Bun.argv.slice(2), process.cwd());

package/src/core/document.ts

@@ -142,7 +142,6 @@ export function renderDeckDocument(
     bodyAttrs: `${presenterOpen ? ' class="is-presenter"' : ""}${pageConfigAttrs({
       mode,
       deck: deck.name,
-      live,
       ...(liveToken ? { liveToken } : {}),
     })}`,
     body: `${progress}

package/src/core/github.ts

@@ -3,7 +3,7 @@ import { DekError } from "./error.ts";
 /**
  * The two GitHub calls dekc ref needs: pin a rev to a commit, and download
  * that commit. DEK_GITHUB_API points them elsewhere, the way DEK_VOICE_URL
- * does for the voice engine.
+ * does for the voice engine, but a token only ever goes here.
  */
 const DEFAULT_API = "https://api.github.com";
 
@@ -16,9 +16,6 @@ const COMMIT_TIMEOUT_MS = 30 * 1000;
 /** A tarball near the size cap on a slow line still fits well inside this. */
 const TARBALL_TIMEOUT_MS = 10 * 60 * 1000;
 
-const SIGN_IN_HINT =
-  "if the repository is private, set GITHUB_TOKEN or run `gh auth login`, then run the command again";
-
 export type GithubOptions = {
   /** Covers the whole call, from connecting to the last byte of the body. */
   timeoutMs?: number;
@@ -32,22 +29,27 @@ function apiBase(): string {
   return (process.env.DEK_GITHUB_API ?? DEFAULT_API).replace(/\/+$/, "");
 }
 
-/** GITHUB_TOKEN, else what `gh auth token` prints, else nothing: public repositories need no token. */
-function token(): string | undefined {
-  const fromEnv = process.env.GITHUB_TOKEN?.trim();
-  if (fromEnv) {
-    return fromEnv;
-  }
-  try {
-    const result = Bun.spawnSync([process.env.DEK_GH ?? "gh", "auth", "token"], {
-      stdout: "pipe",
-      stderr: "ignore",
-    });
-    const printed = result.exitCode === 0 ? result.stdout.toString().trim() : "";
-    return printed || undefined;
-  } catch {
+/**
+ * The Authorization header for a call to `base`: the token the user set in GITHUB_TOKEN, else
+ * GH_TOKEN, and only for api.github.com. Public repositories need none. dek never asks `gh` for
+ * one: that token can write to every repository its owner can, and a tool that takes it unasked
+ * reads as credential theft to the machine's security software.
+ */
+export function authorization(
+  base: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  if (base !== DEFAULT_API) {
     return undefined;
   }
+  const token = env.GITHUB_TOKEN?.trim() || env.GH_TOKEN?.trim();
+  return token ? `Bearer ${token}` : undefined;
+}
+
+function signInHint(base: string): string {
+  return base === DEFAULT_API
+    ? "if the repository is private, set GITHUB_TOKEN to a token that can read it (`gh auth token` prints yours), then run the command again"
+    : "DEK_GITHUB_API points dek away from api.github.com, and a token goes only there; unset it to read a private repository";
 }
 
 /**
@@ -78,7 +80,7 @@ function deadline(what: string, timeoutMs: number): Deadline {
 
 function rateLimitHint(retryAfter: string | null): string {
   const wait = retryAfter ? `wait ${retryAfter}s, and ` : "";
-  return `${wait}set GITHUB_TOKEN or run \`gh auth login\` to raise the limit, then run the command again`;
+  return `${wait}set GITHUB_TOKEN to raise the limit, then run the command again`;
 }
 
 async function request(
@@ -87,14 +89,15 @@ async function request(
   accept: string,
   { signal, timeout, expired }: Deadline,
 ): Promise<Response> {
-  const auth = token();
+  const base = apiBase();
+  const auth = authorization(base);
   let response: Response;
   try {
-    response = await fetch(`${apiBase()}${path}`, {
+    response = await fetch(`${base}${path}`, {
       headers: {
         accept,
         "user-agent": "dek",
-        ...(auth ? { authorization: `Bearer ${auth}` } : {}),
+        ...(auth ? { authorization: auth } : {}),
       },
       redirect: "follow",
       signal,
@@ -112,7 +115,7 @@ async function request(
     return response;
   }
   if (response.status === 404) {
-    throw new DekError(`${what} not found on GitHub`, { hint: SIGN_IN_HINT });
+    throw new DekError(`${what} not found on GitHub`, { hint: signInHint(base) });
   }
   const retryAfter = response.headers.get("retry-after");
   if (
@@ -125,7 +128,7 @@ async function request(
   }
   if (response.status === 401 || response.status === 403) {
     throw new DekError(`GitHub refused access to ${what} (${response.status})`, {
-      hint: SIGN_IN_HINT,
+      hint: signInHint(base),
     });
   }
   throw new DekError(`GitHub answered ${response.status} for ${what}`, {

package/src/core/page.ts

@@ -45,8 +45,6 @@ export type PageMode = "player" | "presenter" | "video";
 export type PageConfig = {
   mode: PageMode;
   deck: string;
-  /** The dev server's page: it follows the server's socket and events. */
-  live: boolean;
   /** What a presenter page sends as `?token=` on its live channels. */
   liveToken?: string;
 };
@@ -56,18 +54,16 @@ export function pageConfigAttrs(config: PageConfig): string {
   return [
     ` data-mode="${config.mode}"`,
     ` data-deck="${escapeAttr(config.deck)}"`,
-    config.live ? ` data-live="true"` : "",
     config.liveToken ? ` data-live-token="${escapeAttr(config.liveToken)}"` : "",
   ].join("");
 }
 
 /** The settings `pageConfigAttrs` wrote on `body`. */
 export function readPageConfig(body: HTMLElement): PageConfig {
-  const { mode, deck, live, liveToken } = body.dataset;
+  const { mode, deck, liveToken } = body.dataset;
   return {
     mode: mode === "presenter" || mode === "video" ? mode : "player",
     deck: deck ?? "",
-    live: live === "true",
     ...(liveToken ? { liveToken } : {}),
   };
 }

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

@@ -33,14 +33,15 @@ declare module "playwright" {
     close(): Promise<void>;
   };
   export type Browser = {
-    newPage(options?: { viewport?: Viewport }): Promise<Page>;
+    newPage(options?: { viewport?: Viewport; offline?: boolean }): Promise<Page>;
     newContext(options?: {
       viewport?: Viewport;
       deviceScaleFactor?: number;
+      offline?: boolean;
     }): Promise<BrowserContext>;
     close(): Promise<void>;
   };
   export const chromium: {
-    launch(options?: { headless?: boolean }): Promise<Browser>;
+    launch(options?: { headless?: boolean; chromiumSandbox?: boolean }): Promise<Browser>;
   };
 }

package/src/core/playwright-visual.ts

@@ -50,9 +50,11 @@ 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 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.
   const context = await browser.newContext({
     viewport: request.viewport,
+    offline: true,
     ...(request.kind === "pptx" ? { deviceScaleFactor: 2 } : {}),
   });
   try {

package/src/core/playwright.ts

@@ -260,7 +260,7 @@ export async function runPlaywrightWorker<Request, Response>(
   }
   const request = await readWorkerRequest<Request>();
   try {
-    const browser = await playwright.chromium.launch({ headless: true });
+    const browser = await launchChromium(playwright.chromium);
     try {
       const response = await handle(browser, request);
       process.stdout.write(`${JSON.stringify(response)}\n`);
@@ -272,6 +272,19 @@ export async function runPlaywrightWorker<Request, Response>(
   }
 }
 
+/**
+ * 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.
+ */
+async function launchChromium(chromium: typeof import("playwright").chromium): Promise<Browser> {
+  try {
+    return await chromium.launch({ headless: true, chromiumSandbox: true });
+  } catch {
+    return await chromium.launch({ headless: true });
+  }
+}
+
 export async function defaultPlaywrightRunner(
   request: VisualRequest,
   options: SpawnTimeoutOptions = {},

package/src/core/slide-script-eval.ts

@@ -7,6 +7,7 @@ import {
   type SlideScriptProblem,
   staticProblems,
 } from "./slide-script.ts";
+import { BUN_FLAGS } from "./spawn.ts";
 import { suggest } from "./suggest.ts";
 
 /** One slide script as lint checks it: its source, and the slide's step keys to check `motion` by. */
@@ -149,7 +150,7 @@ const EVALUATOR_OPTIONS = { stdout: "pipe", stderr: "ignore", env: {} } as const
 
 function evaluatorCommand(): string[] {
   const worker = moduleFilePath(new URL("./slide-eval-worker.ts", import.meta.url));
-  return [process.execPath, "--no-install", worker];
+  return [process.execPath, ...BUN_FLAGS, worker];
 }
 
 /** A worker that was killed still wrote a line for every script it finished. */

package/src/core/spawn.ts

@@ -13,9 +13,16 @@ export async function awaitPiped(proc: {
   return { stdout, stderr, exitCode };
 }
 
+/**
+ * How dek runs bun: with no auto install, and without the working directory's `.env` or
+ * `bunfig.toml`, which a repository someone else wrote can commit to set variables or preload code.
+ * The dekc bin's shebang passes the last two to dek itself; a child does not inherit them.
+ */
+export const BUN_FLAGS = ["--no-install", "--no-env-file", "--config=/dev/null"];
+
 /** `bin` as a command line: a .ts worker runs under bun, anything else as is. */
 export function workerCommand(bin: string, args: string[] = []): string[] {
-  return bin.endsWith(".ts") ? ["bun", "--no-install", bin, ...args] : [bin, ...args];
+  return bin.endsWith(".ts") ? ["bun", ...BUN_FLAGS, bin, ...args] : [bin, ...args];
 }
 
 /** A browser that hangs must not hang dek; a whole visual run or capture fits well inside this. */

package/src/core/sync.ts

@@ -293,6 +293,25 @@ For commands, run \`dekc help --agent\`.
 `;
 }
 
+/** The longest ref title AGENTS.md shows: a title names a deck, it does not describe one. */
+const REF_TITLE_MAX = 80;
+
+/**
+ * A ref's title as it goes into AGENTS.md. Someone else wrote it, and agents read dek's block as
+ * dek's own guidance, so a title must not start a line of its own there, such as a heading or an
+ * instruction: line breaks and control characters become one space, and it is cut to
+ * REF_TITLE_MAX characters.
+ */
+function refTitleLine(title: string | undefined): string | undefined {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point.
+  const line = title?.replace(/[\s\x00-\x1f\x7f-\x9f]+/gu, " ").trim();
+  if (!line) {
+    return undefined;
+  }
+  const chars = [...line];
+  return chars.length > REF_TITLE_MAX ? `${chars.slice(0, REF_TITLE_MAX - 1).join("")}…` : line;
+}
+
 /**
  * The refs dek.toml pins, one line each, so an agent knows which decks it may
  * read as models. Empty when there are none, leaving AGENTS.md as before. A
@@ -311,7 +330,7 @@ function referencesSection(root: string): string {
     return "";
   }
   const lines = refs.map((name) => {
-    const title = refTitle(refDir(root, name), parseRefSource(name).deck)?.title;
+    const title = refTitleLine(refTitle(refDir(root, name), parseRefSource(name).deck)?.title);
     return title ? `- \`${name}\`: ${title}` : `- \`${name}\``;
   });
   return `

package/src/runtime/browser-live.ts

@@ -0,0 +1,6 @@
+// The player of the dev server's pages: the same player, with its line to the server.
+
+import { createDevLine } from "./dev-line.ts";
+import { startPlayer } from "./start.ts";
+
+startPlayer(createDevLine);

package/src/runtime/browser.ts

@@ -1,207 +1,5 @@
-/// <reference lib="dom" />
+// The player of a file that stands alone: a build, a video, a shot. It has no dev server to reach.
 
-import { isLiveEvent } from "../core/live-protocol.ts";
-import { ANNOTATIONS_CHANGED, PAGE_ID, readPageConfig } from "../core/page.ts";
-import { deckStops, moveTarget, positionsEqual } from "../core/position.ts";
-import type { PresenterSlide } from "../core/presenter-state.ts";
-import type { Position } from "../core/step.ts";
-import { createDeckControl } from "./deck-control.ts";
-import { bindInput } from "./input.ts";
-import { createLaserView, type LaserView } from "./laser-view.ts";
-import { applyLiveEvent, hydrateLiveEvent } from "./live.ts";
-import { documentLiveHost } from "./live-host.ts";
-import { createMarksView } from "./marks-view.ts";
-import { createNavigator } from "./navigator.ts";
-import { createPresenterView } from "./presenter-view.ts";
-import { createRailView } from "./rail-view.ts";
-import { createRehearseController, fetchRehearsal } from "./rehearse.ts";
-import { deckChannelName, deckUrl, liveTokenQuery } from "./routes.ts";
-import { createStage } from "./stage.ts";
+import { startPlayer } from "./start.ts";
 
-const dataEl = document.getElementById(PAGE_ID.data);
-if (dataEl?.textContent) {
-  const page = readPageConfig(document.body);
-  const slides = JSON.parse(dataEl.textContent) as PresenterSlide[];
-  const deck = deckStops(slides);
-  const stage = createStage({ slides, deck, videoMode: page.mode === "video" });
-  const presenter = createPresenterView({ slides, deck, stage, mode: page.mode });
-
-  function fitAll(): void {
-    stage.fit();
-    presenter.fit();
-    rail.fit();
-  }
-
-  /** Draw every view at `pos`. */
-  function render(pos: Position): void {
-    stage.render(pos);
-    presenter.render(pos);
-    rail.markCurrent(pos.slideIndex);
-    marks?.render(pos);
-  }
-
-  /**
-   * The first key or move takes the key hint away. Removing it also drops its animation, which
-   * the first move would otherwise wait on before it settles.
-   */
-  function dismissKeyHint(): void {
-    document.getElementById(PAGE_ID.hint)?.remove();
-  }
-
-  const rehearse = createRehearseController({
-    load: () =>
-      fetchRehearsal(location.pathname, {
-        fetch: (input, init) => fetch(input, init),
-        audio: (src) => new Audio(src),
-      }),
-    go: (position, origin) => nav.go(position, origin),
-    current: () => nav.target(),
-  });
-  const control = createDeckControl({ go: (next, origin) => nav.go(next, origin), rehearse });
-
-  // A video shows the talk as narrated; nobody points at it.
-  const laser: LaserView | undefined =
-    page.mode === "video"
-      ? undefined
-      : createLaserView({
-          current: () => nav.position().slideIndex,
-          send: (pointer) => nav.point(pointer),
-        });
-
-  // Only the dev server has a socket to follow; a built file on a static host must not dial one.
-  const socketUrl = page.live
-    ? `${location.protocol === "https:" ? "wss:" : "ws:"}//${location.host}${deckUrl(location.pathname, { kind: "socket" })}${liveTokenQuery(page.liveToken)}`
-    : undefined;
-  const nav = createNavigator({
-    deck,
-    channelName: deckChannelName(
-      page.deck,
-      deck.map((slide) => slide.slug),
-    ),
-    ...(socketUrl ? { socketUrl } : {}),
-    present: stage.present,
-    hurry: stage.hurry,
-    beforeMove: dismissKeyHint,
-    onMove: (from, to) => {
-      render(to);
-      if (from.slideIndex !== to.slideIndex) {
-        stage.announce(to);
-        laser?.sync();
-      }
-      // A hashchange echoing this same position must not cut a running animation short.
-      if (!positionsEqual(from, to)) {
-        stage.showMove(from, to);
-      }
-    },
-    afterMove: presenter.startClock,
-    route: (next) => control.request(next, "remote"),
-    ...(laser ? { onPointer: laser.receive } : {}),
-  });
-
-  const marks = createMarksView({
-    url: `${deckUrl(location.pathname, { kind: "marks" })}${liveTokenQuery(page.liveToken)}`,
-    current: () => nav.position(),
-    fetch: (input, init) => fetch(input, init),
-  });
-
-  const rail = createRailView({
-    slides,
-    stage,
-    onPick: (slideIndex) => control.request({ slideIndex, beatIndex: 0 }, "local"),
-    onResize: fitAll,
-  });
-
-  function setPresenterOpen(open: boolean): void {
-    presenter.setOpen(open);
-    fitAll();
-    render(nav.position());
-  }
-
-  bindInput({
-    onKey: dismissKeyHint,
-    togglePresenter: () => {
-      if (!presenter.available()) {
-        return false;
-      }
-      setPresenterOpen(!presenter.isOpen());
-      return true;
-    },
-    toggleFullscreen: () => {
-      if (document.fullscreenElement) {
-        void document.exitFullscreen?.().catch(() => undefined);
-      } else {
-        void document.documentElement.requestFullscreen?.().catch(() => undefined);
-      }
-    },
-    toggleRail: () => {
-      if (!rail.available() || presenter.isOpen()) {
-        return false;
-      }
-      rail.setOpen(!rail.isOpen());
-      return true;
-    },
-    togglePlay: control.togglePlay,
-    toggleLaser: () => laser?.toggle() ?? false,
-    toggleMark: () => marks?.toggle() ?? false,
-    pointing: () => laser?.isOn() ?? false,
-    move: (move) => control.request(moveTarget(move, nav.target(), deck), "local"),
-  });
-
-  window.addEventListener("resize", fitAll);
-  window.addEventListener("beforeprint", () => stage.setPrinting(true, nav.position()));
-  window.addEventListener("afterprint", () => stage.setPrinting(false, nav.position()));
-  matchMedia("print").addEventListener?.("change", (event) =>
-    stage.setPrinting(event.matches, nav.position()),
-  );
-
-  rail.fill();
-  fitAll();
-  render(nav.position());
-  // A hash that named a beat past the slide's last now says where the deck opened.
-  nav.writeHash("replace");
-  stage.showMotion(nav.position(), page.mode === "video" ? "hold" : "final");
-  // biome-ignore lint/complexity/useLiteralKeys: video recorder looks up window["dekGo"]
-  window["dekGo"] = (next) => nav.go(next, "capture");
-  // The video recorder seeks slide scripts the way it seeks Web Animations.
-  // biome-ignore lint/complexity/useLiteralKeys: video recorder looks up window["dekMotion"]
-  window["dekMotion"] = stage.motion;
-
-  const rehearseMode = new URLSearchParams(location.search).has("rehearse");
-  if (rehearseMode) {
-    void rehearse.load();
-  }
-
-  const liveHost = documentLiveHost();
-  // Keep a string key so minify does not rename the hook liveReloadScript calls.
-  // biome-ignore lint/complexity/useLiteralKeys: liveReloadScript looks up window["dekLive"]
-  window["dekLive"] = async (raw: unknown) => {
-    if (!isLiveEvent(raw)) {
-      location.reload();
-      return;
-    }
-    if (raw.type === "timeline") {
-      if (rehearseMode) {
-        await rehearse.load();
-      }
-      return;
-    }
-    if (raw.type === "annotations") {
-      document.dispatchEvent(new Event(ANNOTATIONS_CHANGED));
-      return;
-    }
-    const event = await hydrateLiveEvent(raw, location.pathname);
-    if (!event) {
-      location.reload();
-      return;
-    }
-    if (applyLiveEvent(event, liveHost).reload) {
-      location.reload();
-      return;
-    }
-    // Whatever changed, drawing the beat again puts it back as it stood.
-    const pos = nav.position();
-    rail.fill();
-    render(pos);
-    stage.showMotion(pos, "final");
-  };
-}
+startPlayer();

package/src/runtime/deck-control.ts

@@ -18,7 +18,8 @@ export type DeckControl = {
  */
 export function createDeckControl(options: {
   go: (next: Position, origin: RequestOrigin) => Promise<void>;
-  rehearse: Pick<RehearseController, "ready" | "move" | "toggle">;
+  /** The rehearsal the dev server can load; a file that stands alone has none. */
+  rehearse?: Pick<RehearseController, "ready" | "move" | "toggle">;
 }): DeckControl {
   const { go, rehearse } = options;
   return {
@@ -26,14 +27,14 @@ export function createDeckControl(options: {
       if (!next) {
         return;
       }
-      if (rehearse.ready()) {
+      if (rehearse?.ready()) {
         rehearse.move(next, origin);
       } else {
         void go(next, origin);
       }
     },
     togglePlay() {
-      if (!rehearse.ready()) {
+      if (!rehearse?.ready()) {
         return false;
       }
       rehearse.toggle();

package/src/runtime/dev-line.ts

@@ -0,0 +1,110 @@
+/// <reference lib="dom" />
+
+import { isLiveEvent } from "../core/live-protocol.ts";
+import { ANNOTATIONS_CHANGED, type PageConfig } from "../core/page.ts";
+import type { Position } from "../core/step.ts";
+import { applyLiveEvent, hydrateLiveEvent } from "./live.ts";
+import { documentLiveHost } from "./live-host.ts";
+import { createMarksView, type MarksView } from "./marks-view.ts";
+import type { GoOrigin } from "./navigator.ts";
+import { createRehearseController, fetchRehearsal, type RehearseController } from "./rehearse.ts";
+import { deckUrl, liveTokenQuery } from "./routes.ts";
+import { createPositionSocket, type PositionHandlers, type PositionSocket } from "./socket.ts";
+
+/**
+ * What the page has of the dev server: the position socket, the marks, the rehearsal, and the
+ * live updates. Only the player the dev server embeds is built with it; a file that stands alone
+ * has no server to reach, so its player never imports this module.
+ */
+export type DevLine = {
+  /** Open the position socket, for the navigator. */
+  connect: (handlers: PositionHandlers) => PositionSocket;
+  rehearse: RehearseController;
+  /** Only the presenter bar has the mark button. */
+  marks: MarksView | undefined;
+  /**
+   * Load the rehearsal the URL asks for, and take the server's live updates from here on.
+   * `redraw` puts the beat back as it stood once one has changed the page.
+   */
+  start(redraw: () => void): void;
+};
+
+export type CreateDevLine = typeof createDevLine;
+
+export function createDevLine(options: {
+  page: PageConfig;
+  /** Move the deck. */
+  go: (position: Position, origin: GoOrigin) => Promise<void>;
+  /** Where the deck is headed. */
+  target: () => Position;
+  /** What is on screen. */
+  position: () => Position;
+}): DevLine {
+  const token = liveTokenQuery(options.page.liveToken);
+  const route = (kind: "socket" | "marks"): string =>
+    `${deckUrl(location.pathname, { kind })}${token}`;
+
+  const rehearse = createRehearseController({
+    load: () =>
+      fetchRehearsal(location.pathname, {
+        fetch: (input, init) => fetch(input, init),
+        audio: (src) => new Audio(src),
+      }),
+    go: options.go,
+    current: options.target,
+  });
+
+  const marks = createMarksView({
+    url: route("marks"),
+    current: options.position,
+    fetch: (input, init) => fetch(input, init),
+  });
+
+  function connect(handlers: PositionHandlers): PositionSocket {
+    const url = `${location.protocol === "https:" ? "wss:" : "ws:"}//${location.host}${route("socket")}`;
+    return createPositionSocket({
+      connect: () => new WebSocket(url),
+      ...handlers,
+      setTimer: (fn, ms) => window.setTimeout(fn, ms),
+      clearTimer: (id) => window.clearTimeout(id),
+    });
+  }
+
+  function start(redraw: () => void): void {
+    const rehearseMode = new URLSearchParams(location.search).has("rehearse");
+    if (rehearseMode) {
+      void rehearse.load();
+    }
+    const liveHost = documentLiveHost();
+    // Keep a string key so minify does not rename the hook liveReloadScript calls.
+    // biome-ignore lint/complexity/useLiteralKeys: liveReloadScript looks up window["dekLive"]
+    window["dekLive"] = async (raw: unknown) => {
+      if (!isLiveEvent(raw)) {
+        location.reload();
+        return;
+      }
+      if (raw.type === "timeline") {
+        if (rehearseMode) {
+          await rehearse.load();
+        }
+        return;
+      }
+      if (raw.type === "annotations") {
+        document.dispatchEvent(new Event(ANNOTATIONS_CHANGED));
+        return;
+      }
+      const event = await hydrateLiveEvent(raw, location.pathname);
+      if (!event) {
+        location.reload();
+        return;
+      }
+      if (applyLiveEvent(event, liveHost).reload) {
+        location.reload();
+        return;
+      }
+      redraw();
+    };
+  }
+
+  return { connect, rehearse, marks, start };
+}

package/src/runtime/navigator.ts

@@ -18,7 +18,7 @@ import {
 } from "../core/position.ts";
 import type { Position } from "../core/step.ts";
 import { applyIncomingPosition, createGuardedGo } from "./go.ts";
-import { createPositionSocket, type PositionSocket } from "./socket.ts";
+import type { PositionHandlers, PositionSocket } from "./socket.ts";
 
 /**
  * Where a move came from. Local moves, and the rehearsal clock's, are published to peers; remote
@@ -52,8 +52,8 @@ type GoRequest = { position: Position; origin: GoOrigin };
 export function createNavigator(options: {
   deck: DeckStops;
   channelName: string;
-  /** The dev server's position socket; a built file on a static host has none. */
-  socketUrl?: string;
+  /** Open the dev server's position socket; a file that stands alone has none to open. */
+  connect?: (handlers: PositionHandlers) => PositionSocket;
   /**
    * Draw the move from `from` to `to`. `apply` puts it on screen, perhaps inside a transition;
    * the promise settles once the move has played.
@@ -156,14 +156,10 @@ export function createNavigator(options: {
       receive(next);
     }
   });
-  if (options.socketUrl) {
-    const url = options.socketUrl;
-    remote = createPositionSocket({
-      connect: () => new WebSocket(url),
+  if (options.connect) {
+    remote = options.connect({
       onPosition: receive,
       ...(options.onPointer ? { onPointer: options.onPointer } : {}),
-      setTimer: (fn, ms) => window.setTimeout(fn, ms),
-      clearTimer: (id) => window.clearTimeout(id),
     });
     // A page that is really going away must not dial back in; one kept for Back reconnects.
     window.addEventListener("pagehide", (event) => {

package/src/runtime/player.ts

@@ -3,14 +3,24 @@ import { join } from "node:path";
 export { liveReloadScript } from "./live-reload.ts";
 
 let player: Promise<string> | undefined;
+let livePlayer: Promise<string> | undefined;
 let annotate: Promise<string> | undefined;
 
-/** The player every deck page runs. */
+/** The player a file that stands alone runs: a build, a video, a shot. */
 export function playerScript(): Promise<string> {
   player ??= compile("browser.ts", "player");
   return player;
 }
 
+/**
+ * The player the dev server's pages run: the same player, and its line to the server besides,
+ * which a file that stands alone has no server for.
+ */
+export function livePlayerScript(): Promise<string> {
+  livePlayer ??= compile("browser-live.ts", "live player");
+  return livePlayer;
+}
+
 /** Annotate mode, which only the dev server's pages for the speaker run, after the player. */
 export function annotateScript(): Promise<string> {
   annotate ??= compile("annotate.ts", "annotate mode");

package/src/runtime/socket.ts

@@ -46,6 +46,13 @@ export type PositionSocket = {
   close(): void;
 };
 
+/** Where what a peer sends over the line goes. */
+export type PositionHandlers = {
+  onPosition: (position: Position) => void;
+  /** Where a presenter's laser points, or null once it went away. */
+  onPointer?: (pointer: Pointer | null) => void;
+};
+
 /**
  * The deck's line to the server, which relays positions between the presenter, the audience,
  * and a phone remote, and where the presenter's laser points. Like an EventSource, it reconnects by itself after a drop (a restarted
@@ -55,15 +62,14 @@ export type PositionSocket = {
  * missed whatever moved meanwhile. A move this deck made while away is sent instead, and that
  * greeting, if it is still where the deck was when the line dropped, is stale and passed over.
  */
-export function createPositionSocket(options: {
-  connect: () => SocketLike;
-  onPosition: (position: Position) => void;
-  /** Where a presenter's laser points, or null once it went away. */
-  onPointer?: (pointer: Pointer | null) => void;
-  setTimer: (fn: () => void, ms: number) => number;
-  clearTimer: (id: number) => void;
-  random?: () => number;
-}): PositionSocket {
+export function createPositionSocket(
+  options: PositionHandlers & {
+    connect: () => SocketLike;
+    setTimer: (fn: () => void, ms: number) => number;
+    clearTimer: (id: number) => void;
+    random?: () => number;
+  },
+): PositionSocket {
   let socket: SocketLike | undefined;
   let timer: number | undefined;
   let attempt = 0;

package/src/runtime/start.ts

@@ -0,0 +1,171 @@
+/// <reference lib="dom" />
+
+import { PAGE_ID, readPageConfig } from "../core/page.ts";
+import { deckStops, moveTarget, positionsEqual } from "../core/position.ts";
+import type { PresenterSlide } from "../core/presenter-state.ts";
+import type { Position } from "../core/step.ts";
+import { createDeckControl } from "./deck-control.ts";
+import type { CreateDevLine } from "./dev-line.ts";
+import { bindInput } from "./input.ts";
+import { createLaserView, type LaserView } from "./laser-view.ts";
+import { createNavigator } from "./navigator.ts";
+import { createPresenterView } from "./presenter-view.ts";
+import { createRailView } from "./rail-view.ts";
+import { deckChannelName } from "./routes.ts";
+import { createStage } from "./stage.ts";
+
+/**
+ * Start the player on the page. The dev server's player passes `createDevLine`, its line to the
+ * server; a file that stands alone has no server, and its player is built without one.
+ */
+export function startPlayer(createDevLine?: CreateDevLine): void {
+  const dataEl = document.getElementById(PAGE_ID.data);
+  if (!dataEl?.textContent) {
+    return;
+  }
+  const page = readPageConfig(document.body);
+  const slides = JSON.parse(dataEl.textContent) as PresenterSlide[];
+  const deck = deckStops(slides);
+  const stage = createStage({ slides, deck, videoMode: page.mode === "video" });
+  const presenter = createPresenterView({ slides, deck, stage, mode: page.mode });
+
+  function fitAll(): void {
+    stage.fit();
+    presenter.fit();
+    rail.fit();
+  }
+
+  /** Draw every view at `pos`. */
+  function render(pos: Position): void {
+    stage.render(pos);
+    presenter.render(pos);
+    rail.markCurrent(pos.slideIndex);
+    marks?.render(pos);
+  }
+
+  /**
+   * The first key or move takes the key hint away. Removing it also drops its animation, which
+   * the first move would otherwise wait on before it settles.
+   */
+  function dismissKeyHint(): void {
+    document.getElementById(PAGE_ID.hint)?.remove();
+  }
+
+  const dev = createDevLine?.({
+    page,
+    go: (position, origin) => nav.go(position, origin),
+    target: () => nav.target(),
+    position: () => nav.position(),
+  });
+  const control = createDeckControl({
+    go: (next, origin) => nav.go(next, origin),
+    ...(dev ? { rehearse: dev.rehearse } : {}),
+  });
+
+  // A video shows the talk as narrated; nobody points at it.
+  const laser: LaserView | undefined =
+    page.mode === "video"
+      ? undefined
+      : createLaserView({
+          current: () => nav.position().slideIndex,
+          send: (pointer) => nav.point(pointer),
+        });
+
+  const nav = createNavigator({
+    deck,
+    channelName: deckChannelName(
+      page.deck,
+      deck.map((slide) => slide.slug),
+    ),
+    ...(dev ? { connect: dev.connect } : {}),
+    present: stage.present,
+    hurry: stage.hurry,
+    beforeMove: dismissKeyHint,
+    onMove: (from, to) => {
+      render(to);
+      if (from.slideIndex !== to.slideIndex) {
+        stage.announce(to);
+        laser?.sync();
+      }
+      // A hashchange echoing this same position must not cut a running animation short.
+      if (!positionsEqual(from, to)) {
+        stage.showMove(from, to);
+      }
+    },
+    afterMove: presenter.startClock,
+    route: (next) => control.request(next, "remote"),
+    ...(laser ? { onPointer: laser.receive } : {}),
+  });
+
+  const marks = dev?.marks;
+
+  const rail = createRailView({
+    slides,
+    stage,
+    onPick: (slideIndex) => control.request({ slideIndex, beatIndex: 0 }, "local"),
+    onResize: fitAll,
+  });
+
+  function setPresenterOpen(open: boolean): void {
+    presenter.setOpen(open);
+    fitAll();
+    render(nav.position());
+  }
+
+  bindInput({
+    onKey: dismissKeyHint,
+    togglePresenter: () => {
+      if (!presenter.available()) {
+        return false;
+      }
+      setPresenterOpen(!presenter.isOpen());
+      return true;
+    },
+    toggleFullscreen: () => {
+      if (document.fullscreenElement) {
+        void document.exitFullscreen?.().catch(() => undefined);
+      } else {
+        void document.documentElement.requestFullscreen?.().catch(() => undefined);
+      }
+    },
+    toggleRail: () => {
+      if (!rail.available() || presenter.isOpen()) {
+        return false;
+      }
+      rail.setOpen(!rail.isOpen());
+      return true;
+    },
+    togglePlay: control.togglePlay,
+    toggleLaser: () => laser?.toggle() ?? false,
+    toggleMark: () => marks?.toggle() ?? false,
+    pointing: () => laser?.isOn() ?? false,
+    move: (move) => control.request(moveTarget(move, nav.target(), deck), "local"),
+  });
+
+  window.addEventListener("resize", fitAll);
+  window.addEventListener("beforeprint", () => stage.setPrinting(true, nav.position()));
+  window.addEventListener("afterprint", () => stage.setPrinting(false, nav.position()));
+  matchMedia("print").addEventListener?.("change", (event) =>
+    stage.setPrinting(event.matches, nav.position()),
+  );
+
+  rail.fill();
+  fitAll();
+  render(nav.position());
+  // A hash that named a beat past the slide's last now says where the deck opened.
+  nav.writeHash("replace");
+  stage.showMotion(nav.position(), page.mode === "video" ? "hold" : "final");
+  // biome-ignore lint/complexity/useLiteralKeys: video recorder looks up window["dekGo"]
+  window["dekGo"] = (next) => nav.go(next, "capture");
+  // The video recorder seeks slide scripts the way it seeks Web Animations.
+  // biome-ignore lint/complexity/useLiteralKeys: video recorder looks up window["dekMotion"]
+  window["dekMotion"] = stage.motion;
+
+  // Whatever a live update changed, drawing the beat again puts it back as it stood.
+  dev?.start(() => {
+    const pos = nav.position();
+    rail.fill();
+    render(pos);
+    stage.showMotion(pos, "final");
+  });
+}

package/src/server/dev.ts

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { DekError } from "../core/error.ts";
 import type { PlaywrightRunner } from "../core/playwright.ts";
 import { locateDeck, type Project, resolveProject } from "../core/resolve.ts";
-import { annotateScript, liveReloadScript, playerScript } from "../runtime/player.ts";
+import { annotateScript, livePlayerScript, liveReloadScript } from "../runtime/player.ts";
 import {
   clearance,
   mayRead,
@@ -69,7 +69,7 @@ export async function startDevServer(options: DevServerOptions): Promise<DevServ
   const { scopedDeckName, deckDir } = serverScope(project, options);
   const access = accessFor(options);
   const embed = {
-    playerScript: await playerScript(),
+    playerScript: await livePlayerScript(),
     liveReloadScript: liveReloadScript(),
     annotateScript: await annotateScript(),
   };

package/src/video/worker.ts

@@ -21,8 +21,10 @@ async function capture(
   request: VideoCaptureRequest,
 ): Promise<VideoCaptureResponse> {
   mkdirSync(request.outDir, { recursive: true });
+  // A deck is self-contained (DEK020), so the page needs no network.
   const page = await browser.newPage({
     viewport: { width: request.viewport.width, height: request.viewport.height },
+    offline: true,
   });
   await loadVideoDoc(page, request.html);
 

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "allowJs": true,
+    "types": ["bun"],
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": ["src", "tests"]
+}