@orbytes/astrolab 0.3.0 → 0.4.0-next.2

package/bin/pin-gallery.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // pin-gallery — render every pin ticket as ONE standalone kanban on disk.
 //
-// The board itself lives at `/pin` on `astro dev` now, generated from `backlog/tasks/` on every
+// The board itself lives at `<subpath>/tasks` on `astro dev` now (`/lab/tasks` by default, or the
+// pin half's `route` when it runs without the lab), generated from `backlog/tasks/` on every
 // request, so looking at it is a refresh and this script is no longer part of that loop. What it
 // is still for is the file: a page that opens with no dev server running — on a plane, on another
 // machine, attached to a message — and a snapshot of the board at a moment in time.
@@ -15,15 +16,16 @@
 //   npx orbytes-pin-gallery                      # → backlog/gallery.html
 //   npx orbytes-pin-gallery --out x.html
 //   npx orbytes-pin-gallery --backlog-dir feedback   # a site that moved its board
+//   npx orbytes-pin-gallery --help                   # the usage; writes nothing
 //
-// IT RUNS IN THE CONSUMER'S REPO, NOT ITS OWN — the same rule as ./lab-cull.mjs, and for the same
-// reason. The root is walked up from `process.cwd()`, never from this file's location, which since
-// the merge into @orbytes/astrolab (2026-09-22) is somewhere under the consumer's node_modules and,
-// when the package is workspace-linked, resolves to THIS repo instead of theirs. A gallery of the
+// IT RUNS IN THE CONSUMER'S REPO, NOT ITS OWN. The root is walked up from `process.cwd()`, never
+// from this file's location, which since the merge into @orbytes/astrolab (2026-09-22) is somewhere
+// under the consumer's node_modules and, when the package is workspace-linked, resolves to THIS
+// repo instead of theirs. A gallery of the
 // lab's own (empty) backlog, written into the lab's own checkout, would exit 0 and look fine.
 //
 // EVERY line of the board — the parser, the cards, the columns, the CSS — comes from
-// `../src/pin/board.mjs`, which the `/pin` board renders with as well. Nothing about a ticket is read
+// `../src/pin/board.mjs`, which the live board renders with as well. Nothing about a ticket is read
 // or drawn here. That is the whole shape of this file, and it is not a preference: this script
 // carried its own copy of the parsing and rendering until 2026-09-21 and that copy produced three
 // separate bugs, each of them a drift from the package's own reader — a frontmatter parser that
@@ -32,19 +34,17 @@
 // A second implementation of this page would be the fourth. Add nothing here; add it to board.mjs.
 //
 // The page opens straight from file:// — image sources stay relative to the output file, so the
-// HTML stays a few KB and the (gitignored) PNGs are never inlined.
+// HTML stays a few KB and the PNGs are never inlined.
 
 import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 
-// `../src/pin/board.mjs` and not the package root: the root pulls in the lab, which imports
-// TypeScript the consumer's Vite compiles and plain Node cannot. The board module is dependency-
-// free by design, and it does not reach shot.mjs — so a static HTML renderer needs no browser and
-// no bundler to run.
+// `../src/pin/board.mjs` and not the package root. The root does load in plain Node now — it
+// imports the compiled core in ../dist/core — but it brings the lab integration and that core
+// with it for a job that needs neither. The board module imports only node:fs and node:path, and it
+// does not reach shot.mjs — so a static HTML renderer needs no browser and no bundler to run.
 import { collectTickets, renderBoard, findRepoRoot } from "../src/pin/board.mjs";
 
-const REPO = findRepoRoot(process.cwd());
-
 /* -------------------------------------------------------------------- main */
 
 const args = process.argv.slice(2);
@@ -53,6 +53,41 @@ const flag = (name) => {
 	return at !== -1 && args[at + 1] ? args[at + 1] : null;
 };
 
