pindeck 3.1.0-beta.1 → 3.2.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # PinDeck
 
-> **macOS, and Linux as a beta · Version 3 beta preview** (`3.1.0-beta.1`). On Linux, PinDeck runs as a
+> **macOS, and Linux as a beta · Version 3 beta preview** (`3.2.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.1.0-beta.1 /path/to/deck
+npx pindeck@3.2.0-beta.1 /path/to/deck
 ```
 
 Or run it from the `v3-beta` branch, which includes the example deck:
@@ -57,14 +57,15 @@ Use `npx pindeck@latest /path/to/deck` for the stable release; the beta channel
 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 front.mjs login`).
+once and logs this browser in; for a new one, run `pindeck login` (or `node front.mjs login`). On a Mac,
+pressing Enter in the terminal where PinDeck runs opens a new link in your default browser.
 
-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;
+The deck is an `.html` 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;
 they share the folder's `theme.css` and `brand.css`, and the assistant edits only the deck that is open.
 PinDeck adds element ids to the deck file when it opens it (see below), so try it on a copy of a deck
 first. Options: `--port 5180`, `--provider claude|codex`, `--model <name>` (for this run only; otherwise the
-model in `~/.pindeck-v3/config.json`), `--asset-root <folder>` (see [Files outside the deck folder](#files-outside-the-deck-folder)),
+deck's own choice, see [Models, providers and configuration](#models-providers-and-configuration)), `--asset-root <folder>` (see [Files outside the deck folder](#files-outside-the-deck-folder)),
 `--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.
 
@@ -75,9 +76,16 @@ the asset roots, and in their folders one level down (`lecture/index.html`). A d
 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.
+adds its element ids. Symlinked decks and folders are listed too; a deck file that links to a deck in
+another folder is greyed out (open that deck itself). 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. Open as many decks in as many tabs as you like:
+the tabs of a browser share one connection for their live updates.
+
+A deck is open in one PinDeck at a time: started again for a deck that another PinDeck (another port, or
+`server.mjs` on its own) has open, PinDeck says where it is open and stops, so their chats and undo
+histories never overwrite each other. `pindeck login <deck>` and `cli.mjs` find the PinDeck that serves
+the deck, whichever port it runs on.
 
 ## Compatibility and requirements
 
@@ -220,7 +228,9 @@ and Haiku model in each family. Claude versions are compared numerically from di
 a rolling family alias wins ties, avoiding duplicate entries. **Show all available models** reveals
 the full discovered catalog; this display preference is remembered in the browser. A currently selected
 older model remains visible and is never switched automatically by the filter.
-**Refresh models** retries discovery. A missing CLI, missing sign-in, or discovery failure is shown in its provider group.
+**Refresh models** asks the backends again; otherwise the lists are shared by the decks you open for 10 minutes
+(`models.json` in the state folder), so opening a deck starts no backend just to list models. A missing CLI,
+missing sign-in, or discovery failure is shown in its provider group.
 These are backend-reported choices, not a guarantee of current quota or entitlement; a later rejected
 request reports its error. Older CLIs may expose fewer models than a provider's website.
 
@@ -234,7 +244,9 @@ additional model-generated summary. It excludes tool output, needs no extra infe
 sent with the first message to the new session. Earlier messages may be omitted. **Start fresh** sends
 no conversation digest; the assistant still receives PinDeck instructions and the current deck context.
 
-Settings are saved when changed in `~/.pindeck-v3/config.json` (or `$PINDECK_HOME/config.json`):
+Each deck keeps its own provider, model and effort with its conversation (in its `chat.json`), so a choice in
+one deck never moves another deck's conversation to another backend. The last choice is also saved in
+`~/.pindeck-v3/config.json` (or `$PINDECK_HOME/config.json`), as the start for decks that have none yet:
 
 ```json
 {
@@ -244,13 +256,22 @@ Settings are saved when changed in `~/.pindeck-v3/config.json` (or `$PINDECK_HOM
 }
 ```
 
-Legacy configuration without `provider` is interpreted as Claude. Unsupported effort choices are
-adjusted to the discovered model's default when starting. Provider-tagged chat/session records prevent
-one backend from resuming the other's IDs. `--provider` and `--model` override startup settings for
-that run; a later menu selection is saved. `CLAUDE_BIN` and `CODEX_BIN` override executable paths.
+Legacy configuration without `provider` is interpreted as Claude; a provider without a model gets that
+provider's default model. Once the backend has listed its models, a saved model it no longer offers gives way
+to its default model (the chat says so), and an effort the model does not offer to its saved or default one,
+before the first message. config.json is read again and merged whenever a choice is saved, so decks open at
+the same time keep each other's effort preferences. Provider-tagged chat/session records prevent one backend
+from resuming the other's IDs. `--provider` and `--model` override the deck's settings for that run; a
+`--provider` other than the deck's starts a new conversation (the chat says so), and the next run without it
+is back on the deck's own choice. A later menu selection is saved. `CLAUDE_BIN` and `CODEX_BIN` override
+executable paths. `CLAUDE_MODEL`, which PinDeck 2 read, is not used: PinDeck warns and names `--model`.
 
 The v3 preview defaults to **`~/.pindeck-v3`**, keeping v2 settings and conversations separate. It does
-not copy the v2 directory automatically. To run both versions at once, use another port, for example:
+not copy the v2 directory automatically; `config.json` and `decks/*/chat.json` can be copied over by hand
+(asset roots too: they are in config.json). Never give both versions the same `PINDECK_HOME`: they keep files
+of the same names in different formats and overwrite each other's settings and chats. PinDeck 3 warns at
+start when its folder holds a chat that PinDeck 2 wrote. To run both versions at once, use another port, for
+example:
 
 ```bash
 node front.mjs /path/to/a/deck-copy --port 5183 --provider codex
@@ -261,16 +282,17 @@ node front.mjs /path/to/a/deck-copy --port 5183 --provider codex
 Claude uses its native Read/Edit tools with PinDeck's narrow allowlist, safe mode, and no inherited
 MCP configuration. Codex runs with a read-only sandbox, command execution disabled, and no approval
 grants. Inherited MCP servers and plugins are disabled in the thread configuration. Codex receives
-three host-controlled tools: `pindeck_read`, `pindeck_edit`, and `pindeck_command`.
-Only `index.html` and `theme.css` can be edited. Linked writable files and paths outside the allowed
-roots are rejected. Commands are restricted to PinDeck's layout, shot, slides, pdf and pdf-figure
-helpers, executed with argument arrays rather than a shell. `brand.css` also retains the server's
-post-turn restoration safeguard.
+four host-controlled tools: `pindeck_read`, `pindeck_edit`, `pindeck_write` and `pindeck_command`.
+Both assistants may edit and create the files of the deck folder: the deck file, `theme.css` and its other
+files. Never `brand.css`, `vendor/`, `.git/`, or the other decks in the folder (its other `.html` files, and
+subfolders that hold a deck of their own). Linked writable files and paths outside the allowed roots are
+rejected. Commands are restricted to PinDeck's layout, shot, slides, pdf and pdf-figure helpers, executed
+with argument arrays rather than a shell. `brand.css` also retains the server's post-turn restoration safeguard.
 
 Codex reads text, PNG/JPEG/WebP/GIF images and screenshots through the bridge. SVG is read as text.
-Attached PDFs are handled page by page using PDFKit on macOS: extracted text plus a rendered page image.
-PDF reading/rendering through this bridge is currently macOS-only. Audio is embedded by path and is
-not transcribed. Read operations have a 12 MB limit; long text can be read in chunks.
+Attached PDFs are handled page by page: a rendered page image (PDFKit on macOS, Poppler on Linux), plus the
+page's text on macOS. Audio is embedded by path and is not transcribed. Read operations have a 12 MB limit;
+long text can be read in chunks.
 
 ### Files outside the deck folder
 
@@ -283,6 +305,8 @@ exports. Claude may read those files but does not edit them.
 Symlinks: PinDeck serves a file only if, with symlinks followed, it lies inside the deck folder or an
 asset root. A symlink in the deck that leads anywhere else is refused (403). To use a symlinked
 library folder, add the folder it points to as an asset root; it does not have to contain the deck.
+PinDeck never writes or deletes through a symlink out of the deck folder: with a `figures/` or `export/`
+that links elsewhere, uploads, exports and deleting a picture's file are refused with the reason.
 
 ## Running on a Linux server (beta)
 
@@ -312,7 +336,7 @@ message twice. If PinDeck restarts, the editor asks you to log in again: run `no
 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
-protects it is only in your browser's cookie and in PinDeck's own files in `~/.pindeck` (readable only by
+protects it is only in your browser's cookie and in PinDeck's own files in `~/.pindeck-v3` (readable only by
 you), never in a page or on a command line.
 
 What works on Linux in this beta: editing by hand, speaker notes, slides, pins, the chat with Claude or Codex,
@@ -331,9 +355,12 @@ Without them the editor says what is missing (hover over "Server: Linux (beta)")
 which commands are not available. LibreOffice may draw some slides a little differently from PowerPoint;
 the pictures are references and figures, the slides themselves are rebuilt from the file. Chromium from snap may not be
 allowed to use hidden folders in your home folder such as `~/.pindeck-v3`; if screenshots fail with it, set
-`PINDECK_HOME` to a folder that is not hidden, or install Chrome or Chromium from a package.
+`PINDECK_HOME` to a folder that is not hidden (not the one PinDeck 2 uses), or install Chrome or Chromium from
+a package. Run as root (in a container, say), PinDeck starts Chrome with `--no-sandbox`, which Chrome needs
+there; a screenshot or PDF that fails gives Chrome's own reason.
 
-Run one PinDeck per deck. While PinDeck or the assistant is working on a deck, do not edit it with other tools
+One PinDeck serves all your decks on one port, and a deck can be open in only one PinDeck at a time (a
+second one says where it is open). While PinDeck or the assistant is working on a deck, do not edit it with other tools
 or switch git branches at the same time. Stop first, or wait until the assistant has finished. PinDeck notices
 changes made by other programs and reloads, and it refuses Undo, Redo or an edit that would overwrite
 them. Its checks cannot rule out every race with a program that writes at the same moment.
@@ -361,10 +388,10 @@ show and commit as usual. Clones without the filter configured simply see the fi
 | Undo, redo | `⌘Z` / `⇧⌘Z` or the toolbar arrows. One history for your hand edits and the assistant's changes. |
 | Pin elements | Press `P` (or the Pin button), click elements; each click gets a number. Click a marker to remove it, `Esc` to stop. |
 | Ask the assistant | Write in the sidebar and refer to pins by number: "1: align with 2, make 3 smaller". The selected element is sent too, so "make this smaller" works. `Enter` sends, `Shift+Enter` adds a new line. |
-| Visual questions | **+** in the chat, then **Screenshot**: the current slide with its pin markers is attached when you send. |
-| Review | Each answer ends with the changed files, a **Diff** button and an **Undo** button (most recent change). |
-| Stop | **Stop** interrupts the assistant; the conversation continues. **New chat** starts over. |
-| New slide | **＋ New slide** above the slide list: a **content slide** (title and bullets), a **section divider**, or a **duplicate** of the current slide. It is added after the current slide, modelled on the deck's own slides, and its title opens for typing. |
+| Visual questions | **+** in the chat, then **Screenshot**: the current slide with the pins of that message is attached when you send. If Chrome cannot take it, the assistant is told. **Stop** during the screenshot stops at once. |
+| Review | Each answer ends with the changed files and a **Diff** button; the most recent change still in effect also has an **Undo** button. After a restart, earlier changes keep their *undone* mark but have no Diff or Undo (the undo history ends with the run). |
+| Stop | **Stop** interrupts the assistant; the conversation continues. **New chat** starts a new conversation; your slides, Undo and Redo stay as they are. |
+| New slide | **＋ New slide** above the slide list: a **content slide** (title and bullets), a **section divider**, or a **duplicate** of the current slide. It is added after the current slide, modelled on the deck's own slides; a new content slide or divider opens its title for typing. |
 | Import from PowerPoint | **＋ New slide** → **Import from PowerPoint…**, then choose a `.pptx` file and tick the slides you want (hidden PowerPoint slides start unticked). They are added after the current slide in this deck's own layouts, and the assistant can improve the complex ones; see [PowerPoint import](#powerpoint-import). `⌘Z` removes them again, with their figures. |
 | Speaker notes | The **Notes** field under the slide shows the current slide's notes (the speaker view, `S`, shows them when presenting). Type to change them; they are saved when you click elsewhere or press `⌘Enter`, and `Esc` puts back what was there. A slide without notes gets them; emptying the field removes them. Notes with formatting other than line breaks are edited as HTML. Drag the line above the notes to give them more or less room (double-click it for the default size); collapse them with their header. |
 | Move a slide | Drag it up or down in the slide list; an orange line shows where it will go. It moves with its notes and the comment above it, and `⌘Z` puts it back. Slides inside vertical stacks cannot be moved yet. |
@@ -373,10 +400,12 @@ show and commit as usual. Clones without the filter configured simply see the fi
 | Attach figures and audio | **+** in the chat, then **File…**, drag and drop onto the chat or a slide, or paste an image. Files are saved in `<deck>/figures/` straight away; audio also gets a waveform SVG. Then ask the assistant, e.g. "put this figure on a new slide after 4". Removing an attachment before sending deletes the file again. |
 | Attach a PDF | The same way: a figure or table to take over, or a paper or report with more details. PDFs stay outside the deck (in `~/.pindeck-v3`); the assistant reads them, rebuilds tables as HTML, and renders a figure (a page or a cropped part of one) into `<deck>/figures/` as PNG with `cli.mjs pdf-figure` (macOS, or Linux with Poppler). E.g. "put Fig. 3 of this paper on slide 7" or "add the results of Table 2 to slide 9". |
 | Export PDF | **Export ▾** in the toolbar. **Handout PDF**: one page per slide, build steps shown complete. **Presentation PDF**: one page per click, so a slide with two build steps gives three pages. Files go to `<deck>/export/`. Needs Chrome or Chromium. |
-| Navigate | Slide list, `←` `→`, or the toolbar. **Present** opens the deck in a new tab. |
+| Navigate | Slide list, `←` `→`, or the toolbar. **Present** opens the deck in a new tab, at the current slide. |
+| Check from a terminal | `node cli.mjs layout 3 --issues`, `slides`, `shot 3` or `pdf handout`, in the deck's folder (or with `--deck <folder or file.html>`): asks the PinDeck that serves the deck. |
 
 You can also edit `index.html` or `theme.css` in any editor; the slide reloads, and the assistant is told
-the files changed. CSS changes are swapped in without a reload.
+the files changed. CSS changes are swapped in without a reload. Typing in the slide is not lost meanwhile:
+when you finish, PinDeck refuses to save it over the other change and offers the text to copy.
 
 ## PowerPoint import
 
@@ -425,7 +454,17 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 * **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.
+  with that token. A deck's server, its assistant and its undo history are those of that deck alone. The
+  editor tabs of a browser share one event stream from the front (a shared worker), since browsers open
+  only six connections to one port; if a deck server stops, the front opens the deck again and the tab
+  catches up. Each PinDeck process notes its address in `~/.pindeck-v3/servers/` for `pindeck login` and
+  `cli.mjs`, and a deck server holds its deck's `open.json`, so a deck opens in one PinDeck only.
+* **Deck pages are sandboxed.** The deck page (in the editor's frames, and in Present) runs with a sandbox
+  policy in an origin of its own, at a per-run address that serves the deck's files and nothing else. A
+  script in a deck, a template, or written by the assistant cannot reach the login cookie, the API, the
+  chat or other decks. The editor and its bridge in the slide frame talk by `postMessage`. Headless Chrome
+  (screenshots, layout, PDFs) does not log in at all; the page it asks for is served without the sandbox,
+  which its screenshot and print modes cannot handle, only with a key made for that one run.
 * **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
@@ -461,13 +500,15 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
   so no allow rule in your own, the deck's or a parent folder's settings widens this. Codex has no shell
   and no file access of its own: it reads and edits through PinDeck's own tools, which apply the same
   rules and refuse symlinks out of the deck. If `brand.css` changes during a turn anyway, the server
-  restores it and says so in the chat.
+  restores it and says so in the chat. Subfolders that hold a deck of their own count as other decks.
 * **Undo.** The server keeps a copy of every file a change touched, from before and after it (an AI
   turn, which may change, create or delete several files of the deck, or a hand edit). Files over 2 MB
   are not copied: the chat says when a turn changed one, and Undo leaves it as it is. Hidden files,
   `vendor/` and `export/` are not part of undo. Undo and redo walk that history and tell the assistant on
   the next message. They first check that the files are still as that change left them; if something
   else changed them since, they do nothing and say which file differs, rather than overwrite that work.
+  Decks that share a folder share its files: while another deck's assistant works there too, a turn keeps
+  only the files its own assistant said it wrote, and says which it left out.
 * **Saving.** Every file PinDeck writes into the deck is written to a temporary file next to it and then
   renamed into place, so other programs never see half a file. Each change from the editor carries the
   revision of the files it was made on; if the files have changed since, the change is refused, the
@@ -480,8 +521,9 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 | `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. |
+| `lib/servers.mjs` | The PinDecks running for this user, and which one serves a deck (`pindeck login`, `cli.mjs`). |
 | `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). |
+| `public/` | The editor page; `bridge.js`, which is injected into the deck in edit mode (never saved to it); `events-worker.js`, the event stream the tabs of a browser share. |
 | `lib/pptx.mjs`, `lib/zip.mjs`, `lib/xml.mjs` | Reading `.pptx` files (no dependencies): slides, text, shapes and their positions, notes. |
 | `lib/pptx-import.mjs` | Turns PowerPoint slides into slides of the deck: figures, tables, build steps, audio, layout, HTML in the deck's style. |
 | `lib/waveform.mjs` | Waveform SVGs for imported audio. |
@@ -511,11 +553,38 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 * 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.
+* A deck's own scripts run sandboxed in the editor and in Present: they cannot use `localStorage`, cookies
+  or the editor page. A deck that needs them for its slides to work should catch the error.
+* Decks are `.html` files; `.htm` files are not listed or opened as decks.
 * 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.2.0-beta.1**: fixes from a code review and a round of user tests.
+  - Security: deck pages run sandboxed, so a deck's script can no longer use the API, read other decks or
+    send messages; the login link's `next` stays on PinDeck. A deck's own script cannot use `localStorage`
+    there either (it throws).
+  - Typing in a bullet that cannot be saved because the deck changed meanwhile can be copied, as other text
+    can; a deck that never chose a model keeps the one its conversation started with.
+  - Several decks in one folder: a turn no longer records or undoes another deck's files, and deleting a
+    picture keeps a file another deck uses. Subfolder decks are locked for the assistant.
+  - Each deck keeps its provider, model and effort; config.json is merged, not overwritten; unusable saved
+    settings are made usable before the first message.
+  - Many tabs on one port; a deck server that stops reconnects; `pindeck login` and `cli.mjs` find the right
+    PinDeck; a deck opens in one PinDeck only.
+  - Screenshots show the pins of their own message; Stop during a screenshot; failures reach the assistant.
+  - New chat keeps Undo; undone marks survive a restart; only the latest change offers Undo.
+  - A deck page that cannot start says why, and Send no longer hangs; typing survives an outside save; the
+    deck menu at every width; keyboard use of the model menus; Enter in a bullet leaves no copied ids.
+  - Large decks get their ids in linear time; symlinked decks; a deck that is gone; Chrome's own errors,
+    and `--no-sandbox` as root; a warning when PinDeck 2 writes to the same state folder.
+  - On a Mac, Enter in the terminal opens PinDeck in the browser.
+  - From the code review: locked paths regardless of case (macOS) and `.git/config` restored after each
+    turn; Codex reads PDFs of a deck reached through a symlink; "not signed in" only when Claude says so;
+    betas tested before they are staged; model lists shared between decks; a faster deck list; smaller
+    status updates; asset roots read alike by the front and the deck servers.
+
 * **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;

package/cli.mjs

@@ -15,14 +15,20 @@
 
    node cli.mjs git-setup [deck]    keep PinDeck's data-eid ids out of git (no server needed; a folder or deck file)
 
-   <slide> is a slide id (data-eid), a slide number (1-based) or "current". */
+   <slide> is a slide id (data-eid), a slide number (1-based) or "current". The assistant's commands reach its
+   own deck server (DECK_EDITOR_URL); run from a terminal, they reach the PinDeck that serves the deck in the
+   current folder (its index.html), or the deck named with --deck <folder | file.html>. */
 
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { deckTarget, homeDir } from "./lib/deck-target.mjs";
+import { serverFor } from "./lib/servers.mjs";
 
