pindeck 3.0.0-beta.1 → 3.0.0-beta.3

package/README.md

@@ -1,8 +1,12 @@
 # PinDeck
 
-> **macOS-only · Version 3 beta preview** (`3.0.0-beta.1`). The beta uses npm’s `beta` channel; stable releases use `latest`. See availability and installation below.
+> **macOS, and Linux as a beta · Version 3 beta preview** (`3.0.0-beta.3`). 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
+> releases (`npx pindeck`) stay on 2.x. See installation below.
 
-**Pin it. Say it. Done.** PinDeck is a local macOS editor for HTML slide decks (reveal.js): the slides on
+**Pin it. Say it. Done.** PinDeck is a local editor for HTML slide decks (reveal.js): the slides on
 the left, the slide in the middle, and a chat with Claude Code or OpenAI Codex on the right. You click elements to
 pin them, write what to change, and the selected assistant edits the HTML and CSS. The slide updates in place.
 
@@ -19,8 +23,8 @@ checked the layout; the next request, still being typed, refers to the new pins
 * **Edit by hand, too.** Move, resize and nudge elements with snapping, edit text in place (math stays
   TeX), write speaker notes, add, hide, move and delete slides. One undo history covers your edits and
   the assistant's.
-* **Stay on brand.** `brand.css` is locked: the assistant edits `index.html` and `theme.css` only, and checks
-  its own work with PinDeck's layout command.
+* **Stay on brand.** `brand.css` is locked: the assistant edits the deck, its styles and other files of the
+  deck folder, never `brand.css` or `vendor/`, and checks its own work with PinDeck's layout command.
 * **Bring material in.** Attach figures, audio and PDFs to a message, or import slides from PowerPoint
   into the deck's own layouts.
 * **Get it out.** Present from the browser, or export a handout or presentation PDF.
@@ -28,17 +32,20 @@ checked the layout; the next request, still being typed, refers to the new pins
 
 ## Quick start
 
-**Requires macOS.** Windows and Linux are not supported in v3.
+Runs on macOS, and on Linux as a beta. The npm package declares `"os": ["darwin", "linux"]`, so normal
+npm installation rejects other operating systems. Overriding that check does not make those platforms
+supported. Running the server from a cloned repository on another OS shows a local support notice
+instead of opening the deck or starting a backend.
 
-Install the public beta once `3.0.0-beta.1` has been published:
+Install the beta from npm:
 
 ```bash
 npx pindeck@beta /path/to/deck
 # Or select this exact beta:
-npx pindeck@3.0.0-beta.1 /path/to/deck
+npx pindeck@3.0.0-beta.3 /path/to/deck
 ```
 
-For the source preview, once the `v3-beta` branch is public:
+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
@@ -46,16 +53,19 @@ cd PinDeck-v3
 node server.mjs ocean-example
 ```
 
-**Availability:** this checkout contains the prepared beta; its branch and npm package have not yet
-been published. Until then, run `node server.mjs ocean-example` from your local v3 checkout.
+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).
 
-Use `npx pindeck@latest /path/to/deck` for the stable release. The beta channel does not replace it.
-The example deck is included in the repository; npm users supply their own deck folder.
-Then open <http://127.0.0.1:5180/>.
+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`).
 