+const USAGE = `Usage: orbytes-pin-gallery [--out <file>] [--backlog-dir <dir>]
+
+Writes every pin ticket in <repo>/<backlog-dir>/tasks/, cancelled ones included, as one read-only
+kanban page that opens with no dev server running. <repo> is the current directory or the nearest
+one above it that holds .git, so run it from inside the site's repo.
+
+  --out <file>          where to write the page, relative to the current directory
+                        (default: <repo>/<backlog-dir>/gallery.html)
+  --backlog-dir <dir>   the board directory, relative to <repo> (default: backlog)
+  -h, --help            print this and exit, writing nothing
+
+If any ticket cannot be read it writes nothing and exits 1.
+The live board is <subpath>/tasks on astro dev (/lab/tasks by default).`;
+
+// Every argument is accounted for, or the run is refused. Until 2026-09-24 nothing checked them:
+// a typo — `--output`, `--out=x.html`, `--help` itself — was ignored and the default gallery was
+// written anyway, exit 0, which reads exactly like the command having done what was asked.
+const VALUE_FLAGS = ["--out", "--backlog-dir"];
+for (let i = 0; i < args.length; i++) {
+	const arg = args[i];
+	if (arg === "--help" || arg === "-h") {
+		console.log(USAGE);
+		process.exit(0);
+	}
+	if (VALUE_FLAGS.includes(arg)) {
+		i++; // its value, read below by `flag()`
+		continue;
+	}
+	console.error(`pin-gallery: unknown argument ${JSON.stringify(arg)} — nothing was written.\n`);
+	console.error(USAGE);
+	process.exit(2);
+}
+
+const REPO = findRepoRoot(process.cwd());
+
 // The board directory, and the reason this flag exists at all.
 //
 // A binary cannot read the integration's options — it runs in a different process, from a shell,
@@ -67,7 +102,7 @@ const outPath = flag("--out")
 	? resolve(process.cwd(), flag("--out"))
 	: join(REPO, backlogDir, "gallery.html");
 
-// `includeCancelled`: this file is the offline twin of `/pin`, so it shows what `/pin` shows —
+// `includeCancelled`: this file is the offline twin of the live board, so it shows what that shows —
 // archive rail included. The default is the other way round precisely because every OTHER reader
 // is agent-facing, and a cancelled ticket must not reach an agent's context (ruled 2026-09-22).
 const { tickets, broken, paths } = collectTickets(REPO, { backlogDir, includeCancelled: true });