-const [cmd, ...rest] = process.argv.slice(2);
+const args = process.argv.slice(2);
+const deckAt = args.indexOf("--deck");
+const deckArg = deckAt >= 0 ? args.splice(deckAt, 2)[1] : null;
+const [cmd, ...rest] = args;
 const arg = rest[0];
 
 /* git-setup: a git "clean" filter strips PinDeck's data-eid attributes whenever git reads the deck's
@@ -68,13 +74,17 @@ function figureQuery(args) {
 
 let url = process.env.DECK_EDITOR_URL, token = process.env.DECK_EDITOR_TOKEN;
 if (!url || !token) {
-  try {
-    const home = process.env.PINDECK_HOME || path.join(os.homedir(), ".pindeck-v3");
-    const s = JSON.parse(fs.readFileSync(path.join(home, "server.json"), "utf8"));
-    url = s.url; token = s.token;
-  } catch {}
+  // from a terminal: the deck's own server if it is open, else a front that lists it (which opens it)
+  const deck = deckTarget(deckArg || process.cwd());
+  if (!fs.existsSync(path.join(deck.dir, deck.file))) {
+    console.error(`No ${deck.file} in ${deck.dir}: run this in a deck's folder, or name the deck with --deck <folder | file.html>.`);
+    process.exit(2);
+  }
+  const found = await serverFor(homeDir(), deck);
+  if (!found) { console.error(`No running PinDeck serves ${path.join(deck.dir, deck.file)} (start it with: pindeck ${deckArg || "."}).`); process.exit(1); }
+  ({ url, token } = found.own || found.front);
+  if (!found.own) url = `${url}/d/${found.key}`;
 }
-if (!url) { console.error("The PinDeck server is not running (start it with: pindeck <deck-folder>)."); process.exit(1); }
 
 /* layout and shot take several slides, so the assistant needs no shell loop or pipe (which PinDeck refuses) */
 const queries = cmd === "pdf-figure" ? [figureQuery([...rest])]

