agentbox-app 0.1.6

package/main/demo.mjs

@@ -0,0 +1,254 @@
+// A SECOND AGENTBOX WITH SOMEBODY ELSE'S WORK IN IT, FOR DEMOS.
+//
+// WHY THIS IS THE NEW-USER ROW AND NOT A NEW MECHANISM. Being a new user
+// already opens a second Agentbox inside a throwaway home
+// (shared/fresh-user-home.mjs, main/fresh-user.mjs), and everything that makes
+// that safe is exactly what a demo needs: her own copy keeps running with every
+// agent in it, nothing of hers is read, and nothing anywhere is deleted. The
+// single-instance lock is keyed on userData and a throwaway home is a different
+// userData, so the two stand side by side. That property is the whole thing,
+// and inventing a second way to get it would be inventing a second way to get
+// it wrong.
+//
+// WHAT IS DIFFERENT IS WHAT IS IN THE STORE. A new user opens on an empty one,
+// which is correct for testing a first run and useless for a demo: an inbox
+// with nothing in it demonstrates nothing. So this seeds three invented
+// products and a day of invented work first (shared/demo-world.mjs), and
+// because the store then has projects in it, the welcome walk does not run
+// (`firstRunNeeded` counts projects) and the copy opens straight on the inbox.
+//
+// AND HER ~/.claude IS NOT LINKED THROUGH, which is the one place this is
+// deliberately stricter than the new-user row. That folder holds the Claude
+// Code sessions already running on this Mac, and the app puts them in the
+// inbox as rows with her real folder names on them. In a demo those names are
+// on a projector. Claude Code itself and its login ARE linked, so answering a
+// row in the demo starts a real agent on an invented product, which is the
+// most convincing thing the demo can do.
+//
+// NOTHING IS DELETED HERE, EVER, and there is no version of this file that may
+// delete anything outside `HOMES` below.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { DEMO_DOCS, DEMO_ENV, DEMO_PRODUCTS, demoLedgerLines } from '../shared/demo-world.mjs';
+import { prepareHome } from '../shared/fresh-user-home.mjs';
+import { Name } from '../shared/product-name.mjs';
+import { relaunchCommand } from './fresh-user.mjs';
+import { encodeProjectPath, storeRootEnv } from './store/home.mjs';
+import { NAME, nameSlug } from '../shared/product-name.mjs';
+
+/**
+ * Where every demo home lives. Its own folder, NOT the first-run one: the two
+ *  are cleared separately, and a demo home under the first-run folder would
+ *  read as a fresh-user install to `runningAsAFreshUser` and send its counts
+ *  under the wrong fixed id. */
+export const HOMES = path.join(os.tmpdir(), `${nameSlug}-demo`);
+
+/**
+ * The account the demo store is laid out under. It matches the id
+ *  `main/config.mjs` defaults to, because the demo copy has no config file and
+ *  will therefore look for its products at exactly this path. */
+export const DEMO_ACCOUNT = '00000000-0000-4000-8000-000000000000';
+
+/**
+ * Named by the clock, like a fresh-user home, so the newest sorts last and two
+ *  demos opened a minute apart are told apart on disk. */
+export function makeDemoHome(now = new Date()) {
+  const stamp = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const home = path.join(HOMES, stamp);
+  fs.mkdirSync(home, { recursive: true });
+  return home;
+}
+
+/** The demo homes on disk, oldest first. */
+export function demoHomes() {
+  if (!fs.existsSync(HOMES)) return [];
+  return fs
+    .readdirSync(HOMES)
+    .map((name) => path.join(HOMES, name))
+    .filter((dir) => { try { return fs.statSync(dir).isDirectory(); } catch { return false; } })
+    .sort();
+}
+
+/**
+ * Delete every demo home. Only ever this /tmp folder: `HOMES` is not
+ *  configurable, and that is on purpose. */
+export function clearDemoHomes() {
+  try {
+    fs.rmSync(HOMES, { recursive: true, force: true });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * Where the demo copy will keep its store, and where it will keep its own
+ *  records. Both are derived from the throwaway home rather than configured,
+ *  because the copy derives them the same way from the same home: `storeRoot`
+ *  defaults to `<home>/<Name>` (main/config.mjs) and the app's home defaults
+ *  to `<home>/.agentbox` (main/store/home.mjs).
+ *
+ *  THE FOLDER IS READ FROM THE SAME CONSTANT AS THAT DEFAULT, not spelled out
+ *  again. It was the literal 'the app' mirroring what config.mjs then said,
+ *  and when that default was renamed on 2026-09-22 this line went on pointing
+ *  at the old folder: the demo copy would have written its store to one place
+ *  and looked for it in another. Two literals that have to agree is the defect;
+ *  one import is the fix. */
+export function demoPaths(home) {
+  const storeRoot = path.join(home, Name);
+  return {
+    storeRoot,
+    accountRoot: path.join(storeRoot, 'accounts', DEMO_ACCOUNT),
+    appHome: path.join(home, `.${nameSlug}`),
+  };
+}
+
+/**
+ * The invented studio, written out as a real store.
+ *
+ * THE LEDGER DOES NOT GO IN THE PRODUCT FOLDER, and this is the one thing in
+ * here that is easy to get wrong: since 2026-08-27 the app keeps its own
+ * records under its own home, `<appHome>/projects/<encoded product dir>/`
+ * (main/store/home.mjs). Writing `work-items.jsonl` beside `project.json`
+ * instead would produce a demo whose inbox is empty, and the file would then be
+ * silently folded away the first time anything touched the store. The encoding
+ * is imported rather than repeated for exactly that reason.
+ *
+ * `.origin` is written alongside, because that is what the app writes on first
+ * use and what `removeMachinery` refuses to act without.
+ */
+export function seedDemoStore(home, { now = Date.now() } = {}) {
+  const { accountRoot, appHome } = demoPaths(home);
+  const ledgers = demoLedgerLines(now);
+  const written = [];
+
+  for (const product of DEMO_PRODUCTS) {
+    const dir = path.join(accountRoot, product.slug);
+    fs.mkdirSync(dir, { recursive: true });
+
+    fs.writeFileSync(path.join(dir, 'project.json'), `${JSON.stringify({
+      schemaVersion: 2,
+      id: product.slug,
+      name: product.name,
+      createdAt: new Date(now - 21 * 86_400_000).toISOString(),
+      oneLiner: product.oneLiner,
+    }, null, 2)}\n`);
+
+    // The documents, and the catalog that makes them visible. A file on disk
+    // with no entry in index.json is a file the pane does not know about
+    // (main/store/project.mjs), so both halves or neither.
+    const docs = DEMO_DOCS[product.slug] ?? [];
+    for (const doc of docs) {
+      const file = path.join(dir, doc.path);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, `${doc.text}\n`);
+    }
+    fs.writeFileSync(path.join(dir, 'index.json'), `${JSON.stringify({
+      schemaVersion: 2,
+      creations: docs.map((doc, i) => ({
+        id: `${product.slug}-doc-${i + 1}`,
+        kind: 'markdown',
+        title: doc.title,
+        path: doc.path,
+        ts: now - (i + 1) * 3_600_000,
+        schemaVersion: 2,
+      })),
+      runs: [],
+      reports: [],
+      updatedAt: now,
+    }, null, 2)}\n`);
+
+    // And the work, where the app will actually look for it.
+    const machinery = path.join(appHome, 'projects', encodeProjectPath(dir));
+    fs.mkdirSync(machinery, { recursive: true });
+    fs.writeFileSync(path.join(machinery, '.origin'), `${dir}\n`);
+    const jsonl = (ledgers[product.slug] ?? []).map((line) => JSON.stringify(line)).join('\n');
+    fs.writeFileSync(path.join(machinery, 'work-items.jsonl'), jsonl ? `${jsonl}\n` : '');
+
+    // ROWS, NOT LINES, because this number is read out loud in the toast. One
+    // row is two or three appended lines (filed, then said, then finished), so
+    // counting the file's lines said twenty where she can see nine.
+    const ids = new Set((ledgers[product.slug] ?? []).map((line) => line.id));
+    written.push({ slug: product.slug, dir, machinery, rows: ids.size });
+  }
+
+  return { accountRoot, appHome, products: written };
+}
+
+/**
+ * The environment a demo copy is launched with.
+ *
+ *  BOTH HOME VARIABLES, ALWAYS, for the reason `freshEnv` gives: HOME alone
+ *  does not move `app.getPath('appData')` on macOS, so the copy would share her
+ *  userData, lose the single-instance lock race and quit in half a second.
+ *
+ *  ASTRAL_HOME IS SET EXPLICITLY AND THAT IS NOT BELT AND BRACES. The app's home
+ *  reads that variable first and only falls back to `~/.astral`, so a parent
+ *  process that happens to have it set (every session Agentbox spawns does) would
+ *  hand it straight through and the demo copy would read HER ledger while
+ *  standing in an invented store. */
+export function demoEnv(home, env = process.env) {
+  const { appHome } = demoPaths(home);
+  return { ...env, HOME: home, CFFIXED_USER_HOME: home, ...storeRootEnv(appHome), [DEMO_ENV]: '1' };
+}
+
+/**
+ * Open one. Returns what happened in the words the app will show her, rather
+ * than throwing: a row in ⌘K that fails silently is worse than one that says
+ * why.
+ *
+ * `withAgents` is FALSE and has no parameter, unlike the new-user row. See the
+ * head of this file: linking her ~/.claude through would put her real folder
+ * names in the demo inbox, and the demo exists so that does not happen.
+ */
+export function openDemo({
+  execPath = process.execPath,
+  argv = process.argv,
+  packaged = true,
+  spawnFn = spawn,
+  now,
+} = {}) {
+  let home;
+  let prepared;
+  let seeded;
+  try {
+    home = makeDemoHome(now ? new Date(now) : undefined);
+    prepared = prepareHome(home, { withAgents: false });
+    seeded = seedDemoStore(home, { now: now ?? Date.now() });
+  } catch (err) {
+    return { ok: false, error: `Could not lay out a demo under ${HOMES}: ${err?.message ?? err}` };
+  }
+
+  const { bin, args } = relaunchCommand({ execPath, argv, packaged });
+  if (!bin || !fs.existsSync(bin)) {
+    return { ok: false, error: `Cannot find this app's own program at ${bin}.`, home };
+  }
+
+  let child;
+  try {
+    child = spawnFn(bin, args, { detached: true, stdio: 'ignore', env: demoEnv(home) });
+    child.unref?.();
+  } catch (err) {
+    return { ok: false, error: `Could not start a second ${NAME}: ${err?.message ?? err}`, home };
+  }
+
+  // THE NOTES ARE THE HONEST PART, the same as the new-user row's. Both of
+  // these are things the demo copy can be missing while still looking fine, and
+  // both of them mean the same thing: answering a row in front of a room will
+  // not start an agent. Better said now than found out on the projector.
+  const notes = [];
+  if (!prepared.claudeBin) notes.push('Claude Code is not at ~/.local/bin/claude, so agents will not run in the demo.');
+  if (!prepared.keychain) notes.push('There is no ~/Library/Keychains here, so Claude Code will say it is not logged in.');
+
+  return {
+    ok: true,
+    home,
+    products: seeded.products.map((p) => p.slug),
+    rows: seeded.products.reduce((n, p) => n + p.rows, 0),
+    notes,
+    pid: child?.pid ?? null,
+  };
+}

package/main/dev-window.mjs

@@ -0,0 +1,103 @@
+// A HOT-RELOADING WINDOW MUST NOT BE THE ONE SHE WORKS IN.
+//
+// She was working in a window an agent had started against a vite dev server,
+// on her real store. Vite rebuilds that window whenever the source under it
+// changes, and the source under it is the checkout every agent shares: it was
+// checked out or merged five times in the eleven minutes before she wrote.
+//
+// The one that gets her is a change to App.tsx that adds, removes or moves a
+// hook, which is what a branch switch does to it. React Fast Refresh keeps a
+// component's state only while its hooks match, so App is rebuilt from nothing:
+// `snap` is null again, App.tsx draws `<div className="boot">the app</div>`, and
+// every child of App is thrown away and remade. That is the screen she means by
+// the zero loading page, and that is the artifact closing and reopening. The
+// page never navigates, which is why nothing in the dev server's log looked bad
+// enough to be it. Six triggers were measured against a real window and exactly
+// one was guilty: scripts/what-throws-her-out-of-agentbox.mjs.
+//
+// THE GUARD IS HERE RATHER THAN IN scripts/dev.mjs BECAUSE THAT IS NOT HOW IT
+// HAPPENED. The dev server that day was started by hand, straight out of a
+// scratchpad, and the app was started beside it with the environment variable
+// set. A guard in the npm script would have watched it go past. Every dev window
+// there can ever be goes through main.mjs asking for this verdict, so this is
+// the only place that actually closes the door.
+//
+// WHAT IS STILL ALLOWED, because a guard that stops the work is a guard somebody
+// deletes:
+//
+//   Fixtures. Nothing in a fixtures window is hers, so there is nothing to be
+//   thrown out of, and this is what screenshot and proof scripts use.
+//
+//   A throwaway store. A script that points HOME at a temp directory has no
+//   accounts under its store root, and a window on an empty store is nobody's
+//   working day.
+//
+//   Saying you meant it, with ZERO_DEV_ON_REAL_STORE=1.
+
+// `storeHasWork` is passed in rather than read here so this stays a pure
+// decision and can be tested without a disk.
+export function hotWindowVerdict({ devUrl, fixtures, forced, storeRoot, storeHasWork }) {
+  if (!devUrl) return { allow: true, reason: 'no dev server' };
+  if (fixtures) return { allow: true, reason: 'fixtures' };
+  if (forced) return { allow: true, reason: 'ZERO_DEV_ON_REAL_STORE' };
+  if (!storeHasWork) return { allow: true, reason: 'no accounts under the store root' };
+  return {
+    allow: false,
+    reason: 'a hot-reloading window on the real store',
+    message: [
+      '',
+      `  ZERO_DEV_URL is set and the store is ${storeRoot}, which is the real one.`,
+      '  A window served by a dev server is rebuilt whenever any agent changes the',
+      '  source under it, and being thrown back to the boot screen mid-task is what',
+      '  w-435356146a was about. Not opening one.',
+      '',
+      '  For development:            ZERO_FIXTURES=1',
+      '  To give her a real window:  npm start, with ZERO_DEV_URL unset',
+      '  If you truly meant this:    ZERO_DEV_ON_REAL_STORE=1',
+      '',
+    ].join('\n'),
+  };
+}
+
+// Whether a store root has anybody's work under it. An account directory is the
+// smallest true sign: a throwaway home has none, hers has one.
+export function storeHasWork(fs, path, storeRoot) {
+  try {
+    const accounts = path.join(storeRoot, 'accounts');
+    return fs.readdirSync(accounts).some((name) => !name.startsWith('.'));
+  } catch {
+    // No store root, no accounts directory, no permission: all of them mean
+    // there is no working day here to interrupt.
+    return false;
+  }
+}
+
+// A DEV SERVER MUST NEVER INHERIT A WINDOW IT DID NOT OPEN.
+//
+// Second half of the same bug, found 2026-08-23 16:00 while getting her out of
+// it. Killing the dev server under her window does not navigate it: vite's
+// client logs "server connection lost, polling for restart" and then polls
+// `${devUrl}` once a second forever, and it only calls `location.reload` once
+// one of those pings SUCCEEDS
+// (node_modules/vite/dist/client/client.mjs:560-562, waitForSuccessfulPing at
+// :732). So her window survived intact with the server gone, but it was left
+// waiting on port 5199 like a trap: the next `npm run dev` anybody ran would
+// bind that port, her poll would succeed, and she would be thrown straight back
+// into the boot screen and back onto the treadmill.
+//
+// A fixed port is what makes that possible, so dev servers stop using one. Each
+// run takes a free ephemeral port and tells its own electron where to find it.
+// A window polling yesterday's port then polls it forever and nothing answers,
+// which is the whole point.
+export function chooseDevPort(net) {
+  const server = net.createServer();
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    // Port 0 asks the OS for one nothing else holds, so this can never pick a
+    // port some other window is already waiting on.
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      server.close((err) => (err ? reject(err) : resolve(port)));
+    });
+  });
+}

