pindeck 2.8.1 → 2.9.0

package/README.md

@@ -1,5 +1,9 @@
 # PinDeck
 
+> **macOS, and Linux as a beta.** On Linux, PinDeck runs as a headless server that you use from your
+> Mac's browser through an SSH tunnel (see [Running on a Linux server](#running-on-a-linux-server-beta)).
+> Windows is not supported.
+
 **Pin it. Say it. Done.** PinDeck is a local editor for HTML slide decks (reveal.js): the slides on
 the left, the slide in the middle, and a chat with Claude Code on the right. You click elements to
 pin them, write what to change, and Claude edits the HTML and CSS. The slide updates in place.
@@ -26,6 +30,11 @@ checked the layout; the next request, still being typed, refers to the new pins
 
 ## Quick start
 
+Runs on macOS, and on Linux as a beta. The npm package declares `"os": ["darwin", "linux"]`, so normal
+npm installation rejects other operating systems. Overriding that check does not make those platforms
+supported. Running the server from a cloned repository on another OS shows a local support notice
+instead of opening the deck or starting Claude.
+
 ```bash
 npx pindeck path/to/deck        # from npm
 
@@ -33,11 +42,13 @@ git clone https://github.com/ehabets/PinDeck.git && cd PinDeck
 node server.mjs ocean-example   # or from source, with the example deck in this repository
 ```
 
-Then open <http://127.0.0.1:5180/>. Requirements: Node 20 or later and the `claude` CLI, signed in
+Then open the login link PinDeck prints (`PinDeck: http://127.0.0.1:5180/login?code=...`). It works
+once and logs this browser in; for a new one, run `pindeck login` (or `node server.mjs login`). Requirements: Node 20 or later and the `claude` CLI, signed in
 with your normal Claude account. Chrome (or Chromium, Edge, Brave) is optional and is used for
 screenshots and PDF export; PowerPoint or Keynote (macOS) for pictures in the PowerPoint import.
 
-Options: `--port 5180`, `--model <name>` (for this run only; otherwise the model in
+PinDeck 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
 `PINDECK_HOME`), not in the deck. `ocean-example/` is a complete example deck to start from.
@@ -76,8 +87,9 @@ cp -R ocean-example my-template
    `pindeck:footer-top` and `pindeck:locked` meta tags if the footer or the brand elements move.
    `deck.js` holds the math macros, the footer markup and the audio player.
 4. **`README.md` and `CLAUDE.md`:** Claude follows both, so describe the new classes and rules there.
-   The example's `CLAUDE.md` calls `../cli.mjs` and `../server.mjs`; fix these paths if the template
-   does not sit next to PinDeck.
+   Refer to PinDeck's commands as "the PinDeck CLI command given in the system prompt", as the
+   example's `CLAUDE.md` does; PinDeck tells Claude the right path wherever the deck is. An older
+   `node ../cli.mjs` in a deck's `CLAUDE.md` is replaced with that command.
 
 **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
@@ -101,6 +113,51 @@ 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.
 