package/front.mjs

@@ -16,15 +16,16 @@
 
 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 { deckTarget, homeDir, homeWarning } from "./lib/deck-target.mjs";
+import { goodHost, LOGIN_PAGE, createLogin, openOnEnter } from "./lib/login.mjs";
 import { listDecks } from "./lib/deck-list.mjs";
+import { assetRoots } from "./lib/asset-roots.mjs";
+import { registerServer, printLogin } from "./lib/servers.mjs";
 import { USAGE } from "./lib/usage.mjs";
 
 const EDITOR_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -48,38 +49,24 @@ if (!isSupportedPlatform(process.platform)) {
   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);
-  }
-}
+/* pindeck login: a new one-time login link from the PinDeck that serves the deck (see lib/servers.mjs), asked
+   with the token in its server file (readable only by this user). With a deck, the link opens that deck. */
+if (argv[0] === "login") await printLogin(HOME_DIR, argv[1] ? deckTarget(argv[1]) : null);
 
 /* 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 homeNote = homeWarning(HOME_DIR);
+if (homeNote) console.warn(homeNote);
 const START = deckTarget(argv[0] || process.cwd());
-const expandHome = (p) => (p === "~" || p.startsWith("~/") ? path.join(os.homedir(), p.slice(1)) : p);
+if (process.env.CLAUDE_MODEL)   // PinDeck 2 read it
+  console.warn(`CLAUDE_MODEL is not used by PinDeck 3: choose the model in the editor's model menu, or start with --model ${process.env.CLAUDE_MODEL}.`);
 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; } })());
+if (!fileConfig || typeof fileConfig !== "object" || Array.isArray(fileConfig)) fileConfig = {};   // the deck server says why
+// a missing asset root stops the start, before anything is written; one that goes later lists nothing
+const givenRoots = assetRoots(assetArgs, fileConfig);
+if (givenRoots.missing.length) { console.error(`Asset root ${givenRoots.missing[0]} is not a folder.\n\n${USAGE}`); process.exit(2); }
+const ROOTS = [...new Set([START.dir, ...givenRoots.roots])];
 const decksNow = () => listDecks(ROOTS);
 const chooser = !START.named && !fs.existsSync(path.join(START.dir, START.file)) && decksNow().some((d) => !d.problem);
 
@@ -93,10 +80,10 @@ const decks = new Map();   // key -> { key, dir, file, label, proc, url, token,
 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 */
