pindeck 2.8.2 → 2.10.0

package/README.md

@@ -1,6 +1,8 @@
 # PinDeck
 
-> **macOS only.** Windows and Linux are not supported.
+> **macOS, and Linux as a beta.** 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.
 
 **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 on the right. You click elements to
@@ -19,8 +21,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
   Claude's.
-* **Stay on brand.** `brand.css` is locked: Claude edits `index.html` and `theme.css` only, and checks
-  its own work with PinDeck's layout command.
+* **Stay on brand.** `brand.css` is locked: Claude 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,9 +30,10 @@ checked the layout; the next request, still being typed, refers to the new pins
 
 ## Quick start
 
-Requires macOS. The npm package declares `"os": ["darwin"]`, 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 Claude.
+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 Claude.
 
 ```bash
 npx pindeck path/to/deck        # from npm
@@ -39,18 +42,24 @@ git clone https://github.com/ehabets/PinDeck.git && cd PinDeck
 node server.mjs ocean-example   # or from source, with the example deck in this repository
 ```
 
-Then open <http://127.0.0.1:5180/>. Requirements: Node 20 or later and the `claude` CLI, signed in
+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`). Requirements: Node 20 or later and the `claude` CLI, signed in
 with your normal Claude account. Chrome (or Chromium, Edge, Brave) is optional and is used for
-screenshots and PDF export; PowerPoint or Keynote (macOS) for pictures in the PowerPoint import.
-
-Options: `--port 5180`, `--model <name>` (for this run only; otherwise the model in
-`~/.pindeck/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/` (change with
+screenshots and PDF export; PowerPoint or Keynote (macOS) for pictures in the PowerPoint import; on
+Linux, Poppler, LibreOffice and ffmpeg (see [Running on a Linux server](#running-on-a-linux-server-beta)).
+
+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 Claude 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`, `--model <name>` (for this run only; otherwise the model in
+`~/.pindeck/config.json`), `--help`. Runtime files (chat history, screenshots, backups) are kept in `~/.pindeck/` (change with
 `PINDECK_HOME`), not in the deck. `ocean-example/` is a complete example deck to start from.
 
 ## 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
@@ -65,6 +74,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 Claude. 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 Claude session; the editor reads
+them when the slide reloads. If a tag stops working meanwhile, the editor shows the same message and Claude
+is told. A Claude 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:
@@ -82,8 +125,22 @@ cp -R ocean-example my-template
    `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`:** Claude follows both, so describe the new classes and rules there.
-   The example's `CLAUDE.md` calls `../cli.mjs` and `../server.mjs`; fix these paths if the template
-   does not sit next to PinDeck.
+   Refer to PinDeck's commands as "the PinDeck CLI command given in the system prompt", as the
+   example's `CLAUDE.md` does; PinDeck tells Claude 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 Claude.** PinDeck gives Claude the deck folder's own `CLAUDE.md` and `AGENTS.md`.
+It does not load `CLAUDE.md` files from parent folders, as Claude Code does in a terminal: those are
+usually written for coding (run the tests, commit), which PinDeck's Claude 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.` Claude 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
@@ -107,6 +164,72 @@ plain players.
 chat header's menu is written to this file, so it always shows what PinDeck uses. Edit it while
 PinDeck is stopped, or simply use the menu.
 
+### 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, Claude Code 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` CLI installed and logged in under your account there, if you want the chat. Without it,
+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,
+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 Claude 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`; 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 Claude 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 Claude 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:
@@ -140,7 +263,7 @@ show and commit as usual. Clones without the filter configured simply see the fi
 | 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 | Click **Claude ▾** in the chat header: Opus or Sonnet, and the effort (how long Claude thinks: low to max). The conversation continues after a change. The choice is saved in `~/.pindeck/config.json` (default: Sonnet, medium). |
 | 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 Claude, 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`); Claude 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`); Claude 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. |
 
@@ -212,34 +335,45 @@ 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). Claude 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 Claude needs a visual judgement.
 * **One Claude Code process.** The server starts `claude -p` in stream-json mode once and keeps it
   running, so there is no start-up delay per message. It runs in the deck folder under your Claude
   login, with `--append-system-prompt` from `lib/system-prompt.md` and the deck's `CLAUDE.md`.
-* **Permissions.** Claude may read files, edit `index.html` and `theme.css`, and run the editor's
-  CLI. Nothing else, and in particular no edits to `brand.css`. Claude Code loads no settings files
+* **Permissions.** Claude 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. 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 the editable files from before each change (a Claude turn
-  or a hand edit). Undo and redo walk that history and tell Claude on the next message.
+* **Undo.** The server keeps a copy of every file a change touched, from before and after it (a Claude
+  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 Claude 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, Claude 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, Claude session, undo, CLI endpoints, `login`. |
 | `cli.mjs` | `layout`, `shot`, `slides`, `pdf handout` / `pdf presentation` and `pdf-figure` commands for Claude (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` | The long-running Claude Code process. |
