pindeck 2.9.0 → 2.10.0

package/README.md

@@ -21,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.
@@ -45,17 +45,21 @@ node server.mjs ocean-example   # or from source, with the example deck in this
 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.
-
-PinDeck adds element ids to the deck's `index.html` 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`. 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
@@ -70,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:
@@ -91,6 +129,19 @@ cp -R ocean-example my-template
    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
 `.kicker` or `.sub`) and `.slide-body`. Imported tables take the class of the deck's first table,
@@ -113,6 +164,18 @@ 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
@@ -146,10 +209,19 @@ 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, with Chrome or Chromium installed on the server, screenshots and PDF export
-(`PINDECK_LINUX_CHROME=0` turns these off). What does not, with the reason shown in the editor (hover
-over "Server: Linux (beta)"): pictures of PDF pages (`pdf-figure`, needs macOS PDFKit) and the
-PowerPoint import. Claude is told which commands are not available. Chromium from snap may not be
+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.
 
@@ -191,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. |
 
@@ -269,12 +341,15 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 * **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. They first check
+* **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
@@ -293,7 +368,7 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 | `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. |
@@ -306,16 +381,44 @@ 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): no PDF page pictures or PowerPoint import yet; tested hosts are listed in the release notes.
+* 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.

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". */
 
@@ -32,6 +32,7 @@ const arg = rest[0];
 if (cmd === "git-setup") {
   const FILTER = `sed 's/ data-eid="[^"]*"//g'`;
   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;

package/lib/capabilities.mjs

@@ -1,8 +1,9 @@
 /* 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 and live reload. Features that need macOS
-   (PDFKit, PowerPoint/Keynote, afconvert) are off with a reason. Chrome features (screenshots, headless
+   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. */
 
@@ -71,11 +72,16 @@ export function detectCapabilities({ platform = process.platform, env = process.
   caps.headlessLayout = chromeCap;
   caps.pdfExport = chromeCap;
 
-  caps.pdfPages = mac ? on() : off("Rendering PDF pages to pictures needs macOS (PDFKit). Attached PDFs can still be read.");
-  caps.pptxImport = mac ? on() : off("PowerPoint import is not available on Linux in this beta.");
-  caps.pptxPictures = mac && OFFICE_APPS.some((a) => fs.existsSync(a)) ? on()
-    : off(mac ? "Pictures of PowerPoint slides need PowerPoint or Keynote." : "Pictures of PowerPoint slides need macOS with PowerPoint or Keynote.");
-  caps.audioConvert = mac ? on() : off("Waveforms for audio other than WAV need macOS (afconvert).");
+  // 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;
 }
 

package/lib/deck-files.mjs

@@ -54,3 +54,41 @@ export function revision(dir, files) {
   }
   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 };
+}

package/lib/eids.mjs

@@ -145,8 +145,97 @@ function find(node, pred) {
   return hit;
 }
 
-/* Slides are leaf <section>s inside .slides; vertical-stack containers are not slides. */
+/* ---- Decks made without reveal.js ----------------------------------------------------------------
+   A deck names its slides with <meta name="pindeck:slides" content="main.deck > section.slide">, a CSS
+   selector, and its size with <meta name="pindeck:size" content="1440x1080">. Selectors stay simple, so
+   the server and the browser find the same slides: tag names, #id, .class, [attr] and [attr="value"],
+   joined by spaces (descendant) or ">" (child), in a comma-separated list. */
+
+const metaOf = (tree, name) => {
+  const m = find(tree, (c) => c.name === "meta" && c.attrs.name?.value.trim().toLowerCase() === `pindeck:${name}`);
+  return m ? decode(m.attrs.content?.value || "").trim() || null : null;
+};
+/* The deck's slide selector, or null for a reveal.js deck */
+export const slideSelector = (tree) => metaOf(tree, "slides");
+/* The deck's slide size from <meta name="pindeck:size">: { width, height } or null */
+export function deckSize(tree) {
+  const m = /^(\d{2,5})\s*[x×*,\s]\s*(\d{2,5})$/i.exec(metaOf(tree, "size") || "");
+  return m ? { width: +m[1], height: +m[2] } : null;
+}
+
+const IDENT = "-?[_a-zA-Z\\u00a0-\\uffff][\\w\\u00a0-\\uffff-]*";
+const COMPOUND = new RegExp(`^(?:(\\*|${IDENT})|#(${IDENT})|\\.(${IDENT})|\\[\\s*(${IDENT})\\s*(?:=\\s*(?:"([^"]*)"|'([^']*)'|(${IDENT}))\\s*)?\\])`);
+/* "main.deck > section.slide, aside.extra" -> one list of compounds and combinators per selector.
+   Throws with the part it cannot read (pseudo-classes, +, ~ ...). */
+export function parseSelector(sel) {
+  const parts = [];   // top-level commas only: not inside [attr="a,b"]
+  let quote = null, depth = 0, from = 0;
+  for (let i = 0; i < sel.length; i++) {
+    const c = sel[i];
+    if (quote) { if (c === quote) quote = null; }
+    else if (c === '"' || c === "'") quote = c;
+    else if (c === "[") depth++;
+    else if (c === "]") depth--;
+    else if (c === "," && !depth) { parts.push(sel.slice(from, i)); from = i + 1; }
+  }
+  parts.push(sel.slice(from));
+  return parts.map((part) => {
+    const steps = [];   // [{ tag, ids, classes, attrs }, ">" | " ", { ... }, ...]
+    let s = part.trim(), cur = null;
+    if (!s) throw new Error(`empty selector in "${sel}"`);
+    while (s) {
+      const ws = /^\s+/.exec(s);
+      const gt = /^\s*>\s*/.exec(s);
+      if (gt) { if (!cur) throw new Error(`"${part.trim()}" starts with ">"`); steps.push(">"); cur = null; s = s.slice(gt[0].length); continue; }
+      if (ws) { steps.push(" "); cur = null; s = s.slice(ws[0].length); continue; }
+      const m = COMPOUND.exec(s);
+      if (!m) throw new Error(`"${s.slice(0, 20)}" in "${part.trim()}" is not supported (use tags, #id, .class, [attr], spaces and ">")`);
+      if (!cur) { cur = { tag: null, ids: [], classes: [], attrs: [] }; steps.push(cur); }
+      if (m[1]) {
+        if (cur.tag || cur.ids.length || cur.classes.length || cur.attrs.length) throw new Error(`a tag name must come first in "${part.trim()}"`);
+        cur.tag = m[1] === "*" ? null : m[1].toLowerCase();
+      }
+      else if (m[2]) cur.ids.push(m[2]);
+      else if (m[3]) cur.classes.push(m[3]);
+      else cur.attrs.push({ name: m[4].toLowerCase(), value: m[5] ?? m[6] ?? m[7] ?? null });
+      s = s.slice(m[0].length);
+    }
+    if (typeof steps.at(-1) === "string") throw new Error(`"${part.trim()}" ends with a combinator`);
+    return steps;
+  });
+}
+function compoundMatches(node, c) {
+  if (!node.attrs) return false;   // the root
+  if (c.tag && node.name !== c.tag) return false;
+  if (c.ids.some((id) => node.attrs.id?.value !== id)) return false;
+  const cls = classesOf(node);
+  if (c.classes.some((k) => !cls.includes(k))) return false;
+  return c.attrs.every((a) => node.attrs[a.name] && (a.value == null || node.attrs[a.name].value === a.value));
+}
+/* steps[i] matches node, and the steps before it match its ancestors as their combinators say */
+function stepsMatch(node, steps, i = steps.length - 1) {
+  if (!compoundMatches(node, steps[i])) return false;
+  if (i === 0) return true;
+  if (steps[i - 1] === ">") return !!node.parent && stepsMatch(node.parent, steps, i - 2);
+  for (let a = node.parent; a; a = a.parent) if (stepsMatch(a, steps, i - 2)) return true;
+  return false;
+}
+/* Elements matching the selector, in document order; an element holding another match is a stack of
+   slides, not a slide (as with reveal.js's vertical stacks) */
+function selectorSlides(tree, sel) {
+  let list;
+  try { list = parseSelector(sel); } catch { return []; }
+  const hits = [];
+  walk(tree, (c) => { if (list.some((steps) => stepsMatch(c, steps))) hits.push(c); });
+  const inside = (a, b) => { for (let p = b.parent; p; p = p.parent) if (p === a) return true; return false; };
+  return hits.filter((h) => !hits.some((o) => o !== h && inside(h, o)));
+}
+
+/* Slides are leaf <section>s inside .slides; vertical-stack containers are not slides. A deck that names
+   its slides with <meta name="pindeck:slides"> has the elements that selector matches instead. */
 export function findSlides(tree) {
+  const sel = slideSelector(tree);
+  if (sel) return selectorSlides(tree, sel);
   const slidesEl = find(tree, (c) => classesOf(c).includes("slides"));
   if (!slidesEl) return [];
   const out = [];
@@ -187,6 +276,7 @@ function elementName(node) {
 export function assignEids(html) {
   const tree = parse(html);
   const sections = findSlides(tree);
+  const isSlide = slideSelector(tree) ? ((c) => sections.includes(c)) : ((c) => c.name === "section");
   const used = new Set();
   const edits = []; // { at, insert } or { start, end, replace }
   const assigned = [], renamed = [];
@@ -240,7 +330,7 @@ export function assignEids(html) {
     // Pass 2: elements inside the slide
     const visit = (node, inSvg) => {
       for (const c of node.children) {
-        if (c.name === "section") continue; // nested slide, handled on its own
+        if (isSlide(c)) continue; // nested slide, handled on its own
         const cls = classesOf(c);
         if (c.name === "aside" && cls.includes("notes")) continue;
         if (c.attrs["data-noeid"]) continue;
@@ -423,10 +513,11 @@ const slideKind = (n) => classList(n).find((c) => /-slide$/.test(c)) || "content
      content    title and two placeholder bullets, from a content slide (the current one if it is one)
      section    a section divider, from the deck's first divider
      duplicate  a copy of the current slide
-   Element ids are left out; assignEids() gives the new slide fresh ones.
+   Element ids are left out; assignEids() gives the new slide fresh ones. In a deck made without reveal.js,
+   the slide's own id is left out too: such decks (and Present) go to slides by their id.
    Returns { html, index } (index of the new slide) or { error }. */
 export function insertSlide(html, kind, afterEid) {
-  const slides = findSlides(parse(html));
+  const tree = parse(html), slides = findSlides(tree);
   if (!slides.length) return { error: "The deck has no slides." };
   const after = slides.find((s) => s.attrs["data-eid"]?.value === afterEid) || slides.at(-1);
   const hasHead = (s) => { let h = false; walk({ children: [s] }, (c) => { if (/^h[1-3]$/.test(c.name)) h = true; }); return h; };
@@ -437,6 +528,7 @@ export function insertSlide(html, kind, afterEid) {
   if (!tpl) return { error: kind === "section" ? "This deck has no section divider to model a new one on." : "This deck has no content slide to model a new one on." };
 
   let frag = html.slice(tpl.start, elementEnd(html, tpl)).replace(/\s+data-eid="[^"]*"/g, "");
+  if (slideSelector(tree)) frag = frag.replace(/^(<[^>]*?)\s+id=(?:"[^"]*"|'[^']*'|[^\s>]+)/, "$1");   // the opening tag only
   if (kind !== "duplicate") frag = placeholderSlide(frag, kind, slides.filter((s, i) => i <= slides.indexOf(after) && slideKind(s) === "section-slide").length + 1);
 
   const indent = lineIndent(html, after.start);
@@ -500,12 +592,13 @@ function slideBlock(html, s) {
    are. Slides inside vertical stacks are not moved. Returns { html, changed, from, index } or { error }. */
 export function moveSlide(html, eid, beforeEid) {
   const byEid = (all, e) => all.find((s) => s.attrs["data-eid"]?.value === e);
-  const slides = findSlides(parse(html));
+  const tree = parse(html), slides = findSlides(tree);
+  const bySelector = !!slideSelector(tree);   // such decks have no vertical stacks
   const slide = byEid(slides, eid), target = beforeEid == null ? null : byEid(slides, beforeEid);
   if (!slide || (beforeEid != null && !target)) return { error: "Slide not found in the file." };
-  if ([slide, target].some((s) => s?.parent.name === "section")) return { error: "Slides inside a vertical stack cannot be moved yet." };
+  if (!bySelector && [slide, target].some((s) => s?.parent.name === "section")) return { error: "Slides inside a vertical stack cannot be moved yet." };
   const from = slides.indexOf(slide);
-  const top = slide.parent.children.filter((c) => c.name === "section");
+  const top = slide.parent.children.filter((c) => (bySelector ? slides.includes(c) : c.name === "section"));
   const next = top[top.indexOf(slide) + 1] || null;
   if (target === slide || target === next) return { html, changed: false, from, index: from };
 
@@ -520,7 +613,7 @@ export function moveSlide(html, eid, beforeEid) {
     out = cut.slice(0, at) + text + `\n\n${indent}` + cut.slice(at);
   } else {
     // A final vertical stack is absent from the leaf-slide list, but we must insert after it.
-    const last = find(parse(cut), (c) => classesOf(c).includes("slides"))
+    const last = bySelector ? rest.at(-1) : find(parse(cut), (c) => classesOf(c).includes("slides"))
       .children.filter((c) => c.name === "section").at(-1);
     const at = elementEnd(cut, last);
     out = cut.slice(0, at) + `\n\n${indent}` + text + cut.slice(at);

package/lib/frameworks.mjs

@@ -0,0 +1,59 @@
+/* Which slide framework a deck uses. PinDeck edits reveal.js decks: <section> slides inside an element
+   with class "slides" (inside <div class="reveal">). Any other deck can name its slides itself with
+   <meta name="pindeck:slides" content="CSS selector"> (see lib/eids.mjs) and is then edited too. Other
+   frameworks are recognised by their markup and scripts, so the user gets a clear "not supported (yet)"
+   before PinDeck changes anything, instead of an editor without slides. Only tags and scripts are looked
+   at, never the slides' text, so a talk that mentions "impress.js" is not taken for one. */
+
+import { parse, findSlides, slideSelector, deckSize, parseSelector } from "./eids.mjs";
+
+const OTHERS = [   // name, markers; the first match wins (Marp before bespoke.js, which it is built on)
+  ["Marp", /\bmarpit\b|bespoke-marp|data-marpit|marp-cli/i],
+  ["Slidev", /slidev/i],
+  ["impress.js", /id=["']impress["']|impress(\.min)?\.js/i],
+  ["remark", /remark(-latest)?(\.min)?\.js|remark\.create\s*\(/i],
+  ["Spectacle", /<script[^>]+src=["'][^"']*spectacle/i],
+  ["Shower", /class=["'][^"']*\bshower\b|shower-core/i],
+  ["deck.js", /deck-container|deck\.core(\.min)?\.js/i],
+  ["bespoke.js", /bespoke(\.min)?\.js|bespoke\.from\s*\(/i],
+];
+
+/* Tags and script contents only: the slides' text could name any framework */
+const markup = (html) => [...String(html).matchAll(/<script\b[^>]*>[\s\S]*?<\/script>|<[^>]+>/gi)].map((m) => m[0]).join("\n");
+
+/* { name, supported }: reveal.js decks are supported, including one without slides yet, and so is a deck
+   whose <meta name="pindeck:slides"> selector finds slides and whose <meta name="pindeck:size"> gives their
+   size ({ name: "selector", selector, supported }) */
+export function detectFramework(html) {
+  const tree = parse(html), selector = slideSelector(tree);
+  if (selector) return { name: "selector", selector, supported: findSlides(tree).length > 0 && !!deckSize(tree) };
+  if (findSlides(tree).length) return { name: "reveal.js", supported: true };
+  const tags = markup(html);
+  const other = OTHERS.find(([, re]) => re.test(tags));
+  if (other) return { name: other[0], supported: false };
+  if (/class=["'][^"']*\breveal\b/i.test(tags) || /Reveal\.initialize\s*\(/.test(tags)) return { name: "reveal.js", supported: true };
+  return { name: null, supported: false };
+}
+
+const HOW = `A deck made otherwise can name its slides in its <head>: ` +
+  `<meta name="pindeck:slides" content="main.deck > section.slide"> (a CSS selector for the slides) and ` +
+  `<meta name="pindeck:size" content="1440x1080"> (their size in px).`;
+
+/* The message for a deck PinDeck cannot edit, or null */
+export function unsupportedMessage(html, file) {
+  const fw = detectFramework(html);
+  if (fw.supported) return null;
+  if (fw.name === "selector") {
+    // the slides are found: the size is what is missing (headless Chrome and the PDF pages need it)
+    if (findSlides(parse(html)).length) return `${file}: <meta name="pindeck:size"> is missing or not a size ` +
+      `such as content="1440x1080" (the slides' width and height in px). PinDeck opens the slides at that size ` +
+      `for screenshots and PDFs. Nothing was changed.`;
+    let why = "matches no elements";
+    try { parseSelector(fw.selector); } catch (e) { why = `cannot be used: ${e.message}`; }
+    return `${file}: the slide selector "${fw.selector}" in <meta name="pindeck:slides"> ${why}. Nothing was changed.`;
+  }
+  const what = fw.name ? `${file} is a ${fw.name} deck.` :
+    `${file} has no reveal.js slides (a <div class="reveal"> with <div class="slides"> holding <section> slides).`;
+  return `${what} PinDeck works with reveal.js decks; other frameworks may follow. ${HOW} ` +
+    `Nothing was changed.`;
+}

package/lib/instructions.mjs

@@ -0,0 +1,74 @@
+/* The deck's own instructions for Claude (CLAUDE.md, AGENTS.md), with @path imports expanded.
+
+   PinDeck does not load CLAUDE.md files from parent folders the way Claude Code does: those are usually
+   written for coding work PinDeck's Claude cannot do (tests, commits, package managers), they change
+   with where the deck happens to sit, and on a shared server a parent folder may be writable by others.
+   A deck pulls in shared rules explicitly instead: "Follow @../shared/STYLE.md" includes that file.
+
+   An import is "@" followed by a path (relative to the file it is in, absolute, or ~/...), at the start
+   of a line or after a space or "(". It is expanded only when that path is a text file: an e-mail address
+   or an @mention stays as it is. Imports in code spans and code blocks are left alone. Included files may
+   import others, up to 5 levels deep; each file is included once (no cycles), and all included text
+   together is limited to 200 KB. The imported text follows the file that imports it. */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const MAX_DEPTH = 5, MAX_BYTES = 200_000;
+
+/* Apply fn to the text outside code: fenced blocks (``` or ~~~) and `code spans` stay as they are */
+function outsideCode(text, fn) {
+  let fence = null;
+  return text.split("\n").map((line) => {
+    const f = /^\s*(```|~~~)/.exec(line);
+    if (f) { fence = fence ? (fence === f[1] ? null : fence) : f[1]; return line; }
+    if (fence) return line;
+    return line.split(/(`+[^`]*`+)/).map((part, i) => (i % 2 ? part : fn(part))).join("");
+  }).join("\n");
+}
+
+const resolveRef = (ref, dir) => (ref === "~" || ref.startsWith("~/") ? path.join(os.homedir(), ref.slice(1))
+  : path.resolve(dir, ref));
+
+function readText(file) {
+  try {
+    if (!fs.statSync(file).isFile()) return null;
+    const buf = fs.readFileSync(file);
+    return buf.includes(0) ? null : buf.toString("utf8");
+  } catch { return null; }
+}
+
+function expand(file, text, depth, seen, budget) {
+  const dir = path.dirname(file), found = [];
+  const body = outsideCode(text, (part) => part.replace(/(^|[\s(])@([^\s`()<>"']+)/g, (m, pre, raw) => {
+    const ref = raw.replace(/[.,:;!?]+$/, ""), tail = raw.slice(ref.length);   // "see @STYLE.md." ends a sentence
+    const abs = resolveRef(ref, dir);
+    const content = readText(abs);
+    if (content == null) return m;   // not a file: an e-mail address, an @mention, a typo
+    let real = abs;
+    try { real = fs.realpathSync(abs); } catch {}
+    const note = (why) => `${pre}${ref} (${why})${tail}`;
+    if (seen.has(real)) return note("included once, above or below");
+    if (depth >= MAX_DEPTH) return note("not included: imports nested too deep");
+    if (Buffer.byteLength(content) > budget.left) return note("not included: imported files over 200 KB in all");
+    budget.left -= Buffer.byteLength(content);
+    seen.add(real);
+    found.push({ ref, abs, content });
+    return note("included below");
+  }));
+  const parts = [body.trim()];
+  for (const imp of found) {
+    parts.push(`### ${imp.ref} (included by ${path.basename(file)})\n` + expand(imp.abs, imp.content, depth + 1, seen, budget));
+  }
+  return parts.filter(Boolean).join("\n\n");
+}
+
+/* A deck instruction file with its imports, or null when it is missing or empty */
+export function readInstructions(file) {
+  const text = readText(file);
+  if (text == null || !text.trim()) return null;
+  let real = file;
+  try { real = fs.realpathSync(file); } catch {}
+  return expand(file, text, 0, new Set([real]), { left: MAX_BYTES });
+}