package/main/doc-file.mjs

@@ -0,0 +1,99 @@
+// Reading and writing the markdown file the document pane has open.
+//
+// So the pane types straight onto the file on disk. Two rules make that safe
+// enough to leave switched on:
+//
+//   1. ONLY MARKDOWN IS WRITABLE. An html page is a program; the pane shows it
+//      in a sandboxed frame and never edits it. Everything else the pane will
+//      not even open (renderer/src/doc-pane.ts).
+//   2. A WRITE STAYS INSIDE THE PRODUCT'S OWN FOLDERS. Reading follows the
+//      finder's own rule and will honour an absolute path a worker typed, which
+//      is how a link into the app's repo works; writing will not. The file has
+//      to sit under the docs dir or the repo of the product whose card is open,
+//      or nothing is written.
+//
+// Pure of Electron on purpose: the IPC layer hands in the resolved path and the
+// product, and these two functions are the whole of the disk access.
+import fsDefault from 'node:fs';
+import path from 'node:path';
+import { artifactRoots } from './artifact-path.mjs';
+
+export const EDITABLE_RE = /\.(md|markdown)$/i;
+export const READABLE_RE = /\.(md|markdown|html?)$/i;
+
+// A megabyte and a half of markdown is already far past anything in her store
+// (the largest is decisions.md). Past that the editor is not the right tool and
+// a silent truncation would eat her file on the next save, so it says so.
+export const MAX_DOC_BYTES = 1_500_000;
+
+/** Is `file` inside `dir`, without a prefix match like /a/bc counting as /a/b. */
+export function isInside(dir, file) {
+  if (!dir || !file) return false;
+  const d = path.resolve(dir);
+  const f = path.resolve(file);
+  return f === d || f.startsWith(d + path.sep);
+}
+
+/** May the pane write to this file, on this product. */
+export function canWrite({ file, product, fs = fsDefault }) {
+  if (!file || !EDITABLE_RE.test(file)) {
+    return { ok: false, error: 'Only markdown files can be edited here.' };
+  }
+  const roots = artifactRoots(product);
+  if (!roots.some((root) => isInside(root, file))) {
+    const name = product?.name || 'this project';
+    return { ok: false, error: `That file is outside ${name}, so nothing was saved.` };
+  }
+  if (!fs.existsSync(file)) {
+    return { ok: false, error: 'That file is no longer there, so nothing was saved.' };
+  }
+  return { ok: true };
+}
+
+/** The text of a document the pane has open, with what it is and when it changed. */
+export function readDoc({ file, fs = fsDefault }) {
+  if (!file || !READABLE_RE.test(file)) return { ok: false, error: 'That is not a document this pane can open.' };
+  let stat;
+  try { stat = fs.statSync(file); } catch { return { ok: false, error: 'That file is no longer there.' }; }
+  if (stat.size > MAX_DOC_BYTES) {
+    return { ok: false, error: 'That file is too big to open here. It opened outside instead.', tooBig: true };
+  }
+  try {
+    return { ok: true, path: file, text: fs.readFileSync(file, 'utf8'), mtime: stat.mtimeMs };
+  } catch (err) {
+    return { ok: false, error: String(err?.message ?? err).slice(0, 200) };
+  }
+}
+
+/**
+ * Her edit, onto the file.
+ *
+ * `mtime` is what the pane believed was on disk when it loaded. If the file has
+ * moved on since — an agent rewrote it while she was typing — the write is
+ * refused rather than silently winning, and the pane says so. The old editor
+ * holds an incoming agent update off while she has unsaved edits, which is the
+ * same rule from the other end; here the file is the shared thing, so the check
+ * is on the file.
+ */
+export function writeDoc({ file, product, text, mtime, fs = fsDefault }) {
+  const allowed = canWrite({ file, product, fs });
+  if (!allowed.ok) return allowed;
+  if (typeof text !== 'string') return { ok: false, error: 'Nothing to save.' };
+  if (mtime) {
+    let now = 0;
+    try { now = fs.statSync(file).mtimeMs; } catch { /* handled by canWrite */ }
+    // A second's slack: some filesystems round mtime, and our own write is what
+    // moved it last in the ordinary case.
+    if (now && now - mtime > 1000) {
+      return { ok: false, stale: true, error: 'Something else changed this file while you were typing, so nothing was saved.' };
+    }
+  }
+  try {
+    fs.writeFileSync(file, text, 'utf8');
+    let after = 0;
+    try { after = fs.statSync(file).mtimeMs; } catch { /* the write succeeded */ }
+    return { ok: true, mtime: after };
+  } catch (err) {
+    return { ok: false, error: String(err?.message ?? err).slice(0, 200) };
+  }
+}

