pindeck 2.9.0 → 2.11.0

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/pptx-render.mjs

@@ -1,6 +1,10 @@
-/* Pictures of PowerPoint slides (macOS): PowerPoint, or else Keynote, exports the deck as a PDF with one
-   page per slide, hidden slides included; macOS PDFKit (pdf-render.jxa.js) then renders whole pages
-   (thumbnails, references for Claude) and regions (diagrams) to PNG.
+/* Pictures of PowerPoint slides, and of PDF pages.
+
+   macOS: PowerPoint, or else Keynote, exports the deck as a PDF with one page per slide, hidden slides
+   included; macOS PDFKit (pdf-render.jxa.js) then renders whole pages (thumbnails, references for Claude)
+   and regions (diagrams, PDF figures) to PNG.
+   Linux: LibreOffice (soffice --headless) exports the PDF, and Poppler (pdfinfo, pdftoppm) renders it.
+   Both are optional; lib/capabilities.mjs turns the features on when they are found.
 
    Both apps are sandboxed, so the files go through a folder inside the app's own container, which
    needs no permission dialog. macOS asks once whether PinDeck may control the app. An app that was
@@ -11,7 +15,8 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { findExecutable } from "./capabilities.mjs";
 
 const JXA = path.join(path.dirname(fileURLToPath(import.meta.url)), "pdf-render.jxa.js");
 const APPS = [
@@ -24,8 +29,16 @@ const osa = (args, timeout = 240000) => new Promise((resolve, reject) =>
     err ? reject(new Error((errOut || err.message).trim().split("\n").pop())) : resolve(out.trim())));
 const q = (s) => JSON.stringify(s);   // AppleScript string literal (same quoting rules for paths)
 
+const mac = () => process.platform === "darwin";
+const tool = (...names) => names.map((n) => findExecutable(n).path).find(Boolean) || null;
+const run = (cmd, args, timeout = 120000) => new Promise((resolve, reject) =>
+  execFile(cmd, args, { timeout, maxBuffer: 1e7 }, (err, out, errOut) =>
+    err ? reject(new Error(String(errOut || err.message).trim().split("\n").pop())) : resolve(String(out))));
+export const popplerAvailable = () => !!(tool("pdftoppm") && tool("pdfinfo"));
+export const sofficePath = () => tool("soffice", "libreoffice");
+
 export function renderAvailable() {
-  return process.platform === "darwin" && APPS.some((a) => fs.existsSync(a.bundle));
+  return mac() ? APPS.some((a) => fs.existsSync(a.bundle)) : !!(sofficePath() && popplerAvailable());
 }
 
 function exportScript(app, pptx, pdf) {
@@ -58,7 +71,7 @@ return "ok"`;
 
 /* Exports the deck to <workDir>/deck.pdf. Returns { pdf, app }. */
 export async function exportPdf(pptxPath, workDir) {
-  if (process.platform !== "darwin") throw new Error("Slide pictures need macOS with PowerPoint or Keynote.");
+  if (!mac()) return exportPdfLibreOffice(pptxPath, workDir);
   const errors = [];
   for (const app of APPS) {
     if (!fs.existsSync(app.bundle)) continue;
@@ -81,17 +94,73 @@ export async function exportPdf(pptxPath, workDir) {
   throw new Error(errors.length ? errors.join("; ") : "Neither PowerPoint nor Keynote is installed.");
 }
 
-/* Renders pages or regions (see pdf-render.jxa.js). Returns the page count. Boxes are in slide px of a
-   page slideWidth wide; with slideWidth = the page width in points, they are in PDF points. */
+/* Linux: LibreOffice exports the deck, hidden slides included (so page n is slide n). Its own profile in
+   the work folder, so a LibreOffice the user has open, or a stale lock, does not get in the way. */
+async function exportPdfLibreOffice(pptxPath, workDir) {
+  const soffice = sofficePath();
+  if (!soffice) throw new Error("LibreOffice (soffice) is not installed.");
+  const dir = fs.mkdtempSync(path.join(workDir, "libreoffice-"));
+  try {
+    const inFile = path.join(dir, "deck.pptx");
+    fs.copyFileSync(pptxPath, inFile);
+    await run(soffice, ["--headless", "--norestore", `-env:UserInstallation=${pathToFileURL(path.join(dir, "profile")).href}`,
+      "--convert-to", 'pdf:impress_pdf_Export:{"ExportHiddenSlides":{"type":"boolean","value":"true"}}',
+      "--outdir", dir, inFile], 240000);
+    const out = path.join(dir, "deck.pdf");
+    if (!fs.existsSync(out)) throw new Error("LibreOffice wrote no PDF.");
+    const pdf = path.join(workDir, "deck.pdf");
+    fs.copyFileSync(out, pdf);
+    return { pdf, app: "LibreOffice" };
+  } finally {
+    fs.rm(dir, { recursive: true, force: true }, () => {});
+  }
+}
+
+/* Renders pages or regions (see pdf-render.jxa.js for the jobs). Returns the page count. Boxes are in
+   slide px of a page slideWidth wide; with slideWidth = the page width in points, they are in PDF points. */
 export async function renderJobs(pdf, jobs, workDir, { slideWidth = 1280 } = {}) {
+  if (!mac()) return renderPoppler(pdf, jobs, slideWidth);
   return +(await runJxa({ pdf, slideWidth, jobs }, workDir));
 }
 
-/* Page count and page sizes in points: { pages, sizes: [[w, h], ...] } (macOS only, no other app needed) */
+/* Page count and page sizes in points: { pages, sizes: [[w, h], ...] } (PDFKit or Poppler, no other app) */
 export async function pdfInfo(pdf, workDir) {
+  if (!mac()) return popplerInfo(pdf);
   return JSON.parse(await runJxa({ pdf, info: true }, workDir));
 }
 
+async function popplerInfo(pdf, exact = false) {
+  const pages = +(/^Pages:\s+(\d+)/m.exec(await run(tool("pdfinfo"), [pdf])) || [])[1];
+  if (!pages) throw new Error("pdfinfo could not read the PDF.");
+  const out = await run(tool("pdfinfo"), ["-f", "1", "-l", String(pages), pdf]);
+  const sizes = [...out.matchAll(/^Page\s+(\d+)\s+size:\s+([\d.]+) x ([\d.]+)/gm)]
+    .sort((a, b) => a[1] - b[1]).map((m) => (exact ? [+m[2], +m[3]] : [Math.round(+m[2]), Math.round(+m[3])]));
+  return { pages, sizes };
+}
+
+/* The same jobs as pdf-render.jxa.js, with pdftoppm: whole pages scaled to a width, or a box of the page
+   (in slide px) at job.scale output px per slide px. White background, as PDFKit's. */
+async function renderPoppler(pdf, jobs, slideWidth) {
+  const info = await popplerInfo(pdf, true);
+  for (const job of jobs) {
+    const size = info.sizes[job.page - 1];
+    if (!size) continue;
+    const [pw, ph] = size;
+    const args = ["-f", String(job.page), "-l", String(job.page), "-png", "-singlefile"];
+    if (job.box) {
+      const [x, y, bw, bh] = job.box, s = job.scale || 2, f = pw / (slideWidth || 1280);   // PDF points per slide px
+      args.push("-r", String((s / f) * 72), "-x", String(Math.round(x * s)), "-y", String(Math.round(y * s)),
+        "-W", String(Math.max(1, Math.round(bw * s))), "-H", String(Math.max(1, Math.round(bh * s))));
+    } else {
+      const scale = (job.width || 1280) / pw;
+      args.push("-scale-to-x", String(Math.round(pw * scale)), "-scale-to-y", String(Math.round(ph * scale)));
+    }
+    const prefix = job.out.replace(/\.png$/i, "");   // pdftoppm adds .png
+    await run(tool("pdftoppm"), [...args, pdf, prefix]);
+  }
+  return info.pages;
+}
+
 async function runJxa(spec, workDir) {
   const file = path.join(workDir, `jobs-${crypto.randomBytes(4).toString("hex")}.json`);
   fs.writeFileSync(file, JSON.stringify(spec));

package/lib/system-prompt.md

@@ -12,7 +12,9 @@ Each user message may start with an <editor-context> block:
 - sometimes the path of a screenshot of the slide with the pin markers drawn on it.
 
 ## Files
-- index.html: the slides. theme.css: the styles. Edit these.
+- {{DECK}}: the slides. theme.css: the styles. Edit these. You may also edit or create other files in the
+  deck folder when a request needs it (a script such as deck.js, a style sheet, the deck's notes), but not
+  vendor/ (third-party libraries). The user can undo everything a turn changed in one step.
 - brand.css is LOCKED (logos, footer, brand colours). Never edit it. If a request needs a brand
   change, say so instead. Elements marked brand-locked are positioned by brand.css.
 - Follow the deck's CLAUDE.md (at the end of these instructions) and README.md for the template's
@@ -37,7 +39,7 @@ in the editor. Do not delete hidden slides, and do not unhide them unless asked.
 
 ## Attached files
 The user can attach figures and audio to a message. PinDeck has already saved them in the deck's
-`figures/` folder; <editor-context> lists their paths (relative to index.html), size and, for audio,
+`figures/` folder; <editor-context> lists their paths (relative to {{DECK}}), size and, for audio,
 the duration and a generated waveform SVG. If a file was dropped onto a slide, the drop position is
 given too. Put them on slides with the deck's existing patterns: a figure like the other `figure.fig`
 blocks, audio like the deck's audio demo (audio element, play button, waveform). Read an image
@@ -84,7 +86,7 @@ If the user asks for a PDF, run `{{CLI}} pdf handout` (one page per slide, build
 
 ## Hand edits
 The user can also select, move and resize elements in the editor. Those changes are written as
-inline styles on the element in index.html: `translate: Xpx Ypx` for moves, `width`/`height` (and
+inline styles on the element in {{DECK}}: `translate: Xpx Ypx` for moves, `width`/`height` (and
 `max-width`/`max-height: none`) for sizes. You get a note about each one. Treat them as intended;
 keep them unless asked. If the user asks to clean up, move them into proper CSS rules.
 The user can also edit text in place (double-click); you get a note with the new text. Keep their

package/lib/waveform.mjs

@@ -1,7 +1,9 @@
 /* Waveform SVG for an audio file, as the editor makes for attached audio (bars, viewBox 1000 x 120):
-   WAV is read directly; other formats are converted to WAV first with macOS afconvert, if available. */
+   WAV is read directly; other formats are converted to WAV first, with afconvert on macOS or ffmpeg on
+   Linux, when available. */
 
 import { execFile } from "node:child_process";
+import { findExecutable } from "./capabilities.mjs";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -52,12 +54,16 @@ function svgOf(wav) {
 /* Returns the SVG text, or null if the audio cannot be read */
 export async function waveformSvg(data, ext) {
   let wav = /^wav(e)?$/i.test(ext) ? readWav(data) : null;
-  if (!wav && process.platform === "darwin") {
+  // other formats: decoded to 16-bit WAV by afconvert (macOS) or ffmpeg (Linux, when installed)
+  const ffmpeg = process.platform !== "darwin" && findExecutable("ffmpeg").path;
+  if (!wav && (process.platform === "darwin" || ffmpeg)) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pindeck-wave-"));
     try {
       const src = path.join(dir, `in.${ext || "audio"}`), out = path.join(dir, "out.wav");
       fs.writeFileSync(src, data);
-      await new Promise((resolve, reject) => execFile("afconvert", ["-f", "WAVE", "-d", "LEI16", src, out], { timeout: 60000 },
+      const [cmd, args] = ffmpeg ? [ffmpeg, ["-v", "error", "-y", "-i", src, "-f", "wav", "-acodec", "pcm_s16le", out]]
+        : ["afconvert", ["-f", "WAVE", "-d", "LEI16", src, out]];
+      await new Promise((resolve, reject) => execFile(cmd, args, { timeout: 60000 },
         (err) => (err ? reject(err) : resolve())));
       wav = readWav(fs.readFileSync(out));
     } catch { wav = null; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pindeck",
-  "version": "2.9.0",
+  "version": "2.11.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",