pindeck 2.8.2 → 3.0.0-beta.1

package/README.md

@@ -1,10 +1,10 @@
 # PinDeck
 
-> **macOS only.** Windows and Linux are not supported.
+> **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.
 
-**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
-pin them, write what to change, and Claude edits the HTML and CSS. The slide updates in place.
+**Pin it. Say it. Done.** PinDeck is a local macOS 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.
 
 ![PinDeck: the slide list, slide 10 of the example deck with two numbered pins, and the chat with Claude's answer to an earlier request and a new one being typed](docs/pindeck.png)
 
@@ -14,40 +14,79 @@ checked the layout; the next request, still being typed, refers to the new pins
 ## What it does
 
 * **Point instead of describe.** Pins name the exact element, word or table cell; "make 2 match 1"
-  is enough. Claude also gets the measured layout of the slide, so it sees overlaps and overflow
+  is enough. The assistant also gets the measured layout of the slide, so it sees overlaps and overflow
   without screenshots.
 * **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
+  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.
 * **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.
-* **Local and small.** One Node process on 127.0.0.1, no npm dependencies, your normal Claude login.
+* **Local and small.** One Node process on 127.0.0.1, no npm dependencies, your existing Claude Code or Codex login.
 
 ## 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.
+**Requires macOS.** Windows and Linux are not supported in v3.
+
+Install the public beta once `3.0.0-beta.1` has been published:
 
 ```bash
-npx pindeck path/to/deck        # from npm
+npx pindeck@beta /path/to/deck
+# Or select this exact beta:
+npx pindeck@3.0.0-beta.1 /path/to/deck
+```
 
-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
+For the source preview, once the `v3-beta` branch is public:
+
+```bash
+git clone --branch v3-beta --single-branch https://github.com/ehabets/PinDeck.git PinDeck-v3
+cd PinDeck-v3
+node server.mjs ocean-example
 ```
 
-Then open <http://127.0.0.1:5180/>. 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.
+**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.
 
-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
+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/>.
+
+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
 `PINDECK_HOME`), not in the deck. `ocean-example/` is a complete example deck to start from.
 
+## Compatibility and requirements
+
+* **Runtime:** Node.js 20 or later, plus a modern browser. The release workflow uses Node.js 24.
+* **Backends:** install and sign in to Claude Code (`claude auth login`) or OpenAI Codex (`codex login`).
+  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.
+* **PowerPoint import:** basic `.pptx` parsing uses Node.js; rendered slide pictures require
+  PowerPoint or Keynote on macOS.
+
+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**:
+editing, Claude effort changes, Codex model changes, conversation handover, undo/redo,
+cancellation and recovery. These are tested versions, not guaranteed minimum requirements. Backends must support the discovery and session interfaces
+used by PinDeck. Older CLIs can expose fewer models or fail initialization.
+
+Codex integration uses OpenAI’s experimental `dynamicTools` extension to the app-server.
+A future Codex update may require a PinDeck adapter update. Incompatible backends report startup
+errors; PinDeck does not fall back to broader permissions. Recheck backend compatibility when upgrading.
+
 ## Preparing a deck
 
 PinDeck works with reveal.js decks whose slides are `<section>` elements inside `.slides`. Two
@@ -63,7 +102,7 @@ the example's `deck.js` does for the footer), count only slides without that att
 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.
+`brand.css` in the deck folder is locked for both backends. See `ocean-example/` for a complete deck.
 
 ## Making your own template
 
@@ -74,14 +113,15 @@ cp -R ocean-example my-template
 ```
 
 1. **Brand in `brand.css`:** palette, backgrounds, footer and logo positions. PinDeck locks this file
-   for Claude, so edit it by hand (or with Claude Code outside PinDeck). Replace the logos in
+   for both backends, so edit it by hand outside PinDeck. Replace the logos in
    `assets/` too.
 2. **Everything else in `theme.css`:** type sizes, spacing, layouts and components. This can be done
-   in PinDeck with Claude.
+   in PinDeck with the selected assistant.
 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`:** Claude follows both, so describe the new classes and rules there.
+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.
 