+/* Its output goes to this terminal, each line marked with the deck. hold(l): keep the line 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`); };
+  const put = (l) => { keep?.(l + "\n"); if (!hold(l)) to.write(`[${label}] ${l}\n`); };
   stream.on("data", (chunk) => {
     const lines = (rest + chunk).split("\n");
     rest = lines.pop();
@@ -114,15 +101,20 @@ function openDeck(entry, start = false) {
   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 });
+    "--port", "0", ...PASS], { env: { ...process.env, PINDECK_FRONT: "1", PINDECK_FRONT_URL: ORIGIN },
+    stdio: ["ignore", "pipe", "pipe", "ipc"], detached: true });
+  // what it says before it listens: its reason if it stops; the start deck's warnings once it runs
   let said = "";
+  const held = [];
   forward(d.proc.stdout, d.label, process.stdout);
-  forward(d.proc.stderr, d.label, process.stderr, (l) => { said += l; }, () => start && !d.url);
+  forward(d.proc.stderr, d.label, process.stderr, (l) => { if (!d.url) said = (said + l).slice(-20000); },
+    (l) => start && !d.url && held.push(l));
   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 });
+      for (const l of held.splice(0)) console.error(l);   // a start that went ahead anyway, as PinDeck said it before the front
       if (!start) console.log(`[${d.label}] opened: ${path.join(d.dir, d.file)}`);
       resolve(d);
     });
@@ -156,14 +148,18 @@ setInterval(async () => {
 
 /* 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) {
+function proxy(req, res, d, rest, anonymous = false) {
   d.last = Date.now();
-  const headers = { ...req.headers, host: new URL(d.url).host, "x-editor-token": d.token };
+  const headers = { ...req.headers, host: new URL(d.url).host, ...(anonymous ? {} : { "x-editor-token": d.token }) };
+  if (anonymous) delete headers["x-editor-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);
+    // the deck server stopped mid-answer (an event stream, say): end ours too, or the browser waits forever
+    r.on("aborted", () => res.destroy());
+    r.on("error", () => res.destroy());
   });
   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") {
@@ -174,6 +170,83 @@ function proxy(req, res, d, rest) {
   req.pipe(up);
 }
 
+/* ---- One event stream per browser -------------------------------------------------------------------
+   Browsers open at most 6 connections to one host and port, and each editor tab held one open for its deck's
+   events: a sixth tab never loaded. The tabs of a browser share one stream through a shared worker
+   (public/events-worker.js): GET /events?stream=<id> holds it, POST /events/subscribe adds a tab's deck (the
+   front opens that deck's events on its server and passes them on, marked with the tab) or removes it. If a
+   deck server stops, the deck is opened again and the tab gets its state afresh (its "hello"). */
+const streams = new Map();   // stream id -> { res, tabs: Map(tab -> { stop() }) }
+function eventStream(res, id) {
+  streams.get(id)?.res.end();   // the worker reconnected: its old stream is done
+  const st = { res, tabs: new Map() };
+  streams.set(id, st);
+  res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+  res.write("event: ready\ndata: {}\n\n");
+  const ping = setInterval(() => res.write(": ping\n\n"), 20000);
+  res.on("close", () => {
+    clearInterval(ping);
+    if (streams.get(id) === st) streams.delete(id);
+    for (const t of st.tabs.values()) t.stop();
+  });
+}
+function follow(st, tab, key) {
+  let stopped = false, up = null, tries = 0;
+  const send = (type, raw) => {
+    if (!stopped && !st.res.writableEnded) st.res.write(`event: deck\ndata: {"tab":${JSON.stringify(tab)},"type":${JSON.stringify(type)},"data":${raw}}\n\n`);
+  };
+  const retry = () => {
+    if (stopped || quitting) return;
+    if (++tries > 20) return send("gone", JSON.stringify({ error: "The deck stopped answering. Reload the page." }));
+    setTimeout(connect, Math.min(5000, 200 * tries));
+  };
+  async function connect() {
+    if (stopped || quitting) return;
+    let d = decks.get(key);
+    try {
+      if (!d) {
+        const entry = START.key === key && !chooser ? { key, dir: START.dir, file: START.file } : decksNow().find((e) => e.key === key);
+        if (!entry || entry.problem) return send("gone", JSON.stringify({ error: entry?.problem || "This deck is not in the deck folder or an asset root (any more)." }));
+        d = entry;
+      }
+      d = await openDeck(d);
+    } catch (e) { return send("gone", JSON.stringify({ error: e.message })); }
+    if (stopped) return;
+    up = http.get(d.url + "/api/events", { headers: { "x-editor-token": d.token } }, (r) => {
+      if (r.statusCode !== 200) { r.resume(); return retry(); }
+      d.sse++;
+      tries = 0;
+      let buf = "", ended = false;
+      r.setEncoding("utf8");
+      r.on("data", (chunk) => {
+        buf += chunk;
+        for (let i; (i = buf.indexOf("\n\n")) >= 0;) {
+          const block = buf.slice(0, i);
+          buf = buf.slice(i + 2);
+          const type = /^event: (.*)$/m.exec(block)?.[1], data = /^data: (.*)$/m.exec(block)?.[1];
+          if (type && data) send(type, data);
+        }
+      });
+      const end = () => {
+        if (ended) return;
+        ended = true;
+        d.sse--;
+        d.last = Date.now();
+        if (!stopped) { send("gone", "{}"); retry(); }
+      };
+      r.on("end", end); r.on("aborted", end); r.on("error", end); r.on("close", end);
+    });
+    up.on("error", retry);
+  }
+  connect();
+  return { stop() { stopped = true; up?.destroy(); } };
+}
+async function readJson(req) {
+  let s = "";
+  for await (const c of req) { s += c; if (s.length > 10000) throw new Error("body too large"); }
+  return s ? JSON.parse(s) : {};
+}
+
 /* ---- 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); };
@@ -210,12 +283,21 @@ function serveEditorFile(res, rel) {
 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 {
+    const url = new URL(req.url, ORIGIN);
+    const p = url.pathname;
     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));
+    /* A deck's pages and files under /d/<deck>/v/<token>/: asked for by the deck itself, which runs sandboxed
+       without the login cookie (see VIEW in server.mjs). Passed on without the token, so the deck server's own
+       check of the path is all they get; only to a deck that is open, so they never start one. */
+    const view = /^\/d\/([\w.-]+)(\/v\/.*)$/.exec(p);
+    if (view && !authed(req)) {
+      const d = decks.get(view[1]);
+      if (!d?.url || (req.method !== "GET" && req.method !== "HEAD")) return text(res, 403, "Not logged in");
+      return proxy(req, res, d, view[2] + url.search, true);
+    }
     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" });
