@orbytes/astrolab 0.4.0-next.1 → 0.4.0-next.2

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,13 @@ 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 },
 };
 
 /**
@@ -118,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,
   };
 };
 
@@ -145,11 +139,8 @@ 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
  */
@@ -163,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),
@@ -174,11 +164,8 @@ 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/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", …)`
@@ -190,6 +212,40 @@ with it is unchanged, because the page renders the SAME markup from the same fun
 `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
@@ -223,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
@@ -255,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

package/docs/PIN.md

@@ -1,8 +1,10 @@
 # The pin board
 
 Click a rendered element on `astro dev`, leave a comment, and get a markdown ticket plus a PNG on
-local disk for a Claude Code agent to pick up. Then work the tickets on a kanban at `/lab/tasks`,
-in the lab, on the same dev server. No cloud, no API key, no MCP, no second process.
+local disk for a Claude Code agent to pick up — from the lab's navbar (**Comment**, on the page it is
+previewing) or from Astro's dev toolbar on the site's own pages. Then work the tickets on a kanban
+at `/lab/tasks`, in the lab, on the same dev server. No cloud, no API key, no MCP, no second
+process. It needs the site to be inside a git repository (› *Wiring*).
 
 It is for a **solo pass** — your own review of a site in dev, before anyone else sees it. It does
 not sync with whatever tool you use for review rounds with other people, and is not meant to
@@ -33,7 +35,7 @@ pin ticket that erases `dispatch`, `source`, `selector`, `rect`, `shot` and `out
 why the pin fields live in a fenced block in the body, and why `/pin` was read-only until
 2026-09-22:
 a second writer of these files would have rebuilt the bug. With backlog.md out of the loop there
-is no second writer, so `/pin` writes them correctly by construction (› *The write path*).
+is no second writer, so the board writes them correctly by construction (› *The write path*).
 
 If backlog.md is still installed globally, this does not uninstall it.
 A `backlog/config.yml` left behind in a repo that used backlog.md is a record and nothing reads it
@@ -84,8 +86,10 @@ neither tab: it is reachable on the board only.
 
 **In the lab since 2026-09-24** (decided that day: one URL, everything under `/lab`). The board is
 two views in the lab's own chrome — **Kanban Board** at `/lab/tasks` and **All Tasks**, a sortable
-table of every ticket, newest first, at `/lab/tasks/all` — with the statuses and their counts in
-the lab's panel; `/lab/tasks?status=Ready%20for%20review` opens the board filtered to one column.
+table of every ticket, newest first, at `/lab/tasks/all` — with no second-level panel beside them
+(decided 2026-09-24: the board's own status chips already filter, so a status list beside it only
+took width from the columns); `/lab/tasks?status=Ready%20for%20review` opens the board filtered to
+one column.
 `/pin`, the board's address until then, redirects there. Both views are Astro pages the pin half
 injects in `astro dev` only, rendered from the same markup, stylesheet and script as the standalone
 file (`boardParts` in [`src/pin/board.mjs`](../src/pin/board.mjs)); the stylesheet is scoped with
@@ -101,8 +105,9 @@ scrolls sideways, rather than wrapping into a stack beside two sidebars.
   with a filled count **only when it actually holds something**. An empty queue stays quiet; one
   that shouts at nothing teaches you to stop looking at it. Its count also leads the top bar.
 - **Cancelled is drawn to be ignored**: a narrow dashed rail rather than a sixth of the wall, its
-  cards desaturated until hovered. Still a real drop target, and still the only place a cancelled
-  ticket can be seen at all — an archive nobody can open is a delete.
+  cards desaturated until hovered. Still a real drop target. This rail, the All Tasks table (which
+  lists every ticket) and the gallery file are the only places a cancelled ticket can be seen at
+  all — an archive nobody can open is a delete.
 - Every column carries a one-line gloss under its name (*agents start here*, *waiting on you*),
   because six nouns with no explanation is a vocabulary you have to be told once and remember.
 - **A card** carries its screenshot, id, title, dispatch mode, priority and source file, plus the
@@ -124,6 +129,29 @@ listening behind it.
 **The standalone board's corner links** are an option (`links`), not the hardcoded `/` and `/lab`
 they were until 2026-09-22. Inside the lab there are none — the lab's own menu is right there.
 
