pindeck 0.0.0-stage → 2.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emanuël A. P. Habets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,322 @@
-# Temporary Holding Version
+# PinDeck
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**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.
+
+![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)
+
+*The example deck in PinDeck. Claude has lined up the three numbers from the first request and
+checked the layout; the next request, still being typed, refers to the new pins 1 and 2.*
+
+## 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
+  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
+  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.
+
+## Quick start
+
+```bash
+npx pindeck path/to/deck        # from npm
+
+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
+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
+`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
+optional `<meta>` tags in the deck's `<head>` tell it about the design:
+
+```html
+<meta name="pindeck:footer-top" content="652">          <!-- y of the footer rule: content must stay above it -->
+<meta name="pindeck:locked" content=".slide-foot, .logo"> <!-- brand elements that cannot be selected or moved -->
+```
+
+Hidden slides use reveal.js's `data-visibility="hidden"`. If the deck numbers its slides itself (as
+the example's `deck.js` does for the footer), count only slides without that attribute, or the
+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.
+
+## Making your own template
+
+PinDeck has no template generator; a template is simply a deck folder. Start from a copy of the example:
+
+```bash
+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
+   `assets/` too.
+2. **Everything else in `theme.css`:** type sizes, spacing, layouts and components. This can be done
+   in PinDeck with Claude.
+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.
+   The example's `CLAUDE.md` calls `../cli.mjs` and `../server.mjs`; fix these paths if the template
+   does not sit next to PinDeck.
+
+**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
+`.kicker` or `.sub`) and `.slide-body`. Imported tables take the class of the deck's first table,
+and imported audio copies the first `.demo-row` (with a `data-target`). Without a title or section
+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:
+
+```json
+{
+  "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.
+
+## 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:
+
+```bash
+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
+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.
+
+## Working with it
+
+| Action | How |
+|---|---|
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| 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". |
+| 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
+the files changed. CSS changes are swapped in without a reload.
+
+## PowerPoint import
+
+The import keeps what can be carried over exactly and makes pictures of the rest:
+
+* **Text becomes HTML** in the deck's layouts: the title (and the subtitle, as a `.sub` line or a
+  kicker, as the deck does it), bullets with their levels, numbered lists, bold, italics, coloured words (as `.hl`),
+  superscripts, web and mail links and line breaks, other text as paragraphs, references at the bottom of a slide
+  as `.refs`, and the speaker notes. Side notes and labels clearly smaller than the body text stay smaller.
+* **Tables become HTML tables** with the class of the deck's own tables, merged header cells, header rows
+  and a caption from the text above them. Cells merged down in the body become a label on the group's
+  first row with empty cells below it, and each later group's first row gets `class="group"`. A table with shapes drawn over it (e.g. boxes marking rows)
+  is kept as a picture instead.
+* **Build steps:** shapes and paragraphs that appear (or disappear) on a click become reveal.js
+  fragments in the same order, also when several things appear on one click. A picture made of several
+  shapes appears on a click only if all of its shapes do.
+* **Audio** goes into the deck's own audio player (a copy of its first `.demo-row`, with a waveform made
+  from the sound), labelled with the nearest text on the slide; without such a player, plain players.
+  **Video** keeps its place, with its poster frame.
+  The first slide is filled into the deck's title slide (title, subtitle, authors, event, institute)
+  and PowerPoint section headers into its section divider.
+* **Pictures are copied** to `figures/` (`<file>-s04-1.png`, ...).
+* **Everything drawn** (diagrams built from shapes and arrows, charts, pictures with labels on
+  them, EMF graphics) becomes a picture cut from the slide as PowerPoint renders it. For this PinDeck
+  asks PowerPoint (or else Keynote) to save the presentation as a PDF; macOS asks once whether PinDeck
+  may control the app. The same PDF gives the thumbnails in the import dialog.
+* **Layout:** blocks that sit side by side become `.cols` with the slide's proportions, others are
+  stacked top to bottom; figures and, if needed, the text are scaled so that the slide fits.
+* **Equations** (PowerPoint's equation editor) become TeX for the deck's KaTeX: `\( \)` in the text,
+  `\[ \]` on their own line; fractions, scripts, roots, sums and integrals, functions and limits,
+  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:
+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
+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.
+
+Without PowerPoint or Keynote (or on other systems than macOS) only the text and the pictures are imported.
+
+## How it works
+
+* **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
+  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
+  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
+  the file. On save only that element's content is replaced. Browser editing artefacts are cleaned
+  up: `<b>`/`<i>` become `<strong>`/`<em>`, styled spans from formatting are removed, trailing
+  `<br>`s dropped.
+* **Pins.** A pin records the element id, its box in slide coordinates (1280 x 720), the click
+  point, the clicked word and, in tables, the cell. Pins on the footer or logos are marked as
+  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
+  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.
+
+## 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`. |
+| `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/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. |
+| `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.
+* 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.
+
+## Versions
+
+* **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
+  server cannot be reached is reported, and the edits after it (drags, text, bullets, notes) are still
+  saved instead of being dropped without a word. Stop no longer ends a turn started after it. Slides in
+  vertical stacks keep their order and ids, and a slide moved to the end goes after a final stack.
+  A first automated test suite (`npm test`).
+* **2.8**: a code review: safer, sturdier, and a PowerPoint import that keeps more. The server answers
+  only to `127.0.0.1` and `localhost`, so another website cannot read the editor's token (DNS
+  rebinding). A missing `claude` command ends the turn with a message instead of leaving the chat
+  working forever, and a replaced Claude Code process can no longer end the next turn. Esc in the import
+  dialog no longer repeats the last import, and an import never overwrites edits made while it runs. The
+  PowerPoint import keeps animations that play by themselves off the clicks, wraps shapes that come and
+  go in fragments of their own, skips hidden shapes and `javascript:` links, reads packages with
+  absolute part names, takes only the first line of a subtitle placeholder as the subtitle, keeps
+  equations in titles and notes, writes numbered lists as `<ol>`, keeps the text of coloured boxes
+  without PowerPoint or Keynote, and makes valid TeX of escaped text, equation arrays, odd delimiters
+  and primes after superscripts. Damaged WAV or XML parts no longer stop an import. The toolbar wraps
+  instead of overlapping when the slide area is narrow.
+* **2.7**: attach PDFs to chat messages (a figure, a table, a paper or report). They stay outside the deck; Claude reads
+  them, rebuilds tables as HTML and renders figures into `figures/` with `cli.mjs pdf-figure` (a page or a cropped part, macOS).
+* **2.6.1**: tinted table rows are one rectangle per row instead of one per cell, so PDF viewers show no hairline seams between the cells.
+* **2.6**: booktabs-style tables in both example decks (rules at top, under the header and at the bottom,
+  short rules under grouped headings, numbers right-aligned); the import writes row groups without `rowspan`.
+* **2.5**: a notes field under the slide for the speaker notes, saved as hand edits with undo.
+* **2.4.1**: the layout check judges a plain container by what it draws (its children), not by its box, so
+  a body stretched down to the references no longer counts as an overlap; a real overlap is reported once,
+  for the outermost pair.
+* **2.4**: move slides by dragging them in the slide list; undo puts them back.
+* **2.3**: lessons from a PowerPoint hand-off. Claude Code runs without settings files or MCP servers
+  (the deck's `CLAUDE.md` goes into the system prompt instead), so stray allow rules no longer let it run
+  scripts; `layout` takes several slides and `--issues`; the chat no longer labels a refused script as a
+  layout check; shared SVG arrowheads live outside the slides, where hidden slides cannot hide them.
+* **2.2**: PowerPoint import with equations as TeX for KaTeX, and the hand-off to Claude: complex slides are
+  tagged in the import dialog and, if wanted, improved by Claude right after the import, with a picture of
+  each original slide.
+* **2.1**: PowerPoint import with build steps (fragments in click order), HTML tables in the deck's table
+  style, audio in the deck's player with a waveform, video with its poster, coloured words as `.hl`.
+* **2.0**: import slides from PowerPoint (`.pptx`): text as HTML in the deck's layouts, pictures copied,
+  diagrams, tables and charts as pictures cut from PowerPoint's rendering; thumbnails in the import
+  dialog; undo removes the imported slides and their figures.
+* **1.12.1**: the PinDeck pin as the browser tab icon (SVG, with PNG versions for Safari).
+* **1.12**: double-clicking an equation opens its text with the equation's TeX selected, also for
+  equations on their own line and for parts KaTeX draws as SVG (roots, wide accents, arrows).
+* **1.11.3**: a calmer interface: no slide count, no Hide/Show button in the header (eye and `H`
+  remain), no messages or chat entries for hiding and showing, shorter export descriptions.
+* **1.11.2**: the header shows the deck's name instead of the slide title; the browser tab is named after the deck.
+* **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.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.
+* **1.6**: attach figures and audio to chat messages (file picker, drag and drop, paste); audio gets a waveform SVG; files dropped on a slide carry their position.
+* **1.5**: PDF export (handout and presentation with build steps on separate pages).
+* **1.4**: decks describe their footer and locked brand elements with `<meta name="pindeck:...">` tags; the layout check ignores invisible elements. New public example deck: `ocean-example/`.
+* **1.3**: `Enter` in a bullet starts a new bullet (split at the cursor); empty new bullets are removed again.
+* **1.2**: text editing on the slide (double-click or Enter), with math as TeX, table cells, bold and italic, plain-text paste; text edits are part of the undo history and reported to Claude.
+* **1.1**: select, drag, resize and nudge with snapping guides; one undo/redo history for hand edits and Claude's changes; the selected element is sent to Claude.
+* **1.0**: pins, chat with Claude Code, layout reports, element ids, diff and undo.
+
+## Contributing
+
+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.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/cli.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/* PinDeck command line: Claude'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)
+   node cli.mjs shot <slide>...     screenshots with pin markers; prints the PNG paths
+   node cli.mjs slides              slide numbers and ids
+   node cli.mjs pdf handout         PDF with one page per slide (build steps in their final state)
+   node cli.mjs pdf presentation    PDF with one page per build step
+                                    (add "all" to include hidden slides: pdf handout all)
+   node cli.mjs pdf-figure <pdf> <page> [x,y,w,h] [figures/name.png] [--width 1600]
+                                    a page of an attached PDF, or a box of it (fractions of the page
+                                    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)
+
+   <slide> is a slide id (data-eid), a slide number (1-based) or "current". */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const [cmd, ...rest] = process.argv.slice(2);
+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
+   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 || ".");
+  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`;
+  const attrFile = path.join(root, ".gitattributes");
+  const attrs = fs.existsSync(attrFile) ? fs.readFileSync(attrFile, "utf8") : "";
+  const line = `${pattern} filter=pindeck-ids`;
+  const added = !attrs.split("\n").some((l) => l.trim() === line);
+  if (added) fs.writeFileSync(attrFile, attrs + (attrs && !attrs.endsWith("\n") ? "\n" : "") + line + "\n");
+  console.log(`Git filter "pindeck-ids" configured in ${root} (local git config).`);
+  console.log(added ? `Added "${line}" to .gitattributes; commit that file.` : `.gitattributes already has "${line}".`);
+  process.exit(0);
+}
+const issuesOnly = cmd === "layout" && rest.includes("--issues");
+const slides = rest.filter((a) => a !== "--issues");
+if (!["layout", "shot", "slides", "pdf", "pdf-figure"].includes(cmd)) {
+  console.error("Usage: node cli.mjs layout|shot <slide>... [--issues]  |  node cli.mjs slides  |  node cli.mjs pdf handout|presentation  |  " +
+    "node cli.mjs pdf-figure <pdf> <page> [x,y,w,h] [figures/name.png] [--width px]  |  node cli.mjs git-setup [deck]");
+  process.exit(2);
+}
+/* pdf-figure: the box and the output name are told apart by their form, so their order does not matter */
+function figureQuery(args) {
+  const w = args.indexOf("--width"), width = w >= 0 ? args.splice(w, 2)[1] : "";
+  const [file = "", page = "1", ...more] = args;
+  return { file: file && path.resolve(file), page, width,
+    box: more.find((a) => /^[\d.]+(,[\d.]+){3}$/.test(a)) || "", out: more.find((a) => /\.png$/i.test(a)) || "" };
+}
+
+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 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) */
+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 }));
+let ok = true;
+for (const q of queries) {
+  let res, out;
+  try {
+    res = await fetch(`${url}/api/${cmd}?` + new URLSearchParams(q), { headers: { "x-editor-token": token } });
+    out = await res.text();
+  } catch {
+    console.error("Cannot reach the PinDeck server at " + url + ". Is it running?");
+    process.exit(1);
+  }
+  if (res.ok && issuesOnly) {
+    const lines = out.split("\n"), i = lines.findIndex((l) => l.startsWith("Issues"));
+    out = [lines[0], ...lines.slice(i)].join("\n");
+  }
+  (res.ok ? console.log : console.error)(out);
+  ok &&= res.ok;
+}
+process.exit(ok ? 0 : 1);

package/lib/claude.mjs

@@ -0,0 +1,70 @@
+/* A long-running Claude Code process in stream-json mode.
+
+   One process serves the whole chat: messages are written to stdin as JSON lines,
+   events come back on stdout. It runs under the user's normal Claude login. */
+
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+
+export class ClaudeSession {
+  constructor({ cwd, args, env, onEvent, onExit, onStderr }) {
+    Object.assign(this, { cwd, args, env, onEvent, onExit, onStderr });
+    this.proc = null;
+    this.sessionId = null;
+    this.reqId = 0;
+  }
+
+  get running() { return !!this.proc; }
+
+  start(resumeId) {
+    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"],
+    });
+    this.proc = proc;
+    readline.createInterface({ input: proc.stdout }).on("line", (line) => {
+      if (this.proc !== proc && this.proc) return;   // a stopped process that is still talking
+      if (!line.trim()) return;
+      let ev;
+      try { ev = JSON.parse(line); } catch { return; }
+      if (ev.session_id) this.sessionId = ev.session_id;
+      this.onEvent(ev);
+    });
+    proc.stderr.on("data", (d) => this.onStderr?.(String(d)));
+    proc.stdin.on("error", () => {});   // writing to a process that has died: its exit is reported below
+    // a process that could not start (no `claude` on the PATH) reports an error and never exits
+    let ended = false;
+    const end = (code, signal) => {
+      if (ended) return;
+      ended = true;
+      // stale: a newer process has been started since (model change, new chat); its turn is not ours to end
+      const stale = this.proc !== proc && this.proc !== null;
+      if (this.proc === proc) this.proc = null;
+      this.onExit(code, signal, { stale });
+    };
+    proc.on("error", (err) => { this.onStderr?.(String(err)); if (proc.pid === undefined) end(null, null); });
+    proc.on("exit", end);
+  }
+
+  send(content) {
+    this.#write({ type: "user", message: { role: "user", content } });
+  }
+
+  interrupt() {
+    this.#write({ type: "control_request", request_id: `int-${++this.reqId}`, request: { subtype: "interrupt" } });
+  }
+
+  stop() {
+    if (!this.proc) return;
+    const p = this.proc;
+    this.proc = null;
+    p.stdin.end();
+    setTimeout(() => p.kill("SIGTERM"), 1500);
+  }
+
+  #write(obj) {
+    if (!this.proc) throw new Error("Claude Code is not running");
+    this.proc.stdin.write(JSON.stringify(obj) + "\n");
+  }
+}

package/lib/diff.mjs

@@ -0,0 +1,46 @@
+/* Line diff (LCS) with unified-style hunks, good enough for slide-sized files. */
+
+export function diffLines(a, b) {
+  const A = a.split("\n"), B = b.split("\n");
+  // trim common prefix/suffix so the LCS table stays small
+  let pre = 0;
+  while (pre < A.length && pre < B.length && A[pre] === B[pre]) pre++;
+  let suf = 0;
+  while (suf < A.length - pre && suf < B.length - pre && A[A.length - 1 - suf] === B[B.length - 1 - suf]) suf++;
+  const a2 = A.slice(pre, A.length - suf), b2 = B.slice(pre, B.length - suf);
+  const n = a2.length, m = b2.length;
+  const L = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+  for (let i = n - 1; i >= 0; i--)
+    for (let j = m - 1; j >= 0; j--)
+      L[i][j] = a2[i] === b2[j] ? L[i + 1][j + 1] + 1 : Math.max(L[i + 1][j], L[i][j + 1]);
+  const ops = [];
+  for (let k = 0; k < pre; k++) ops.push([" ", A[k], k + 1, k + 1]);
+  let i = 0, j = 0;
+  while (i < n || j < m) {
+    if (i < n && j < m && a2[i] === b2[j]) { ops.push([" ", a2[i], pre + i + 1, pre + j + 1]); i++; j++; }
+    else if (i < n && (j === m || L[i + 1][j] >= L[i][j + 1])) { ops.push(["-", a2[i], pre + i + 1, null]); i++; }
+    else { ops.push(["+", b2[j], null, pre + j + 1]); j++; }
+  }
+  for (let k = 0; k < suf; k++) ops.push([" ", A[A.length - suf + k], A.length - suf + k + 1, B.length - suf + k + 1]);
+  return ops;
+}
+
+export function unifiedDiff(a, b, file, context = 2) {
+  const ops = diffLines(a, b);
+  let added = 0, removed = 0;
+  const changed = ops.map((o, k) => (o[0] !== " " ? k : -1)).filter((k) => k >= 0);
+  if (!changed.length) return { text: "", added, removed };
+  const keep = new Set();
+  for (const k of changed) for (let d = -context; d <= context; d++) keep.add(k + d);
+  const lines = [`--- ${file}`, `+++ ${file}`];
+  let last = -2;
+  ops.forEach((o, k) => {
+    if (!keep.has(k)) return;
+    if (k !== last + 1) lines.push(`@@ line ${o[2] ?? o[3]} @@`);
+    lines.push(o[0] + o[1]);
+    if (o[0] === "+") added++;
+    if (o[0] === "-") removed++;
+    last = k;
+  });
+  return { text: lines.join("\n"), added, removed };
+}