viewable-one 0.0.0-stage → 0.12.2

package/lib/pagePictures.mjs

@@ -0,0 +1,396 @@
+// BEFORE AND AFTER PICTURES OF THE PAGE A CODING RUN CHANGED (#2194, the
+// result card #2023, ruling #2040 item 5: still pictures, nothing runs).
+//
+// The one module the runner calls for pictures and the page check. Drop it
+// (and pageRoutes.mjs, which only it uses) and a run goes back to tests and
+// build only (library choices are on trial). It
+// adds no dependency: the browser is one already installed (Chrome, Edge or
+// Chromium), driven headless over its own DevTools pipe, and the changed area
+// is found by comparing the two pictures inside that same browser.
+//
+// The order is fixed and one app runs at a time:
+//   checkPage      the copy's app, After, and the page check (part of the
+//                  check pass, so a failure gets the one automatic fix)
+//   beforePicture  the folder's app, Before, and the changed area
+// The folder is still the "before" state at the end of a run, because the run
+// worked in its copy. Nothing here ever fails a run: every problem is a
+// skipped or failed check and a plain line.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { access, mkdtemp, readFile, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { devServerEnv } from "./child.mjs";
+import { killTree } from "./kill.mjs";
+import { pageOf, isScreenFile } from "./pageRoutes.mjs";
+import { runnableCommand } from "./windows-command.mjs";
+
+export { isScreenFile, PAGE_RECORD_FILE, pageNameOf, pageOf, routeOf } from "./pageRoutes.mjs";
+
+
+export const NO_BROWSER = "No pictures: no browser found.";
+export const NO_APP = "No pictures: the app did not start.";
+export const NO_APP_SCRIPT = "No pictures: this folder has no app to start.";
+export const BROWSER_CLOSED = "No pictures: the browser closed.";
+
+const VIEWPORT = { width: 1440, height: 900 };
+const APP_START_MS = 60_000;
+const PAGE_LOAD_MS = 30_000;
+const SETTLE_MS = 1_000;
+const CALL_MS = 20_000;
+const CLOSE_MS = 2_000;
+const POLL_MS = 200;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// ---------- which browser ----------
+
+const MAC_APPS = ["Google Chrome", "Microsoft Edge", "Chromium"];
+const WINDOWS_EXES = [["Google", "Chrome", "Application", "chrome.exe"], ["Microsoft", "Edge", "Application", "msedge.exe"], ["Chromium", "Application", "chrome.exe"]];
+const LINUX_BINS = ["google-chrome", "google-chrome-stable", "microsoft-edge", "microsoft-edge-stable", "chromium", "chromium-browser"];
+
+/** A browser already on this computer, as `{bin, args}`, or null. Nothing is
+ *  ever downloaded. `GLYTCH_BROWSER` names one, or `none` turns pictures off. */
+export function findBrowser({ env = process.env, platform = process.platform, exists = existsSync } = {}) {
+  const named = (env.VIEWABLE_BROWSER ?? env.GLYTCH_BROWSER)?.trim();
+  if (named) return named.toLowerCase() === "none" ? null : { bin: named, args: [] };
+  const candidates = [];
+  if (platform === "darwin") {
+    for (const app of MAC_APPS) {
+      for (const base of ["/Applications", env.HOME && join(env.HOME, "Applications")].filter(Boolean)) {
+        candidates.push(join(base, `${app}.app`, "Contents", "MacOS", app));
+      }
+    }
+  } else if (platform === "win32") {
+    const bases = [env.ProgramFiles ?? env.PROGRAMFILES, env["ProgramFiles(x86)"], env.LOCALAPPDATA].filter(Boolean);
+    for (const parts of WINDOWS_EXES) for (const base of bases) candidates.push(join(base, ...parts));
+  } else {
+    const dirs = String(env.PATH ?? "").split(delimiter).filter(Boolean);
+    for (const bin of LINUX_BINS) for (const dir of dirs) candidates.push(join(dir, bin));
+  }
+  const bin = candidates.find((c) => exists(c));
+  return bin ? { bin, args: [] } : null;
+}
+
+// ---------- the browser, over its DevTools pipe ----------
+
+/** Start the browser headless with a fresh profile it forgets afterwards. */
+export async function openBrowser(browser, { platform = process.platform, stopCheck, deadline = Infinity } = {}) {
+  const profile = await mkdtemp(join(tmpdir(), "viewable-browser-"));
+  const args = [
+    ...browser.args, "--headless=new", "--remote-debugging-pipe", `--user-data-dir=${profile}`,
+    "--no-first-run", "--no-default-browser-check", "--disable-extensions", "--disable-sync",
+    "--disable-background-networking", "--hide-scrollbars", "--mute-audio",
+    `--window-size=${VIEWPORT.width},${VIEWPORT.height}`, "about:blank",
+  ];
+  // The person's own browser, but not the runner's secrets.
+  const child = spawn(browser.bin, args, { stdio: ["ignore", "ignore", "ignore", "pipe", "pipe"], windowsHide: true, env: devServerEnv(process.env, platform) });
+  const waiting = new Map();
+  const listeners = new Set();
+  let nextId = 1;
+  let gone = null;
+  let buffer = "";
+  const fail = (error) => {
+    gone ??= error;
+    for (const { reject } of waiting.values()) reject(gone);
+    waiting.clear();
+  };
+  child.on("error", fail);
+  child.on("exit", () => fail(new Error("The browser closed.")));
+  child.stdio[3].on("error", () => {});
+  child.stdio[4].setEncoding("utf8");
+  child.stdio[4].on("data", (chunk) => {
+    buffer += chunk;
+    for (let end = buffer.indexOf("\0"); end >= 0; end = buffer.indexOf("\0")) {
+      let message;
+      try { message = JSON.parse(buffer.slice(0, end)); } catch { message = null; }
+      buffer = buffer.slice(end + 1);
+      if (!message) continue;
+      const call = message.id !== undefined ? waiting.get(message.id) : undefined;
+      if (call) {
+        waiting.delete(message.id);
+        if (message.error) call.reject(new Error(message.error.message ?? "DevTools error"));
+        else call.resolve(message.result ?? {});
+      } else {
+        for (const listener of listeners) listener(message);
+      }
+    }
+  });
+  const send = (method, params = {}, sessionId, ms = CALL_MS) => new Promise((resolve, reject) => {
+    if (gone) return reject(gone);
+    const id = nextId++;
+    const timer = setTimeout(() => { waiting.delete(id); reject(new Error(`${method} did not answer.`)); }, ms);
+    waiting.set(id, { resolve: (v) => { clearTimeout(timer); resolve(v); }, reject: (e) => { clearTimeout(timer); reject(e); } });
+    child.stdio[3].write(`${JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })}\0`);
+  });
+  const close = async ({ ask = true } = {}) => {
+    if (ask) try { await send("Browser.close", {}, undefined, CLOSE_MS); } catch { /* gone, or not answering */ }
+    if (child.exitCode === null && child.signalCode === null) {
+      await killTree(child.pid, { force: true, platform, signal: (_pid, sig) => child.kill(sig) }).catch(() => {});
+    }
+    await rm(profile, { recursive: true, force: true, maxRetries: 3 }).catch(() => {});
+  };
+  const tab = async () => {
+    const { targetId } = await send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await send("Target.attachToTarget", { targetId, flatten: true });
+    const call = (method, params) => send(method, params, sessionId);
+    await call("Page.enable");
+    await call("Network.enable");
+    await call("Emulation.setDeviceMetricsOverride", { ...VIEWPORT, deviceScaleFactor: 1, mobile: false });
+    return { sessionId, call };
+  };
+  /** `promise`, looked at every POLL_MS so Stop, the time limit and a browser
+   *  that went away each end the wait at once. */
+  const waitFor = async (promise, { until, stopCheck }) => {
+    let settled = null;
+    promise.then((value) => { settled = { value }; }, (error) => { settled = { error }; });
+    for (;;) {
+      if (settled?.error) throw settled.error;
+      if (settled) return { value: settled.value };
+      if (gone) throw gone;
+      if (await stopCheck?.()) return { stopped: true };
+      if (Date.now() >= until) return { late: true };
+      await sleep(Math.max(1, Math.min(POLL_MS, until - Date.now())));
+    }
+  };
+  /** Open `url` and take a still picture once it has loaded. */
+  const shoot = async (url, { stopCheck, deadline = Infinity } = {}) => {
+    const until = Math.min(Date.now() + PAGE_LOAD_MS, deadline);
+    const page = await tab();
+    let status;
+    let loaded;
+    const load = new Promise((resolve) => { loaded = resolve; });
+    const listener = (m) => {
+      if (m.sessionId !== page.sessionId) return;
+      if (m.method === "Network.responseReceived" && m.params?.type === "Document" && status === undefined) status = m.params.response?.status;
+      if (m.method === "Page.loadEventFired") loaded(true);
+    };
+    listeners.add(listener);
+    const late = () => ({ ok: false, status, reason: "it did not finish loading", ...(Date.now() >= deadline ? { timedOut: true } : {}) });
+    try {
+      const nav = await waitFor(page.call("Page.navigate", { url }), { until, stopCheck });
+      if (nav.stopped) return { ok: false, stopped: true };
+      if (nav.late) return late();
+      if (nav.value.errorText) return { ok: false, reason: nav.value.errorText };
+      const done = await waitFor(load, { until, stopCheck });
+      if (done.stopped) return { ok: false, stopped: true };
+      if (done.late) return late();
+      await sleep(SETTLE_MS);
+      const shot = await page.call("Page.captureScreenshot", { format: "jpeg", quality: 70 });
+      return { ok: status === undefined || status < 400, status, image: `data:image/jpeg;base64,${shot.data}`, ...(status >= 400 ? { reason: `it answered ${status}` } : {}) };
+    } finally {
+      listeners.delete(listener);
+    }
+  };
+  /** The part of After that differs from Before, as fractions, or null. */
+  const changedArea = async (before, after) => {
+    const page = await tab();
+    const out = await page.call("Runtime.evaluate", {
+      expression: `(${compareInPage.toString()})(${JSON.stringify(before)}, ${JSON.stringify(after)})`,
+      awaitPromise: true, returnByValue: true,
+    });
+    return out.result?.value ?? null;
+  };
+  // A browser that is missing or crashes on start says so here, not as a
+  // page that did not open.
+  // One that starts but never answers is bounded by Stop and the deadline,
+  // and is killed without being asked to close.
+  let up;
+  try { up = await waitFor(send("Browser.getVersion"), { until: Math.min(Date.now() + CALL_MS, deadline), stopCheck }); } catch (error) { up = { error }; }
+  if (!up.value) {
+    await close({ ask: false });
+    throw Object.assign(up.error ?? new Error("The browser did not answer."), { stopped: Boolean(up.stopped) });
+  }
+  return { shoot, changedArea, close, isGone: () => gone !== null };
+}
+
+/** Runs inside the headless page: both pictures on a half-size canvas, the box
+ *  around every pixel that moved more than a little. */
+async function compareInPage(a, b) {
+  const load = (src) => new Promise((resolve, reject) => { const img = new Image(); img.onload = () => resolve(img); img.onerror = reject; img.src = src; });
+  const [one, two] = await Promise.all([load(a), load(b)]);
+  const w = 720;
+  const h = Math.max(1, Math.round((one.height / one.width) * w));
+  const pixels = (img) => { const c = document.createElement("canvas"); c.width = w; c.height = h; const g = c.getContext("2d"); g.drawImage(img, 0, 0, w, h); return g.getImageData(0, 0, w, h).data; };
+  const p = pixels(one);
+  const q = pixels(two);
+  let x0 = w, y0 = h, x1 = -1, y1 = -1;
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const i = (y * w + x) * 4;
+      if (Math.abs(p[i] - q[i]) + Math.abs(p[i + 1] - q[i + 1]) + Math.abs(p[i + 2] - q[i + 2]) > 30) {
+        if (x < x0) x0 = x; if (x > x1) x1 = x; if (y < y0) y0 = y; if (y > y1) y1 = y;
+      }
+    }
+  }
+  if (x1 < 0) return null;
+  const pad = 4;
+  x0 = Math.max(0, x0 - pad); y0 = Math.max(0, y0 - pad); x1 = Math.min(w - 1, x1 + pad); y1 = Math.min(h - 1, y1 + pad);
+  return { x: x0 / w, y: y0 / h, w: (x1 - x0 + 1) / w, h: (y1 - y0 + 1) / h };
+}
+
+// ---------- the folder's app ----------
+
+const freePort = () => new Promise((resolve) => {
+  const server = createServer();
+  server.unref();
+  server.on("error", () => resolve(undefined));
+  server.listen(0, "127.0.0.1", () => { const { port } = server.address(); server.close(() => resolve(port)); });
+});
+
+const ANSI = /\u001b\[[0-9;?]*[A-Za-z]/g;
+const ADDRESS = /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1?\]):\d{2,5}/;
+
+/** The folder's own `dev` script, else `start`, or what is missing. */
+async function appScript(dir) {
+  let pkg;
+  try { pkg = JSON.parse(await readFile(join(dir, "package.json"), "utf8")); } catch { return { missing: "script" }; }
+  const script = ["dev", "start"].find((s) => typeof pkg?.scripts?.[s] === "string" && pkg.scripts[s].trim());
+  if (!script) return { missing: "script" };
+  if (Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).length) {
+    try { await access(join(dir, "node_modules")); } catch { return { missing: "dependencies" }; }
+  }
+  return { script };
+}
+
+/** Start the folder's app on a free port and wait until it answers. */
+export async function startApp(dir, { env, platform = process.platform, deadline, stopCheck, killGraceMs = 3_000, fetchImpl = fetch }) {
+  const found = await appScript(dir);
+  if (!found.script) return { ok: false, missing: found.missing };
+  const port = await freePort();
+  const cmd = runnableCommand("npm", ["run", found.script], { platform, env });
+  const child = spawn(cmd.file, cmd.args, {
+    cwd: dir, shell: cmd.shell, windowsHide: true, detached: platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...devServerEnv(env, platform), ...(port ? { PORT: String(port) } : {}), BROWSER: "none", NO_COLOR: "1", FORCE_COLOR: "0" },
+  });
+  let log = "";
+  let exited = false;
+  const take = (chunk) => { log = (log + String(chunk)).slice(-8_000); };
+  child.stdout.on("data", take);
+  child.stderr.on("data", take);
+  child.on("error", (e) => { take(`${e.message}\n`); exited = true; });
+  child.on("exit", () => { exited = true; });
+  // The app's server can outlive npm, so the whole group is stopped, and
+  // killed after the grace, whether or not npm itself has exited.
+  let stopping;
+  const stop = () => (stopping ??= (async () => {
+    if (!child.pid) return;
+    const signal = (_pid, sig) => (platform === "win32" ? child.kill(sig) : process.kill(-child.pid, sig));
+    if (platform === "win32") {
+      if (!exited) await killTree(child.pid, { platform, signal }).catch(() => {});
+      if (!exited) await new Promise((resolve) => { const t = setTimeout(resolve, killGraceMs); child.once("exit", () => { clearTimeout(t); resolve(); }); });
+      await killTree(child.pid, { force: true, platform, signal }).catch(() => {});
+      return;
+    }
+    const groupAlive = () => { try { process.kill(-child.pid, 0); return true; } catch { return false; } };
+    if (groupAlive()) await killTree(child.pid, { platform, signal }).catch(() => {});
+    const until = Date.now() + killGraceMs;
+    while (groupAlive() && Date.now() < until) await sleep(50);
+    if (groupAlive()) await killTree(child.pid, { force: true, platform, signal }).catch(() => {});
+  })());
+  const until = Math.min(deadline, Date.now() + APP_START_MS);
+  while (Date.now() < until && !exited) {
+    if (await stopCheck?.()) { await stop(); return { ok: false, stopped: true, log }; }
+    const said = ADDRESS.exec(log.replace(ANSI, ""));
+    const url = (said?.[0] ?? (port ? `http://localhost:${port}` : "")).replace("0.0.0.0", "127.0.0.1").replace(/\[::\]/, "[::1]");
+    if (url) {
+      try {
+        await fetchImpl(url, { signal: AbortSignal.timeout(2_000), redirect: "manual" });
+        return { ok: true, url, stop, log: () => log };
+      } catch { /* not answering yet */ }
+    }
+    await sleep(300);
+  }
+  await stop();
+  return { ok: false, timedOut: Date.now() >= deadline, log };
+}
+
+// ---------- what the runner calls ----------
+
+const pageUrl = (base, path) => new URL(path, `${base.replace(/\/$/, "")}/`).toString();
+
+/** Start the app in `dir`, take one picture of `path`, stop the app. */
+async function pictureOf(dir, page, browser, options) {
+  const app = await startApp(dir, options);
+  if (!app.ok) return { started: false, ...app };
+  try {
+    const shot = await browser.shoot(pageUrl(app.url, page.path), { stopCheck: options.stopCheck, deadline: options.deadline });
+    return { started: true, url: app.url, ...shot, log: app.log() };
+  } catch (error) {
+    if (browser.isGone?.()) return { started: true, url: app.url, ok: false, browserGone: true };
+    return { started: true, url: app.url, ok: false, reason: error.message, log: app.log() };
+  } finally {
+    await app.stop();
+  }
+}
+
+/** The page check and After, from the copy. Null when no screen changed.
+ *
+ *  `files` are the paths the run changed. `folder` is where the app is tried
+ *  when the copy's does not start: if it does not start there either, the
+ *  check is skipped (not the run's doing), never failed. */
+export async function checkPage({ cwd, folder, files, env, baseEnv = process.env, platform = process.platform, deadline, stopCheck, killGraceMs, browser: given, fetchImpl }) {
+  // A page the run deleted has no address left to open.
+  const screens = files.filter((file) => isScreenFile(file) && existsSync(join(cwd, file)));
+  if (screens.length === 0) return null;
+  const page = await pageOf(cwd, screens);
+  const check = (status, reason) => ({ kind: "page", status, failed: status === "failed" ? 1 : 0, page: page.name, ...(reason ? { reason } : {}) });
+  const browser = given === undefined ? findBrowser({ env: baseEnv, platform }) : given;
+  if (!browser) return { page, check: check("skipped", "No browser was found on this computer."), note: NO_BROWSER };
+  if (await stopCheck?.()) return { page, browser, stopped: true, check: check("skipped", "Stopped before this check finished.") };
+  if (Date.now() >= deadline) return { page, browser, check: check("failed", "Ran out of time before this check finished.") };
+  const options = { env, platform, deadline, stopCheck, killGraceMs, ...(fetchImpl ? { fetchImpl } : {}) };
+  let opened;
+  let stoppedStarting = false;
+  try { opened = await openBrowser(browser, { platform, stopCheck, deadline }); } catch (error) { opened = null; stoppedStarting = error.stopped === true; }
+  if (stoppedStarting) return { page, browser, stopped: true, check: check("skipped", "Stopped before this check finished.") };
+  if (!opened) return { page, check: check("skipped", "The browser on this computer did not start."), note: NO_BROWSER };
+  try {
+    const after = await pictureOf(cwd, page, opened, options);
+    if (after.stopped) return { page, browser, stopped: true, check: check("skipped", "Stopped before this check finished.") };
+    if (after.browserGone) return { page, browser, check: check("skipped", "The browser on this computer closed."), note: BROWSER_CLOSED };
+    if (after.missing === "script") return { page, browser, check: check("skipped", "This folder has no app to start."), note: NO_APP_SCRIPT };
+    if (after.missing === "dependencies") return { page, browser, check: check("skipped", "The folder's dependencies are not installed."), note: NO_APP };
+    if (after.timedOut) return { page, browser, check: check("failed", "Ran out of time before this check finished.") };
+    if (!after.started) {
+      const there = folder ? await startApp(folder, options) : { ok: false };
+      if (there.ok) await there.stop();
+      if (!there.ok) return { page, browser, check: check("skipped", "The app did not start."), note: NO_APP };
+      return {
+        page, browser, check: check("failed", "The app did not start after this change."),
+        failure: `The app did not start with npm (it starts in the original folder).\n${after.log ?? ""}`,
+      };
+    }
+    if (!after.ok) {
+      return {
+        page, browser, ...(after.image ? { after: after.image } : {}),
+        check: check("failed", `The ${page.name} did not open.`),
+        failure: `Opening ${pageUrl(after.url, page.path)} in a browser failed: ${after.reason ?? "unknown"}.\n${after.log ?? ""}`,
+      };
+    }
+    return { page, browser, after: after.image, check: check("passed") };
+  } finally {
+    await opened.close();
+  }
+}
+
+/** Before, from the folder, and the changed part of After. Pictures that do
+ *  not differ mean the wrong page was opened: no pictures at all. */
+export async function beforePicture({ folder, page, after, browser, env, platform = process.platform, deadline, stopCheck, killGraceMs, fetchImpl }) {
+  if (!after || !browser) return {};
+  if (!folder || await stopCheck?.() || Date.now() >= deadline) return { after };
+  let opened;
+  try { opened = await openBrowser(browser, { platform, stopCheck, deadline }); } catch { return { after }; }
+  try {
+    const before = await pictureOf(folder, page, opened, { env, platform, deadline, stopCheck, killGraceMs, ...(fetchImpl ? { fetchImpl } : {}) });
+    if (!before.started || !before.ok || !before.image) return { after };
+    let changed = null;
+    try { changed = await opened.changedArea(before.image, after); } catch { return { before: before.image, after }; }
+    if (!changed) return {};
+    return { before: before.image, after, changed };
+  } finally {
+    await opened.close();
+  }
+}
+