package/main/doc-scheme.mjs

@@ -0,0 +1,126 @@
+// THE ORIGIN THE DOCUMENT PANE SERVES A PAGE FROM, so its pictures load.
+//
+// She was reading one of our own design pages and every <img> in it was a
+// broken placeholder with the alt text beside it.
+//
+// WHY THEY WERE BROKEN, measured before this was written. The pane drew the
+// page in `<iframe sandbox="allow-scripts" src="file://…">`. A sandbox without
+// allow-same-origin gives the frame an OPAQUE origin, and Chromium refuses to
+// let an opaque origin pull a file:// subresource. The probe: the same image,
+// same folder, same frame.
+//
+//   sandbox="allow-scripts"                    naturalWidth 0
+//     console: "Not allowed to load local resource: file:///…/shot.png"
+//   sandbox="allow-scripts allow-same-origin"  naturalWidth 2880
+//
+// So the one-line fix is to add allow-same-origin, AND THAT IS THE HOLE, not
+// the fix. The app's own window is loaded with loadFile (main.mjs), so the app
+// itself is a file:// page. A file:// frame that is allowed to be same-origin
+// sits in the same origin as the app, and a page an agent wrote could then
+// reach straight into her inbox. Chromium says as much out loud: "An iframe
+// which has both allow-scripts and allow-same-origin for its sandbox attribute
+// can escape its sandboxing."
+//
+// So the page gets an origin of its OWN instead. This scheme is registered as
+// standard and secure, the pane points the frame at astral-doc://file/…, and
+// the frame may keep allow-same-origin because "same origin" now means "the
+// same as other documents", not "the same as Agentbox". Measured in the same
+// probe, on this scheme:
+//
+//   naturalWidth 2880, origin "astral-doc://file", parent.document -> BLOCKED
+//
+// WHAT MAY BE SERVED. A page can ask this scheme for any path it likes, so the
+// answer cannot be "whatever is on disk". Grants below are the whole of it: the
+// pane names a file when it opens one, and only that file's own folder and the
+// product's own artifact roots become readable. Her real design pages do climb
+// out of their own folder — 17 references across the 200 html files in this
+// product point at ../attachments, ../landing and ../../landing/assets — which
+// is why the roots are granted and not just the folder.
+import path from 'node:path';
+import { DOC_SCHEME, DOC_SCHEMES, isScheme } from '../shared/schemes.mjs';
+
+// The name is read rather than typed, and every spelling this app has used is
+// still answered, because a url on this scheme is STORED. shared/schemes.mjs
+// carries that argument in full.
+export { DOC_SCHEME, DOC_SCHEMES };
+
+// A standard scheme needs a host, and this one has exactly one: every document
+// is a full absolute path under it. Keeping a single host keeps a single
+// origin, so a page and the picture beside it never look cross-origin to each
+// other.
+export const DOC_HOST = 'file';
+
+/** The url the pane points its frame at, for a file already resolved on disk. */
+export function docUrl(file) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) return null;
+  // Each segment on its own: encodeURIComponent would eat the separators, and
+  // encodeURI would leave '#' and '?' in a filename to be read as url syntax.
+  const parts = file.split('/').filter(Boolean).map(encodeURIComponent);
+  return `${DOC_SCHEME}://${DOC_HOST}/${parts.join('/')}`;
+}
+
+/** The file a request under this scheme is asking for, or null if it is not one. */
+export function docPath(url) {
+  let parsed;
+  try { parsed = new URL(String(url)); } catch { return null; }
+  if (!isScheme(DOC_SCHEMES, parsed.protocol)) return null;
+  let file;
+  try { file = decodeURIComponent(parsed.pathname); } catch { return null; }
+  if (!file.startsWith('/')) return null;
+  // The url is the only thing between a page and the disk, so a climb written
+  // into it is normalised away here rather than trusted to the grant check.
+  const normal = path.normalize(file);
+  return path.isAbsolute(normal) ? normal : null;
+}
+
+/** Is `file` inside `dir`, without /a/bc counting as inside /a/b. */
+function inside(dir, file) {
+  if (!dir || !file) return false;
+  const d = path.resolve(dir);
+  const f = path.resolve(file);
+  return f === d || f.startsWith(d + path.sep);
+}
+
+/**
+ * What the scheme is allowed to hand out.
+ *
+ * The pane opens one document at a time, so this stays small on purpose: a
+ * grant is made when a document is resolved for the pane and the oldest falls
+ * off. It is a plain object with no Electron in it so the rule can be tested
+ * for real rather than asserted against the source.
+ */
+export class DocGrants {
+  constructor(limit = 8) {
+    this.limit = limit;
+    this.roots = [];
+  }
+
+  /** Open this file, and the folders that come with it, to the scheme. */
+  grant(file, roots = []) {
+    if (typeof file !== 'string' || !path.isAbsolute(file)) return;
+    const add = [path.dirname(file), ...roots.filter((r) => typeof r === 'string' && r)];
+    for (const root of add) {
+      const r = path.resolve(root);
+      if (this.roots.includes(r)) continue;
+      this.roots.push(r);
+    }
+    while (this.roots.length > this.limit) this.roots.shift();
+  }
+
+  /** May the scheme read this path. */
+  allows(file) {
+    if (typeof file !== 'string' || !path.isAbsolute(file)) return false;
+    return this.roots.some((root) => inside(root, file));
+  }
+}
+
+// A PAGE GOES OUT EXACTLY AS IT WAS WRITTEN, and that is deliberate.
+//
+// For a few hours on 2026-08-21 this file also injected a listener into every
+// page it served, so a pinch with the cursor inside the document could reach
+// the app and zoom the page on its own.
+//
+// So the document has no zoom of its own. The app zoom (main/menu.mjs,
+// main/zoom-keys.mjs) scales the window, and the pane is an ordinary iframe in
+// that window, so an open file follows it like everything else. Do not put a
+// listener back into a served page: nothing is injected into a file she reads.