@@ -234,6 +316,20 @@ const server = http.createServer(async (req, res) => {
     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() });
+    if (p === "/events" && req.method === "GET") {
+      const id = url.searchParams.get("stream") || "";
+      return /^[\w-]{8,64}$/.test(id) ? eventStream(res, id) : text(res, 400, "Bad stream");
+    }
+    if (p === "/events/subscribe" && req.method === "POST") {
+      const b = await readJson(req);
+      const st = streams.get(String(b.stream));
+      const tab = String(b.tab || "");
+      if (!st || !/^\d{1,9}$/.test(tab)) return json(res, 404, { error: "No such stream." });
+      st.tabs.get(tab)?.stop();
+      st.tabs.delete(tab);
+      if (b.on && /^[\w.-]+$/.test(String(b.deck))) st.tabs.set(tab, follow(st, tab, String(b.deck)));
+      return json(res, 200, {});
+    }
 
     const m = /^\/d\/([\w.-]+)(\/.*)?$/.exec(p);
     if (!m) return text(res, 404, "Not found");
@@ -254,20 +350,18 @@ const server = http.createServer(async (req, res) => {
     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));
+    const bad = e instanceof SyntaxError || e instanceof URIError || e.message === "body too large";
+    if (!res.headersSent) text(res, bad ? 400 : 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. */
+let removeServerInfo = () => {};
 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 {}
+  removeServerInfo = registerServer(HOME_DIR, { url: ORIGIN, token: TOKEN, deckDir: START.dir, front: true });
 }
 let listening = false;
 server.on("error", (e) => {
@@ -291,6 +385,7 @@ server.listen(PORT, "127.0.0.1", async () => {
   writeServerInfo();
   console.log(`PinDeck: ${loginUrl(loginCode(3600000))}`);
   console.log("  (a one-time login link, valid for an hour; for a new one: pindeck login)");
+  openOnEnter(() => loginUrl(loginCode(3600000)));
   console.log(chooser ? `Decks: ${START.dir}` : `Deck: ${START.dir}`);
   console.log(`Server: ${CAPS.label}`);
   for (const [name, c] of Object.entries(publicCapabilities(CAPS)))