@@ -84,7 +119,7 @@ const { tickets, broken, paths } = collectTickets(REPO, { backlogDir, includeCan
 // on disk is left exactly as it was — stale, but the message below says so in as many words, which
 // is the difference between a stale file and a lie.
 //
-// The `/pin` board does the opposite and shows the panel instead, because a live page that refuses is a
+// The live board does the opposite and shows the panel instead, because a live page that refuses is a
 // blank screen with nothing to act on. A file that refuses is simply the file you already had.
 if (broken.length) {
 	console.error(`pin-gallery: refusing to write — ${broken.length} ticket(s) could not be read:`);
@@ -92,7 +127,7 @@ if (broken.length) {
 	console.error(`  ${tickets.length} readable ticket(s) were NOT written anywhere.`);
 	console.error(`  An agent reading the board hits the same wall: listTickets() throws on the first`);
 	console.error(`  of these and returns no tickets at all. Fix the ticket(s) and run again.`);
-	console.error(`  The /pin board lists them by name on the dev server, if it is running.`);
+	console.error(`  The live board (<subpath>/tasks, /lab/tasks by default) lists them by name on the dev server, if it is running.`);
 	if (existsSync(outPath)) {
 		const stamp = statSync(outPath).mtime.toLocaleString("en-AU", { dateStyle: "medium", timeStyle: "short" });
 		console.error(`  ${relative(REPO, outPath) || outPath} was left untouched (written ${stamp}) and is now out of date.`);
@@ -108,8 +143,7 @@ const assetHref = (t) => (t.shotAbs ? relative(outDir, t.shotAbs).split(sep).joi
 // The directory may not exist yet: on a fresh install `backlog/` is only created when the first
 // ticket is written, and this command can run before that — or be pointed somewhere else entirely
 // with `--out`. Measured 2026-09-22 on a clean project: without this the command died with a raw
-// `ENOENT ... open 'backlog/gallery.html'` stack trace. Its sibling `orbytes-lab-cull` already
-// handles the same case.
+// `ENOENT ... open 'backlog/gallery.html'` stack trace.
 mkdirSync(outDir, { recursive: true });
 writeFileSync(outPath, renderBoard(tickets, broken, { assetHref }), "utf8");
 
@@ -117,5 +151,5 @@ const missing = tickets.filter((t) => !assetHref(t)).length;
 console.log(`pin-gallery: ${tickets.length} ticket(s), ${missing} without a screenshot`);
 console.log(`  → ${relative(REPO, outPath) || outPath}`);
 console.log(`  read from ${relative(REPO, paths.tasks)}`);
-console.log(`  the live board is /pin on the dev server; this file is the read-only standalone copy`);
+console.log(`  the live board is <subpath>/tasks on the dev server (/lab/tasks by default); this file is the read-only standalone copy`);
 if (!existsSync(paths.assets)) console.log(`  note: ${relative(REPO, paths.assets)} does not exist yet`);

package/defaults.mjs

@@ -1,6 +1,6 @@
-// The lab's defaults and the one option resolver — imported by the integration (./index.mjs) and
-// by the cull binary (./bin/lab-cull.mjs), so a path the lab writes and a path the cull script
-// reads can never drift. Dependency-free: the binary runs in plain Node, outside Vite.
+// The lab's defaults and the one option resolver — imported by the integration (./index.mjs), so
+// every path the lab reads and writes is derived in one place. Dependency-free: it loads in plain
+// Node, from the consumer's astro.config.mjs, outside Vite.
 //
 // Everything `resolveLabOptions` returns is JSON-serialisable on purpose. It is handed to the
 // package's own .astro pages through the `virtual:orbytes-lab/config.mjs` module the integration
@@ -25,17 +25,74 @@ export const DEFAULT_TIERS = ["sections", "components", "explorations"];
  * What a tier NAMED like one of these does, unless the consumer says otherwise on the tier itself:
  *
  * - `responsive` — its stories are section versions: they carry the responsive mark (ticked by
- *   hand in the sidebar, stored in `<directory>/responsive.json`) and they render at page width
- *   in thumbnails and in the viewport configurator.
- * - `cullable` — its stories may be marked for deletion (`<directory>/cull.json`, drained by
- *   `orbytes-lab-cull`). Nothing else in the lab can be marked: version history and shared chrome
- *   are never culled from a browser.
+ *   hand on the component's page in the lab, stored in `<directory>/responsive.json`) and they
+ *   render at page width in thumbnails and in the viewport configurator.
  *
- * At most one tier holds each role; the first one that claims it wins.
+ * At most one tier holds the role; the first one that claims it wins.
  */
 export const TIER_ROLES = {
   sections: { responsive: true },
-  explorations: { cullable: true },
+};
+
+/**
+ * The screen sizes the viewport offers — a per-site setting (decided 2026-09-24), defaulting to the
+ * orbytes scale.
+ *
+ * - `design` — the widths the design is drawn at: the navbar's device switch, in this order. The
+ *   `icon` names one of the chrome's icons (monitor, tablet, phone-landscape, phone).
+ * - `breakpoints` — the lower edge of each CSS band, widest first; the last is 0. The readout
+ *   names the band the frame is in, and the presets offer both sides of every edge (992 and 991).
+ * - `devices` — named sizes that set width AND height.
+ *
+ * @typedef {{ label: string; width: number; icon: string }} DesignWidth
+ * @typedef {{ name: string; min: number }} Breakpoint
+ * @typedef {{ label: string; width: number; height: number }} Device
+ * @typedef {{ design: DesignWidth[]; breakpoints: Breakpoint[]; devices: Device[] }} Viewports
+ */
+/** @type {Viewports} */
+export const DEFAULT_VIEWPORTS = {
+  design: [
+    { label: "Desktop", width: 1440, icon: "monitor" },
+    { label: "Tablet", width: 834, icon: "tablet" },
+    { label: "Phone landscape", width: 550, icon: "phone-landscape" },
+    { label: "Phone", width: 390, icon: "phone" },
+  ],
+  breakpoints: [
+    { name: "desktop", min: 992 },
+    { name: "tablet", min: 768 },
+    { name: "phone landscape", min: 480 },
+    { name: "phone", min: 0 },
+  ],
+  devices: [
+    { label: "iPhone 15", width: 390, height: 844 },
+    { label: "iPhone 15 Pro Max", width: 430, height: 932 },
+    { label: "iPad", width: 834, height: 1194 },
+    { label: "iPad landscape", width: 1194, height: 834 },
+    { label: "MacBook", width: 1440, height: 900 },
+    { label: "Wide", width: 1920, height: 1080 },
+    { label: "Ultra-wide", width: 2560, height: 1080 },
+  ],
+};
+
+/** @param {unknown} value @returns {Viewports} */
+const resolveViewports = (value) => {
+  const given = value && typeof value === "object" ? /** @type {Partial<Viewports>} */ (value) : {};
+  const list = (v, fallback) => (Array.isArray(v) && v.length ? v : fallback);
+  return {
+    design: list(given.design, DEFAULT_VIEWPORTS.design).map((d) => ({
+      label: String(d.label ?? `${d.width}`),
+      width: Number(d.width),
+      icon: String(d.icon ?? "monitor"),
+    })),
+    breakpoints: list(given.breakpoints, DEFAULT_VIEWPORTS.breakpoints)
+      .map((b) => ({ name: String(b.name), min: Number(b.min) || 0 }))
+      .sort((a, b) => b.min - a.min),
+    devices: list(given.devices, DEFAULT_VIEWPORTS.devices).map((d) => ({
+      label: String(d.label),
+      width: Number(d.width),
+      height: Number(d.height),
+    })),
+  };
 };
 
 /** `./src/lab/` and `src/lab` both mean `src/lab`. @param {string} value */
@@ -57,19 +114,17 @@ export const normaliseSubpath = (value) => {
  * @property {string} id             the first path segment under `directory`
  * @property {string} label          shown on the tier card and the folder pages
  * @property {boolean} responsive    section versions: responsive marks, page-width thumbnails
- * @property {boolean} cullable      may be marked for deletion
  */
 
 /** @param {string | Partial<LabTier>} tier @returns {LabTier} */
 const resolveTier = (tier) => {
   const raw = typeof tier === "string" ? { id: tier } : { ...tier };
   const id = String(raw.id ?? "");
-  const role = /** @type {Record<string, {responsive?: boolean, cullable?: boolean}>} */ (TIER_ROLES)[id] ?? {};
+  const role = /** @type {Record<string, {responsive?: boolean}>} */ (TIER_ROLES)[id] ?? {};
   return {
     id,
     label: raw.label ?? (id ? id.charAt(0).toUpperCase() + id.slice(1) : "Root"),
     responsive: raw.responsive ?? role.responsive ?? false,
-    cullable: raw.cullable ?? role.cullable ?? false,
   };
 };
 
@@ -84,11 +139,10 @@ const resolveTier = (tier) => {
  * @property {string | null} feedbucketKey
  * @property {LabTier[]} tiers
  * @property {string | null} sectionsTier   the id of the tier holding the responsive role
- * @property {string | null} cullTier       the id of the tier holding the cull role
  * @property {string | null} responsiveDir  `<directory>/<sectionsTier>/`, or null
- * @property {string | null} cullDir        `<directory>/<cullTier>/`, or null
  * @property {string} responsiveFile        `<directory>/responsive.json`
- * @property {string} cullFile              `<directory>/cull.json`
+ * @property {Viewports} viewports          the viewport's screen sizes (DEFAULT_VIEWPORTS)
+ * @property {null} tasks                   filled in by the integration when the pin board runs
  */
 
 /**
@@ -100,7 +154,6 @@ export function resolveLabOptions(options = {}) {
   const directory = normaliseDirectory(options.directory ?? DEFAULT_DIRECTORY);
   const tiers = (Array.isArray(options.tiers) ? options.tiers : DEFAULT_TIERS).map(resolveTier);
   const sections = tiers.find((tier) => tier.responsive) ?? null;
-  const cull = tiers.find((tier) => tier.cullable) ?? null;
   return {
     directory,
     subpath: normaliseSubpath(options.subpath ?? DEFAULT_SUBPATH),
@@ -111,10 +164,9 @@ export function resolveLabOptions(options = {}) {
     feedbucketKey: options.feedbucketKey ? String(options.feedbucketKey) : null,
     tiers,
     sectionsTier: sections ? sections.id : null,
-    cullTier: cull ? cull.id : null,
     responsiveDir: sections ? `${directory}/${sections.id}/` : null,
-    cullDir: cull ? `${directory}/${cull.id}/` : null,
     responsiveFile: `${directory}/responsive.json`,
-    cullFile: `${directory}/cull.json`,
+    viewports: resolveViewports(options.viewports),
+    tasks: null,
   };
 }

package/dist/core/virtual-module/virtual-routes.js

@@ -51,7 +51,18 @@ async function getVirtualRoutes(rootDir, codegenDir, logger, dashboardSubpath, p
 }
 function createVirtualRouteComponent(route) {
   const modName = `astrobook_module_${route.storyModule.id}`.replaceAll(/\W+/g, "_").replaceAll(/_+/g, "_").replace(/_+$/, "");
-  const page = route.props.hasSidebar ? STORY_PAGE : PREVIEW_PAGE;
+  if (route.props.hasSidebar) {
+    return `
+---
+// Automatically generated by Astrobook
+
+import StoryPage from '${STORY_PAGE}';
+---
+
+<StoryPage story={'${route.props.story}'} hasSidebar={true} />
+`.trim();
+  }
+  const page = PREVIEW_PAGE;
   return `
 ---
 // Automatically generated by Astrobook

package/docs/PIN-CONTRACT.md

@@ -1,6 +1,6 @@
 # orbytes-pin — the contract
 
-The interfaces the parts of the pin board agree on. Four source files under
+The interfaces the parts of the pin board agree on. Five source files under
 [`../src/pin/`](../src/pin/) cite this document by name, and it lives inside the package so those
 citations resolve wherever the package is copied. The board moved into the lab package — today
 `@orbytes/astrolab`, and named `orbytes-astro-lab` until the 2026-09-22 rename — on 2026-09-22,
@@ -120,14 +120,27 @@ naming no readable ticket, or an `expect` that disagrees with disk.
 Canonical: `~/.orbytes/feedback-archive/<project>/pin-<NNN>.png`, **hardlinked** into
 `<repo>/backlog/assets/` so the board can serve it — the same bytes under two names, zero extra
 storage. Copy is the fallback across filesystems, and the log says which happened.
-`backlog/assets/` is gitignored; the ticket markdown is committed.
+
+**The package ignores nothing in git.** It writes no `.gitignore` and adds no rule anywhere, so in
+a site's repo `<backlogDir>/assets/` is committed like any other folder unless that repo ignores
+it. This repo's own `.gitignore` carries `backlog/assets/` and `backlog/gallery.html`, so here the
+ticket markdown is committed and the pictures and the gallery snapshot are not; a site that wants
+the same adds those two lines (with its own `backlogDir`) to its `.gitignore`.
 
 Taken by a warm Playwright singleton against a freshly loaded page, motion frozen two ways, toolbar
 hidden, clipped to the ticket's rect with `fullPage: true` — **`clip` is viewport-relative without
 it**, so a pin below the fold would throw *"Clipped area is either empty or outside the resulting
-image"*. Measured cost: ~2.0–2.4s per shot, warm or cold, dominated by `waitForLoadState`, not by
-browser launch. You never wait on it: the ticket is written and the panel confirms in under 30ms,
-on the same tick, and the shot lands afterwards on its own event.
+image"*. You never wait on a shot: the ticket is written and the panel confirms in under 30ms, on
+the same tick, and the shot lands afterwards on its own event.
+
+**What a shot costs was measured three times, and each figure times a different span**, so they
+are not competing readings of one number:
+
+| Measured | Where | Span timed | Figure |
+|---|---|---|---|
+| 2026-09-21 | the client site the board was first built in, an Apple-silicon laptop | the capture: navigate, freeze motion, settle every image, hold the scroll position, clip | ~1.34 s warm, ~1.42 s cold; launching chromium ~98 ms |
+| 2026-09-21 | the same site, cold cache, real input | the toolbar's submit to the screenshot | 2.0–2.4 s, warm or cold, dominated by the `networkidle` wait in `page.goto`, not by browser launch |
+| 2026-09-22 | this repo's testbed home page, a real mouse | the *Create ticket* click to the *screenshot landed* status line | 1934 ms (below) |
 
 **`playwright` is an optional peer and it has to be installed** — `npm i -D playwright && npx
 playwright install chromium`. Nothing else gates screenshots: the dynamic import inside
@@ -154,9 +167,18 @@ A dead-selector ticket is **labelled, never discarded** — the screenshot, sour
 `outer_html` still make it workable by hand. The defect this guards against is silence, not
 instability.
 
+The board's label is `selectorFlag` in [`../src/pin/board.mjs`](../src/pin/board.mjs): `0` and
+`2+` put a *needs a human* banner on the card, and for `0` its note says an agent cannot locate the
+element — by selector, which is the one thing that died. **It is a label, not a gate.** It changes
+no status, and `isAgentReady()` and `listTickets()` do not read `selector_matches`, so a flagged
+ticket left in `Ready for agent` still reaches an agent. Only its status keeps an agent off it.
+
 ## The browser ↔ server channel
 
-Over the Vite HMR socket. No HTTP endpoint for writes from the toolbar, no port, no CORS.
+Creating a ticket goes over the Vite HMR socket: no HTTP endpoint, no port, no CORS. A status
+change is the one HTTP write, from the board and from the panel's own menus alike —
+`POST <route>/api/ticket`, same-origin, on the dev server already running, with the address read
+from the board's `data-api` (› *Writing a ticket*).
 
 Client, inside `init(canvas, app, server)` ([`../src/pin/toolbar.js`](../src/pin/toolbar.js)):
 `server.send("orbytes-pin:create", payload)` · `server.on("orbytes-pin:created" | "orbytes-pin:shot", …)`
@@ -182,6 +204,48 @@ site setting `pin: { route: "/__pin" }` got a panel that fetched a path the midd
 serve and showed an empty list — fixed 2026-09-22. One function normalises the trailing
 slash, `boardRoute`, and both the middleware and the toolbar read it, so they cannot disagree.
 
+**The board page moved into the lab on 2026-09-24.** Through `orbytesLab()` the route is
+`<subpath>/tasks` and the page there is an Astro page in the lab's chrome
+(`../src/chrome/views/Tasks.astro`), not this middleware's standalone document. The panel's contract
+with it is unchanged, because the page renders the SAME markup from the same function
+(`boardParts`): it still reads `[data-board]`, its `data-api`, every `[data-col][data-status]`, the
+`script.card-data` payloads and `.broken li code` off the page at `route`. A change to those
+selectors in `board.mjs` is a change to this contract.
+
+## The lab's channel — `orbytes-pin:command` and `orbytes-pin:state`
+
+Added 2026-09-24, when the lab's navbar took over pinning inside `/lab`. The lab imports nothing
+from [`../src/pin/toolbar.js`](../src/pin/toolbar.js); it drives the one pin app on the lab page's
+dev toolbar through two window events, so there is one picker and one composer, never a second
+copy.
+
+| Direction | Event | Detail |
+|---|---|---|
+| lab → app | `orbytes-pin:command` | `{ action: "pick", within?: Element }` or `{ action: "stop" }` |
+| app → lab | `orbytes-pin:state` | `{ active, mode, tickets }` |
+
+- **`pick`** turns the app on in pick mode; if it is already on, it goes back to picking unless an
+  element is already selected. **`within`** confines the pick to that element's box, and within
+  it to what lies inside a frame: the lab passes its canvas, so Comment pins the previewed page and
+  never the lab's chrome. The scope clears when the app turns off, and the toolbar's own button
+  still opens the app unscoped.
+- **`stop`** turns the app off.
+- **`orbytes-pin:state`** is published after every mode change and every board read. `active` is
+  whether the app is on; `mode` is `idle`, `picking` or `selected`; `tickets` is the list the app
+  read off the board — the same `script.card-data` payloads described above, so the lab parses no
+  ticket either.
+- **`window.__orbytesPin`** holds the same snapshot, for a listener that arrives after the last
+  event. The lab's Comment button is disabled until it exists.
+
+**Anything the lab draws over a framed page carries `data-orbytes-pin-ui`**, the attribute the
+picker skips in whichever document it finds it (`isChrome`). The picker takes the topmost element
+under the pointer, so an unmarked overlay stands in front of the frame: a scoped pick finds nothing
+there, and an unscoped one pins the overlay. **And it is drawn in the chrome,
+outside the frame** — the lab's markers and hint live in the lab page's own document, over the
+`<iframe>`, never in the framed one. The framed document is what the picker measures, builds a selector against and
+copies into `outer_html`, and what `shot.mjs` re-loads fresh for the screenshot; an element the lab
+added to it would be in the first and absent from the second.
+
 ## The status line — one line, not a log
 
 Decided 2026-09-22, replacing a running four-entry list that narrated every step. The log was
@@ -215,7 +279,7 @@ binding Astro 7 uses contains zero. So this package stamps its own `data-orbytes
 via a dev-only Vite `load` hook. **Expect it to break again** — Astro dropped these once before,
 silently, with no deprecation.
 
-A file matched by the `stamp` glob with no stampable element is a hard throw naming the file. That
+A file under a `stamp` directory with no stampable element is a hard throw naming the file. That
 is the guard, not an inconvenience: a warned-past file silently produces tickets with no source.
 
 Selectors are built up to the **shortest form resolving to exactly one node**, verified against the
@@ -247,15 +311,25 @@ four times independently, and verified on real production builds — normal and
   the inner `<button>` in their shadow root.
 - **Markers belong in the toolbar canvas, never `document.body`.** The screenshotter hides only
   `astro-dev-toolbar`, so a page-parented marker is photographed into every later ticket.
+- **An overlay the lab draws over a frame needs `data-orbytes-pin-ui`, and belongs in the chrome.**
+  The picker takes the topmost element under the pointer and skips only what carries the
+  attribute, so an unmarked overlay blocks or becomes the pick; and an overlay put inside the
+  framed document changes the DOM a selector is built against (› *The lab's channel*).
+- **Inside the lab, Astro's dev toolbar is hidden in every frame** (2026-09-24), so the lab page's
+  own toolbar is the only one. A test that looks for the pin app inside a framed story will not
+  find it; drive the lab page's app instead.
 
 ## Chrome
 
 Neutral tool chrome, never the host site's styling — decided for this board and, separately, for
 the component lab. A standard board that reads the same in every project it is installed in.
 
-Every value is a custom property in one namespaced block (`--pin-*`, on `.pin-chrome`). No literal
-colours outside it, and **no bare element selectors** anywhere — those inherit down into the
-previewed page.
+In the in-page panel and its markers ([`../src/pin/toolbar.js`](../src/pin/toolbar.js)) every value
+is a custom property in one namespaced block (`--pin-*`, on `.pin-chrome`). No literal colours
+outside it, and **no bare element selectors** anywhere — those inherit down into the previewed
+page. The kanban's stylesheet (`BOARD_CSS`, [`../src/pin/board.mjs`](../src/pin/board.mjs)) is
+fenced differently: its tokens are unprefixed, on its own root inside `@scope (.pin-board)`, and
+inside the lab `.pin-board--lab` maps them onto the lab's `--lab-*` tokens.
 
 **The `--pin-*` namespace survived the merge and is still the board's own** (2026-09-22). Repointing
 it at the lab's `--lab-*` tokens is the shared-chrome design — lab phase 2 — and was deliberately