@@ -92,20 +132,73 @@ and imported audio copies the first `.demo-row` (with a `data-target`). Without
 slide, those PowerPoint slides are imported as content slides; without a `.demo-row`, audio gets
 plain players.
 
-## Configuration
-
-`~/.pindeck/config.json` (or `$PINDECK_HOME/config.json`) is created on first start:
+## Models, providers and configuration
+
+Open the existing model menu in the chat header to choose a model under **Claude** or
+**OpenAI / ChatGPT**. Choices come from the installed backends: Claude's initialization response
+and Codex's paginated `model/list`. Hidden or explicitly unavailable entries are omitted. Effort
+choices appear in a separate reasoning-effort selector beside the model and follow its reported
+capabilities. Readable labels preserve the exact backend values (for example, Extra high sends `xhigh`).
+The selector shows provider descriptions where available and distinguishes **Model default** from a
+**PinDeck default** fallback. Models without effort controls show a disabled Effort N/A selector.
+Effort choices are remembered per provider/model in `effortPreferences` in config.json. A model with
+no saved choice uses its default; an unsupported saved choice falls back to the current default.
+The picker defaults to GPT-6 models (including 6.x) and the newest discovered Fable, Opus, Sonnet,
+and Haiku model in each family. Claude versions are compared numerically from discovered names;
+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.
+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.
+
+Changing models within a provider resumes that provider's conversation. Changing providers opens
+**Switch with summary**, **Start fresh**, and **Cancel**. A switch prepares the new backend before
+replacing the old one. Chat remains visible with a divider, and deck files and undo/redo are retained.
+Switching back to a provider creates another new session; it does not silently restore old context.
+
+The current handover is a local, bounded digest of recent user/assistant messages and notices, not an
+additional model-generated summary. It excludes tool output, needs no extra inference request, and is
+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`):
 
 ```json
 {
+  "provider": "claude",
   "model": "sonnet",
   "effort": "medium"
 }
 ```
 
-`model` is `opus` or `sonnet`; `effort` is `low`, `medium`, `high`, `xhigh` or `max`. A choice in the
-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.
+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.
+
+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:
+
+```bash
+node server.mjs /path/to/a/deck-copy --port 5183 --provider codex
+```
+
+## Backend permissions and attachments
+
+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.
+
+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.
 
 ## Keeping the ids out of git
 
@@ -117,7 +210,7 @@ node cli.mjs git-setup path/to/deck
 
 This adds a line like `path/to/deck/*.html filter=pindeck-ids` to `.gitattributes` (commit it) and
 defines the filter in the clone's git config: git then strips the ids whenever it reads the deck's
-HTML. The ids stay in the file on disk, where PinDeck and Claude need them, but commits and diffs
+HTML. The ids stay in the file on disk, where PinDeck and the assistant need them, but commits and diffs
 never contain them, and a change that only adds ids does not show in `git status`. Your own edits
 show and commit as usual. Clones without the filter configured simply see the file as it is.
 
@@ -127,24 +220,24 @@ show and commit as usual. Clones without the filter configured simply see the fi
 |---|---|
 | Select, move, resize | Select mode (`V`, the default): click an element to select it, drag to move, pull a handle to resize. Elements snap to the slide edges and centre, the footer rule and other elements (pink guides); hold `Alt` to turn snapping off, `Shift` to move along one axis. Images keep their aspect ratio (`Shift` toggles). Arrow keys nudge by 1 px, `Shift`+arrows by 10 px. `Delete` removes the selected element after a confirmation; a picture goes with its caption, and files nothing else in the deck uses can be deleted with it. `⌘Z` brings both back. |
 | Edit text | Double-click the text (or select it and press `Enter`). The element shows its source, so math appears as TeX, e.g. `\(\mu=0.5\)`. `Enter` or a click elsewhere saves, `Esc` cancels, `Shift+Enter` adds a line break, `⌘B` / `⌘I` make text bold or italic. In a bullet, `Enter` splits it at the cursor and continues in a new bullet below; `Enter` on an empty new bullet removes it and stops. Pasted text arrives as plain text. Table cells are edited one at a time. |
-| Undo, redo | `⌘Z` / `⇧⌘Z` or the toolbar arrows. One history for your hand edits and Claude's changes. |
+| 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 Claude | 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. |
+| 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 Claude; the conversation continues. **New chat** starts over. |
+| 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. |
-| 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 Claude can improve the complex ones; see [PowerPoint import](#powerpoint-import). `⌘Z` removes them again, with their figures. |
+| 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. |
 | 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". |
+| 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. |
+| 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". |
 | 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. |
 
-You can also edit `index.html` or `theme.css` in any editor; the slide reloads, and Claude is told
+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.
 
 ## PowerPoint import
@@ -179,10 +272,10 @@ The import keeps what can be carried over exactly and makes pictures of the rest
   accents, braces, matrices and the bold, italic and double-struck math letters are converted.
 * **Hidden slides** stay hidden (`data-visibility="hidden"`).
 
-**Hand-off to Claude.** Slides the import can only approximate are tagged *complex* in the dialog:
+**Hand-off to the assistant.** Slides the import can only approximate are tagged *complex* in the dialog:
 diagrams of many shapes or tables with shapes over them that became pictures, pictures placed inside
 text (often equations as images), build steps on parts of a diagram, slides without a title, and
-text that had to shrink to fit. With **Then ask Claude to improve the complex slides** ticked, Claude
+text that had to shrink to fit. With **Then ask the assistant to improve the complex slides** ticked, the assistant
 gets these slides right after the import, each with a picture of the original slide and the texts of
 its diagrams, and rebuilds diagrams as SVG, equations as TeX and tables as HTML in the deck's style.
 The request shows in the chat like your own messages, and its changes can be undone as usual.
@@ -194,12 +287,12 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 * **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
-  kept in `~/.pindeck/decks/<deck>/backups/`. Ids survive edits, so pins, layout reports and Claude all name
+  kept in `~/.pindeck-v3/decks/<deck>/backups/`. Ids survive edits, so pins, layout reports and the assistant all name
   the same element.
 * **Hand edits.** A move is stored as the CSS `translate` property and a resize as `width`/`height`,
   inline on the element in `index.html`. `translate` moves an element without changing the layout
   around it, for elements in the flow and absolutely positioned ones alike. Only that one style
-  attribute is rewritten; the rest of the file stays as it was. Claude gets a note about each hand
+  attribute is rewritten; the rest of the file stays as it was. The assistant gets a note about each hand
   edit. Brand-locked elements (footer, logos) cannot be selected.
 * **Text edits.** While you type, the element holds its source HTML from `index.html`, not the
   rendered slide, so math stays TeX and nothing that KaTeX or the deck script generates ends up in
@@ -211,26 +304,25 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
   locked.
 * **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
+  (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
   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
-  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.
+  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.
 
 ## 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. |
-| `cli.mjs` | `layout`, `shot`, `slides`, `pdf handout` / `pdf presentation` and `pdf-figure` commands for Claude (and for you), and `git-setup`. |
+| `server.mjs` | Local server (127.0.0.1 only, random token per run): UI, deck files, events, backend session, undo, CLI endpoints. |
+| `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. |
@@ -239,25 +331,26 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 | `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/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/system-prompt.md` | What Claude is told about the editor. |
+| `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/system-prompt.md` | What the assistant is told about the editor. |
 | `CONTRIBUTING.md` | How to report bugs and contribute. |
 | `docs/` | Images for this README. |
 | `LICENSE` | MIT. |
 
 ## Current Limitations
 
-* Text inside inline SVG diagrams cannot be edited in place; pin it and ask Claude.
+* 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 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.
+* 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.
 
 ## Versions
 
-* **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.
+* **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.
 
 * **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
@@ -308,7 +401,7 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 * **1.11.1**: the Hide and Show icons sit at the same height.
 * **1.11**: hide and show slides (eye in the slide list, toolbar button, `H`); hidden slides are skipped
   when presenting and in PDFs unless the export includes them.
-* **1.10**: model and effort without "Default" entries (default Sonnet, medium), set in `~/.pindeck/config.json`.
+* **1.10**: model and effort without "Default" entries (default Sonnet, medium), set in `~/.pindeck-v3/config.json`.
 * **1.9**: `node cli.mjs git-setup` keeps PinDeck's ids out of git with a clean filter; id-only changes no longer show in `git status`.
 * **1.8**: ＋ New slide (content slide, section divider, duplicate); model (Opus, Sonnet) and effort menu in the chat header; a + menu in the chat for files and screenshots.
 * **1.7**: `Delete` removes the selected element after a confirmation, a picture with its caption, and optionally the files nothing else uses; undo restores elements and files. Claude reads attached images directly instead of trying to convert them; refused commands are explained in the chat.
@@ -325,7 +418,7 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 Bug reports, ideas, example decks and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md)
 explains how to report a bug, set up PinDeck for development, test a change by hand, and what a pull
 request should contain. In short: no npm dependencies, deck files are edited only where they must
-change, Claude's permissions stay narrow, and the README describes what users see.
+change, both backends’ permissions stay narrow, and the README describes what users see.
 
 ## License
 

package/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/* PinDeck command line: Claude's self-checks (need the PinDeck server running) and git setup.
+/* PinDeck command line: the assistant's self-checks (need the PinDeck server running) and git setup.
 
    node cli.mjs layout <slide>...   measured layout and issues of one or more slides
                                     (add --issues for the issues only: layout 9 10 11 --issues)
@@ -27,7 +27,7 @@ const arg = rest[0];
 
 /* git-setup: a git "clean" filter strips PinDeck's data-eid attributes whenever git reads the deck's
    HTML, so ids never reach a commit and id-only changes do not show in `git status`. The ids stay in
-   the file on disk, where PinDeck and Claude need them. The filter is plain sed, so it does not depend
+   the file on disk, where PinDeck and the assistant need them. The filter is plain sed, so it does not depend
    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'`;
@@ -66,14 +66,14 @@ 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");
+    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 {}
 }
 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 Claude needs no shell loop or pipe (which PinDeck refuses) */