-Options: `--port 5180`, `--provider claude|codex`, `--model <name>` (for this run only; otherwise the model in
-`~/.pindeck-v3/config.json`), `--help`. The deck folder defaults to the current folder and must contain
-`index.html`. Runtime files (chat history, screenshots, backups) are kept in `~/.pindeck-v3/` (change with
+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;
+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)),
+`--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.
 
 ## Compatibility and requirements
@@ -65,17 +75,19 @@ Options: `--port 5180`, `--provider claude|codex`, `--model <name>` (for this ru
   The corresponding executable must be on `PATH`; `CLAUDE_BIN` and `CODEX_BIN` can override its path.
   Only the selected backend is required for editing. Model and effort availability comes from that
   backend and account, and may differ from the provider’s website or desktop app.
-* **Platforms:** macOS only. Windows and Linux are not supported in v3. The npm package declares
-  `"os": ["darwin"]`, so normal npm installation rejects other operating systems. This check can be
-  overridden; bypassing it does not make those platforms supported. Source launches on unsupported
-  platforms show a local support page without opening the deck or starting a backend. Native Windows support is a
-  possible v4 feature, not part of this beta.
-* **Screenshots and PDF export:** require a locally installed Chrome, Chromium, Edge or Brave.
-* **PDF input through Codex:** page-text extraction and figure rendering use macOS PDFKit and
-  `osascript`; this bridge is macOS-only. Claude uses its native PDF-reading capabilities, while
-  PinDeck’s PDF figure-rendering helper still requires macOS.
+* **Platforms:** macOS, and Linux as a beta (see [Running on a Linux server](#running-on-a-linux-server-beta)).
+  Windows is not supported. The npm package declares `"os": ["darwin", "linux"]`, so normal npm
+  installation rejects other operating systems. This check can be overridden; bypassing it does not make
+  those platforms supported. Source launches on unsupported platforms show a local support page without
+  opening the deck or starting a backend. Native Windows support is a possible v4 feature, not part of this beta.
+* **Screenshots and PDF export:** require Chrome, Chromium, Edge or Brave where the server runs.
+* **PDF input through Codex:** pages are rendered with macOS PDFKit, or Poppler on Linux. Page-text
+  extraction uses `osascript` and is macOS-only; on Linux Codex reads the rendered page image. Claude uses
+  its native PDF-reading capabilities.
 * **PowerPoint import:** basic `.pptx` parsing uses Node.js; rendered slide pictures require
-  PowerPoint or Keynote on macOS.
+  PowerPoint or Keynote on macOS, or LibreOffice and Poppler on Linux.
+* **Linux tools:** Poppler, LibreOffice and ffmpeg, each optional; features that need a missing one are
+  switched off with the reason shown in the editor.
 
 The initial live editing checks used Codex CLI **0.144.1** and Claude Code **2.1.289**.
 Further live checks on macOS passed with Codex CLI **0.162.1** and Claude Code **2.1.301**:
@@ -89,7 +101,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
@@ -104,6 +117,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:
@@ -120,10 +167,24 @@ cp -R ocean-example my-template
 3. **`index.html`:** the footer text in the `data-` attributes of `<div class="reveal">`, and the
    `pindeck:footer-top` and `pindeck:locked` meta tags if the footer or the brand elements move.
    `deck.js` holds the math macros, the footer markup and the audio player.
-4. **`README.md` and `CLAUDE.md`:** describe the new classes and rules there. PinDeck includes
-   the deck’s `CLAUDE.md` in both backends’ instructions; the assistant can read `README.md` for details.
-   The example's `CLAUDE.md` calls `../cli.mjs` and `../server.mjs`; fix these paths if the template
-   does not sit next to PinDeck.
+4. **`README.md`, `CLAUDE.md` and `AGENTS.md`:** both backends follow the deck's `CLAUDE.md` and
+   `AGENTS.md`, so describe the new classes and rules there; the assistant can read `README.md` for details.
+   Refer to PinDeck's commands as "the PinDeck CLI command given in the system prompt", as the
+   example's `CLAUDE.md` does; PinDeck tells the assistant the right path wherever the deck is. An older
+   `node ../cli.mjs` in a deck's `CLAUDE.md` is replaced with that command.
+
+**Instructions for the assistant.** PinDeck gives both backends the deck folder's own `CLAUDE.md` and
+`AGENTS.md`. It does not load such files from parent folders, as Claude Code and Codex do in a terminal:
+those are usually written for coding (run the tests, commit), which PinDeck's assistant cannot do; they
+would change with where the deck happens to sit; and on a shared server a parent folder may be writable
+by others. To share rules between decks, say so in the deck's own file, in one of two ways:
+
+- **Import:** `Follow @../shared/STYLE.md for wording.` includes that file's text. Paths are relative to
+  the file they are in (or absolute, or `~/...`); imported files may import others, up to 5 levels,
+  each file once, 200 KB in all. Only text files are imported; an e-mail address, an `@name` that is
+  not a file, and anything in code are left as written.
+- **Pointer:** `The style rules are in ../shared/STYLE.md; read them first.` The assistant reads the file
+  when it needs it.
 
 **New slide** and the PowerPoint import model new slides on the deck's own: keep a slide with class
 `title-slide`, one with `section-slide`, and a content slide with `.slide-head` (`h2`, optionally a
@@ -200,6 +261,72 @@ Attached PDFs are handled page by page using PDFKit on macOS: extracted text plu
 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.
 
+### Files outside the deck folder
+
+A deck can use files from a folder around it, such as a style sheet or figures shared by several
+talks: start PinDeck with `--asset-root <folder>` (repeatable), or list the folders in config.json as
+`"assetRoots": ["~/talks"]`. When the folder contains the deck, PinDeck serves the deck from inside
+it, so relative paths such as `../shared/style.css` work, in the editor, in screenshots and in PDF
+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.
+
+## Running on a Linux server (beta)
+
+PinDeck can run on a Linux machine where the deck lives, with the editor in your Mac's browser. The
+deck, PinDeck, the backend (Claude Code or Codex) and the deck's git clone all stay on the server; the browser only shows the
+editor. The server listens on 127.0.0.1 there, as on a Mac, and an SSH tunnel brings that port to your Mac.
+
+On the server you need Node 20 or later (22 or 24 recommended), git if the deck is in a repository, and
+the `claude` or `codex` CLI installed and logged in under your account there, if you want the chat. Without one,
+editing by hand still works. Then, in one SSH session on the server:
+
+```bash
+node server.mjs path/to/deck --port 5180
+```
+
+and on your Mac, in another terminal (`myserver` is your usual SSH host):
+
+```bash
+ssh -N -T -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -L 127.0.0.1:5180:127.0.0.1:5180 myserver
+```
+
+Open the login link PinDeck printed on the server in the Mac's browser. The local port may differ from
+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
+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
+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,
+Undo/Redo, live reload when files change on the server, layout checks, attaching figures, audio and
+PDFs, `git-setup` and the PowerPoint import. Some features use programs on the server, and are on when
+they are installed (on Debian or Ubuntu: `sudo apt install poppler-utils libreoffice-impress ffmpeg`):
+
+| Feature | Needs |
+|---|---|
+| Screenshots, layout checks without an open editor, PDF export | Chrome or Chromium (`PINDECK_LINUX_CHROME=0` turns these off) |
+| Pictures of PDF pages (`pdf-figure`) | Poppler (`pdftoppm`, `pdfinfo`) |
+| Pictures of PowerPoint slides in the import (thumbnails, diagrams) | LibreOffice (`soffice`) and Poppler |
+| Waveforms of audio other than WAV in the import | ffmpeg |
+
+Without them the editor says what is missing (hover over "Server: Linux (beta)"), and the assistant is told
+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.
+
+Run one PinDeck per deck. 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.
+
 ## Keeping the ids out of git
 
 PinDeck adds `data-eid` attributes to the deck it opens. If the deck is in git, run once per clone:
@@ -231,9 +358,9 @@ show and commit as usual. Clones without the filter configured simply see the fi
 | 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. |
 | Hide a slide | The eye on a slide in the list, or `H`. A hidden slide stays in the deck and in PinDeck (greyed out, with a banner) but is skipped when presenting and in PDFs; **Export ▾** can include hidden slides. Show it the same way. |
-| Model and effort | Choose a discovered Claude or OpenAI model in the chat header, then use the separate reasoning-effort selector. Provider changes offer an optional handover; same-provider changes continue the conversation. |
+| Model and effort | Choose a discovered Claude or OpenAI model in the chat header, then use the separate reasoning-effort selector. Provider changes offer an optional handover; same-provider changes continue the conversation. The choice is saved in `~/.pindeck-v3/config.json`. |
 | 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). E.g. "put Fig. 3 of this paper on slide 7" or "add the results of Table 2 to slide 9". |
+| 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. |
 
@@ -305,34 +432,50 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 * **Layout instead of screenshots.** With each message the editor measures the current slide and
   every pinned slide in your browser: position and size of every element, font sizes, and issues
   (content below the footer rule, outside the slide, overlaps, clipped text). The assistant gets this as
-  text. To check its own work it runs `node ../cli.mjs layout <slide>...` (`--issues` for the
+  text. To check its own work it runs the PinDeck CLI's `layout <slide>...` (`--issues` for the
   issues only). Screenshots are
   only taken when you tick the box or the assistant needs a visual judgement.
-* **One selected backend.** Claude runs as a long-lived stream-json process; Codex runs as a local
-  app-server over stdio. Codex model and effort changes reuse the active thread writer and apply
-  to the next turn. Claude changes and provider switches prepare a replacement process before
-  retiring the old one. Events from replaced sessions are ignored. Provider-specific tool instructions share the same pin/layout context.
-* **Permissions.** The selected backend edits the two slide files through the restrictions described
-  above; it does not receive unrestricted workspace write access.
-* **Undo.** The server keeps a copy of the editable files from before each change (an AI turn
-  or a hand edit). Undo and redo walk that history and tell the assistant on the next message.
+* **One selected backend.** Claude runs as a long-lived `claude -p` stream-json process; Codex runs as a
+  local app-server over stdio. Both run in the deck folder under your own login, with the instructions
+  from `lib/system-prompt.md` and the deck's `CLAUDE.md` and `AGENTS.md`. Codex model and effort changes
+  reuse the active thread writer and apply to the next turn. Claude changes and provider switches prepare
+  a replacement process before retiring the old one. Events from replaced sessions are ignored.
+* **Permissions.** The assistant may read files, edit and create files in the deck folder, and run the
+  editor's CLI. Nothing else: no other commands, and no edits to `brand.css`, `vendor/`, `.git/` or, for a
+  named deck file, the other decks in its folder. Claude Code loads no settings files and no MCP servers,
+  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.
+* **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.
+* **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
+  slide reloads, and edited text can be copied from the message to type in again.
 
 ## Files
 
 | File | Purpose |
 |---|---|
-| `server.mjs` | Local server (127.0.0.1 only, random token per run): UI, deck files, events, backend session, undo, CLI endpoints. |
+| `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`. |
 | `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. |
 | `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. |
 | `lib/omml.mjs` | PowerPoint equations (Office Math) to TeX. |
-| `lib/pptx-render.mjs`, `lib/pdf-render.jxa.js` | Slide pictures: PowerPoint or Keynote saves a PDF, macOS PDFKit renders pages and regions of it. |
+| `lib/pptx-render.mjs`, `lib/pdf-render.jxa.js` | Slide and PDF pictures: PowerPoint or Keynote (macOS) or LibreOffice (Linux) saves a PDF; macOS PDFKit or Poppler renders pages and regions of it. |
 | `lib/pdf.mjs` | PDF export: reveal.js print layout in headless Chrome, then print to PDF. |
 | `lib/eids.mjs` | Adds the `data-eid` attributes by editing the HTML as text. |
 | `lib/claude.mjs`, `lib/codex.mjs`, `lib/agent-process.mjs` | Backend adapters and JSON-line transport. |
 | `lib/models.mjs`, `lib/agent-tools.mjs` | Model/settings normalization, handover, and restricted Codex tools. |
+| `lib/capabilities.mjs` | What this server can do on this system (macOS, Linux), for the editor, the API, the CLI and the assistant. |
+| `lib/deck-files.mjs` | Atomic writes and the revision of the deck's files. |
 | `lib/system-prompt.md` | What the assistant is told about the editor. |
 | `CONTRIBUTING.md` | How to report bugs and contribute. |
 | `docs/` | Images for this README. |
@@ -340,17 +483,96 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 
 ## Current Limitations
 
+* 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.
+* 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.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
+    start (`pindeck login` prints a new one). Update from beta.1.
+  - Linux as a beta, safe saving, Undo/Redo that refuses to overwrite outside changes, decks with their
+    own file names, `--asset-root`, `@imports` in the deck's `CLAUDE.md` and `AGENTS.md`, and the other
+    2.9 and 2.10 changes (see below).
+  - Both assistants may edit and create other files of the deck, never `brand.css`, `vendor/`, `.git/`
+    or other decks in the folder; one Undo takes back a whole turn. Codex creates files with a new
+    `pindeck_write` tool and edits through PinDeck's safe saving.
+  - Claude may run only PinDeck's own commands (layout, shot, slides, pdf, pdf-figure), each named.
+  - Starting with `--provider codex` and no saved model now picks Codex's default model, also while
+    the model lists are still loading.
+  - Stopping PinDeck waits for every backend process, including those that list models.
+
 * **3.0.0-beta.1**: Claude and Codex adapters, discovered model/effort menu, explicit provider
   switching with optional handover, curated model lists, a separate effort selector with per-model
-  preferences, restricted Codex tools, and separate v3 runtime state. Not published.
+  preferences, restricted Codex tools, and separate v3 runtime state. On npm as `pindeck@beta`.
+
+* **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
+    `brand.css`, `vendor/` or other decks in the folder. One Undo takes back everything a turn changed,
+    created or deleted; files over 2 MB are not copied, and the chat says so.
+  - Files outside the deck folder: `--asset-root <folder>` (or `"assetRoots"` in config.json) serves
+    the deck from inside that folder, so paths such as `../shared/style.css` work in the editor,
+    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 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.
+
+* **2.9**: Linux as a beta, and safer editing.
+  - Linux (beta): PinDeck runs as a headless server, used from a Mac's browser through an SSH tunnel,
+    with Claude Code running on the server. The tunnel may use another local port than the server.
+    Screenshots, layout checks without an open editor and PDF export work when Chrome or Chromium is
+    found (`PINDECK_LINUX_CHROME=0` turns them off). Features a system cannot provide are switched off,
+    with the reason shown in the editor. Changes made to the deck by other programs are seen every
+    time, also after a file was replaced by a rename.
+  - Security: 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 start
+    (`pindeck login` prints a new one), which keeps the token in an HttpOnly cookie named after the
+    server's port; headless Chrome logs in the same way, so the token is never on a command line. After
+    a restart, log in again with a new link.
+  - Saving is atomic; edits made on files that changed meanwhile are refused, and Undo/Redo no longer
+    overwrite changes made outside PinDeck.
+  - Audio and video play in Safari: deck files are sent with their length and byte ranges, and ogg,
+    opus, m4a, aac, flac and mov get their media types.
+  - Claude gets the right CLI command for decks outside the PinDeck folder; the example's `CLAUDE.md`
+    no longer names a path. The deck's `AGENTS.md` reaches Claude along with its `CLAUDE.md`.
+  - macOS: pictures of PDF pages (`pdf-figure`) and of PowerPoint slides have a white page instead of a
+    transparent one, so dark text no longer disappears on a dark slide.
+  - Screenshots and PDF exports are no longer now and then reported as failed although Chrome wrote them.
+  - `git-setup` works for decks behind symlinks or with spaces in their path. The tests run on Linux
+    and macOS in CI, including a real Chrome.
+
+* **2.8.2**: declares macOS-only support in npm metadata and the README to prevent accidental
+  installation on unsupported operating systems. Source launches on other platforms show a support
+  notice without opening the deck.
 
 * **2.8.1**: fixes from a review. Speaker notes that fail to load leave the field empty and locked, instead
   of showing the previous slide's notes and saving your edits over them. A save that fails because the

package/cli.mjs

@@ -13,7 +13,7 @@
                                     from the top left), as PNG: without a name in the screenshots
                                     folder to look at, with one saved into the deck
 
-   node cli.mjs git-setup [deck]    keep PinDeck's data-eid ids out of git (no server needed)
+   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". */
 
@@ -31,14 +31,17 @@ const arg = rest[0];
    on where PinDeck is installed; git config is per clone, so run this once in each clone. */
 if (cmd === "git-setup") {
   const FILTER = `sed 's/ data-eid="[^"]*"//g'`;
-  const deck = path.resolve(arg || ".");
+  let deck = path.resolve(arg || ".");
+  try { if (!fs.statSync(deck).isDirectory()) deck = path.dirname(deck); } catch {}   // a deck file: its folder
+  try { deck = fs.realpathSync(deck); } catch {}   // git reports the real path; a symlinked path would not match
   const git = (...a) => execFileSync("git", ["-C", deck, ...a], { encoding: "utf8" }).trim();
   let root;
   try { root = git("rev-parse", "--show-toplevel"); }
   catch { console.error(`${deck} is not inside a git repository.`); process.exit(1); }
   git("config", "filter.pindeck-ids.clean", FILTER);
   const rel = path.relative(root, deck).split(path.sep).join("/");
-  const pattern = `${rel ? rel + "/" : ""}*.html`;
+  // .gitattributes patterns end at whitespace: spaces in folder names are written as [[:space:]]
+  const pattern = `${rel ? rel.replace(/\s/g, "[[:space:]]") + "/" : ""}*.html`;
   const attrFile = path.join(root, ".gitattributes");
   const attrs = fs.existsSync(attrFile) ? fs.readFileSync(attrFile, "utf8") : "";
   const line = `${pattern} filter=pindeck-ids`;

package/lib/agent-process.mjs

@@ -6,6 +6,7 @@ export class AgentProcess {
     Object.assign(this, { onMessage, onExit });
     this.pending = new Map(); this.seq = 0; this.closed = false; this.stderr = '';
     this.proc = spawn(binary, args, { cwd, env: { ...process.env, ...env }, stdio: ['pipe', 'pipe', 'pipe'] });
+    this.exited = new Promise(resolve => this.proc.once('close', resolve).once('error', () => this.proc.pid === undefined && resolve()));
     readline.createInterface({ input: this.proc.stdout }).on('line', line => {
       if (this.closed) return;
       let m; try { m = JSON.parse(line); } catch { return; }
@@ -39,11 +40,14 @@ export class AgentProcess {
     for (const p of this.pending.values()) { clearTimeout(p.timer); p.reject(error); }
     this.pending.clear(); this.onExit(error);
   }
+  /* End of input first (the CLI finishes and exits), SIGTERM after 1.5 s, SIGKILL after 4 s.
+     Resolves once the process has exited, so shutdown can wait for it. */
   stop() {
     this.end(new Error('Agent stopped.'));
-    this.proc.stdin.destroy(); this.proc.kill('SIGTERM');
     const proc = this.proc;
-    const timer = setTimeout(() => { if (proc.exitCode === null && proc.signalCode === null) proc.kill('SIGKILL'); }, 1500);
-    timer.unref();
+    if (proc.exitCode !== null || proc.signalCode !== null || proc.pid === undefined) return Promise.resolve();
+    proc.stdin.end();
+    const term = setTimeout(() => proc.kill('SIGTERM'), 1500), kill = setTimeout(() => proc.kill('SIGKILL'), 4000);
+    return this.exited.finally(() => { clearTimeout(term); clearTimeout(kill); });
   }
 }

package/lib/agent-tools.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { writeAtomic } from './deck-files.mjs';
 const exec = promisify(execFile);
 const text = value => ({ type: 'inputText', text: String(value) });
 const schema = properties => ({ type: 'object', properties, additionalProperties: false });
@@ -10,22 +11,35 @@ const str = { type: 'string' };
 export const renderedImagePath = result => result.match(/^(.+\.png) \(\d+ × \d+ px\)/m)?.[1];
 export const deckTools = [
   { type: 'function', name: 'pindeck_read', description: 'Read a deck text file, attached image, screenshot, or PDF page. For PDFs supply a 1-based page; returns page text and its rendered image. For text use offset to read beyond the first 120000 characters.', inputSchema: { ...schema({ path: str, page: { type: 'integer', minimum: 1 }, offset: { type: 'integer', minimum: 0 } }), required: ['path'] } },
-  { type: 'function', name: 'pindeck_edit', description: 'Replace one exact unique text occurrence in index.html or theme.css. Read the file first. Only these two files are editable; brand.css is locked.', inputSchema: { ...schema({ path: str, oldText: str, newText: str }), required: ['path', 'oldText', 'newText'] } },
+  { type: 'function', name: 'pindeck_edit', description: 'Replace one exact unique text occurrence in a file of the deck folder: the deck file, theme.css or another of its files. Read the file first. brand.css, vendor/, .git/ and other decks in the folder are locked.', inputSchema: { ...schema({ path: str, oldText: str, newText: str }), required: ['path', 'oldText', 'newText'] } },
+  { type: 'function', name: 'pindeck_write', description: 'Create a new file in the deck folder (missing folders are created), or replace all of an existing one. Prefer pindeck_edit for changes to existing files. The same files are locked as for pindeck_edit.', inputSchema: { ...schema({ path: str, content: str }), required: ['path', 'content'] } },
   { type: 'function', name: 'pindeck_command', description: 'Run a PinDeck command: layout, shot, slides, pdf, or pdf-figure. Pass individual arguments in an array, never a shell command. Use pindeck_read on returned image paths.', inputSchema: { ...schema({ command: { enum: ['layout', 'shot', 'slides', 'pdf', 'pdf-figure'] }, args: { type: 'array', items: str, maxItems: 100 } }), required: ['command', 'args'] } },
 ];
-export function createDeckTools({ deckDir, readDirs = [], cliFile, env, pdfTextFile }) {
+/* Codex may read the deck, screenshots, attached PDFs and asset roots, and write any file of the deck folder
+   except the locked ones: the same rules as Claude's --allowedTools / --disallowedTools. locked: patterns
+   such as brand.css or vendor/** (or a function returning them, as the other decks in the folder change);
+   env: an object or a function (the server's address is known only once it listens). */
+export function createDeckTools({ deckDir, readDirs = [], cliFile, env, pdfTextFile, locked = ['brand.css', 'vendor/**', '.git/**'] }) {
   const deck = fs.realpathSync(deckDir);
-  const roots = [deck, ...readDirs.map(d => fs.realpathSync(d))];
+  // looked up when used: the state folders (screenshots, attachments) are created once the server listens
+  const roots = () => [deck, ...readDirs.flatMap(d => { try { return [fs.realpathSync(d)]; } catch { return []; } })];
   const inside = (root, file) => file === root || file.startsWith(root + path.sep);
+  const envNow = () => (typeof env === 'function' ? env() : env);
+  const isLocked = rel => (typeof locked === 'function' ? locked() : locked)
+    .some(p => p.endsWith('/**') ? rel === p.slice(0, -3) || rel.startsWith(p.slice(0, -2)) : rel === p);
   function checked(file, write = false) {
     if (typeof file !== 'string' || !file || file.includes('\0')) throw new Error('Invalid file path.');
     const full = path.resolve(deck, file);
-    if (write && !['index.html', 'theme.css'].some(n => full === path.join(deck, n))) throw new Error('Only index.html and theme.css can be edited.');
+    if (write) {
+      const rel = path.relative(deck, full).split(path.sep).join('/');
+      if (!rel || !inside(deck, full)) throw new Error('Only files inside the deck folder can be edited.');
+      if (isLocked(rel)) throw new Error(`${rel} is locked: it cannot be edited in PinDeck.`);
+    }
     // Check every component, including missing-file parents, to reject symlink escapes.
     let existing = full;
     while (!fs.existsSync(existing)) { const parent = path.dirname(existing); if (parent === existing) throw new Error('Missing file.'); existing = parent; }
     const real = fs.realpathSync(existing);
-    if (!roots.some(root => inside(root, real)) || (write && real !== existing)) throw new Error('File is outside the permitted directories or is a symlink.');
+    if (!(write ? [deck] : roots()).some(root => inside(root, real)) || (write && real !== existing)) throw new Error('File is outside the permitted directories or is a symlink.');
     if (write && fs.existsSync(full) && (fs.lstatSync(full).isSymbolicLink() || fs.statSync(full).nlink !== 1)) throw new Error('Linked files cannot be edited.');
     return full;
   }
@@ -41,7 +55,7 @@ export function createDeckTools({ deckDir, readDirs = [], cliFile, env, pdfTextF
         if (!inside(figures, full) || (fs.existsSync(full) && (fs.lstatSync(full).isSymbolicLink() || fs.statSync(full).nlink !== 1))) throw new Error('Linked or invalid output file.');
       }
     }
-    const { stdout } = await exec(process.execPath, [cliFile, name, ...args], { cwd: deck, env: { ...process.env, ...env }, signal, timeout: 120000, maxBuffer: 2 * 1024 * 1024 });
+    const { stdout } = await exec(process.execPath, [cliFile, name, ...args], { cwd: deck, env: { ...process.env, ...envNow() }, signal, timeout: 120000, maxBuffer: 2 * 1024 * 1024 });
     return stdout;
   }
   async function read(file, page, offset, signal) {
@@ -63,7 +77,7 @@ export function createDeckTools({ deckDir, readDirs = [], cliFile, env, pdfTextF
     const data = fs.readFileSync(full);
     const mime = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' }[ext];
     if (mime) return [{ type: 'inputImage', imageUrl: `data:${mime};base64,${data.toString('base64')}` }];
-    if (!['.html', '.css', '.md', '.txt', '.svg', '.json', '.js', '.mjs', '.csv'].includes(ext)) throw new Error('Read supports text, PNG/JPEG/WebP/GIF images, and rendered PDF pages. Audio is embedded by path, not transcribed.');
+    if (!['.html', '.htm', '.css', '.md', '.txt', '.svg', '.json', '.js', '.mjs', '.csv'].includes(ext)) throw new Error('Read supports text, PNG/JPEG/WebP/GIF images, and rendered PDF pages. Audio is embedded by path, not transcribed.');
     const start = Number.isInteger(offset) && offset >= 0 ? offset : 0;
     return [text(data.toString('utf8').slice(start, start + 120000))];
   }
@@ -77,8 +91,17 @@ export function createDeckTools({ deckDir, readDirs = [], cliFile, env, pdfTextF
       const old = fs.readFileSync(full, 'utf8');
       if (old.indexOf(args.oldText) < 0 || old.indexOf(args.oldText) !== old.lastIndexOf(args.oldText)) throw new Error('oldText must match exactly once. Re-read the file.');
       signal?.throwIfAborted();
-      fs.writeFileSync(full, old.replace(args.oldText, () => args.newText));
-      return [text('Edited ' + path.basename(full))];
+      writeAtomic(full, old.replace(args.oldText, () => args.newText));
+      return [text('Edited ' + path.relative(deck, full))];
+    }
+    if (name === 'pindeck_write') {
+      const full = checked(args.path, true);
+      if (typeof args.content !== 'string' || args.content.length > 2e6) throw new Error('Supply the file content as text (at most 2 MB).');
+      if (fs.existsSync(full) && !fs.statSync(full).isFile()) throw new Error('That path is a folder, not a file.');
+      signal?.throwIfAborted();
+      fs.mkdirSync(path.dirname(full), { recursive: true });
+      writeAtomic(full, args.content);
+      return [text('Wrote ' + path.relative(deck, full))];
     }
     throw new Error('Unknown PinDeck tool.');
   };