package/lib/pageRoutes.mjs

@@ -0,0 +1,70 @@
+// WHICH FILES A CODING RUN CHANGED ARE A SCREEN, AND WHICH PAGE TO OPEN
+// (#2194). Pure path rules plus the session's own page record; only
+// pagePictures.mjs uses this, and goes with it.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** The file a session writes in its copy's root to name the page it changed. */
+export const PAGE_RECORD_FILE = ".viewable-page.json";
+
+const SCREEN_EXT = /\.(?:tsx|jsx|vue|svelte|astro|html|css|scss|sass|less)$/i;
+const NOT_SCREEN = /(?:\.(?:test|spec|stories)\.[a-z]+$|(?:^|\/)(?:__tests__|tests?|e2e)\/)/i;
+
+/** A changed file a person could see on a page: markup, styles or a routed
+ *  page file (page.ts, an .mdx page), not tests. */
+export const isScreenFile = (file) => (SCREEN_EXT.test(file) || routeOf(file) !== null) && !NOT_SCREEN.test(file);
+
+const PAGE_EXT = "(?:tsx|jsx|ts|js|mdx|vue|svelte|astro)";
+const ROUTE_RULES = [
+  // Next app router: app/settings/page.tsx; (groups) are not in the address.
+  [new RegExp(`^(?:src/)?app/(?:(.*)/)?page\\.${PAGE_EXT}$`), (m) => m[1] ?? ""],
+  // SvelteKit: src/routes/settings/+page.svelte
+  [/^src\/routes\/(?:(.*)\/)?\+page\.svelte$/, (m) => m[1] ?? ""],
+  // Next pages router, Nuxt, Astro: pages/settings.tsx, src/pages/index.astro
+  [new RegExp(`^(?:src/)?pages/(.*)\\.${PAGE_EXT}$`), (m) => (/(?:^|\/)(?:_app|_document|_error|api)(?:\/|$)/.test(m[1]) ? null : m[1].replace(/(?:^|\/)index$/, ""))],
+  // Remix: app/routes/account.settings.tsx, app/routes/_index.tsx
+  [new RegExp(`^app/routes/(.*)\\.${PAGE_EXT}$`), (m) => m[1].replace(/^_index$/, "").replace(/\./g, "/")],
+];
+
+/** The address of a page file in a folder that routes by file, or null. */
+export function routeOf(file) {
+  for (const [rule, take] of ROUTE_RULES) {
+    const m = rule.exec(file);
+    if (!m) continue;
+    const route = take(m);
+    if (route === null) return null;
+    const parts = route.split("/").filter((p) => p && !/^\(.*\)$/.test(p));
+    // A [slug] page has no one address to open.
+    if (parts.some((p) => /[[\]$]/.test(p))) return null;
+    return `/${parts.join("/")}`;
+  }
+  return null;
+}
+
+/** "/" is the home page, "/sign-in" the sign in page. */
+export function pageNameOf(path) {
+  const last = path.split(/[?#]/)[0].split("/").filter(Boolean).pop();
+  if (!last) return "home page";
+  return `${decodeURIComponent(last).replace(/[-_]+/g, " ").trim().toLowerCase()} page`;
+}
+
+/** Which page the run touched: the session's own record, else the file route
+ *  of a changed page file, else the home page. */
+export async function pageOf(cwd, files) {
+  try {
+    const record = JSON.parse(await readFile(join(cwd, PAGE_RECORD_FILE), "utf8").catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+      return readFile(join(cwd, ".glytch-page.json"), "utf8");
+    }));
+    const path = typeof record?.path === "string" ? record.path.trim() : "";
+    if (/^\/(?!\/)[^\s]{0,300}$/.test(path)) {
+      const name = typeof record.name === "string" ? record.name.replace(/\s+/g, " ").trim().slice(0, 60) : "";
+      return { path, name: name || pageNameOf(path), recorded: true };
+    }
+  } catch { /* no record: guess from the files */ }
+  for (const file of files) {
+    const route = routeOf(file);
+    if (route !== null) return { path: route, name: pageNameOf(route), recorded: false };
+  }
+  return { path: "/", name: pageNameOf("/"), recorded: false };
+}

package/lib/paths.mjs

@@ -0,0 +1,10 @@
+// Local runner scratch and image staging. Board coordination uses hosted rows.
+// Historical request files and the repo-map cache still live under SPAWN_DIR.
+
+export const BOARD_DIR = ".viewable";
+export const INBOX_DIR = `${BOARD_DIR}/inbox`;
+// Kept on purpose: the sweep reads receipts written by old runners.
+export const SPAWN_DIR = ".glytch/inbox/spawn";
+
+/** Path segments, for join(root, ...segmentsOf(DIR)). */
+export const segmentsOf = (dir) => dir.split("/");