+| `lib/capabilities.mjs` | What this server can do on this system (macOS, Linux), for the editor, the API, the CLI and Claude. |
+| `lib/deck-files.mjs` | Atomic writes and the revision of the deck's files. |
 | `lib/system-prompt.md` | What Claude is told about the editor. |
 | `CONTRIBUTING.md` | How to report bugs and contribute. |
 | `docs/` | Images for this README. |
@@ -247,14 +381,68 @@ 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 Claude.
 * 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 Claude for those.
 * Moves are offsets (`translate`), so the space an element came from stays reserved. Ask Claude 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
 
+* **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.

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/capabilities.mjs

@@ -0,0 +1,118 @@
+/* What this server can do on this machine, decided once on the backend and used everywhere: the editor
+   (status), the API (refusals before any side effect), the CLI (its error text) and Claude's system prompt.
+
+   macOS: everything, as before. Linux (beta): editing, the chat, live reload and the PowerPoint import;
+   pictures of PDF pages with Poppler, pictures of PowerPoint slides with LibreOffice and Poppler, and
+   waveforms of non-WAV audio with ffmpeg, each when installed, else off with a reason. Chrome features (screenshots, headless
+   layout, PDF export) work on Linux as on macOS when Chrome or Chromium is found; PINDECK_LINUX_CHROME=0
+   turns them off. Each entry is { available, reason }: reason says why not, in plain words. */
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const SUPPORTED_PLATFORMS = ["darwin", "linux"];
+export const isSupportedPlatform = (platform) => SUPPORTED_PLATFORMS.includes(platform);
+export const platformLabel = (platform) => ({ darwin: "macOS", linux: "Linux (beta)" }[platform] || platform);
+
+const CHROME_PATHS = {
+  darwin: ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+    "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"],
+  linux: ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium", "/usr/bin/chromium-browser",
+    "/snap/bin/chromium"],
+};
+const OFFICE_APPS = ["/Applications/Microsoft PowerPoint.app", "/Applications/Keynote.app"];
+
+const isExecutable = (p) => {
+  try { return fs.statSync(p).isFile() && (fs.accessSync(p, fs.constants.X_OK), true); } catch { return false; }
+};
+
+/* An executable by path, or by name on PATH. Never runs it. Returns { path } or { path: null, reason }. */
+export function findExecutable(name, { env = process.env } = {}) {
+  if (name.includes("/")) {
+    if (isExecutable(name)) return { path: name };
+    return { path: null, reason: fs.existsSync(name) ? `${name} is not an executable file` : `${name} does not exist` };
+  }
+  for (const dir of String(env.PATH || "").split(path.delimiter).filter(Boolean)) {
+    const p = path.join(dir, name);
+    if (isExecutable(p)) return { path: p };
+  }
+  return { path: null, reason: `no "${name}" command on the PATH` };
+}
+
+const on = () => ({ available: true, reason: "" });
+const off = (reason) => ({ available: false, reason });
+
+export function detectCapabilities({ platform = process.platform, env = process.env } = {}) {
+  const mac = platform === "darwin";
+  const caps = { platform, label: platformLabel(platform) };
+
+  const claudeBin = env.CLAUDE_BIN || "claude";
+  const claude = findExecutable(claudeBin, { env });
+  caps.claude = claude.path ? on() : off(`Claude Code is not available on the server (${claude.reason}). ` +
+    `Install and log in to the claude CLI there, or set CLAUDE_BIN. Editing by hand still works.`);
+
+  let chrome = null, chromeWhy = "";
+  if (env.CHROME_BIN) {
+    const c = findExecutable(env.CHROME_BIN, { env });
+    chrome = c.path;
+    chromeWhy = c.reason ? `CHROME_BIN: ${c.reason}` : "";
+  } else {
+    chrome = (CHROME_PATHS[platform] || []).find(isExecutable) || null;
+    chromeWhy = chrome ? "" : "no Chrome or Chromium found (set CHROME_BIN)";
+  }
+  if (chrome && platform === "linux" && env.PINDECK_LINUX_CHROME === "0") {
+    chrome = null;
+    chromeWhy = "Chrome features are turned off (PINDECK_LINUX_CHROME=0)";
+  }
+  const chromeCap = chrome ? on() : off(chromeWhy);
+  caps.chromePath = chrome;
+  caps.screenshot = chromeCap;
+  caps.headlessLayout = chromeCap;
+  caps.pdfExport = chromeCap;
+
+  // Linux: Poppler renders PDF pages, LibreOffice exports PowerPoint slides to PDF, ffmpeg decodes audio
+  const has = (name) => !!findExecutable(name, { env }).path;
+  const poppler = has("pdftoppm") && has("pdfinfo"), soffice = has("soffice") || has("libreoffice");
+  caps.pdfPages = mac || poppler ? on()
+    : off("Pictures of PDF pages need Poppler on the server (pdftoppm and pdfinfo; install poppler-utils). Attached PDFs can still be read.");
+  caps.pptxImport = on();   // the import itself reads the .pptx file: no other program needed
+  caps.pptxPictures = mac ? (OFFICE_APPS.some((a) => fs.existsSync(a)) ? on() : off("Pictures of PowerPoint slides need PowerPoint or Keynote."))
+    : soffice && poppler ? on()
+    : off("Pictures of PowerPoint slides need LibreOffice (soffice) and Poppler (pdftoppm, pdfinfo) on the server.");
+  caps.audioConvert = mac || has("ffmpeg") ? on() : off("Waveforms for audio other than WAV need ffmpeg on the server.");
+  return caps;
+}
+
+/* The capabilities for the editor and the status API: no executable paths. */
+export const publicCapabilities = ({ chromePath, ...caps }) => caps;
+
+/* The lines of Claude's system prompt about what this server cannot do. Empty on a full macOS setup. */
+export function capabilityPrompt(caps, cli) {
+  const lines = [];
+  if (!caps.screenshot.available)
+    lines.push(`- \`${cli} shot\` does not work here: ${caps.screenshot.reason}. Use \`${cli} layout\` to check slides; ` +
+      `it works while the editor is open in the user's browser.`);
+  if (!caps.pdfExport.available) lines.push(`- \`${cli} pdf\` does not work here: ${caps.pdfExport.reason}.`);
+  if (!caps.pdfPages.available) lines.push(`- \`${cli} pdf-figure\` does not work here: ${caps.pdfPages.reason}`);
+  if (!lines.length) return "";
+  return `\n\n## This PinDeck server (${caps.label})\nSome commands are not available, so do not try them:\n${lines.join("\n")}\n`;
+}
+
+/* --port / PORT: an integer 0–65535 (0: any free port, for tests). null if invalid. */
+export function parsePort(value) {
+  const s = String(value ?? "").trim();
+  if (!/^\d+$/.test(s)) return null;
+  const n = Number(s);
+  return n <= 65535 ? n : null;
+}
+
+/* The command Claude runs for the CLI, quoted for the shell. The Bash permission is this exact prefix, so
+   it must be one fixed string; double quotes as before, single quotes when the path has characters that
+   double quotes do not protect. */
+export function cliCommand(rel) {
+  if (/^[\w./@%+=:,-]+$/.test(rel)) return `node ${rel}`;
+  if (!/["$`\\!]/.test(rel)) return `node "${rel}"`;
+  return `node '${rel.replaceAll("'", `'\\''`)}'`;
+}

package/lib/claude.mjs

@@ -20,7 +20,7 @@ export class ClaudeSession {
     const args = ["-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose",
       ...(typeof this.args === "function" ? this.args() : this.args), ...(resumeId ? ["--resume", resumeId] : [])];
     const proc = spawn(process.env.CLAUDE_BIN || "claude", args, {
-      cwd: this.cwd, env: { ...process.env, ...this.env }, stdio: ["pipe", "pipe", "pipe"],
+      cwd: this.cwd, env: { ...process.env, ...(typeof this.env === "function" ? this.env() : this.env) }, stdio: ["pipe", "pipe", "pipe"],
     });
     this.proc = proc;
     readline.createInterface({ input: proc.stdout }).on("line", (line) => {
@@ -45,6 +45,7 @@ export class ClaudeSession {
     };
     proc.on("error", (err) => { this.onStderr?.(String(err)); if (proc.pid === undefined) end(null, null); });
     proc.on("exit", end);
+    proc.exited = new Promise((resolve) => proc.once("close", resolve).once("error", () => proc.pid === undefined && resolve()));
   }
 
   send(content) {
@@ -55,12 +56,16 @@ export class ClaudeSession {
     this.#write({ type: "control_request", request_id: `int-${++this.reqId}`, request: { subtype: "interrupt" } });
   }
 
+  /* End of input first (Claude Code 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() {
-    if (!this.proc) return;
+    if (!this.proc) return Promise.resolve();
     const p = this.proc;
     this.proc = null;
     p.stdin.end();
-    setTimeout(() => p.kill("SIGTERM"), 1500);
+    const term = setTimeout(() => p.kill("SIGTERM"), 1500);
+    const kill = setTimeout(() => p.kill("SIGKILL"), 4000);
+    return p.exited.finally(() => { clearTimeout(term); clearTimeout(kill); });
   }
 
   #write(obj) {

package/lib/deck-files.mjs

@@ -0,0 +1,94 @@
+/* Writing deck files safely, and telling whether they changed.
+
+   writeAtomic: the new content goes to a temporary file next to the target, is flushed, gets the target's
+   permissions and then replaces the target with one rename. A reader (the browser, Claude, an editor, the
+   watcher) sees the old file or the new one, never half of it. A symlinked target is written where the link
+   points, so the link stays a link. Each file is atomic on its own; a set of files is not one transaction.
+
+   revision: a hash of the deck's editable files as they are now. The editor sends the revision it shows
+   with each change; a different one means someone else changed the files in between (409, nothing written).
+   This catches stale edits from the editor. It is not a lock: a program that writes between PinDeck's check
+   and its write can still lose its change, so only one writer (PinDeck, Claude, or another tool) at a time. */
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export function writeAtomic(file, data) {
+  let target = file, mode = null;
+  try {
+    if (fs.lstatSync(file).isSymbolicLink()) target = fs.realpathSync(file);
+    mode = fs.statSync(target).mode & 0o7777;
+  } catch (e) { if (e.code !== "ENOENT") throw e; }
+  const tmp = path.join(path.dirname(target), `.${path.basename(target)}.pindeck-${crypto.randomBytes(6).toString("hex")}.tmp`);
+  let fd = null;
+  try {
+    fd = fs.openSync(tmp, "wx", mode ?? 0o666);   // wx: never reuse an existing file
+    fs.writeFileSync(fd, data);
+    fs.fsyncSync(fd);
+    if (mode != null) fs.fchmodSync(fd, mode);   // the umask must not change the file's permissions
+    fs.closeSync(fd);
+    fd = null;
+    fs.renameSync(tmp, target);
+  } catch (e) {
+    if (fd != null) try { fs.closeSync(fd); } catch {}
+    try { fs.rmSync(tmp, { force: true }); } catch {}
+    throw new Error(`Could not save ${path.basename(file)}: ${e.message}`);
+  }
+}
+
+/* Same bytes? (a missing file is null) */
+export function sameContent(file, data) {
+  let now;
+  try { now = fs.readFileSync(file); } catch (e) { if (e.code === "ENOENT") return data == null; throw e; }
+  return data != null && now.equals(Buffer.isBuffer(data) ? data : Buffer.from(data));
+}
+
+export function revision(dir, files) {
+  const h = crypto.createHash("sha256");
+  for (const f of files) {
+    let c = null;
+    try { c = fs.readFileSync(path.join(dir, f)); } catch {}
+    h.update(f + (c == null ? "\0-" : `\0${c.length}\0`));
+    if (c) h.update(c);
+  }
+  return h.digest("hex").slice(0, 16);
+}
+
+/* The deck's files for undo: every file a turn may change, with its content (bigger files: only size and
+   time, too large to keep a copy of). Hidden files and folders (.git), node_modules, and the vendor/ and
+   export/ folders are left out; so are symlinks, which point elsewhere. */
+const SKIP_TOP = new Set(["vendor", "export", "node_modules"]);
+export const KEEP_BYTES = 2 * 1024 * 1024;
+export function scanFiles(dir, maxBytes = KEEP_BYTES) {
+  const files = new Map();
+  const walk = (rel) => {
+    let entries = [];
+    try { entries = fs.readdirSync(path.join(dir, rel), { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) { if (rel || !SKIP_TOP.has(e.name)) walk(r); continue; }
+      if (!e.isFile()) continue;
+      try {
+        const st = fs.statSync(path.join(dir, r));
+        files.set(r, { size: st.size, mtimeMs: st.mtimeMs, data: st.size <= maxBytes ? fs.readFileSync(path.join(dir, r)) : null });
+      } catch {}
+    }
+  };
+  walk("");
+  return files;
+}
+
+/* What changed between two scans: { rel: { before, after } } with the content on each side (null: the
+   file did not exist), and the files that changed but are too large to keep a copy of. */
+export function scanChanges(before, after) {
+  const changed = {}, tooLarge = [];
+  for (const rel of new Set([...before.keys(), ...after.keys()])) {
+    const b = before.get(rel), a = after.get(rel);
+    if (b && a && b.size === a.size && (b.data && a.data ? b.data.equals(a.data) : b.mtimeMs === a.mtimeMs)) continue;
+    if ((b && !b.data) || (a && !a.data)) { tooLarge.push(rel); continue; }
+    changed[rel] = { before: b ? b.data : null, after: a ? a.data : null };
+  }
+  return { changed, tooLarge };
+}