+## Running on a Linux server (beta)
+
+PinDeck can run on a Linux machine where the deck lives, with the editor in your Mac's browser. The
+deck, PinDeck, Claude Code and the deck's git clone all stay on the server; the browser only shows the
+editor. The server listens on 127.0.0.1 there, as on a Mac, and an SSH tunnel brings that port to your Mac.
+
+On the server you need Node 20 or later (22 or 24 recommended), git if the deck is in a repository, and
+the `claude` CLI installed and logged in under your account there, if you want the chat. Without it,
+editing by hand still works. Then, in one SSH session on the server:
+
+```bash
+node server.mjs path/to/deck --port 5180
+```
+
+and on your Mac, in another terminal (`myserver` is your usual SSH host):
+
+```bash
+ssh -N -T -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -L 127.0.0.1:5180:127.0.0.1:5180 myserver
+```
+
+Open the login link PinDeck printed on the server in the Mac's browser. The local port may differ from
+the server's: with `-L 127.0.0.1:8080:127.0.0.1:5180`, change 5180 in the link to 8080. PinDeck accepts any
+port, as long as the address is `127.0.0.1` or `localhost`. If the tunnel drops, a message you have already sent keeps running on the
+server. Restart the tunnel and the editor reconnects and shows the files as they are then; it never sends a
+message twice. If PinDeck restarts, the editor asks you to log in again: run `node server.mjs login
+path/to/deck` on the server for a new link.
+
+Other users of a shared server cannot open the editor or read the deck through PinDeck: the token that
+protects it is only in your browser's cookie and in PinDeck's own files in `~/.pindeck` (readable only by
+you), never in a page or on a command line.
+
+What works on Linux in this beta: editing by hand, speaker notes, slides, pins, the chat with Claude,
+Undo/Redo, live reload when files change on the server, layout checks, attaching figures, audio and
+PDFs, `git-setup`, and, 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
+allowed to use hidden folders in your home folder such as `~/.pindeck`; if screenshots fail with it, set
+`PINDECK_HOME` to a folder that is not hidden, or install Chrome or Chromium from a package.
+
+Run one PinDeck per deck. While PinDeck or Claude is working on a deck, do not edit it with other tools
+or switch git branches at the same time. Stop first, or wait until Claude has finished. PinDeck notices
+changes made by other programs and reloads, and it refuses Undo, Redo or an edit that would overwrite
+them. Its checks cannot rule out every race with a program that writes at the same moment.
+
 ## Keeping the ids out of git
 
 PinDeck adds `data-eid` attributes to the deck it opens. If the deck is in git, run once per clone:
@@ -206,7 +263,7 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 * **Layout instead of screenshots.** With each message the editor measures the current slide and
   every pinned slide in your browser: position and size of every element, font sizes, and issues
   (content below the footer rule, outside the slide, overlaps, clipped text). Claude gets this as
-  text. To check its own work it runs `node ../cli.mjs layout <slide>...` (`--issues` for the
+  text. To check its own work it runs the PinDeck CLI's `layout <slide>...` (`--issues` for the
   issues only). Screenshots are
   only taken when you tick the box or Claude needs a visual judgement.
 * **One Claude Code process.** The server starts `claude -p` in stream-json mode once and keeps it
@@ -217,13 +274,19 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
   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.
+  or a hand edit). Undo and redo walk that history and tell Claude on the next message. They first check
+  that the files are still as that change left them; if something else changed them since, they do
+  nothing and say which file differs, rather than overwrite that work.
+* **Saving.** Every file PinDeck writes into the deck is written to a temporary file next to it and then
+  renamed into place, so other programs never see half a file. Each change from the editor carries the
+  revision of the files it was made on; if the files have changed since, the change is refused, the
+  slide reloads, and edited text can be copied from the message to type in again.
 
 ## Files
 
 | File | Purpose |
 |---|---|
-| `server.mjs` | Local server (127.0.0.1 only, random token per run): UI, deck files, events, Claude session, undo, CLI endpoints. |
+| `server.mjs` | Local server (127.0.0.1 only, random token per run, one-time login links): UI, deck files, events, Claude session, undo, CLI endpoints, `login`. |
 | `cli.mjs` | `layout`, `shot`, `slides`, `pdf handout` / `pdf presentation` and `pdf-figure` commands for Claude (and for you), and `git-setup`. |
 | `public/` | The editor page, and `bridge.js`, which is injected into the deck in edit mode (never saved to it). |
 | `lib/pptx.mjs`, `lib/zip.mjs`, `lib/xml.mjs` | Reading `.pptx` files (no dependencies): slides, text, shapes and their positions, notes. |
@@ -234,6 +297,8 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 | `lib/pdf.mjs` | PDF export: reveal.js print layout in headless Chrome, then print to PDF. |
 | `lib/eids.mjs` | Adds the `data-eid` attributes by editing the HTML as text. |
 | `lib/claude.mjs` | The long-running Claude Code process. |
+| `lib/capabilities.mjs` | What this server can do on this system (macOS, Linux), for the editor, the API, the CLI and Claude. |
+| `lib/deck-files.mjs` | Atomic writes and the revision of the deck's files. |
 | `lib/system-prompt.md` | What Claude is told about the editor. |
 | `CONTRIBUTING.md` | How to report bugs and contribute. |
 | `docs/` | Images for this README. |
