viteboard 0.1.9 → 0.2.1

package/bin/pdf-export.mjs

@@ -0,0 +1,457 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import http from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { pathToFileURL } from "node:url";
+
+const execFileAsync = promisify(execFile);
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+
+let browserBinaryPromise = null;
+
+export async function renderPdfFromHtml(html, fileName, pdf = {}) {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "viteboard-pdf-"));
+  const htmlPath = path.join(tmpDir, "publication.html");
+  const profileDir = path.join(tmpDir, "profile");
+  let browserProcess = null;
+  try {
+    const browser = await resolveBrowserBinary();
+    await fs.writeFile(htmlPath, html, "utf-8");
+    await fs.mkdir(profileDir, { recursive: true });
+    browserProcess = execFile(browser, [
+      "--headless",
+      "--disable-gpu",
+      "--no-sandbox",
+      `--user-data-dir=${profileDir}`,
+      "--remote-debugging-port=0",
+      "about:blank",
+    ], { windowsHide: true, detached: process.platform !== "win32" });
+
+    const activePortPath = path.join(profileDir, "DevToolsActivePort");
+    const port = await waitForDevToolsPort(activePortPath);
+    const wsUrl = await openCdpPage(port);
+    return await withTimeout(printPdfViaCdp(wsUrl, pathToFileURL(htmlPath).href, {
+      displayHeaderFooter: Boolean(pdf.displayHeaderFooter),
+      headerTemplate: pdf.headerTemplate,
+      footerTemplate: pdf.footerTemplate,
+      marginTopMm: pdf.marginTopMm,
+      marginBottomMm: pdf.marginBottomMm,
+      marginLeftMm: pdf.marginLeftMm,
+      marginRightMm: pdf.marginRightMm,
+    }), 120_000, "PDF rendering timed out.");
+  } finally {
+    await stopBrowserProcess(browserProcess);
+    await removeTemporaryDirectory(tmpDir);
+  }
+}
+
+export async function evaluatePageFromUrl(url, expression) {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "viteboard-pdf-"));
+  const profileDir = path.join(tmpDir, "profile");
+  let browserProcess = null;
+  try {
+    const browser = await resolveBrowserBinary();
+    await fs.mkdir(profileDir, { recursive: true });
+    browserProcess = execFile(browser, [
+      "--headless",
+      "--disable-gpu",
+      "--no-sandbox",
+      `--user-data-dir=${profileDir}`,
+      "--remote-debugging-port=0",
+      "about:blank",
+    ], { windowsHide: true, detached: process.platform !== "win32" });
+    const port = await waitForDevToolsPort(path.join(profileDir, "DevToolsActivePort"));
+    const wsUrl = await openCdpPage(port);
+    return await withTimeout(evaluatePageViaCdp(wsUrl, url, expression), 120_000, "PDF preparation timed out.");
+  } finally {
+    await stopBrowserProcess(browserProcess);
+    await removeTemporaryDirectory(tmpDir);
+  }
+}
+
+async function stopBrowserProcess(browserProcess) {
+  if (!browserProcess || !browserProcess.pid) return;
+  const exited = new Promise((resolve) => {
+    if (browserProcess.exitCode !== null || browserProcess.signalCode !== null) return resolve();
+    browserProcess.once("close", resolve);
+  });
+  try {
+    if (process.platform === "win32") {
+      await execFileAsync("taskkill", ["/pid", String(browserProcess.pid), "/t", "/f"]).catch(() => browserProcess.kill());
+    } else {
+      process.kill(-browserProcess.pid, "SIGTERM");
+    }
+  } catch {
+    try { browserProcess.kill(); } catch { /* already stopped */ }
+  }
+  if (await Promise.race([exited.then(() => true), delay(1000).then(() => false)])) return;
+  try {
+    if (process.platform !== "win32") process.kill(-browserProcess.pid, "SIGKILL");
+    else browserProcess.kill("SIGKILL");
+  } catch { /* already stopped */ }
+  await Promise.race([exited, delay(1000)]);
+}
+
+async function removeTemporaryDirectory(tmpDir) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    try {
+      await fs.rm(tmpDir, { recursive: true, force: true, maxRetries: 2, retryDelay: 100 });
+      return;
+    } catch (error) {
+      if (attempt === 7) {
+        console.warn("ViteBoard could not remove a temporary PDF export directory:", error.message);
+        return;
+      }
+      await delay(100 * (attempt + 1));
+    }
+  }
+}
+
+export function sanitizePdfFileName(input) {
+  const cleaned = String(input ?? "").trim().replace(/[\\/:*?"<>|]+/g, "-").replace(/\s+/g, " ").slice(0, 120) || "export";
+  return cleaned.toLowerCase().endsWith(".pdf") ? cleaned : `${cleaned}.pdf`;
+}
+
+async function resolveBrowserBinary() {
+  if (browserBinaryPromise) return browserBinaryPromise;
+  browserBinaryPromise = (async () => {
+    const override = process.env.VITEBOARD_PDF_BROWSER || process.env.VITEBOARD_BROWSER || process.env.BROWSER || "";
+    if (override && await fileExists(override)) return override;
+
+    const commandCandidates = process.platform === "win32"
+      ? ["msedge.exe", "chrome.exe", "chromium.exe", "brave.exe"]
+      : ["microsoft-edge", "microsoft-edge-stable", "google-chrome", "google-chrome-stable", "chromium-browser", "chromium", "brave-browser"];
+    const lookupCommand = process.platform === "win32" ? "where" : "which";
+    for (const candidate of commandCandidates) {
+      try {
+        const { stdout } = await execFileAsync(lookupCommand, [candidate]);
+        const first = stdout.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+        if (first) return first;
+      } catch {
+        /* try next */
+      }
+    }
+
+    for (const candidate of absoluteBrowserCandidates()) {
+      if (await fileExists(candidate)) return candidate;
+    }
+
+    throw new Error("No supported Chromium-based browser was found for PDF export. Install Chrome, Edge, Chromium, or Brave, or set VITEBOARD_PDF_BROWSER.");
+  })();
+  return browserBinaryPromise;
+}
+
+function absoluteBrowserCandidates() {
+  if (process.platform === "darwin") {
+    return [
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium",
+      "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+      path.join(os.homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+      path.join(os.homedir(), "Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"),
+    ];
+  }
+  if (process.platform === "win32") {
+    const roots = [process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.LOCALAPPDATA].filter(Boolean);
+    const suffixes = [
+      path.join("Google", "Chrome", "Application", "chrome.exe"),
+      path.join("Microsoft", "Edge", "Application", "msedge.exe"),
+      path.join("Chromium", "Application", "chrome.exe"),
+      path.join("BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+    ];
+    return roots.flatMap((root) => suffixes.map((suffix) => path.join(root, suffix)));
+  }
+  return [
+    "/usr/bin/chromium-browser",
+    "/usr/bin/chromium",
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/microsoft-edge",
+    "/snap/bin/chromium",
+  ];
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForDevToolsPort(activePortPath) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try {
+      const raw = await fs.readFile(activePortPath, "utf-8");
+      const port = raw.split(/\r?\n/)[0]?.trim();
+      if (port) return port;
+    } catch {
+      /* wait */
+    }
+    await delay(100);
+  }
+  throw new Error("Timed out starting Chromium PDF export session.");
+}
+
+async function openCdpPage(port) {
+  const response = await fetch(`http://127.0.0.1:${port}/json/new?about:blank`, { method: "PUT" });
+  const target = await response.json();
+  if (!target.webSocketDebuggerUrl) throw new Error("Could not open Chromium page target for PDF export.");
+  return target.webSocketDebuggerUrl;
+}
+
+async function printPdfViaCdp(wsUrl, url, pdf) {
+  const ws = await connectWebSocket(wsUrl);
+  let nextId = 0;
+  const pending = new Map();
+  let loadResolve = null;
+  const loaded = new Promise((resolve) => { loadResolve = resolve; });
+
+  ws.onMessage = (text) => {
+    const message = JSON.parse(text);
+    if (message.method === "Page.loadEventFired") {
+      if (loadResolve) loadResolve();
+      loadResolve = null;
+      return;
+    }
+    if (!message.id) return;
+    const entry = pending.get(message.id);
+    if (!entry) return;
+    pending.delete(message.id);
+    if (message.error) entry.reject(new Error(message.error.message || "CDP error"));
+    else entry.resolve(message.result);
+  };
+
+  const send = (method, params = {}) => new Promise((resolve, reject) => {
+    const id = ++nextId;
+    pending.set(id, { resolve, reject });
+    ws.send(JSON.stringify({ id, method, params }));
+  });
+
+  try {
+    await send("Page.enable");
+    await send("Runtime.enable");
+    await send("Page.navigate", { url });
+    await loaded;
+    await send("Runtime.evaluate", {
+      expression: "document.fonts ? document.fonts.ready.then(() => true) : true",
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    const result = await send("Page.printToPDF", {
+      printBackground: true,
+      preferCSSPageSize: true,
+      displayHeaderFooter: Boolean(pdf.displayHeaderFooter),
+      headerTemplate: pdf.headerTemplate || "<div></div>",
+      footerTemplate: pdf.footerTemplate || "<div></div>",
+      marginTop: mmToInches(pdf.marginTopMm ?? 12),
+      marginBottom: mmToInches(pdf.marginBottomMm ?? 12),
+      marginLeft: mmToInches(pdf.marginLeftMm ?? 12),
+      marginRight: mmToInches(pdf.marginRightMm ?? 12),
+    });
+    return Buffer.from(result.data, "base64");
+  } finally {
+    ws.close();
+  }
+}
+
+async function evaluatePageViaCdp(wsUrl, url, expression) {
+  const ws = await connectWebSocket(wsUrl);
+  let nextId = 0;
+  const pending = new Map();
+  let loadResolve = null;
+  const loaded = new Promise((resolve) => { loadResolve = resolve; });
+
+  ws.onMessage = (text) => {
+    const message = JSON.parse(text);
+    if (message.method === "Page.loadEventFired") {
+      if (loadResolve) loadResolve();
+      loadResolve = null;
+      return;
+    }
+    if (!message.id) return;
+    const entry = pending.get(message.id);
+    if (!entry) return;
+    pending.delete(message.id);
+    if (message.error) entry.reject(new Error(message.error.message || "CDP error"));
+    else entry.resolve(message.result);
+  };
+
+  const send = (method, params = {}) => new Promise((resolve, reject) => {
+    const id = ++nextId;
+    pending.set(id, { resolve, reject });
+    ws.send(JSON.stringify({ id, method, params }));
+  });
+
+  try {
+    await send("Page.enable");
+    await send("Runtime.enable");
+    await send("Page.navigate", { url });
+    await loaded;
+    await send("Runtime.evaluate", {
+      expression: "document.fonts ? document.fonts.ready.then(() => true) : true",
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    const result = await send("Runtime.evaluate", {
+      expression,
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    if (result.exceptionDetails) {
+      throw new Error(result.exceptionDetails.exception?.description || result.exceptionDetails.text || "Could not prepare ViteBoard PDF export.");
+    }
+    if (result.result?.type === "undefined") return null;
+    return result.result?.value ?? null;
+  } finally {
+    ws.close();
+  }
+}
+
+function mmToInches(mm) {
+  return Number(mm ?? 0) / 25.4;
+}
+
+async function connectWebSocket(wsUrl) {
+  const parsed = new URL(wsUrl);
+  if (parsed.protocol !== "ws:") throw new Error(`Unsupported DevTools protocol: ${parsed.protocol}`);
+
+  return new Promise((resolve, reject) => {
+    const key = randomBytes(16).toString("base64");
+    const req = http.request({
+      hostname: parsed.hostname,
+      port: parsed.port || 80,
+      path: `${parsed.pathname}${parsed.search}`,
+      headers: {
+        Connection: "Upgrade",
+        Upgrade: "websocket",
+        "Sec-WebSocket-Version": 13,
+        "Sec-WebSocket-Key": key,
+      },
+    });
+    req.once("upgrade", (res, socket) => {
+      const expectedAccept = createHash("sha1").update(key + WS_GUID).digest("base64");
+      if (res.headers["sec-websocket-accept"] !== expectedAccept) {
+        socket.destroy();
+        reject(new Error("Invalid DevTools WebSocket handshake."));
+        return;
+      }
+      resolve(new SimpleWebSocket(socket));
+    });
+    req.once("error", reject);
+    req.end();
+  });
+}
+
+class SimpleWebSocket {
+  constructor(socket) {
+    this.socket = socket;
+    this.buffer = Buffer.alloc(0);
+    this.onMessage = null;
+    socket.on("data", (chunk) => this.handleData(chunk));
+    socket.on("error", () => {});
+  }
+
+  send(text) {
+    const payload = Buffer.from(String(text));
+    const frame = encodeClientFrame(0x1, payload);
+    this.socket.write(frame);
+  }
+
+  close() {
+    try { this.socket.end(); } catch { /* ignore */ }
+  }
+
+  handleData(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    while (true) {
+      const frame = decodeFrame(this.buffer);
+      if (!frame) return;
+      this.buffer = this.buffer.slice(frame.byteLength);
+      if (frame.opcode === 0x1 && this.onMessage) this.onMessage(frame.payload.toString("utf-8"));
+      if (frame.opcode === 0x9) this.socket.write(encodeClientFrame(0xA, frame.payload));
+      if (frame.opcode === 0x8) {
+        this.close();
+        return;
+      }
+    }
+  }
+}
+
+function encodeClientFrame(opcode, payload) {
+  const payloadLength = payload.length;
+  const mask = randomBytes(4);
+  let header;
+  if (payloadLength < 126) {
+    header = Buffer.alloc(2);
+    header[1] = 0x80 | payloadLength;
+  } else if (payloadLength < 65536) {
+    header = Buffer.alloc(4);
+    header[1] = 0x80 | 126;
+    header.writeUInt16BE(payloadLength, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[1] = 0x80 | 127;
+    header.writeBigUInt64BE(BigInt(payloadLength), 2);
+  }
+  header[0] = 0x80 | (opcode & 0x0f);
+  const masked = Buffer.alloc(payloadLength);
+  for (let i = 0; i < payloadLength; i += 1) masked[i] = payload[i] ^ mask[i % 4];
+  return Buffer.concat([header, mask, masked]);
+}
+
+function decodeFrame(buffer) {
+  if (buffer.length < 2) return null;
+  const first = buffer[0];
+  const second = buffer[1];
+  let offset = 2;
+  let payloadLength = second & 0x7f;
+  if (payloadLength === 126) {
+    if (buffer.length < 4) return null;
+    payloadLength = buffer.readUInt16BE(2);
+    offset = 4;
+  } else if (payloadLength === 127) {
+    if (buffer.length < 10) return null;
+    payloadLength = Number(buffer.readBigUInt64BE(2));
+    offset = 10;
+  }
+  const masked = (second & 0x80) !== 0;
+  let mask = null;
+  if (masked) {
+    if (buffer.length < offset + 4) return null;
+    mask = buffer.slice(offset, offset + 4);
+    offset += 4;
+  }
+  if (buffer.length < offset + payloadLength) return null;
+  const payload = Buffer.from(buffer.slice(offset, offset + payloadLength));
+  if (masked && mask) {
+    for (let i = 0; i < payload.length; i += 1) payload[i] ^= mask[i % 4];
+  }
+  return {
+    fin: (first & 0x80) !== 0,
+    opcode: first & 0x0f,
+    payload,
+    byteLength: offset + payloadLength,
+  };
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function withTimeout(promise, ms, message) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), ms); }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/content/docs/guide/boards-in-markdown.md

@@ -32,10 +32,11 @@ The easiest way to create an embed:
 
 1. Open the board in the editor
 2. Navigate to the region you want to embed
-3. Click **Copy embed** in the toolbar
-4. Paste the snippet into your markdown document
+3. Click **Select region to embed or export** in the toolbar and drag over the area
+4. Choose **Embed in a document** from the popup
+5. Paste the copied snippet into your markdown document
 
-The copied snippet includes the exact viewport coordinates for the current view.
+The copied snippet includes the exact board coordinates for the selected region. Region selection also offers PDF, JPEG, and SVG export; SVG contains the rendered board as an image rather than editable vector shapes.
 
 ## How It Works
 

package/content/docs/guide/boards.md

@@ -52,3 +52,11 @@ These files are small, diffable, and work naturally with git.
 ## Exiting the Board Editor
 
 Click the back arrow in the top-left corner to return to the documentation view. Your board is saved automatically.
+
+## Exporting
+
+Open **Export / Import** in the board toolbar to export the current view or full board as PNG, or to export the board JSON or a JSON-plus-images bundle.
+
+To export or embed a specific region, choose **Select region to embed or export** and drag over the board. Then choose **Embed in a document**, **Export as PDF**, **Export as JPEG**, or **Export as SVG**. SVG preserves the canvas appearance by embedding a PNG image; its shapes are not editable vector paths. PDF export uses a Chromium-compatible browser installed on the machine running ViteBoard.
+
+From a Markdown document, use its **Export to PDF** action to create a PDF. Before exporting, choose the page format and any optional sections or publication details. ViteBoard returns the PDF for download and does not select a save path on your behalf.

package/content/machine/guide.md

@@ -54,6 +54,19 @@ Important discovery endpoints:
 - `GET /__api/project-tree?projectId={projectId}`
 - `GET /__api/tree?rootId={rootId}`
 
+### Live change notifications
+
+The UI subscribes to `GET /__api/events` as a Server-Sent Events (SSE) stream. API clients can use the same endpoint with the browser `EventSource` API or another SSE client. It is a one-way notification channel; after receiving an event, fetch the authoritative workspace, tree, file, or board again rather than treating the event as the content itself. Native SSE clients reconnect automatically, and a newly opened stream should trigger a fresh snapshot fetch to cover any events missed while disconnected.
+
+Mutations made through the HTTP API publish these named events after writing:
+
+- `workspace-changed`: project or docs-root registration changes (`action`, optional `projectId`).
+- `file-changed`: file/directory writes, renames, and deletes (`rootId`, `path`, `action`; rename includes `oldPath`).
+- `board-changed`: board create, write, or delete (`rootId`, `boardId`, `action`).
+- `asset-changed`: asset write or cleanup (`rootId`, optional `path`, `action`).
+
+Events include `actorId` when the caller sends `X-ViteBoard-Actor-Id`; the UI uses this to ignore its own write notifications while keeping other tabs current. Notifications refresh views and flag revision conflicts—they do not merge live drafts or replace revision-checked writes. Direct filesystem changes that bypass the API do not emit events.
+
 The machine can navigate the same app surfaces a human uses:
 
 - workspace home: `#/`
@@ -144,6 +157,33 @@ automation/docs-refresh
 
 Machines should treat the whole branch as the capability context and use `llms.txt` as the first machine-facing file when it exists.
 
+### Agent Skills compatibility
+
+Every capability is also exposed as a portable [Agent Skills](https://agentskills.io) skill. ViteBoard generates `SKILL.md` from the branch metadata, optional branch-local `SKILL.md`, `llms.txt` rules, and the supporting-file list; `index.md`, `llms.txt`, and the rest of the capability branch remain the source of truth.
+
+Discover and inspect capabilities through the HTTP API:
+
+- `GET /__api/capabilities` lists capabilities across registered docs roots. Add `?rootId={rootId}` or `?projectId={projectId}` to scope the result.
+- `GET /__api/capability?rootId={rootId}&path={branchPath}` returns one capability, including its rules, generated `skillMarkdown`, and supporting-file URLs. `path` is the capability branch path, for example `capabilities/automation/docs-refresh`. `omittedFiles` lists items too large or unsupported for the skill bundle; they remain in the source branch.
+- `GET /__api/skills/catalog/index.json` returns an OpenCode-compatible HTTP skill catalog. Skill files are served under `/__api/skills/catalog/{skillId}/{filePath}`; the catalog version changes when included skill/source content changes.
+
+For OpenCode, add the live catalog URL to `skills` in the project's `opencode.json` or `opencode.jsonc` (merge this into existing config):
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "skills": ["http://localhost:5173/__api/skills/catalog/"]
+}
+```
+
+Use the exact ViteBoard origin instead of the example URL. This keeps OpenCode skills live; the catalog includes every registered docs root. For local Agent Skills consumers, save the API's `skillMarkdown` as `SKILL.md` and preserve the returned `catalogPath` files beside it:
+
+- Codex: `.agents/skills/{skillId}/`
+- Claude Code: `.claude/skills/{skillId}/`
+- OpenCode: `.opencode/skills/{skillId}/` or `.agents/skills/{skillId}/`
+
+The `SKILL.md` uses portable `name` and `description` frontmatter. Up to 200 text/support files (1 MiB each) and common image/PDF assets (5 MiB each) are bundled, with a 16 MiB aggregate content limit; see `omittedFiles` for anything excluded. Catalog metadata is cached briefly, while skill file contents are read on demand. Local copies are snapshots; fetch them again after the capability changes. ViteBoard does not write into agent configuration directories automatically.
+
 ## 3. Markdown board embeds
 
 Use fenced `board` blocks inside Markdown:
@@ -272,11 +312,14 @@ When deciding how much to change:
 
 ## 8. Concurrent edits
 
-ViteBoard keeps autosave, but it does not coordinate live writers.
+ViteBoard keeps autosave, but it does not coordinate live writers with locks.
+
+1. Read `GET /__api/file?rootId={rootId}&path={path}` or `GET /__api/board?rootId={rootId}&id={boardId}` and retain its `revision`.
+2. Send that value as `expectedRevision` in the matching `PUT /__api/file` or `PUT /__api/board` request.
+3. For a create-only write, send `"expectedRevision": null`; this succeeds only if the target does not already exist.
+4. If the write returns `409`, reload the latest version and re-apply your change.
 
-1. Read the current file or board revision before editing.
-2. Write changes with the expected revision.
-3. If the write returns a conflict, reload the latest version and re-apply your change.
+The API serializes writes and deletes for each target, so simultaneous revision-checked requests cannot both pass against the same old state. Omitting `expectedRevision` remains available for compatibility but permits unconditional overwrites; machine clients should always send it.
 
 This keeps the runtime simple and fast. The UI does not lock files or boards while an agent writes.
 
@@ -296,3 +339,57 @@ Avoid these anti-patterns:
 - Embeds resolve by relative path.
 - Embed crops stay inside the intended frame.
 - The resulting layout is readable to a human.
+
+## 10. HTTP PDF export
+
+Use `POST /__api/export/document/pdf` to export a document or a directory of Markdown documents. The server renders Markdown and board embeds with ViteBoard's renderer, then returns PDF bytes with `Content-Type: application/pdf` and a suggested filename in `Content-Disposition`. Save those bytes with the agent's own file tools. The server does not write to a path on the agent's machine.
+
+Example request:
+
+```http
+POST /__api/export/document/pdf
+Content-Type: application/json
+
+{
+  "rootId": "root-...",
+  "kind": "doc",
+  "path": "guide/getting-started.md",
+  "options": {
+    "paper": "A4",
+    "style": "clean",
+    "scale": "100",
+    "showHeaderChrome": false,
+    "showFooterChrome": false,
+    "includeCoverPage": false,
+    "includeTableOfContents": false,
+    "includeFilePaths": false,
+    "pageBreakBetweenDocs": false
+  }
+}
+```
+
+Set `kind` to `dir` and `path` to a docs-root-relative directory to export its Markdown files. Optional `selectedPaths` limits that set. The `options` object supports the same publication settings as the UI: `title`, `subtitle`, `style` (`clean` or `report`), `paper` (`A4` or `Letter`), `scale` (`90`, `100`, or `110`), `includeCoverPage`, `includeTableOfContents`, `includeFilePaths`, `pageBreakBetweenDocs`, `showHeaderChrome`, `showFooterChrome`, `author`, `organization`, `publicationDate`, `classification`, `legalNotice`, and `logoDataUrl`.
+
+Optional features and metadata default to off or blank. Before every export, ask the human to choose the options. Explain each option and do not silently enable one. For agent workflows, see `/viteboard-skill.md`.
+
+## 11. HTTP board-region export
+
+Use `POST /__api/export/board` to export a saved board as PDF, JPEG, or SVG bytes. Provide a docs `rootId`, `boardId` (board ID without `.board.json`), and `format`. An optional `region` is `[x, y, width, height]` in board world units; it must have positive width and height. If omitted, ViteBoard exports the visible board content with 48 world units of padding. `padding` can override that inferred-content padding; for an explicit region it defaults to zero.
+
+```http
+POST /__api/export/board
+Content-Type: application/json
+
+{
+  "rootId": "root-...",
+  "boardId": "product-roadmap",
+  "format": "jpeg",
+  "region": [-400, 0, 1800, 900],
+  "scale": 2,
+  "quality": 0.92
+}
+```
+
+The optional `scale` sets output pixels per world unit (default `2`, accepted range `0.1`–`16`); dimensions are safely capped. `quality` sets JPEG quality from `0.1` to `1` (default `0.92`). For PDF, `paper` may be `A4` or `Letter` (default `A4`); page orientation follows the selected region. The endpoint returns bytes with the matching `Content-Type` and a suggested `Content-Disposition` filename. Save the response on the agent's machine.
+
+SVG exports are standards-compliant SVG containers with the rendered board embedded as a PNG image. This preserves ViteBoard's canvas rendering accurately, but the shapes inside are not editable vector paths; use `scale` to choose raster resolution.

package/content/machine/llms.txt

@@ -71,6 +71,7 @@ When helpful, tell the human which of these are relevant in the current workspac
 ## Core machine docs
 
 - [ViteBoard authoring guide](/viteboard-guide.md): Workspace model, routes, boards, embeds, capabilities, and revision-checked editing.
+- [ViteBoard agent skill](/viteboard-skill.md): HTTP workflows, safe edits, and user-selected PDF export settings.
 - [Board schema v1](/board-v1.schema.json): JSON Schema for `.board.json` files.
 - [Example board](/viteboard-example.board.json): One complete valid ViteBoard board.
 
@@ -79,8 +80,11 @@ When helpful, tell the human which of these are relevant in the current workspac
 - Capabilities are managed directory branches under `capabilities/` inside a docs root.
 - Human entrypoint: `index.md`
 - Machine entrypoint: `llms.txt`
+- Agent Skills entrypoint: generated standard `SKILL.md`, including branch rules from `llms.txt`.
 - The rest of the branch may contain markdown, scripts, helpers, assets, examples, and nested directories.
 
+Discover skills with `GET /__api/capabilities`; read a capability's rules, generated skill, and file URLs with `GET /__api/capability?rootId={rootId}&path={branchPath}`. OpenCode can consume the live catalog at `/__api/skills/catalog/`. See `/viteboard-guide.md` for setup and portable local skill locations.
+
 ## App discovery
 
 - [Workspace listing](/__api/workspace): Registered projects and docs roots.