+/* 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])]
   : cmd === "pdf" ? [{ slide: rest[0] || "handout", ...(rest[1] === "all" ? { all: "1" } : {}) }]
   : cmd === "slides" ? [{}] : (slides.length ? slides : ["current"]).map((slide) => ({ slide }));

package/lib/agent-process.mjs

@@ -0,0 +1,49 @@
+/* JSON-line subprocess transport. Requests and notifications never outlive their process. */
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+export class AgentProcess {
+  constructor({ binary, args, cwd, env, onMessage = () => {}, onExit = () => {}, onStderr = () => {} }) {
+    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'] });
+    readline.createInterface({ input: this.proc.stdout }).on('line', line => {
+      if (this.closed) return;
+      let m; try { m = JSON.parse(line); } catch { return; }
+      const id = m.type === 'control_response' ? m.response?.request_id : m.id;
+      const pending = this.pending.get(id);
+      if (pending && (m.type === 'control_response' || !m.method)) {
+        this.pending.delete(id); clearTimeout(pending.timer);
+        const err = m.error || (m.response?.subtype === 'error' && m.response.error);
+        if (err) pending.reject(new Error(err.message || String(err)));
+        else pending.resolve(m.type === 'control_response' ? m.response.response : m.result);
+      } else this.onMessage(m);
+    });
+    this.proc.stderr.on('data', d => { this.stderr = (this.stderr + d).slice(-2000); onStderr(String(d)); });
+    this.proc.stdin.on('error', e => this.end(e));
+    this.proc.on('error', e => this.end(e));
+    this.proc.on('exit', (code, signal) => this.end(new Error(`Agent stopped (${signal || code}). ${this.stderr.trim()}`)));
+  }
+  write(value) { if (this.closed) throw new Error('Agent is not running.'); this.proc.stdin.write(JSON.stringify(value) + '\n'); }
+  request(method, params, { claude = false, timeout = 30000 } = {}) {
+    const id = claude ? `pindeck-${++this.seq}` : ++this.seq;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`Agent timed out: ${method}`)); }, timeout);
+      this.pending.set(id, { resolve, reject, timer });
+      try { this.write(claude ? { type: 'control_request', request_id: id, request: { subtype: method, ...params } } : { id, method, params }); }
+      catch (e) { clearTimeout(timer); this.pending.delete(id); reject(e); }
+    });
+  }
+  end(error) {
+    if (this.closed) return;
+    this.closed = true;
+    for (const p of this.pending.values()) { clearTimeout(p.timer); p.reject(error); }
+    this.pending.clear(); this.onExit(error);
+  }
+  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();
+  }
+}