@@ -246,9 +311,39 @@ Without PowerPoint or Keynote (or on other systems than macOS) only the text and
 * 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.
 
 ## Versions
 
+* **2.9**: Linux as a beta, and safer editing.
+  - Linux (beta): PinDeck runs as a headless server, used from a Mac's browser through an SSH tunnel,
+    with Claude Code running on the server. The tunnel may use another local port than the server.
+    Screenshots, layout checks without an open editor and PDF export work when Chrome or Chromium is
+    found (`PINDECK_LINUX_CHROME=0` turns them off). Features a system cannot provide are switched off,
+    with the reason shown in the editor. Changes made to the deck by other programs are seen every
+    time, also after a file was replaced by a rename.
+  - Security: the editor page no longer contains the token, and the deck needs it too, so other users
+    of the same machine cannot read either. PinDeck prints a one-time login link at start
+    (`pindeck login` prints a new one), which keeps the token in an HttpOnly cookie named after the
+    server's port; headless Chrome logs in the same way, so the token is never on a command line. After
+    a restart, log in again with a new link.
+  - Saving is atomic; edits made on files that changed meanwhile are refused, and Undo/Redo no longer
+    overwrite changes made outside PinDeck.
+  - Audio and video play in Safari: deck files are sent with their length and byte ranges, and ogg,
+    opus, m4a, aac, flac and mov get their media types.
+  - Claude gets the right CLI command for decks outside the PinDeck folder; the example's `CLAUDE.md`
+    no longer names a path. The deck's `AGENTS.md` reaches Claude along with its `CLAUDE.md`.
+  - macOS: pictures of PDF pages (`pdf-figure`) and of PowerPoint slides have a white page instead of a
+    transparent one, so dark text no longer disappears on a dark slide.
+  - Screenshots and PDF exports are no longer now and then reported as failed although Chrome wrote them.
+  - `git-setup` works for decks behind symlinks or with spaces in their path. The tests run on Linux
+    and macOS in CI, including a real Chrome.
+
+* **2.8.2**: declares macOS-only support in npm metadata and the README to prevent accidental
+  installation on unsupported operating systems. Source launches on other platforms show a support
+  notice without opening the deck.
+
 * **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

package/cli.mjs

