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

package/lib/capabilities.mjs

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

package/lib/claude.mjs

@@ -3,19 +3,22 @@ import { promisify } from 'node:util';
 const exec = promisify(execFile);
 import { AgentProcess } from './agent-process.mjs';
 import { normalizeModels } from './models.mjs';
+/* A long-running Claude Code process in stream-json mode. One process serves the whole chat; it runs under
+   the user's normal Claude login. env may be a function: the server's address is known only once it listens. */
 export class ClaudeSession {
   constructor(options) { Object.assign(this, options); this.transport = null; this.sessionId = null; }
   get running() { return !!this.transport && !this.transport.closed; }
   async start(resumeId) {
     if (this.running) return;
     this.stopped = false;
+    const env = typeof this.env === 'function' ? this.env() : this.env;
     try {
       const { stdout } = await exec(process.env.CLAUDE_BIN || 'claude', ['auth', 'status', '--json'],
-        { env: { ...process.env, ...this.env }, timeout: 15000, maxBuffer: 65536 });
+        { env: { ...process.env, ...env }, timeout: 15000, maxBuffer: 65536 });
       if (!JSON.parse(stdout).loggedIn) throw new Error('Not signed in.');
     } catch (e) { throw new Error(e.code === 'ENOENT' ? 'Claude CLI is not installed (or set CLAUDE_BIN).' : 'Claude is not signed in. Run claude auth login, then refresh models.'); }
     if (this.stopped) throw new Error('Agent stopped.');
-    const transport = new AgentProcess({ binary: process.env.CLAUDE_BIN || 'claude', cwd: this.cwd, env: this.env,
+    const transport = new AgentProcess({ binary: process.env.CLAUDE_BIN || 'claude', cwd: this.cwd, env,
       args: ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
         ...(typeof this.args === 'function' ? this.args() : this.args || []), ...(resumeId ? ['--resume', resumeId] : [])],
       onStderr: this.onStderr,
@@ -34,5 +37,6 @@ export class ClaudeSession {
   }
   async send(content) { this.transport.write({ type: 'user', message: { role: 'user', content } }); }
   async interrupt() { if (this.running) await this.transport.request('interrupt', {}, { claude: true, timeout: 5000 }); }
-  stop() { this.stopped = true; const t = this.transport; this.transport = null; t?.stop(); }
+  /* Resolves once the process has exited, so shutdown can wait for it. */
+  stop() { this.stopped = true; const t = this.transport; this.transport = null; return t ? t.stop() : Promise.resolve(); }
 }

package/lib/codex.mjs

@@ -1,6 +1,8 @@
+import fs from 'node:fs';
 import { AgentProcess } from './agent-process.mjs';
 import { normalizeModels } from './models.mjs';
 import { deckTools } from './agent-tools.mjs';
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 export const CODEX_CONFIG = {
   'features.shell_tool': false, 'features.unified_exec': false, 'features.js_repl': false,
   'features.apps': false, 'features.plugins': false, 'features.multi_agent': false,
@@ -23,7 +25,7 @@ export class CodexSession {
     });
     this.transport = transport;
     try {
-      await transport.request('initialize', { clientInfo: { name: 'pindeck', version: '3.0.0-beta.1' }, capabilities: { experimentalApi: true } });
+      await transport.request('initialize', { clientInfo: { name: 'pindeck', version: VERSION }, capabilities: { experimentalApi: true } });
       transport.write({ method: 'initialized', params: {} });
       const auth = await transport.request('account/read', { refreshToken: false });
       if (auth.requiresOpenaiAuth && !auth.account) throw new Error('Codex is not signed in. Run codex login, then refresh models.');
@@ -100,5 +102,5 @@ export class CodexSession {
     this.cancelRequested = true; this.controller?.abort();
     if (this.turnId && this.running) await this.transport.request('turn/interrupt', { threadId: this.sessionId, turnId: this.turnId });
   }
-  stop() { this.controller?.abort(); this.controller = null; const t = this.transport; this.transport = null; t?.stop(); }
+  stop() { this.controller?.abort(); this.controller = null; const t = this.transport; this.transport = null; return t ? t.stop() : Promise.resolve(); }
 }

package/lib/deck-files.mjs

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

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 });
+}