package/lib/agent-tools.mjs

@@ -0,0 +1,85 @@
+/* All Codex writes pass through this host-owned bridge, never through a shell. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+const text = value => ({ type: 'inputText', text: String(value) });
+const schema = properties => ({ type: 'object', properties, additionalProperties: false });
+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_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 }) {
+  const deck = fs.realpathSync(deckDir);
+  const roots = [deck, ...readDirs.map(d => fs.realpathSync(d))];
+  const inside = (root, file) => file === root || file.startsWith(root + path.sep);
+  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.');
+    // 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 && fs.existsSync(full) && (fs.lstatSync(full).isSymbolicLink() || fs.statSync(full).nlink !== 1)) throw new Error('Linked files cannot be edited.');
+    return full;
+  }
+  async function command(name, args, signal) {
+    if (!['layout', 'shot', 'slides', 'pdf', 'pdf-figure'].includes(name) || !Array.isArray(args) || args.length > 100 || args.some(a => typeof a !== 'string' || a.length > 4096 || a.includes('\0'))) throw new Error('Invalid PinDeck command.');
+    if (name === 'pdf-figure') {
+      checked(args[0]);
+      // Host renderer can create figures: disallow symlinked output directories too.
+      const figures = path.join(deck, 'figures');
+      if (fs.existsSync(figures) && fs.realpathSync(figures) !== figures) throw new Error('Linked figures directory is not allowed.');
+      for (const a of args.slice(2).filter(a => /^figures\//.test(a))) {
+        const full = path.resolve(deck, a);
+        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 });
+    return stdout;
+  }
+  async function read(file, page, offset, signal) {
+    const full = checked(file), ext = path.extname(full).toLowerCase();
+    if (ext === '.pdf') {
+      if (!Number.isInteger(page) || page < 1) throw new Error('Specify a PDF page number, starting at 1.');
+      const result = await command('pdf-figure', [full, String(page)], signal);
+      const png = renderedImagePath(result);
+      if (!png) throw new Error('PDF renderer did not return an image path.');
+      let words = '';
+      if (process.platform === 'darwin' && pdfTextFile) {
+        try { words = (await exec('/usr/bin/osascript', ['-l', 'JavaScript', pdfTextFile, full, String(page)], { signal, timeout: 30000, maxBuffer: 1024 * 1024 })).stdout; }
+        catch (e) { if (signal?.aborted) throw e; words = 'Text extraction unavailable; inspect the page image.'; }
+      }
+      return [text(words), ...await read(png, undefined, 0, signal)];
+    }
+    if (!fs.statSync(full).isFile()) throw new Error('Read a file, not a directory.');
+    if (fs.statSync(full).size > 12 * 1024 * 1024) throw new Error('File exceeds the 12 MB read limit.');
+    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.');
+    const start = Number.isInteger(offset) && offset >= 0 ? offset : 0;
+    return [text(data.toString('utf8').slice(start, start + 120000))];
+  }
+  return async (name, args, signal) => {
+    signal?.throwIfAborted();
+    if (name === 'pindeck_read') return read(args.path, args.page, args.offset, signal);
+    if (name === 'pindeck_command') return [text(await command(args.command, args.args, signal))];
+    if (name === 'pindeck_edit') {
+      const full = checked(args.path, true);
+      if (typeof args.oldText !== 'string' || !args.oldText || typeof args.newText !== 'string' || args.newText.length > 2e6) throw new Error('Supply nonempty oldText and replacement text.');
+      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))];
+    }
+    throw new Error('Unknown PinDeck tool.');
+  };
+}