pindeck 3.0.0-beta.2 → 3.1.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # PinDeck
 
-> **macOS, and Linux as a beta · Version 3 beta preview** (`3.0.0-beta.2`). On Linux, PinDeck runs as a
+> **macOS, and Linux as a beta · Version 3 beta preview** (`3.1.0-beta.1`). On Linux, PinDeck runs as a
 > headless server that you use from your Mac's browser through an SSH tunnel (see
 > [Running on a Linux server](#running-on-a-linux-server-beta)). Windows is not supported. The beta is on
 > npm’s `beta` channel and the [`v3-beta`](https://github.com/ehabets/PinDeck/tree/v3-beta) branch; stable
@@ -42,7 +42,7 @@ Install the beta from npm:
 ```bash
 npx pindeck@beta /path/to/deck
 # Or select this exact beta:
-npx pindeck@3.0.0-beta.2 /path/to/deck
+npx pindeck@3.1.0-beta.1 /path/to/deck
 ```
 
 Or run it from the `v3-beta` branch, which includes the example deck:
@@ -50,14 +50,14 @@ Or run it from the `v3-beta` branch, which includes the example deck:
 ```bash
 git clone --branch v3-beta --single-branch https://github.com/ehabets/PinDeck.git PinDeck-v3
 cd PinDeck-v3
-node server.mjs ocean-example
+node front.mjs ocean-example
 ```
 
 Use `npx pindeck@latest /path/to/deck` for the stable release; the beta channel does not replace it.
 Releases, with notes for each beta, are on [GitHub](https://github.com/ehabets/PinDeck/releases).
 
 Then open the login link PinDeck prints (`PinDeck: http://127.0.0.1:5180/login?code=...`). It works
-once and logs this browser in; for a new one, run `pindeck login` (or `node server.mjs login`).
+once and logs this browser in; for a new one, run `pindeck login` (or `node front.mjs login`).
 
 The deck is a file (`pindeck path/to/talk.html`) or a folder, which opens its `index.html`; without
 one, the current folder. Several decks can share a folder, each with its own chat and undo history;
@@ -68,6 +68,17 @@ model in `~/.pindeck-v3/config.json`), `--asset-root <folder>` (see [Files outsi
 `--help`. Runtime files (chat history, screenshots, backups) are kept in `~/.pindeck-v3/` (change with
 `PINDECK_HOME`), not in the deck. `ocean-example/` is a complete example deck to start from.
 
+### Several decks
+
+Click the deck's name above the slide for the other decks: the `.html` files in the deck's folder and in
+the asset roots, and in their folders one level down (`lecture/index.html`). A deck opens in the same
+tab, or with ⌘-click in a new one, on the same port and login, so one SSH tunnel serves them all. Each keeps
+its own chat and undo history while it is open, and the assistant finishes a turn in a deck you leave. A
+file PinDeck cannot open is greyed out with the reason; listing a deck changes nothing, and only opening it
+adds its element ids. Started with a folder that has no `index.html`, PinDeck shows the list of its decks.
+A deck with no editor open for 30 minutes is closed (its undo history goes, as on a restart) and opens
+again when you choose it.
+
 ## Compatibility and requirements
 
 * **Runtime:** Node.js 20 or later, plus a modern browser. The release workflow uses Node.js 24.
@@ -101,7 +112,8 @@ errors; PinDeck does not fall back to broader permissions. Recheck backend compa
 
 ## Preparing a deck
 
-PinDeck works with reveal.js decks whose slides are `<section>` elements inside `.slides`. Two
+PinDeck works with reveal.js decks whose slides are `<section>` elements inside `.slides`, and with other
+decks that name their slides (see [Decks made without reveal.js](#decks-made-without-revealjs)). Two
 optional `<meta>` tags in the deck's `<head>` tell it about the design:
 
 ```html
@@ -116,6 +128,40 @@ numbers will jump where a slide is hidden.
 Without them PinDeck runs no footer check and locks only `.slide-foot` and `.logo`. A file called
 `brand.css` in the deck folder is locked for both backends. See `ocean-example/` for a complete deck.
 
+### Decks made without reveal.js
+
+A deck with a script of its own, or made with a framework whose slides are elements of their own
+(Shower, deck.js, a hand-written deck), can be edited too once it names its slides in its `<head>`:
+
+```html
+<meta name="pindeck:slides" content="main.deck > section.slide">  <!-- a CSS selector for the slides -->
+<meta name="pindeck:size" content="1440x1080">                     <!-- their size in px -->
+```
+
+The selector may use tag names, `#id`, `.class`, `[attr]` and `[attr="value"]`, joined by spaces or `>`,
+and a list of them separated by commas. In the editor, PinDeck shows the slides itself, one at a time and
+scaled to the window, and switches off the deck's own scaling, slide keys and inert or hidden marks while
+you edit; that changes nothing in the deck file. Everything in [Working with it](#working-with-it) works as
+with a reveal.js deck, with these differences:
+
+* Build steps (`.fragment`) belong to reveal.js: other decks show every element at once.
+* Hidden slides (`data-visibility="hidden"`) are left out of PinDeck's PDF exports; whether presenting
+  skips them is up to the deck's own script.
+* Speaker notes are an `<aside class="notes">` in the slide, as in reveal.js. PinDeck hides them in the
+  editor; the deck's CSS should hide them too (`aside.notes { display: none }`).
+* **Present** opens the deck at `#<slide id>`, or `#<number>` (counting from 1) for a slide without an id.
+  Present may open on the first slide if the deck does not go to slides by their address.
+* **＋ New slide** models a new slide on the deck's own (see [Making your own template](#making-your-own-template)):
+  a content slide gets placeholder bullets in a `.slide-body`; without one it has only its title. A new or
+  duplicated slide does not take the original's `id`.
+
+Both tags are needed: PinDeck opens the slides at the given size for screenshots and PDF pages. A missing
+size, or a selector that finds no slides or that PinDeck cannot read, is reported before anything changes.
+While PinDeck runs, it reads the tags again for every screenshot, PDF and assistant session; the editor
+reads them when the slide reloads. If a tag stops working meanwhile, the editor shows the same message and
+the assistant is told. A session already running keeps the slide selector it started with; **New chat**
+starts one with the new selector.
+
 ## Making your own template
 
 PinDeck has no template generator; a template is simply a deck folder. Start from a copy of the example:
@@ -207,7 +253,7 @@ The v3 preview defaults to **`~/.pindeck-v3`**, keeping v2 settings and conversa
 not copy the v2 directory automatically. To run both versions at once, use another port, for example:
 
 ```bash
-node server.mjs /path/to/a/deck-copy --port 5183 --provider codex
+node front.mjs /path/to/a/deck-copy --port 5183 --provider codex
 ```
 
 ## Backend permissions and attachments
@@ -249,7 +295,7 @@ the `claude` or `codex` CLI installed and logged in under your account there, if
 editing by hand still works. Then, in one SSH session on the server:
 
 ```bash
-node server.mjs path/to/deck --port 5180
+node front.mjs path/to/deck --port 5180
 ```
 
 and on your Mac, in another terminal (`myserver` is your usual SSH host):
@@ -262,7 +308,7 @@ Open the login link PinDeck printed on the server in the Mac's browser. The loca
 the server's: with `-L 127.0.0.1:8080:127.0.0.1:5180`, change 5180 in the link to 8080. PinDeck accepts any
 port, as long as the address is `127.0.0.1` or `localhost`. If the tunnel drops, a message you have already sent keeps running on the
 server. Restart the tunnel and the editor reconnects and shows the files as they are then; it never sends a
-message twice. If PinDeck restarts, the editor asks you to log in again: run `node server.mjs login
+message twice. If PinDeck restarts, the editor asks you to log in again: run `node front.mjs login
 path/to/deck` on the server for a new link.
 
 Other users of a shared server cannot open the editor or read the deck through PinDeck: the token that
@@ -376,6 +422,10 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 
 ## How it works
 
+* **One port, a server per deck.** `pindeck` starts the front (`front.mjs`): it holds the port, the login
+  and the deck list, and serves each open deck at `/d/<deck>/`. Every deck runs its own deck server
+  (`server.mjs`) on a private port of 127.0.0.1 with a token of its own; the front passes each request on
+  with that token. A deck's server, its assistant and its undo history are those of that deck alone.
 * **Element ids.** On start, the server gives every slide and every visible element a readable
   `data-eid` attribute (`summary`, `summary/callout`, `summary/li-2`). Only the attribute is
   inserted; the rest of the file stays as it was. A backup of the file before the first change is
@@ -427,7 +477,9 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 
 | File | Purpose |
 |---|---|
-| `server.mjs` | Local server (127.0.0.1 only, random token per run, one-time login links): UI, deck files, events, backend session, undo, CLI endpoints, `login`. |
+| `front.mjs` | What `pindeck` starts (127.0.0.1 only, random token per run, one-time login links): the login, the deck list and one deck server per open deck at `/d/<deck>/`; `login`. |
+| `server.mjs` | The server for one deck: UI, deck files, events, backend session, undo, CLI endpoints. Behind the front, or on its own (`node server.mjs <deck>`). |
+| `lib/login.mjs`, `lib/deck-target.mjs`, `lib/deck-list.mjs` | Login links and cookies, which deck a path names (and its state folder), and the decks the menu lists. |
 | `cli.mjs` | `layout`, `shot`, `slides`, `pdf handout` / `pdf presentation` and `pdf-figure` commands for the backends (and for you), and `git-setup`. |
 | `public/` | The editor page, and `bridge.js`, which is injected into the deck in edit mode (never saved to it). |
 | `lib/pptx.mjs`, `lib/zip.mjs`, `lib/xml.mjs` | Reading `.pptx` files (no dependencies): slides, text, shapes and their positions, notes. |
@@ -448,19 +500,39 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 
 ## Current Limitations
 
-* reveal.js decks only. A deck made with another framework (Marp, Slidev, impress.js, remark, Spectacle,
-  Shower, deck.js, bespoke.js) is recognised and refused with its name before PinDeck changes anything.
+* reveal.js decks, and decks that name their slides with `<meta name="pindeck:slides">` (see [Decks made
+  without reveal.js](#decks-made-without-revealjs)). Any other deck made with another framework (Marp, Slidev,
+  impress.js, remark, Spectacle, Shower, deck.js, bespoke.js) is recognised and refused with its name before
+  PinDeck changes anything.
 * Text inside inline SVG diagrams cannot be edited in place; pin it and ask the assistant.
 * Parts of an inline SVG move with the whole SVG; inline text (bold, spans) moves with its block.
 * No indenting or outdenting of bullets with `Tab` yet, and `Backspace` at the start of a bullet does not merge it with the one above; ask the assistant for those.
 * Moves are offsets (`translate`), so the space an element came from stays reserved. Ask the assistant to turn hand edits into proper CSS when a layout should really change.
-* The undo history lives on the server and starts fresh when PinDeck restarts.
+* The undo history lives on the server and starts fresh when PinDeck restarts, or when a deck closes after
+  30 minutes without an open editor.
 * One writer at a time: PinDeck is not made for editing the same deck from two editors or tools at once.
 * Linux (beta): pictures of PDF pages and PowerPoint slides, and waveforms of non-WAV audio, need
   Poppler, LibreOffice and ffmpeg on the server (see [Running on a Linux server](#running-on-a-linux-server-beta)).
 
 ## Versions
 
+* **3.1.0-beta.1**: several decks on one port, and screenshots you can open from the chat.
+  - A deck menu: click the deck's name above the slide to open another deck from its folder or the
+    asset roots (and one folder down). Each open deck keeps its own chat, assistant session and Undo;
+    listing decks changes no file. `pindeck` now starts a small front that holds the port and the
+    login and runs one deck server per open deck. A deck with no editor open for 30 minutes closes
+    (its Undo history goes, as on a restart) and reopens when chosen again.
+  - A folder without `index.html` opens a page listing its decks instead of failing.
+  - `pindeck login talk.html` prints a link that opens that deck.
+  - Screenshots the assistant took show as a small picture on the chat line; click it to see it large.
+    A screenshot PinDeck no longer keeps says so.
+
+* **3.0.0-beta.3**: everything from 2.10.0, for both assistants.
+  - Decks made without reveal.js: a deck that names its slides with `<meta name="pindeck:slides">`
+    and their size with `<meta name="pindeck:size">` is edited like a reveal.js deck (contributed by
+    Zeyu Xu). Claude and Codex are both told what the deck's slides are.
+  - Screenshots fill the picture instead of being letterboxed into a shorter page.
+
 * **3.0.0-beta.2**: everything from 2.9 and 2.10, with Codex brought up to it.
   - Security: the fix from 2.9. The editor page no longer contains the token, and the deck needs it
     too, so other users of the same machine cannot read either. PinDeck prints a one-time login link at
@@ -480,8 +552,8 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
   switching with optional handover, curated model lists, a separate effort selector with per-model
   preferences, restricted Codex tools, and separate v3 runtime state. On npm as `pindeck@beta`.
 
-* **2.10.0-beta.1** (2.10 beta): decks with their own file names and shared files, and Claude working
-  on the whole deck.
+* **2.10**: decks with their own file names and shared files, decks made without reveal.js, and Claude
+  working on the whole deck.
   - A deck file by name: `pindeck path/to/talk.html` (a folder still opens its `index.html`). Several
     decks can share a folder, each with its own chat and undo history.
   - Claude may edit and create other files of the deck (scripts, style sheets, notes), never
@@ -492,8 +564,14 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
     screenshots and PDF exports. A symlink that leads out of the deck and its asset roots is refused.
   - Shared instructions: the deck's `CLAUDE.md` and `AGENTS.md` may import other files with `@path`.
     `CLAUDE.md` files in parent folders are still not loaded, on purpose (see the README).
-  - Decks made with other slide frameworks (Marp, Slidev, impress.js, remark and others) are
-    recognised and refused with their name, before PinDeck changes anything.
+  - Decks made without reveal.js (a script of their own, Shower, deck.js, a hand-written deck): a deck
+    that names its slides with `<meta name="pindeck:slides">` (a CSS selector) and their size with
+    `<meta name="pindeck:size">` is edited like a reveal.js deck, with screenshots at the slide size and
+    one PDF page per slide (contributed by Zeyu Xu). Decks made with other slide frameworks (Marp,
+    Slidev, impress.js, remark and others) without these tags are recognised and refused with their
+    name, before PinDeck changes anything; the message says how to add the tags.
+  - Screenshots fill the picture: headless Chrome lays the page out shorter than its window, which
+    left the slide letterboxed in some Chrome versions (reported by Zeyu Xu).
   - Linux: pictures of PDF pages with Poppler, the PowerPoint import with slide pictures from
     LibreOffice, and waveforms of non-WAV audio with ffmpeg, each when installed.
 

package/front.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/* PinDeck: the front, which is what `pindeck` starts.
+
+   pindeck [deck-dir | deck.html] [--port 5180] [--provider claude|codex] [--model <name>] [--asset-root <dir>]
+   pindeck login [deck-dir | deck.html]
+
+   One port and one login for several decks. Each deck that is open runs its own deck server (server.mjs, on
+   a private port of 127.0.0.1 with a token of its own) and is reached here as /d/<deck key>/: the front logs
+   the browser in, then passes each request on with that deck's token. A deck starts when it is first asked
+   for (from the editor's deck menu, or a bookmark), so its chat, Claude session and undo stay while it is
+   open, and Claude can go on working in one deck while you edit another. A deck with no editor open for
+   PINDECK_IDLE_MS (30 minutes) is closed; it opens again when asked for.
+
+   The menu lists the decks in the start folder and the asset roots, and in their folders one level down
+   (lib/deck-list.mjs). Only those can be opened: there is no free path entry. */
+
+import http from "node:http";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { isSupportedPlatform, detectCapabilities, publicCapabilities, parsePort } from "./lib/capabilities.mjs";
+import { deckTarget, homeDir } from "./lib/deck-target.mjs";
+import { goodHost, LOGIN_PAGE, createLogin } from "./lib/login.mjs";
+import { listDecks } from "./lib/deck-list.mjs";
+import { USAGE } from "./lib/usage.mjs";
+
+const EDITOR_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SERVER = path.join(EDITOR_DIR, "server.mjs");
+const HOME_DIR = homeDir();
+const IDLE_MS = Number(process.env.PINDECK_IDLE_MS) || 30 * 60000;
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) { console.log(USAGE); process.exit(0); }
+const opt = (name, dflt) => { const i = argv.indexOf(name); return i >= 0 ? argv.splice(i, 2)[1] : dflt; };
+const portArg = opt("--port", process.env.PORT || 5180);
+const PASS = [];   // what every deck server gets: the backend and the asset roots
+for (const name of ["--provider", "--model"]) { const v = opt(name); if (v !== undefined) PASS.push(name, v); }
+const assetArgs = [];
+for (let a; (a = opt("--asset-root")) !== undefined;) { assetArgs.push(a); PASS.push("--asset-root", a); }
+let PORT = parsePort(portArg);   // the port actually bound once listening (--port 0 picks a free one)
+if (PORT === null) { console.error(`Invalid port "${portArg}": use a number from 1 to 65535.\n\n${USAGE}`); process.exit(2); }
+if (!isSupportedPlatform(process.platform)) {
+  const { showPlatformNotice } = await import("./lib/platform-notice.mjs");
+  await showPlatformNotice(PORT);
+  process.exit(0);
+}
+
+/* pindeck login: a new one-time login link from the running front, asked with the token in its server file
+   (readable only by this user). With a deck, the link opens that deck. A deck server started on its own
+   (node server.mjs) for that deck answers instead, as before the front. */
+const SERVER_FILE = path.join(HOME_DIR, "server.json");
+if (argv[0] === "login") {
+  const deck = argv[1] ? deckTarget(argv[1]) : null;
+  let info = null;
+  for (const f of [...(deck ? [path.join(HOME_DIR, "decks", deck.key, "server.json")] : []), SERVER_FILE]) {
+    try { info = JSON.parse(fs.readFileSync(f, "utf8")); break; } catch {}
+  }
+  if (!info) { console.error("No PinDeck is running."); process.exit(1); }
+  const next = deck && info.front ? `/d/${deck.key}/` : "/";
+  try {
+    const res = await fetch(`${info.url}/api/login-link?` + new URLSearchParams({ next }), { headers: { "x-editor-token": info.token } });
+    if (!res.ok) throw new Error(res.status);
+    console.log(`PinDeck (${deck ? path.join(deck.dir, deck.file) : info.deckDir}): ${(await res.json()).url}`);
+    process.exit(0);
+  } catch {
+    console.error(`The PinDeck at ${info.url} does not answer. Is it still running?`);
+    process.exit(1);
+  }
+}
+
+/* The start deck, and the folders whose decks the menu offers. A folder without index.html opens the list
+   of its decks; if it has none, its deck server says why, as for any deck that cannot be opened. */
+const START = deckTarget(argv[0] || process.cwd());
+const expandHome = (p) => (p === "~" || p.startsWith("~/") ? path.join(os.homedir(), p.slice(1)) : p);
+let fileConfig = {};
+try { fileConfig = JSON.parse(fs.readFileSync(path.join(HOME_DIR, "config.json"), "utf8")); } catch {}
+const ROOTS = [START.dir, ...assetArgs, ...(Array.isArray(fileConfig.assetRoots) ? fileConfig.assetRoots : [])]
+  .map((r) => path.resolve(expandHome(String(r))))
+  .filter((r, i, all) => all.indexOf(r) === i && (() => { try { return fs.statSync(r).isDirectory(); } catch { return false; } })());
+const decksNow = () => listDecks(ROOTS);
+const chooser = !START.named && !fs.existsSync(path.join(START.dir, START.file)) && decksNow().some((d) => !d.problem);
+
+const TOKEN = crypto.randomBytes(16).toString("hex");
+let ORIGIN = `http://127.0.0.1:${PORT}`;   // set again from the bound port once listening
+const { loginCode, loginUrl, authed, login } = createLogin({ token: TOKEN, port: () => PORT, origin: () => ORIGIN });
+const CAPS = detectCapabilities();
+
+/* ---- Deck servers -------------------------------------------------------------------------------- */
+const decks = new Map();   // key -> { key, dir, file, label, proc, url, token, ready, exited, sse, last }
+const labelOf = (d) => (d.file === "index.html" ? path.basename(d.dir) : d.file);
+let quitting = false;
+
+/* Its output goes to this terminal, each line marked with the deck. hold(): keep the lines back for now */
+function forward(stream, label, to, keep, hold = () => false) {
+  let rest = "";
+  const put = (l) => { keep?.(l + "\n"); if (!hold()) to.write(`[${label}] ${l}\n`); };
+  stream.on("data", (chunk) => {
+    const lines = (rest + chunk).split("\n");
+    rest = lines.pop();
+    lines.forEach(put);
+  });
+  stream.on("end", () => { if (rest) put(rest); });
+}
+
+/* The deck's server, started once: the promise resolves when it listens, or rejects with what it printed.
+   The start deck's complaints are printed by the front as they are, like those of PinDeck before the front. */
+function openDeck(entry, start = false) {
+  const known = decks.get(entry.key);
+  if (known) return known.ready;
+  const d = { key: entry.key, dir: entry.dir, file: entry.file, label: labelOf(entry), sse: 0, last: Date.now() };
+  decks.set(d.key, d);
+  // its own process group: Ctrl+C reaches the front only, which then ends every deck once
+  d.proc = spawn(process.execPath, [SERVER, entry.file === "index.html" ? entry.dir : path.join(entry.dir, entry.file),
+    "--port", "0", ...PASS], { env: { ...process.env, PINDECK_FRONT: "1" }, stdio: ["ignore", "pipe", "pipe", "ipc"], detached: true });
+  let said = "";
+  forward(d.proc.stdout, d.label, process.stdout);
+  forward(d.proc.stderr, d.label, process.stderr, (l) => { said += l; }, () => start && !d.url);
+  d.exited = new Promise((r) => d.proc.once("exit", r));
+  d.ready = new Promise((resolve, reject) => {
+    d.proc.on("message", (m) => {
+      if (!m?.ready) return;
+      Object.assign(d, { url: m.ready.url, token: m.ready.token });
+      if (!start) console.log(`[${d.label}] opened: ${path.join(d.dir, d.file)}`);
+      resolve(d);
+    });
+    d.proc.once("exit", (code, signal) => {
+      if (decks.get(d.key) === d) decks.delete(d.key);
+      if (d.url && !quitting) console.log(`[${d.label}] closed`);
+      reject(Object.assign(new Error(said.trim() || `The deck server stopped (${code ?? signal}).`), { exitCode: code || 1 }));
+    });
+  });
+  d.ready.catch(() => {});
+  return d.ready;
+}
+
+function stopDeck(d) {
+  try { d.proc.kill("SIGTERM"); } catch {}
+}
+
+/* A deck with no editor open (no event stream) and nothing to do for IDLE_MS is closed */
+setInterval(async () => {
+  for (const d of decks.values()) {
+    if (!d.url || d.sse > 0 || Date.now() - d.last < IDLE_MS) continue;
+    try {
+      const res = await fetch(`${d.url}/api/status`, { headers: { "x-editor-token": d.token } });
+      const st = await res.json();
+      if (st.busy || d.sse > 0 || Date.now() - d.last < IDLE_MS) continue;
+    } catch { continue; }
+    console.log(`[${d.label}] no editor open for ${Math.round(IDLE_MS / 60000)} min: closing it (it opens again when asked for)`);
+    stopDeck(d);
+  }
+}, Math.min(60000, IDLE_MS / 2)).unref();
+
+/* The request, without the front's cookie and with the deck's token, to the deck's server; the answer
+   streamed back (event streams, media ranges and large uploads included) */
+function proxy(req, res, d, rest) {
+  d.last = Date.now();
+  const headers = { ...req.headers, host: new URL(d.url).host, "x-editor-token": d.token };
+  delete headers.cookie;
+  delete headers.origin;   // checked here against the front's address; the deck server checks its own
+  const up = http.request(d.url + rest, { method: req.method, headers }, (r) => {
+    res.writeHead(r.statusCode, r.headers);
+    r.pipe(res);
+  });
+  up.on("error", () => { if (!res.headersSent) page(res, 502, "This deck stopped answering", "Reload the page to open it again."); else res.destroy(); });
+  if (rest.split("?")[0] === "/api/events") {
+    d.sse++;
+    res.on("close", () => { d.sse--; d.last = Date.now(); });
+  }
+  res.on("close", () => { if (!res.writableFinished) up.destroy(); });
+  req.pipe(up);
+}
+
+/* ---- HTTP ------------------------------------------------------------------------------------- */
+const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+const text = (res, code, s) => { res.writeHead(code, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" }); res.end(s); };
+const json = (res, code, o) => { res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store" }); res.end(JSON.stringify(o)); };
+function page(res, code, title, body) {
+  res.writeHead(code, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+  res.end(`<!doctype html><meta charset="utf-8"><title>${esc(title)} · PinDeck</title>
+<link rel="icon" href="/editor/favicon.svg" type="image/svg+xml"><link rel="stylesheet" href="/editor/front.css">
+<main class="front"><h1>${esc(title)}</h1>${body}</main>`);
+}
+/* The decks for the menu (and the start page without a start deck), with which are open and working */
+const deckList = () => decksNow().map((e) => ({ key: e.key, rel: e.rel, root: e.root, problem: e.problem,
+  open: !!decks.get(e.key)?.url }));
+function chooserPage(res) {
+  const list = deckList(), groups = new Map(ROOTS.map((r) => [r, list.filter((d) => d.root === r)]).filter(([, l]) => l.length));
+  const body = [...groups].map(([root, list]) => `<h2>${esc(root)}</h2><ul>${list.map((d) => d.problem
+    ? `<li class="off" title="${esc(d.problem)}">${esc(d.rel)}<small>${esc(d.problem)}</small></li>`
+    : `<li><a href="/d/${esc(d.key)}/">${esc(d.rel)}</a>${d.open ? " <small>open</small>" : ""}</li>`).join("")}</ul>`).join("");
+  page(res, 200, "Decks", body || "<p>No decks here.</p>");
+}
+const MIME = { html: "text/html; charset=utf-8", css: "text/css; charset=utf-8", js: "text/javascript; charset=utf-8",
+  svg: "image/svg+xml", png: "image/png" };
+function serveEditorFile(res, rel) {
+  const base = path.join(EDITOR_DIR, "public");
+  const f = path.resolve(base, "." + path.posix.normalize("/" + decodeURIComponent(rel)));
+  if (!f.startsWith(base + path.sep)) return text(res, 403, "Forbidden");
+  fs.readFile(f, (err, data) => {
+    if (err) return text(res, 404, "Not found");
+    res.writeHead(200, { "content-type": MIME[path.extname(f).slice(1)] || "application/octet-stream", "cache-control": "no-store" });
+    res.end(data);
+  });
+}
+
+const server = http.createServer(async (req, res) => {
+  const host = String(req.headers.host || "").toLowerCase();
+  if (!goodHost(host)) return text(res, 403, "Bad host");
+  const url = new URL(req.url, ORIGIN);
+  const p = url.pathname;
+  try {
+    if (req.method === "GET" && p === "/login") return login(res, url);
+    // the editor's own scripts and styles hold nothing secret; the deck page loads bridge.js from here
+    if (req.method === "GET" && p.startsWith("/editor/")) return serveEditorFile(res, p.slice(8));
+    if (!authed(req)) {
+      if (req.method === "GET" && /^\/(d\/[^/]+\/(index\.html)?)?$/.test(p)) {
+        res.writeHead(403, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+        return res.end(LOGIN_PAGE);
+      }
+      return text(res, 403, "Not logged in");
+    }
+    const origin = req.headers.origin;
+    if (req.method === "POST" && origin && origin.toLowerCase() !== `http://${host}`) return text(res, 403, "Bad origin");
+
+    if (p === "/") {
+      if (chooser) return chooserPage(res);
+      res.writeHead(302, { location: `/d/${START.key}/`, "cache-control": "no-store" });
+      return res.end();
+    }
+    if (p === "/api/ping") return json(res, 200, { ok: true, front: true });
+    if (p === "/api/login-link") return json(res, 200, { url: loginUrl(loginCode(3600000), url.searchParams.get("next") || "/") });
+    if (p === "/api/decks") return json(res, 200, { decks: deckList() });
+
+    const m = /^\/d\/([\w.-]+)(\/.*)?$/.exec(p);
+    if (!m) return text(res, 404, "Not found");
+    if (!m[2]) {
+      res.writeHead(301, { location: `/d/${m[1]}/${url.search}` });
+      return res.end();
+    }
+    let d = decks.get(m[1]);
+    if (!d) {
+      // only a deck from the list, and only one PinDeck can open
+      const entry = START.key === m[1] && !chooser ? { key: START.key, dir: START.dir, file: START.file }
+        : decksNow().find((e) => e.key === m[1]);
+      if (!entry) return page(res, 404, "No such deck", `<p>It is not in the deck folder or an asset root (any more).</p><p><a href="/">All decks</a></p>`);
+      if (entry.problem) return page(res, 409, "PinDeck cannot open this deck", `<p>${esc(entry.problem)}</p><p><a href="/">All decks</a></p>`);
+      d = entry;
+    }
+    try { d = await openDeck(d); }
+    catch (e) { return page(res, 502, "PinDeck could not open this deck", `<pre>${esc(e.message)}</pre><p><a href="/">All decks</a></p>`); }
+    return proxy(req, res, d, m[2] + url.search);
+  } catch (e) {
+    if (!res.headersSent) text(res, 500, String(e.message || e));
+  }
+});
+
+/* ---- Start ----------------------------------------------------------------------------------------
+   The port is bound first, then the start deck opens (its server checks it before writing anything). If it
+   cannot, the front says why and stops: as before the front, nothing is written. */
+function writeServerInfo() {
+  fs.mkdirSync(HOME_DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(SERVER_FILE, JSON.stringify({ url: ORIGIN, token: TOKEN, deckDir: START.dir, pid: process.pid, front: true }, null, 2), { mode: 0o600 });
+  fs.chmodSync(SERVER_FILE, 0o600);
+}
+function removeServerInfo() {
+  try { if (JSON.parse(fs.readFileSync(SERVER_FILE, "utf8")).token === TOKEN) fs.rmSync(SERVER_FILE, { force: true }); } catch {}
+}
+let listening = false;
+server.on("error", (e) => {
+  if (listening) return console.error(e);
+  console.error(e.code === "EADDRINUSE"
+    ? `Port ${PORT} is in use (another PinDeck, or an SSH tunnel?). Choose another with --port, the same on both ends of a tunnel.`
+    : `Cannot listen on 127.0.0.1:${PORT}: ${e.message}`);
+  process.exit(1);
+});
+server.listen(PORT, "127.0.0.1", async () => {
+  listening = true;
+  PORT = server.address().port;
+  ORIGIN = `http://127.0.0.1:${PORT}`;
+  if (!chooser) {
+    try { await openDeck({ key: START.key, dir: START.dir, file: START.file }, true); }
+    catch (e) {
+      console.error(e.message.replace(/\n+$/, ""));
+      process.exit(e.exitCode);   // 2 for a bad argument, as the deck server says
+    }
+  }
+  writeServerInfo();
+  console.log(`PinDeck: ${loginUrl(loginCode(3600000))}`);
+  console.log("  (a one-time login link, valid for an hour; for a new one: pindeck login)");
+  console.log(chooser ? `Decks: ${START.dir}` : `Deck: ${START.dir}`);
+  console.log(`Server: ${CAPS.label}`);
+  for (const [name, c] of Object.entries(publicCapabilities(CAPS)))
+    if (c && c.available === false) console.log(`  ${name}: off (${c.reason})`);
+});
+
+/* Ctrl+C or SIGTERM: every deck ends as it does on its own (its assistant gets end of input; at most 6 s),
+   then the front. A second Ctrl+C ends them at once. */
+async function quit() {
+  if (quitting) {
+    for (const d of decks.values()) try { process.kill(-d.proc.pid, "SIGKILL"); } catch {}
+    process.exit(1);
+  }
+  quitting = true;
+  server.close();
+  server.closeAllConnections?.();
+  removeServerInfo();
+  const all = [...decks.values()];
+  all.forEach(stopDeck);
+  await Promise.race([Promise.all(all.map((d) => d.exited)), new Promise((r) => setTimeout(r, 7000))]);
+  for (const d of all) if (d.proc.exitCode === null && d.proc.signalCode === null) try { process.kill(-d.proc.pid, "SIGKILL"); } catch {}
+  process.exit(0);
+}
+process.on("SIGINT", quit);
+process.on("SIGTERM", quit);

package/lib/deck-list.mjs

@@ -0,0 +1,49 @@
+/* The decks the front offers in the editor's deck menu: .html files in the start folder and the asset roots,
+   and in their folders one level down. Reading only: a deck gets its element ids (and PinDeck writes its
+   state) only once it is opened. A file PinDeck cannot open is listed with the reason, as at start-up. */
+
+import fs from "node:fs";
+import path from "node:path";
+import { deckTarget } from "./deck-target.mjs";
+import { unsupportedMessage } from "./frameworks.mjs";
+
+const SKIP = new Set(["node_modules", "export"]);   // dependencies, and PinDeck's own PDF exports
+const MAX_FILES = 300;
+const MAX_BYTES = 5 * 1024 * 1024;
+
+const htmlFiles = (dir) => {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && /\.html?$/i.test(e.name) && !e.name.startsWith(".")).map((e) => e.name).sort();
+  } catch { return []; }
+};
+const subfolders = (dir) => {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith(".") && !SKIP.has(e.name)).map((e) => e.name).sort();
+  } catch { return []; }
+};
+
+/* [{ key, dir, file, rel, root, problem }]: rel is the path shown in the menu, relative to its root;
+   problem is null for a deck PinDeck can open. A file under several roots is listed once, under the first. */
+export function listDecks(roots) {
+  const out = [], seen = new Set();
+  for (const root of roots) {
+    for (const dir of [root, ...subfolders(root).map((d) => path.join(root, d))]) {
+      for (const file of htmlFiles(dir)) {
+        const abs = path.join(dir, file);
+        if (seen.has(abs) || out.length >= MAX_FILES) continue;
+        seen.add(abs);
+        let problem = null;
+        try {
+          const size = fs.statSync(abs).size;
+          problem = size > MAX_BYTES ? `${file} is larger than 5 MB, too large for a deck.`
+            : unsupportedMessage(fs.readFileSync(abs, "utf8"), file)?.replace(/ Nothing was changed\.$/, "") || null;
+        } catch (e) { problem = `${file} cannot be read (${e.code || e.message}).`; }
+        const t = deckTarget(file === "index.html" ? dir : abs);
+        out.push({ key: t.key, dir, file, rel: path.relative(root, abs).split(path.sep).join("/"), root, problem });
+      }
+    }
+  }
+  return out;
+}

package/lib/deck-target.mjs

@@ -0,0 +1,25 @@
+/* Which deck a path names, and where PinDeck keeps that deck's state: shared by the front (pindeck), which
+   lists decks and addresses them as /d/<key>/, and the deck server, which keeps its chat and undo there. */
+
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import crypto from "node:crypto";
+
+export const homeDir = (env = process.env) => env.PINDECK_HOME || path.join(os.homedir(), ".pindeck-v3");
+
+/* A file (talk.html), or a folder, which means its index.html. A path ending in .html or .htm that is
+   not a folder is a file, so a missing file gets a clear message. */
+export function deckTarget(target) {
+  const abs = path.resolve(target);
+  const isFolder = (() => { try { return fs.statSync(abs).isDirectory(); } catch { return false; } })();
+  const dir = isFolder || !/\.html?$/i.test(abs) ? abs : path.dirname(abs);
+  const file = dir === abs ? "index.html" : path.basename(abs);
+  const named = file !== "index.html";   // a deck file with its own name; several can share a folder
+  const name = named ? file.replace(/\.html?$/i, "") : path.basename(dir);   // for exports and titles
+  /* State per deck file. A folder's index.html keeps the key it always had, so existing chats and undo
+     histories stay; a named file gets its own, so two decks in one folder never share chat or undo. */
+  const key = (named ? `${path.basename(dir)}-${name}` : path.basename(dir)).replace(/[^\w.-]+/g, "_") + "-" +
+    crypto.createHash("sha1").update(named ? path.join(dir, file) : dir).digest("hex").slice(0, 8);
+  return { dir, file, named, name, key };
+}