package/lib/models.mjs

@@ -22,7 +22,8 @@ export function selectModel(catalog, current, requested, preferences = {}) {
   const provider = requested.provider ?? current.provider;
   if (!PROVIDERS.includes(provider)) throw new Error('Unknown provider.');
   const models = catalog[provider]?.models || [];
-  const id = requested.model ?? (provider === current.provider ? current.model : models.find(m => m.isDefault)?.id || models[0]?.id);
+  // no model chosen yet (a provider picked on the command line, before discovery): the backend's default
+  const id = requested.model ?? ((provider === current.provider && current.model) || models.find(m => m.isDefault)?.id || models[0]?.id);
   const model = models.find(m => m.id === id);
   if (!model) throw new Error(catalog[provider]?.error || 'This model is not available. Refresh the model list.');
   const sameModel = provider === current.provider && id === current.model;

package/lib/pdf-render.jxa.js

@@ -39,10 +39,12 @@ function run(argv) {
       null, w, h, 8, 4, true, false, $.NSDeviceRGBColorSpace, 0, 0);
     const ctx = $.NSGraphicsContext.graphicsContextWithBitmapImageRep(rep);
     $.NSGraphicsContext.saveGraphicsState;
-    $.NSGraphicsContext.currentContext = ctx;
-    $.NSColor.whiteColor.setFill;
-    $.NSRectFill($.NSMakeRect(0, 0, w, h));
+    $.NSGraphicsContext.setCurrentContext(ctx);
     const cg = ctx.CGContext;
+    // a white page, as in a PDF viewer (and as Poppler renders on Linux): most PDFs paint no background,
+    // and a transparent picture would show dark text on a dark slide
+    $.CGContextSetRGBFillColor(cg, 1, 1, 1, 1);
+    $.CGContextFillRect(cg, $.CGRectMake(0, 0, w, h));
     $.CGContextScaleCTM(cg, scale, scale);
     $.CGContextTranslateCTM(cg, tx, ty);
     page.drawWithBoxToContext($.kPDFDisplayBoxMediaBox, cg);

package/lib/pdf.mjs

@@ -46,7 +46,8 @@ function chromeRun(chrome, args, profile, done, timeout) {
     proc.stdout.on("data", (d) => { out += d; check(); });
     proc.stderr.on("data", (d) => { err += d; check(); });
     proc.on("error", (e) => finish(e));
-    proc.on("exit", () => (done(out, err) ? finish(null, out) : finish(new Error("Chrome exited early."))));
+    // "close", not "exit": at exit Chrome's last output (the line saying the file is written) may still be unread
+    proc.on("close", () => (done(out, err) ? finish(null, out) : finish(new Error("Chrome exited early."))));
   });
 }
 
@@ -61,7 +62,8 @@ export async function printLayout(chrome, url, profile) {
 /* Step 2: print a (static) page to a PDF file. */
 export async function printPdf(chrome, url, out, profile) {
   try { fs.rmSync(out, { force: true }); } catch {}
-  await chromeRun(chrome, ["--no-pdf-header-footer", `--print-to-pdf=${out}`, url], profile,
+  // the virtual-time budget lets Chrome follow PinDeck's login start page to the print page before printing
+  await chromeRun(chrome, ["--virtual-time-budget=5000", "--no-pdf-header-footer", `--print-to-pdf=${out}`, url], profile,
     (_o, e) => /bytes written to file/.test(e), 90000);
   if (!fs.existsSync(out)) throw new Error("Chrome did not write the PDF.");
   return out;