@orbytes/astrolab 0.3.0

package/src/pin/index.mjs

@@ -0,0 +1,666 @@
+// orbytes-pin — click a rendered element on `astro dev`, leave a comment, get a markdown ticket
+// and a PNG on local disk for an agent to pick up.
+//
+// SHIPPED AS HALF OF THE LAB since 2026-09-22 — decided that day: the lab and the pin board are ONE
+// app, bundled and working as one, not two packages a site installs separately. A consumer configures
+// ONE integration and gets both:
+//
+//   import orbytesLab from "@orbytes/astrolab";
+//   integrations: [ includeLab ? orbytesLab({ css: [...] }) : null ]   // /lab and /pin
+//   integrations: [ includeLab ? orbytesLab({ pin: false }) : null ]   // /lab alone
+//
+// `orbytesLab()` returns an array Astro flattens, and this integration is one of its entries — see
+// ../../index.mjs, which also hands it the lab's RESOLVED subpath so the board's "Lab" link points
+// at wherever the lab actually is. Calling this module directly still works and is what the tests
+// do; nothing about it assumes the lab is present.
+//
+// No cloud, no API key, no MCP, no second process — ../../docs/PIN-CONTRACT.md. It replaces the
+// hosted-widget → issue-tracker feedback chain for a solo build pass, and only for that.
+//
+// Three jobs:
+//   1. stamp `data-orbytes-src="<repo-relative path>"` on the first top-level element of every
+//      `.astro` file under the configured directories, so the picker can name the file an element
+//      came from (./source-stamp.mjs — Astro 7 emits no source attribute of its own).
+//   2. register the dev toolbar app the picking happens in (./toolbar.js — the client half: the
+//      element picker, the comment panel and the ticket list, loaded by Astro's dev toolbar).
+//   3. on the toolbar's `orbytes-pin:create`, write the ticket and REPLY, then take the
+//      screenshot and send a second event when it lands (./tickets.mjs, ./shot.mjs).
+//   4. serve the KANBAN at `<route>` — every ticket in `backlog/tasks`, read fresh on each
+//      request — its screenshots at `<route>/assets/*`, and the one write endpoint at
+//      `<route>/api/ticket`, all from the dev server you are already on (./board.mjs, which
+//      `orbytes-pin-gallery` renders the standalone file with too).
+//
+// `route` DEFAULTS TO `/pin` AND SHADOWS ANY HOST PAGE AT THAT PATH. This middleware is installed
+// before Astro's own request handler, so a site with its own `src/pages/pin.astro` would serve the
+// board instead of its page, in dev only, with nothing on screen to say why. The default stays —
+// `/pin` is the chosen address and the one every doc names — and the collision is a
+// one-liner to avoid: `pin: { route: "/__pin" }`. Said here, in ../../docs/PIN.md and in
+// ../../README.md, because a silent shadow is only findable if somebody wrote it down.
+//
+// The board is MIDDLEWARE, not an injected route, and the choice is deliberate. The lab injects its
+// pages because they are prerendered; this one is generated per request from files outside the
+// site, so it belongs with the lab's other half — the mark APIs it serves from `astro:server:setup`.
+// That hook does not exist in a build, so `/pin` cannot leak into `dist/` even by accident, and
+// nothing has to be marked `prerender: false` in a project with `output: "static"` and no adapter.
+// ── backlog.md is retired (2026-09-22) ──────────────────────────────────────────────────────────
+// Until today `<route>` was read-only and pointed at backlog.md's own web UI — a second server on
+// a third port — for the one thing it could not do: change a ticket's status. That made three
+// places to remember. backlog.md re-serialises frontmatter on any write and silently drops every
+// key it does not know, which is why the pin fields live in a fenced block in the BODY, and a
+// SECOND writer of that frontmatter would have rebuilt the bug.
+//
+// With backlog.md out of the loop there is no second writer, so `<route>/api/ticket` can write
+// those files correctly by construction: `updateTicket` (./board.mjs) rewrites only the
+// frontmatter lines it is changing and returns the body — comment, image and fenced pin block —
+// byte for byte, asserting that on every write rather than documenting it. That endpoint is the
+// ONLY write path, it is POST-only, same-origin, and it lives in `astro:server:setup`, which does
+// not exist in a build. Do not run `backlog browser`; do not run `backlog task edit` on a pin
+// ticket.
+//
+// DEV ONLY, asserted FOUR times independently, because the whole write path's safety rests on it
+// (contract non-negotiable 1). All four are kept, and none of them is the spare:
+//   · `astro:config:setup` returns early unless `command === "dev"` — nothing is registered;
+//   · the Vite plugins carry `apply: "serve"`, so they cannot load in a build even if they were;
+//   · `astro:server:setup` never runs in a build at all, which is where the writes live;
+//   · that hook still returns early when `repoRoot` is null, i.e. when config:setup stood down —
+//     the one that covers a host that calls the hooks in an order this file did not choose.
+//
+// This matters more now than it did in its own package. The lab is deliberately included in
+// STAGING builds (`PUBLIC_DEPLOY_ENV=staging`), and `orbytesLab()` returns this integration
+// alongside it — so from 2026-09-22 this file is registered in a build for the first time. The
+// first assertion is what makes that a no-op: `command` is `build` there, not `dev`.
+//
+// Ordering is the one thing not to tune. The reply goes out on the same synchronous tick as the
+// ticket write; the browser launch happens after it. A ticket with no screenshot yet is valid, a
+// ticket somebody waited two seconds for is not.
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { createReadStream, realpathSync, statSync } from "node:fs";
+import { extname, join, resolve, sep } from "node:path";
+import { findRepoRoot, projectName, writeTicket } from "./tickets.mjs";
+import { sourceStampPlugin } from "./source-stamp.mjs";
+import { close as closeBrowser, shoot } from "./shot.mjs";
+import { collectTickets, renderBoard, renderCard, updateTicket } from "./board.mjs";
+
+const file = (relative) => fileURLToPath(new URL(relative, import.meta.url));
+
+/** One plain sentence, never a stack — this string is shown to the user in the toolbar. */
+const oneLine = (e) => String(e?.message ?? e).split("\n")[0].trim();
+
+/**
+ * What `<route>/assets/*` will serve. An allowlist, not a lookup with a fallback: an extension
+ * that is not on this list is a 404, so no file type can be handed out because nobody thought
+ * about it. Every PNG the picker writes is the first entry; the rest are for a shot dropped in
+ * by hand.
+ */
+const ASSET_MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".avif": "image/avif",
+};
+
+/**
+ * `child` is inside `parent`, or is `parent`. Both must already be absolute and resolved.
+ * The `+ sep` is the whole point: a plain `startsWith` would let `/x/backlog-secrets` pass as
+ * inside `/x/backlog`.
+ */
+const contains = (parent, child) => child === parent || child.startsWith(parent + sep);
+
+/**
+ * The one file `<route>/assets/<rel>` names, or null when it names anything else.
+ *
+ * The screenshots sit in `backlog/assets/`, outside `site/public/`, so the dev server has no route
+ * to them and this opens exactly one — a single directory, image types only, read-only. Four
+ * refusals, in order, because each catches something the one before it cannot:
+ *
+ *   1. a null byte, which truncates a path inside some syscalls;
+ *   2. containment AFTER `resolve`, which is what stops `../` and an absolute `/etc/passwd`
+ *      (`new URL()` normalises literal dot segments in a pathname, so the form that actually
+ *      arrives here is the percent-encoded one — `%2e%2e%2f` — and it is decoded above this
+ *      line precisely so this check is the thing that sees it);
+ *   3. containment AGAIN after `realpathSync`, because step 2 is defeated by a symlink inside
+ *      the directory pointing out of it, and the PNGs here are hardlinks into ~/.orbytes, so
+ *      links in this folder are normal rather than suspicious;
+ *   4. a regular file with a known image extension — a directory, a socket or a `.md` is a 404.
+ */
+function resolveAsset(assetsRoot, rel) {
+  if (!rel || rel.includes("\0")) return null;
+  const abs = resolve(assetsRoot, rel);
+  if (!contains(assetsRoot, abs)) return null;
+  let real;
+  let realRoot;
+  try {
+    real = realpathSync(abs);
+    realRoot = realpathSync(assetsRoot);
+  } catch {
+    return null; // missing, or a broken link
+  }
+  if (!contains(realRoot, real)) return null;
+  const type = ASSET_MIME[extname(real).toLowerCase()];
+  if (!type) return null;
+  let stat;
+  try {
+    stat = statSync(real);
+  } catch {
+    return null;
+  }
+  if (!stat.isFile()) return null;
+  return { file: real, type, size: stat.size };
+}
+
+/**
+ * The resolved options the TOOLBAR APP needs, handed to it as a virtual module.
+ *
+ * A dev-toolbar app entrypoint is instantiated by Astro with `(canvas, app, server)` and nothing
+ * else — there is no channel for integration options, which is why `./toolbar.js` carried a
+ * hardcoded `/pin` and a site setting `pin: { route: "/__pin" }` got a panel that fetched a route
+ * it does not serve. The lab solves the same problem the same way, with
+ * `virtual:orbytes-lab/config.mjs` (../../index.mjs), so this mirrors it rather than inventing a
+ * second mechanism.
+ *
+ * Client-side and dev-only: the plugin carries `apply: "serve"`, and in a build this whole
+ * integration stands down before `updateConfig` is ever reached.
+ *
+ * The resolved id carries no leading NUL, the same choice the lab and Astrobook make — Astro's
+ * pipeline handles a plain id and a NUL-prefixed one has to be special-cased.
+ */
+const PIN_VIRTUAL = "virtual:orbytes-pin/config.mjs";
+const PIN_VIRTUAL_RESOLVED = "__virtual_orbytes_pin_config__.mjs";
+
+/**
+ * The board's path, with any trailing slashes off. ONE definition: the middleware matches on it
+ * and the toolbar app fetches and opens it, and the two disagreeing is the defect this replaces.
+ */
+const boardRoute = (raw) => String(raw ?? "").replace(/\/+$/, "") || "/pin";
+
+const pinConfigPlugin = (exposed) => ({
+  name: "orbytes-pin/virtual",
+  apply: "serve",
+  resolveId: (id) => (id === PIN_VIRTUAL ? PIN_VIRTUAL_RESOLVED : undefined),
+  load: (id) =>
+    id === PIN_VIRTUAL_RESOLVED ? `export default ${JSON.stringify(exposed)};` : undefined,
+});
+
+const DEFAULTS = {
+  /** Site-relative directories whose `.astro` files get the source stamp. */
+  stamp: ["src/lab/sections", "src/components"],
+  /**
+   * Repo-relative `.astro` paths exempt from the stamp's hard failure. A file whose template has
+   * no element to stamp throws by design; this is the only way past it, and it is a deliberate,
+   * named decision per file rather than a warning that lets every such file through silently.
+   */
+  stampSkip: [],
+  /** Repo-relative board directory. Tickets land in `<backlogDir>/tasks`, PNGs in `/assets`. */
+  backlogDir: "backlog",
+  /** Canonical screenshot home. The repo copy is a hardlink to a file in here. */
+  archiveDir: join(homedir(), ".orbytes", "feedback-archive"),
+  /**
+   * The archive folder this project's screenshots live in: `<archiveDir>/<project>/`.
+   *
+   * `null` derives it from the checkout's own directory name, which is what it always did and is
+   * right almost always — and wrong in the one case nobody would notice. TWO CHECKOUTS OF
+   * DIFFERENT REPOS UNDER THE SAME FOLDER NAME SHARE AN ARCHIVE, silently: `pin-007.png` from one
+   * overwrites `pin-007.png` from the other, both boards go on rendering (the repo copy is a
+   * hardlink, so the survivor keeps a name in each), and the only evidence is a screenshot of
+   * somebody else's site. Two clients called `site`, a `~/work/acme` beside a `~/archive/acme`,
+   * or a worktree named after its branch all reach it. Set it explicitly to be sure.
+   *
+   * Added on the move into astrolab, 2026-09-22 — a package that travels between repos is exactly
+   * where a path derived from the checkout stops being safe.
+   */
+  project: null,
+  /** Set false to write tickets and take no screenshots at all. */
+  shots: true,
+  /**
+   * Where the board is served, dev only. `<route>/assets/*` serves its screenshots and
+   * `<route>/api/ticket` is the one write endpoint.
+   *
+   * It is MIDDLEWARE and it shadows a host page at the same path (see the note at the top of this
+   * file). A site with its own `/pin` page sets something else here.
+   */
+  route: "/pin",
+  /**
+   * The links in the board's top-right corner, `[{ href, label }]`. `null` means the pair the
+   * board has always drawn — the site root and `/lab` — which was hardcoded until 2026-09-22 and
+   * is a guess anywhere the lab is not at `/lab`. `orbytesLab()` passes the lab's RESOLVED subpath
+   * rather than the guess; `[]` draws no links at all.
+   */
+  links: null,
+  appId: "orbytes-pin",
+  appName: "Pin",
+  icon: "bug",
+};
+
+/** The dev server's own origin, read from Vite. Never hardcode 4321 — Astro picks a free port. */
+function devOrigin(server) {
+  const resolved = server.resolvedUrls?.local?.[0];
+  if (resolved) return resolved.replace(/\/+$/, "");
+  const address = server.httpServer?.address?.();
+  if (address && typeof address === "object") return `http://localhost:${address.port}`;
+  const port = server.config?.server?.port;
+  if (port) return `http://localhost:${port}`;
+  throw new Error("the dev server has not reported a port yet, so there is nowhere to screenshot from");
+}
+
+/**
+ * @param {Partial<typeof DEFAULTS>} [options]
+ * @returns {import("astro").AstroIntegration}
+ */
+export default function orbytesPin(options = {}) {
+  const config = { ...DEFAULTS, ...options };
+  let repoRoot = null;
+  let project = null;
+
+  return {
+    name: "orbytes-pin",
+    hooks: {
+      "astro:config:setup": ({ config: astroConfig, command, updateConfig, addDevToolbarApp, logger }) => {
+        // Assertion one. In `build`, `preview` or `sync` this integration registers nothing at
+        // all — no plugin, no toolbar app, no stamp.
+        if (command !== "dev") {
+          logger.debug(`command is ${command}, not dev — orbytes-pin stands down`);
+          return;
+        }
+        const siteRoot = fileURLToPath(astroConfig.root);
+
+        // Assertion one and a half. `findRepoRoot` throws rather than guess, which is right for a
+        // library — every ticket path hangs off it and a guessed root writes files somewhere
+        // nobody asked for. But an integration that lets that reach Astro takes the whole dev
+        // server down with it, and the board is ON BY DEFAULT: measured 2026-09-22, a freshly
+        // scaffolded Astro project (which has no git yet) could not run `astro dev` at all after
+        // installing this package. The lab half had already logged that it found its stories, so
+        // the failure looked like the package rather than the one check it was.
+        //
+        // So: stand down the way the non-dev path does, and say both escapes. The lab is
+        // unaffected, and `astro build` never reaches here at all.
+        try {
+          repoRoot = findRepoRoot(siteRoot);
+        } catch {
+          logger.warn(
+            `no git repository found above ${siteRoot} — the pin board needs one, because every ` +
+              `ticket path is stored relative to it. The board is disabled for this run; the lab ` +
+              `is unaffected. Run \`git init\` to enable it, or pass \`pin: false\` to silence this.`,
+          );
+          return;
+        }
+        project = String(config.project ?? projectName(repoRoot));
+
+        addDevToolbarApp({
+          id: config.appId,
+          name: config.appName,
+          icon: config.icon,
+          entrypoint: file("./toolbar.js"),
+        });
+
+        updateConfig({
+          vite: {
+            plugins: [
+              sourceStampPlugin({
+                repoRoot,
+                siteRoot,
+                dirs: config.stamp,
+                skip: config.stampSkip,
+              }),
+              // The resolved options ./toolbar.js reads — today just the board's route, which it
+              // fetches for the ticket list and opens with the "Board ↗" button. Registered here
+              // rather than hardcoded there, because a toolbar app entrypoint is handed no
+              // options (› pinConfigPlugin, above).
+              pinConfigPlugin({ route: boardRoute(config.route) }),
+              // The browser outlives every request, so something has to end it. Vite fires
+              // `closeBundle` when the dev environment's plugin container closes; the httpServer
+              // handler in astro:server:setup covers the path where it does not, and Playwright
+              // kills its own child on process exit. Three, because a stray headless chromium is
+              // invisible until you notice the fans.
+              { name: "orbytes-pin/lifecycle", apply: "serve", closeBundle: () => closeBrowser() },
+            ],
+            // The same exemption the lab integration declares for itself. It is SSR-only by
+            // definition and cannot reach the CLIENT graph, which is where ./src/toolbar.js is
+            // loaded — checked 2026-09-21, because the toolbar's bare `astro/...` imports look
+            // like they might need one. They do not: resolving its three specifiers from this
+            // package's own directory, `astro/toolbar`,
+            // `astro/client/dev-toolbar/apps/utils/highlight.js` and `.../window.js` all resolve
+            // through astro's declared "./toolbar" and "./client/*" exports. NO alias for
+            // `astro` is declared anywhere here, and none may be added.
+            //
+            // The NAME is the lab's since the merge — one package now ships both halves, and this
+            // file is `@orbytes/astrolab/src/pin/index.mjs`. `orbytes-pin` no longer resolves to
+            // anything, so exempting it would exempt nothing. (The lab's own integration declares
+            // the same line; declaring it twice is harmless — Vite dedupes the array — and it is
+            // kept here so calling this module on its own still works.)
+            ssr: { noExternal: ["@orbytes/astrolab"] },
+            // The CLIENT-side counterpart, and the one that actually keeps the dev toolbar
+            // alive. Measured on astro 7.3.1 / vite 8.2.2, 2026-09-21.
+            //
+            // `node_modules/orbytes-pin` is a symlink to `packages/orbytes-pin`, and Vite
+            // resolves symlinks (`resolve.preserveSymlinks` is false by default). So the
+            // importer of ./src/toolbar.js is its REAL path, which is not inside
+            // node_modules — and Vite's `finalizeBareSpecifier` only skips the dep optimizer
+            // when `importer && isInNodeModules(importer)` (vite/dist/node/chunks/node.js,
+            // the `skipOptimization` expression). A package that genuinely sat in
+            // node_modules would be skipped; this one is workspace-linked, so it is not, and
+            // its three bare `astro/...` specifiers are treated as app source imports.
+            //
+            // They are reachable only through the toolbar app entrypoint, which Astro loads
+            // by dynamic import from the `astro:toolbar:internal` virtual module — after the
+            // scan, after the server is up. Two of them are not in Astro's own include list
+            // (`astro/toolbar` is — vite-plugin-dev-toolbar.js `config()`), so they arrive as
+            // missing imports and force a re-optimize of a set that already contains
+            // `astro/runtime/client/dev-toolbar/entrypoint.js`. The HTML asks for that
+            // entrypoint at a URL with no version query, so once its optimized copy is
+            // replaced the request can no longer be matched and answers 504 Outdated Optimize
+            // Dep — permanently, warm cache included. `customElements.get("astro-dev-toolbar")`
+            // stays undefined and ALL FIVE of Astro's own apps die with ours.
+            //
+            // The lever is `exclude` rather than `include`: `skipOptimization` reads
+            // `exclude?.includes(rawId)` — an exact match on the specifier as written — so
+            // these two names, and nothing else, stop being optimizer candidates. They then
+            // resolve to Astro's own dist files, the same ones the built-in apps use. Naming
+            // the package (`exclude: ["astro"]`) would match via `pkgId` too, but it would
+            // also swallow `astro/toolbar` and the toolbar entrypoint, both of which Astro
+            // deliberately pre-bundles. `include` would be the wrong shape as well: it would
+            // pre-bundle a second copy of Astro's highlight/window helpers to cure a problem
+            // whose cause is that they were bundled at all.
+            optimizeDeps: {
+              exclude: [
+                "astro/client/dev-toolbar/apps/utils/highlight.js",
+                "astro/client/dev-toolbar/apps/utils/window.js",
+              ],
+            },
+            // Tickets land OUTSIDE site/, so Vite's watcher should never see them — but a write
+            // that reloads the page mid-comment would be the one defect a user notices every
+            // single time, so it is ruled out here as well (contract non-negotiable 4).
+            server: {
+              watch: {
+                ignored: [
+                  `**/${config.backlogDir}/**`,
+                  join(repoRoot, config.backlogDir, "**"),
+                  join(config.archiveDir, "**"),
+                ],
+              },
+            },
+          },
+        });
+
+        logger.info(`pin app on the dev toolbar · tickets → ${config.backlogDir}/tasks · stamping ${config.stamp.join(", ")}`);
+      },
+
+      "astro:server:setup": ({ server, toolbar, logger }) => {
+        // Assertion three: this hook does not exist in a build. The write path lives only here,
+        // and so does the wall — neither can exist in `dist/`.
+        if (!repoRoot) return; // config:setup stood down; nothing to wire
+
+        const route = boardRoute(config.route);
+        const assetPrefix = `${route}/assets/`;
+        const apiPath = `${route}/api/ticket`;
+        const assetsRoot = join(repoRoot, config.backlogDir, "assets");
+        const assetHref = (t) =>
+          t.shotName ? assetPrefix + t.shotName.split("/").map(encodeURIComponent).join("/") : null;
+
+        // The wall, and its screenshots. Registered here rather than as an injected route (see the
+        // note at the top of this file), which also puts it ahead of Astro's own request handler:
+        // Astro installs that in a Vite post hook, after every integration's middleware is in
+        // place, so `/pin` reaches this and never reaches Astro's 404.
+        server.middlewares.use((req, res, next) => {
+          let url;
+          try {
+            url = new URL(req.url ?? "/", "http://localhost");
+          } catch {
+            return next();
+          }
+          const path = url.pathname;
+          const wall = path === route || path === `${route}/`;
+          const api = path === apiPath;
+          if (!wall && !api && !path.startsWith(assetPrefix)) return next();
+
+          const json = (code, body) => {
+            res.statusCode = code;
+            res.setHeader("Content-Type", "application/json; charset=utf-8");
+            res.setHeader("Cache-Control", "no-store");
+            return res.end(JSON.stringify(body));
+          };
+
+          // ── the one write path ───────────────────────────────────────────────────────────
+          // Four refusals before a byte of the request body is even parsed, then `updateTicket`,
+          // which refuses again on everything it cannot verify. None of them warn; all of them
+          // answer with a sentence the board puts on screen.
+          if (api) {
+            if (req.method !== "POST") {
+              res.statusCode = 405;
+              res.setHeader("Allow", "POST");
+              return res.end("POST");
+            }
+            // Same-origin. A page on another origin can POST JSON cross-site without a preflight
+            // only if it lies about its content type, which the next check refuses — but the
+            // browser always sends `Origin` on a cross-site POST, so this is the cheap first no.
+            const origin = req.headers.origin;
+            if (origin) {
+              let sameOrigin = false;
+              try {
+                sameOrigin = new URL(origin).host === req.headers.host;
+              } catch {
+                sameOrigin = false;
+              }
+              if (!sameOrigin) return json(403, { ok: false, error: "cross-origin writes are refused" });
+            }
+            if (!String(req.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) {
+              return json(415, { ok: false, error: "send application/json" });
+            }
+
+            const chunks = [];
+            let size = 0;
+            let overflowed = false;
+            req.on("data", (c) => {
+              size += c.length;
+              if (size > 16384) {
+                // A ticket change is three short strings. Anything larger is not one.
+                overflowed = true;
+                req.destroy();
+                return;
+              }
+              chunks.push(c);
+            });
+            req.on("end", () => {
+              if (overflowed) return json(413, { ok: false, error: "that request body is far too large for a status change" });
+              let change;
+              try {
+                change = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+              } catch {
+                return json(400, { ok: false, error: "the request body was not JSON" });
+              }
+              let result;
+              try {
+                result = updateTicket(repoRoot, change, { backlogDir: config.backlogDir });
+              } catch (e) {
+                // 409: the board asked for something the file does not agree with — a stale
+                // `expect`, a ticket that moved. Every other refusal is a bad request.
+                const msg = oneLine(e);
+                logger.warn(`pin write refused: ${msg}`);
+                return json(/changed on disk|on disk, not|was out of date/.test(msg) ? 409 : 400, { ok: false, error: msg });
+              }
+              // Re-read rather than echo: the card that goes back is the card the FILE now draws.
+              // `includeCancelled`, because the write that just landed may have BEEN a cancel —
+              // without it the ticket would be written correctly and then reported unreadable.
+              const { tickets } = collectTickets(repoRoot, { backlogDir: config.backlogDir, includeCancelled: true });
+              const fresh = tickets.find((t) => t.id === result.id);
+              if (!fresh) return json(500, { ok: false, error: `${result.id} was written but cannot be read back` });
+              if (result.changed.length) {
+                logger.info(`${result.id} → ${result.changed.map((k) => `${k}=${k === "status" ? result.status : result.priority}`).join(" ")}  (${result.file})`);
+              }
+              return json(200, {
+                ok: true,
+                id: fresh.id,
+                status: fresh.status,
+                priority: fresh.priority,
+                file: fresh.file,
+                changed: result.changed,
+                card: renderCard(fresh, { assetHref, live: true }),
+              });
+            });
+            req.on("error", () => json(400, { ok: false, error: "the request stream failed" }));
+            return;
+          }
+
+          if (req.method !== "GET" && req.method !== "HEAD") {
+            res.statusCode = 405;
+            res.setHeader("Allow", "GET, HEAD");
+            return res.end("GET or HEAD");
+          }
+
+          if (wall) {
+            // Read from disk on every request — that is the whole point of the route, and why
+            // `orbytes-pin-gallery` is no longer part of looking at the board.
+            try {
+              // `includeCancelled`: `/pin` is the ONE surface where the archive is visible. Every
+              // agent-facing read drops cancelled tickets by default — a cancelled ticket must not
+              // take up context space for an agent — and an archive nobody can open is a delete.
+              const { tickets, broken } = collectTickets(repoRoot, { backlogDir: config.backlogDir, includeCancelled: true });
+              const html = renderBoard(tickets, broken, {
+                // The presence of an endpoint is what makes the page writable. The standalone
+                // file passes none, so it renders the same board with no drag and no menus —
+                // there is nothing listening behind a `file://` page.
+                apiHref: apiPath,
+                // A shot outside `backlog/assets/` has no URL here, because this route serves that
+                // one directory and nothing else; the card then shows its placeholder, naming the
+                // path it expected. Nothing the picker writes can land outside it.
+                assetHref,
+                // Where "Site" and "Lab" point. `null` keeps the board's own default pair; the
+                // lab passes its resolved subpath so the link is the truth rather than a guess.
+                links: config.links,
+              });
+              res.statusCode = 200;
+              res.setHeader("Content-Type", "text/html; charset=utf-8");
+              res.setHeader("Cache-Control", "no-store");
+              return res.end(req.method === "HEAD" ? undefined : html);
+            } catch (e) {
+              // A broken TICKET never gets here — collectTickets collects those and the page says
+              // so. This is the board directory being unreadable, which is worth saying plainly.
+              logger.warn(`${route} failed: ${oneLine(e)}`);
+              res.statusCode = 500;
+              res.setHeader("Content-Type", "text/plain; charset=utf-8");
+              return res.end(`orbytes-pin: could not read ${config.backlogDir}/tasks — ${oneLine(e)}\n`);
+            }
+          }
+
+          let rel;
+          try {
+            rel = decodeURIComponent(path.slice(assetPrefix.length));
+          } catch {
+            res.statusCode = 400;
+            return res.end("bad path");
+          }
+          const asset = resolveAsset(assetsRoot, rel);
+          if (!asset) {
+            res.statusCode = 404;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            return res.end("not found\n");
+          }
+          res.statusCode = 200;
+          res.setHeader("Content-Type", asset.type);
+          res.setHeader("Content-Length", String(asset.size));
+          // A ticket's PNG is a hardlink that shot.mjs can replace under the same name, so a
+          // cached copy would show the previous shot after a re-pin.
+          res.setHeader("Cache-Control", "no-store");
+          if (req.method === "HEAD") return res.end();
+          return createReadStream(asset.file).pipe(res);
+        });
+
+        toolbar.on("orbytes-pin:create", (payload) => {
+          // ── Synchronous half: the ticket, and the reply. Nothing awaited before send(). ──
+          let ticket;
+          try {
+            ticket = writeTicket(repoRoot, payload, { backlogDir: config.backlogDir });
+          } catch (e) {
+            logger.warn(`pin refused: ${oneLine(e)}`);
+            toolbar.send("orbytes-pin:created", { id: null, file: null, shot: null, error: oneLine(e) });
+            return;
+          }
+          toolbar.send("orbytes-pin:created", {
+            id: ticket.id,
+            file: ticket.file,
+            shot: config.shots ? ticket.shot : null,
+            error: null,
+          });
+          logger.info(`${ticket.id} → ${ticket.file}  (dispatch: ${payload.dispatch})`);
+
+          // ── Asynchronous half: the screenshot. The user is already back at work. ──
+          if (!config.shots) return;
+          const dest = join(config.archiveDir, project, ticket.archiveName);
+          const link = join(repoRoot, config.backlogDir, "assets", ticket.archiveName);
+          shoot({
+            origin: devOrigin(server),
+            url: payload.url,
+            viewport: payload.viewport,
+            scroll: payload.scroll,
+            rect: payload.rect,
+            dest,
+            link,
+            // The fresh page this shot loads is the only honest test of whether the selector
+            // written a moment ago survives a reload — the picking page cannot answer, because
+            // it IS the load the selector was built against. shoot() counts the matches there
+            // and writes the number into the ticket; these two arguments are what let it.
+            selector: payload.selector,
+            ticketFile: ticket.absolute,
+            log: (m) => logger.warn(`${ticket.id}: ${m}`),
+          })
+            .then(({ ms, cold, linked, selectorMatches }) => {
+              logger.info(`${ticket.id} shot in ${ms} ms${cold ? " (cold launch)" : ""} → ${ticket.shot}${linked === "copy" ? " (copied, not hardlinked)" : ""}`);
+              if (selectorMatches !== 1 && selectorMatches !== null) {
+                logger.warn(
+                  selectorMatches === 0
+                    ? `${ticket.id}: its selector matched NOTHING on a fresh load — the ticket is still workable from its source file, screenshot and outer_html, but not by selector`
+                    : `${ticket.id}: its selector matched ${selectorMatches} elements on a fresh load — it does not name one element`,
+                );
+              }
+              toolbar.send("orbytes-pin:shot", { id: ticket.id, shot: ticket.shot, selectorMatches, error: null });
+            })
+            .catch((e) => {
+              // The ticket stands. Only the picture is missing, and the ticket says where it
+              // would have been — no stale PNG is left behind to read as a success. The ticket's
+              // `selector_matches` stays `pending`, which is the truth: nothing was tested.
+              logger.warn(`${ticket.id} screenshot failed: ${oneLine(e)}`);
+              toolbar.send("orbytes-pin:shot", { id: ticket.id, shot: null, selectorMatches: null, error: oneLine(e) });
+            });
+        });
+
+        server.httpServer?.once("close", () => { closeBrowser(); });
+
+        logger.info(`the pin board is at ${route} · every ticket in ${config.backlogDir}/tasks, live on refresh · drag a card to change its status · agents work "Ready for agent" and stop at "Ready for review"; only you set "Resolved"`);
+        // The path comes from `config.archiveDir`, the same value the shot actually writes to —
+        // it was a hardcoded `~/.orbytes/feedback-archive/...` until 2026-09-22, so a site that
+        // set `archiveDir` was told at every startup that its screenshots were somewhere they had
+        // never been. `~` is restored only when the directory really is under $HOME.
+        const home = homedir();
+        const archiveHere = join(config.archiveDir, project);
+        const shown = archiveHere.startsWith(home + sep) ? `~${archiveHere.slice(home.length)}` : archiveHere;
+        logger.info(`listening for orbytes-pin:create (dev only) · screenshots ${config.shots ? `→ ${shown}` : "disabled"}`);
+      },
+    },
+  };
+}
+
+export { findRepoRoot, listTickets, parseTicket, writeTicket } from "./tickets.mjs";
+// The status vocabulary, and the three questions everything asks of a status. An agent picking
+// work off the board asks `isAgentReady` — not "is it open", and certainly not `=== "To Do"`,
+// which no longer exists. `listTickets` already drops `Cancelled` before an agent sees it.
+export {
+  BACKLOG,
+  CANCELLED,
+  CLOSED_STATUSES,
+  DEFAULT_STATUS,
+  IN_PROGRESS,
+  OPEN_STATUSES,
+  READY_FOR_AGENT,
+  READY_FOR_REVIEW,
+  RESOLVED,
+  STATUSES,
+  isAgentReady,
+  isCancelled,
+  isOpen,
+  normaliseStatus,
+} from "./tickets.mjs";
+export { sourceStampPlugin, stampSource } from "./source-stamp.mjs";
+export { close as closeBrowser, shoot } from "./shot.mjs";
+export { BOARD_CONVENTIONS, PRIORITIES, collectTickets, renderBoard, renderCard, updateTicket } from "./board.mjs";