+## Pinning from inside the lab
+
+Every preview in the lab is an `<iframe>`, and Astro's dev toolbar is hidden inside the lab's
+frames, so a lab page has one toolbar — its own — and one pin app. The lab drives that app rather
+than carrying a second picker:
+
+- **Comment**, in the navbar of a component page and of a page view, starts a pick confined to the
+  canvas: only the framed page can be picked, never the lab's chrome around it. Escape stops the
+  pick and turns Comment off; a comment already typed into the composer is kept, never discarded.
+  The composer that follows is the pin app's own window on the dev toolbar. The button is disabled
+  until the pin app has started, which it does when the dev toolbar is idle.
+- **The pins** already left on the framed page are drawn over the frame at their elements: blue
+  while open, grey once resolved, numbered in the order they were made, cancelled ones never. A
+  ticket whose selector finds nothing on that page, or more than one thing, draws no pin rather
+  than a guessed one. A pin, and the pin row in the component's Properties panel, open All Tasks.
+- **⋯ › Pins** holds two switches, Show pins (on) and Show resolved (off), remembered per browser
+  in `localStorage` (`lab-pins-show`, `lab-pins-resolved`).
+
+The list of pins is the pin app's own, re-read after every write, so a new pin appears as soon as
+its ticket lands. How the lab and the app talk is in [the contract](./PIN-CONTRACT.md) › *The lab's
+channel*. On the site's own pages, outside `/lab`, the dev toolbar's pin app works exactly as it
+always did.
+
 ## The write path
 
 One endpoint, `POST <route>/api/ticket`, registered in `astro:server:setup` — which does not exist
@@ -132,14 +160,17 @@ in a build, so it cannot reach `dist/`.
 **The endpoint, the screenshots and the `/pin` redirect are middleware**, installed ahead of
 Astro's own request handler, so they shadow a host page at the same path — in dev only. Through
 `orbytesLab()` the route is `<subpath>/tasks`, which no site page is likely to be; the one exposed
-address is `/pin`, which redirects. On its own, without the lab, the pin half still serves its
-standalone board at `route`, default `/pin`.
+address is `/pin`, which redirects. Setting `route` does not free it: inside the lab `/pin`
+redirects to `route` whatever that is, and a `route` of `/pin` puts the Tasks views there instead,
+so no `route` leaves a site's own `/pin` page alone in dev — `pin: false` does. On its own,
+without the lab, the pin half still serves its standalone board at `route`, default `/pin`, and
+there `pin: { route: "/__pin" }` moves it off a site page.
 
 ```json
 { "id": "PIN-004", "status": "Ready for review", "expect": { "status": "In Progress" } }
 ```
 
-`updateTicket` (`src/board.mjs`) rewrites **only** the frontmatter lines it is changing, plus
+`updateTicket` (`src/pin/board.mjs`) rewrites **only** the frontmatter lines it is changing, plus
 `updated_date`. It never serialises: the file is split by index, and the slice from the closing
 `---` onward — the comment, the image and the fenced ```yaml pin block — is the same substring on
 the way out as on the way in. That identity is asserted on every write, and the write is a temp
@@ -181,7 +212,7 @@ Nothing is wired separately: the board comes with the lab, through the one integ
 already configures.
 
 ```js
-import orbytesLab from "./packages/astro-lab/index.mjs";
+import orbytesLab from "@orbytes/astrolab";
 
 const includeLab =
   process.argv.includes("dev") || process.env.PUBLIC_DEPLOY_ENV === "staging";