@@ -31,14 +31,16 @@ const arg = rest[0];
    on where PinDeck is installed; git config is per clone, so run this once in each clone. */
 if (cmd === "git-setup") {
   const FILTER = `sed 's/ data-eid="[^"]*"//g'`;
-  const deck = path.resolve(arg || ".");
+  let deck = path.resolve(arg || ".");
+  try { deck = fs.realpathSync(deck); } catch {}   // git reports the real path; a symlinked path would not match
   const git = (...a) => execFileSync("git", ["-C", deck, ...a], { encoding: "utf8" }).trim();
   let root;
   try { root = git("rev-parse", "--show-toplevel"); }
   catch { console.error(`${deck} is not inside a git repository.`); process.exit(1); }
   git("config", "filter.pindeck-ids.clean", FILTER);
   const rel = path.relative(root, deck).split(path.sep).join("/");
-  const pattern = `${rel ? rel + "/" : ""}*.html`;
+  // .gitattributes patterns end at whitespace: spaces in folder names are written as [[:space:]]
+  const pattern = `${rel ? rel.replace(/\s/g, "[[:space:]]") + "/" : ""}*.html`;
   const attrFile = path.join(root, ".gitattributes");
   const attrs = fs.existsSync(attrFile) ? fs.readFileSync(attrFile, "utf8") : "";
   const line = `${pattern} filter=pindeck-ids`;

package/lib/capabilities.mjs

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

package/lib/claude.mjs

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

package/lib/deck-files.mjs

@@ -0,0 +1,56 @@
+/* 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);
+}

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;

package/lib/platform-notice.mjs

@@ -0,0 +1,34 @@
+import http from 'node:http';
+
+export function createPlatformNoticeServer(platform) {
+  const windows = platform === 'win32';
+  const heading = windows ? 'Windows support is on the roadmap' : 'PinDeck runs on macOS and Linux';
+  const explanation = windows
+    ? 'PinDeck runs on macOS and, as a beta, on Linux. Windows support is planned for a future version; there is no release date yet.'
+    : 'This version of PinDeck runs on macOS and, as a beta, on Linux. This operating system is not supported.';
+  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>PinDeck · system not supported</title><style>
+  :root{font-family:system-ui,sans-serif;color:#243348;background:#f4f6f8;color-scheme:light}*{box-sizing:border-box}body{margin:0;min-height:100vh;display:grid;place-items:center;padding:24px}main{width:min(100%,620px);padding:40px;background:white;border:1px solid #dde3ea;border-radius:18px;box-shadow:0 12px 40px #20334d0a}.brand{font-weight:700;color:#c36516;margin:0 0 32px}h1{font-size:clamp(26px,5vw,36px);line-height:1.2;margin:0 0 20px}p{line-height:1.65}a{color:#945012}footer{margin-top:28px;font-size:14px;color:#596577}
+  </style></head><body><main><p class="brand">PinDeck</p><h1>${heading}</h1><p>${explanation}</p><p>Your deck has not been opened or changed, and no AI backend has been started.</p><p>You can run PinDeck on a Mac or a Linux machine (and use it from this browser through an SSH tunnel), or follow updates on <a href="https://github.com/ehabets/PinDeck">GitHub</a>.</p><footer>Close this tab and press Ctrl+C in the terminal to stop this notice.</footer></main></body></html>`;
+  return http.createServer((req, res) => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') { res.writeHead(405, { Allow: 'GET, HEAD' }); return res.end(); }
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store',
+      'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; frame-ancestors 'none'" });
+    res.end(req.method === 'HEAD' ? undefined : html);
+  });
+}
+
+// Keep startup here until the notice is closed: no deck/state initialization runs on unsupported OSes.
+export async function showPlatformNotice(port, platform = process.platform) {
+  const server = createPlatformNoticeServer(platform);
+  await new Promise((resolve, reject) => {
+    const stop = () => server.close();
+    server.once('error', reject);
+    server.once('close', () => {
+      process.off('SIGINT', stop); process.off('SIGTERM', stop); resolve();
+    });
+    server.listen(port, '127.0.0.1', () => {
+      process.once('SIGINT', stop); process.once('SIGTERM', stop);
+      console.log(`PinDeck runs on macOS and Linux only. Open http://127.0.0.1:${server.address().port}/ for details. Press Ctrl+C to stop.`);
+    });
+  });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pindeck",
-  "version": "2.8.1",
-  "description": "PinDeck: a local editor for HTML slide decks. Pin elements, describe the change, and Claude Code edits the slides.",
+  "version": "2.9.0",
+  "description": "PinDeck: an editor for HTML slide decks on macOS, and on Linux (beta) through an SSH tunnel. Pin elements, describe the change, and Claude Code edits the slides.",
   "keywords": [
     "slides",
     "presentation",
@@ -35,6 +35,10 @@
     "start": "node server.mjs",
     "test": "node --test"
   },
+  "os": [
+    "darwin",
+    "linux"
+  ],
   "engines": {
     "node": ">=20"
   }

package/public/editor.css

@@ -65,6 +65,7 @@ code { font: 12.5px ui-monospace, SFMono-Regular, Menlo, monospace; background:
 }
 .pos { font-variant-numeric: tabular-nums; color: var(--muted); min-width: 52px; text-align: center; }
 .deck-name { min-width: 0; margin-left: 8px; font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.server-note { flex: none; margin-left: 8px; padding: 1px 6px; border-radius: 4px; font-size: 12px; color: #6b4a12; background: #fbf0dc; cursor: help; }
 .toggle { display: inline-flex; align-items: center; gap: 6px; }
 .toggle .dot { display: inline-block; width: 18px; height: 18px; border-radius: 50%; background: var(--orange); color: #fff;
   font-size: 11px; font-weight: 700; line-height: 18px; text-align: center; }