@@ -197,6 +228,15 @@ export default defineConfig({
 gates itself on `command === "dev"`, so including the lab in a staging build registers it and it
 does nothing there.
 
+**The site must be inside a git repository.** Every path in a ticket is repo-relative, and the root
+is the Astro project's folder or the nearest one above it that holds `.git`. With none, the board
+stands down for that run instead of taking the dev server with it (measured 2026-09-22: a freshly
+scaffolded Astro project, which has no git yet, could not run `astro dev` at all before the board
+learned to stand down). The only sign is a warning in the dev server's log. `<route>`,
+`<route>/all` and `/pin` answer 404, the lab shows no Tasks group and no Comment button, and there
+is no pin app on the dev toolbar and no source stamp. `git init` and a restart turn it on;
+`pin: false` silences the warning.
+
 `playwright` is an **optional** peer and is loaded by dynamic import inside the screenshotter, not
 at module scope — a site without it loads its config, runs the lab and writes tickets without
 pictures. Install it (`npm i -D playwright && npx playwright install chromium`) for the screenshots,
@@ -208,7 +248,7 @@ Pass these as `orbytesLab({ pin: { … } })`.
 
 | Option | Default | What it does |
 |---|---|---|
-| `stamp` | `["src/lab/sections", "src/components"]` | **Site-relative** directories whose `.astro` files get `data-orbytes-src`. |
+| `stamp` | `["src/lab/sections", "src/components"]` | **Site-relative** directories whose `.astro` files get `data-orbytes-src`. Replaces the default whole, and does not follow the lab's `directory`. `src/lab/components` and `src/lab/explorations` are not in it — see *The source attribute*. |
 | `stampSkip` | `[]` | **Site-relative** `.astro` paths exempt from the stamp's hard failure. See below. A repo-relative path is accepted too — until 2026-09-22 that was the only spelling that worked, while `stamp` beside it was site-relative, so the exemption silently lapsed wherever the Astro project was not the repo root. |
 | `backlogDir` | `"backlog"` | Repo-relative board directory: tickets in `tasks/`, PNGs in `assets/`. |
 | `archiveDir` | `~/.orbytes/feedback-archive` | Canonical screenshot home; the repo copy is a hardlink into it. |
@@ -315,26 +355,33 @@ Two rules now keep a selector off that ground, both in
 - **A class naming a runtime condition never enters a selector** (`isTransientClass`,
   `extendsSiblingClass`) — `swiper-slide-active` is on slide 1 now and slide 2 after a scroll.
 
-Neither is complete, and the field is what makes the remainder visible. `src/shot.mjs` already
+Neither is complete, and the field is what makes the remainder visible. `src/pin/shot.mjs` already
 loads the page **fresh in a real browser** to take the screenshot; before the shutter it asks that
 page how many nodes the ticket's selector finds, and writes the answer back into the pin block:
 
 | Value | Means |
 |---|---|
 | `1` | healthy — the selector names exactly this element on a fresh load |
-| `0` | dead — work the ticket from `source`, the screenshot and `outer_html` |
+| `0` | dead — flagged *needs a human* on the board; a person works it from `source`, the screenshot and `outer_html` |
 | `2`+ | ambiguous — the selector names several elements |
 | `pending` | never tested — shots are off, or the screenshot failed |
 
 Anything but `1` is said in the dev log and in the toolbar panel. A ticket whose selector died is
 **still a good ticket** — it is labelled, never discarded. The defect was the silence.
 
+On the board, `0` and `2`+ put a banner on the card, count towards *needing a human* in the
+summary, and match the *Needs a human* filter. The banner's note for `0` says an agent cannot
+locate the element: its selector cannot, and the rest of the ticket is intact for a person to work
+from. **The flag is a label, not a gate.** It changes no status, and neither `isAgentReady()` nor
+`listTickets()` reads `selector_matches` — a flagged ticket left in `Ready for agent` is still
+handed to an agent. Only its status keeps an agent off it.
+
 ## Screenshots
 
 One chromium for the whole dev session, launched lazily on the first pin and kept warm, closed
-when the dev server closes. Measured on an Apple-silicon laptop, 2026-09-21: the launch itself is
-~98 ms, and a full capture — navigate, freeze motion, settle every image, hold the scroll position,
-clip — is ~1.34 s warm against ~1.42 s cold.
+when the dev server closes. What a shot costs has been measured three times, each timing a
+different span; the figures, their dates and what each one timed are in
+[the contract](./PIN-CONTRACT.md) › *Screenshots*.
 
 You never wait for any of it. The ticket is written and `orbytes-pin:created` replied on the
 same synchronous tick; the screenshot follows and sends `orbytes-pin:shot` when it lands. A ticket
@@ -358,6 +405,22 @@ file under `stamp`, and the picker walks up from the clicked node to the nearest
 it. No ancestor found → `source` is `unresolved`, and the CSS selector plus `outer_html` still
 make the ticket actionable.
 
+**The default does not cover every tier.** It stamps `src/lab/sections` and `src/components`, so a
+component kept in the lab's own `src/lab/components/` (or `src/lab/explorations/`) and pinned on its
+own variant has no stamped ancestor, and its tickets say `unresolved`. Name the folder to include it
+— `stamp` replaces the default, so restate what you keep:
+
+```js
+orbytesLab({
+  pin: {
+    stamp: ["src/lab/sections", "src/lab/components", "src/components"],
+  },
+})
+```
+
+Widening `stamp` widens the hard failure below with it, so check the folder for templates with no
+element to stamp first.
+
 The attribute is inserted immediately after the tag name (`<section` → `<section
 data-orbytes-src="…"`), so no attribute value, expression, spread or self-closing slash can be
 mangled and no line number moves.
@@ -383,14 +446,17 @@ orbytesLab({
 
 ## The browser ↔ server channel
 
-Astro's dev toolbar, over the existing Vite HMR socket. No HTTP endpoint, no port, no CORS.
+Creating a ticket goes over Astro's dev toolbar, on the existing Vite HMR socket — no HTTP endpoint,
+no port, no CORS. Changing a ticket's status 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.
 
 | Direction | Event | Payload |
 |---|---|---|
 | browser → server | `orbytes-pin:create` | `{ comment, dispatch, source, selector, url, viewport, scroll, rect, outerHTML }` |
 | server → browser | `orbytes-pin:created` | `{ id, file, shot, error }` — all four keys, always |
 | server → browser | `orbytes-pin:shot` | `{ id, shot, selectorMatches, error }` |
-| board → server | `POST <route>/api/ticket` | `{ id, status?, priority?, expect? }` → `{ ok, id, status, priority, file, changed, card }` |
+| board or panel → server | `POST <route>/api/ticket` | `{ id, status?, priority?, expect? }` → `{ ok, id, status, priority, file, changed, card }` |
 
 On failure the reply is `{ id: null, file: null, shot: null, error: "why, in one plain sentence" }`.
 
@@ -419,7 +485,8 @@ window, so clicking it again focuses that tab instead of opening another.
 
 1. `astro:config:setup` returns early unless the Astro command is `dev` — no plugin, no toolbar
    app, no stamp.
-2. Both Vite plugins carry `apply: "serve"`, so they cannot load in a build even if they were
+2. All three Vite plugins — the source stamp, the toolbar's config module and the one that closes
+   the browser — carry `apply: "serve"`, so they cannot load in a build even if they were
    registered.
 3. `astro:server:setup`, where every write lives — the ticket writer, the screenshots and the
    `<route>/api/ticket` endpoint — does not run in a build at all. The lab's two Tasks views are
@@ -432,8 +499,11 @@ The first one matters more since the merge than it did before: the lab is delibe
 in a build for the first time, and `command === "dev"` is what makes that a no-op.
 
 Verified by running a real `npm run build` and grepping `dist/` for `orbytes-pin`, `data-orbytes-src`
-and `/pin/api`: no hit.
+and `/pin/api`: no hit. Re-checked 2026-09-24 on a staging build of the testbed, the case where the
+pin half is registered: no hit for those three or for `/tasks/api`, and no `lab/tasks/` page.
 
 No path this package emits into served HTML or into a ticket is absolute. The repo root is found
-by walking up from the Astro config root to the first directory containing `.git`, and it throws
-rather than guess.
+by walking up from the Astro config root to the first directory containing `.git`, and
+`findRepoRoot` throws rather than guess. The integration catches that throw, warns, and stands down
+for the run (› *Wiring*) — a library that guesses writes files where nobody asked, and an
+integration that rethrows takes the dev server down.

package/index.d.ts

@@ -11,11 +11,6 @@ export interface LabTierOption {
    * thumbnails and in the viewport configurator. Defaults to true for a tier named "sections".
    */
   responsive?: boolean;
-  /**
-   * This tier's stories may be marked for deletion in the sidebar and removed by
-   * `orbytes-lab-cull`. Defaults to true for a tier named "explorations".
-   */
-  cullable?: boolean;
 }
 
 export interface OrbytesLabOptions {
@@ -52,8 +47,7 @@ export interface OrbytesLabOptions {
   feedbucketKey?: string;
   /**
    * The tiers, in reading order. Default `["sections", "components", "explorations"]`; a tier
-   * named "sections" takes the responsive role and one named "explorations" the cull role unless
-   * the entry says otherwise.
+   * named "sections" takes the responsive role unless the entry says otherwise.
    */
   tiers?: (string | LabTierOption)[];
   /**

package/index.mjs

@@ -11,9 +11,10 @@
 //
 // ── the pin board (./src/pin/, moved in 2026-09-22) ─────────────────────────────────────────────
 // Decided 2026-09-22: the lab and the pin board are ONE app, bundled and working as one — not two
-// packages a site installs separately. So `/lab` and `/pin` come from one call, one install, one
-// dev server. `pin: false` omits it entirely — a site may want the lab alone — and `pin: {…}` passes
-// options straight through (ops/standalone-plan.md › The pin board merges in; docs/PIN.md).
+// packages a site installs separately. So the lab (`<subpath>`) and its Tasks board
+// (`<subpath>/tasks`) come from one call, one install, one dev server. `pin: false` omits it
+// entirely — a site may want the lab alone — and `pin: {…}` passes options straight through
+// (ops/standalone-plan.md › The pin board merges in; docs/PIN.md).
 //
 // The pin half is DEV ONLY and gates itself four times over; it is registered in staging builds
 // along with the lab and does nothing there, because its first assertion is `command === "dev"`.
@@ -33,18 +34,13 @@
 //      (the task views, <subpath>/tasks and /tasks/all, are the pin half's, dev only)
 //      and define `virtual:orbytes-lab/*` so those pages can read the resolved options, the
 //      consumer's head component and the consumer's CSS without importing anything by path.
-//   3. serve the two mark APIs on the Vite dev server only (astro:server:setup never runs in a
-//      build, so a deployed lab has no write path and the switches hide themselves):
-//        GET /__lab/cull         { marked: string[], updated: string | null }
-//        PUT /__lab/cull         body { marked: string[] } — every entry must be an existing
-//                                stories file in the CULLABLE tier AND not live on any page;
-//                                otherwise 400 with the offenders. Writes <directory>/cull.json.
+//   3. serve the responsive marks API on the Vite dev server only (astro:server:setup never runs
+//      in a build, so a deployed lab has no write path and the switches hide themselves):
 //        GET /__lab/responsive   { done: string[], approved: string[], updated: string | null }
 //        PUT /__lab/responsive   body { done: string[], approved?: string[] } — every entry must
 //                                be an existing stories file in the RESPONSIVE tier; otherwise 400
 //                                with the offenders. Writes <directory>/responsive.json.
-//      Marks only. NOTHING HERE DELETES A FILE — that is `orbytes-lab-cull`, a separate command,
-//      run by hand and with a dry run first.
+//      Marks only. NOTHING HERE DELETES A FILE.
 //
 // Gotcha (2026-09-06): Astro re-imports astro.config.mjs on a config change, but this module and
 // its ./src/shell/*.mjs imports stay in Node's ESM cache for the life of the process — so an edit
@@ -59,15 +55,7 @@ import { fileURLToPath } from "node:url";
 import { createAstrobookIntegration } from "./dist/core/index.js";
 import { resolveLabOptions } from "./defaults.mjs";
 import orbytesPin from "./src/pin/index.mjs";
-import { defaultImports, liveComponentFiles, storyComponentFile } from "./src/shell/live-files.mjs";
-import {
-  cullOffence,
-  readCull,
-  readResponsive,
-  responsiveOffence,
-  writeCull,
-  writeResponsive,
-} from "./src/shell/marks.mjs";
+import { readResponsive, responsiveOffence, writeResponsive } from "./src/shell/marks.mjs";
 
 const file = (relative) => fileURLToPath(new URL(relative, import.meta.url));
 
@@ -84,22 +72,6 @@ const RESOLVED = {
   [VIRTUAL.css]: "__virtual_orbytes_lab_user_css__.mjs",
 };
 
-/**
- * Why an entry may not be marked for deletion, or null when it may. `importedByLive` maps a
- * component file to the live section that imports it, so an exploration a live section uses is
- * refused here with the same reason the cull script would give later.
- */
-const cullEntryOffence = (rootDir, config, entry, liveByFile, importedByLive) => {
-  const bad = cullOffence(rootDir, config, entry);
-  if (bad) return bad;
-  const component = storyComponentFile(rootDir, entry);
-  const mount = component ? liveByFile.get(component) : undefined;
-  if (mount) return `live on ${mount.page} (slot ${mount.slot}: ${component})`;
-  const user = component ? importedByLive.get(component) : undefined;
-  if (user) return `used by live section ${user}`;
-  return null;
-};
-
 const readBody = (req) =>
   new Promise((resolve, reject) => {
     let body = "";
@@ -184,10 +156,10 @@ function labShell(options, shared = { tasks: null }) {
             // consumer should need one line in its config and nothing more, so the exemption is
             // declared here rather than there.
             ssr: { noExternal: ["@orbytes/astrolab"] },
-            // Marking writes JSON files under src/; keep Vite from treating those as source
-            // changes and reloading the lab mid-triage.
+            // Marking writes a JSON file under src/; keep Vite from treating it as a source
+            // change and reloading the lab mid-triage.
             server: {
-              watch: { ignored: [`**/${config.cullFile}`, `**/${config.responsiveFile}`] },
+              watch: { ignored: [`**/${config.responsiveFile}`] },
             },
           },
         });
@@ -196,47 +168,8 @@ function labShell(options, shared = { tasks: null }) {
         );
       },
       "astro:server:setup": ({ server, logger }) => {
-        server.middlewares.use(async (req, res, next) => {
-          const url = new URL(req.url ?? "/", "http://x");
-          if (url.pathname !== "/__lab/cull") return next();
-          try {
-            if (req.method === "GET") return send(res, 200, readCull(rootDir, config));
-            if (req.method === "PUT") {
-              const body = await readBody(req);
-              if (!Array.isArray(body.marked))
-                return send(res, 400, { error: "body must be { marked: string[] }" });
-              const live = liveComponentFiles(rootDir);
-              // First mount wins, so the refusal names the page a reader would look at first.
-              const liveByFile = new Map();
-              for (const l of live) if (!liveByFile.has(l.file)) liveByFile.set(l.file, l);
-              const importedByLive = new Map();
-              for (const l of live) {
-                for (const dep of defaultImports(rootDir, l.file)) {
-                  if (!importedByLive.has(dep.file)) importedByLive.set(dep.file, l.file);
-                }
-              }
-              const offenders = body.marked
-                .map((entry) => ({
-                  path: entry,
-                  reason: cullEntryOffence(rootDir, config, entry, liveByFile, importedByLive),
-                }))
-                .filter((o) => o.reason !== null);
-              if (offenders.length > 0) {
-                return send(res, 400, { error: "some entries cannot be marked", offenders });
-              }
-              const data = writeCull(rootDir, config, body.marked);
-              logger.info(`cull marks saved: ${data.marked.length} → ${config.cullFile}`);
-              return send(res, 200, { ok: true, file: config.cullFile, ...data });
-            }
-            return send(res, 405, { error: "GET or PUT" });
-          } catch (e) {
-            return send(res, 500, { error: String(e?.message ?? e) });
-          }
-        });
-
-        // The responsive marks — same shape of API as the cull one above, and deliberately its
-        // sibling rather than a second mechanism: a section version is marked responsive (and,
-        // separately, approved for that work) by hand, because neither fact is in the code.
+        // The responsive marks: a section version is marked responsive (and, separately, approved
+        // for that work) by hand, because neither fact is in the code.
         server.middlewares.use(async (req, res, next) => {
           const url = new URL(req.url ?? "/", "http://x");
           if (url.pathname !== "/__lab/responsive") return next();
@@ -269,7 +202,7 @@ function labShell(options, shared = { tasks: null }) {
           }
         });
 
-        logger.info("mark APIs at /__lab/cull and /__lab/responsive (dev only)");
+        logger.info("mark API at /__lab/responsive (dev only)");
       },
     },
   };