@orbytes/astrolab 0.3.0

package/docs/PIN.md

@@ -0,0 +1,429 @@
+# 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 `/pin`, on the
+same dev server. No cloud, no API key, no MCP, no second process.
+
+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
+replace one. **Dev only** — nothing here can run in `astro build`.
+
+> **It ships as half of `@orbytes/astrolab`.** Built as its own package, `orbytes-pin`, over
+> 2026-09-21/22 and merged into the lab on 2026-09-22 so the two install, configure and version as
+> one thing. The source is [`src/pin/`](../src/pin/), the interface it agrees on is
+> [PIN-CONTRACT.md](./PIN-CONTRACT.md), and there is no `orbytes-pin` package any more — import
+> from `@orbytes/astrolab` or `@orbytes/astrolab/pin`.
+
+## backlog.md is retired (2026-09-22)
+
+The board used to be [backlog.md](https://github.com/MrLesk/Backlog.md): a separate server on its
+own port (`backlog browser`, 6420). That is the whole reason it is gone — the site was on
+`localhost:4321`, the lab on `localhost:4321/lab`, and the tickets somewhere else entirely.
+
+**Stop doing two things.** Neither is merely redundant:
+
+| Stop | Do instead |
+|---|---|
+| `backlog browser` | `npm run dev`, then `/pin` |
+| `backlog task edit <n> …` on a pin ticket | drag the card, or use the status menu in its detail panel |
+
+`backlog task edit` is the original defect, not an alternative. Any write through backlog.md
+re-serialises frontmatter to its own schema and silently drops every key it does not know; on a
+pin ticket that erases `dispatch`, `source`, `selector`, `rect`, `shot` and `outer_html`. It is
+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*).
+
+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
+— those values live in `BOARD_CONVENTIONS` and `PRIORITIES`
+([`src/pin/board.mjs`](../src/pin/board.mjs)) and `STATUSES`
+([`src/pin/tickets.mjs`](../src/pin/tickets.mjs)). `backlog/tasks/` and `backlog/assets/` are
+unchanged.
+
+## The status model
+
+Six statuses, in board order. Three of them carry a rule, and each rule is enforced by code rather
+than left as a convention to remember.
+
+| Status | What it means | The rule |
+|---|---|---|
+| **Backlog** | raised, but not ready for an agent to pick up | not work yet |
+| **Ready for agent** | queued work — it replaces the usual *To Do* | **the only status an agent may start work from** — `isAgentReady()` |
+| **In Progress** | an agent is on it | — |
+| **Ready for review** | an agent has finished; a human decides whether it is done | **the human review queue.** An agent that finishes a ticket writes this and stops |
+| **Resolved** | accepted by a human | **only a human sets this.** No agent moves a ticket here, ever |
+| **Cancelled** | an archive for abandoned work, which must not take up an agent's context | **excluded from every agent-facing read** — `listTickets()` drops it unless asked |
+
+Adopted 2026-09-22. Until then the last column was **Done**, which conflated *an agent finished it*
+with *a human accepted it*. Work waiting on a person had nowhere to sit, and nothing on the board
+could say **this one needs you** — which is the entire point of the change.
+
+**Never write `To Do` or `Done` again.** Both still *read*, as `Ready for agent` and `Resolved`,
+so nothing written before 2026-09-22 fails to parse; `updateTicket` rewrites the line on the next write
+of that ticket, so the aliases drain themselves rather than living on disk forever. The detail
+panel says so on any ticket where the card and the file still disagree.
+
+Ask the status a question rather than comparing it to a string — every one of these handles the
+aliases, and a bare `=== "Ready for agent"` does not:
+
+```js
+import { isAgentReady, isOpen, isCancelled, normaliseStatus } from "@orbytes/astrolab";
+
+isAgentReady("To Do");   // true  — legacy alias for Ready for agent
+isOpen("Done");          // false — legacy alias for Resolved
+isCancelled(t.status);   // the archive test
+```
+
+`isOpen()` is *not `Resolved` and not `Cancelled`* — one definition, shared by this board's chips
+and the in-page panel's Open tab, so the two cannot disagree by one ticket. `Cancelled` appears in
+neither tab: it is reachable on `/pin` only.
+
+## The board at `/pin`
+
+Six columns in the order above, read fresh from `backlog/tasks/` on every request. No build step,
+no regeneration; a refresh is the reload.
+
+- **Ready for review is drawn to be seen**, because it is the human review queue and the whole
+  reason the model changed — violet rule, violet dot, *waiting on you* under the name, a tinted panel
+  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.
+- 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
+  selector-health banner when the ticket needs a human. Click it for the full comment, the shot at
+  full width, and every field.
+- **Drag a card to another column** to change its status. Priority changes in the detail panel;
+  so does status, which is the keyboard and touch path to the same write.
+- **Search** matches the title, the comment, the source file, the page, the selector and the
+  labels at once. The status chips and *Needs a human* filter alongside it, and `/` focuses the box.
+- Neutral tool chrome, deliberately sharing nothing with the site being built (decided
+  2026-09-22).
+
+`orbytes-pin-gallery` still writes `backlog/gallery.html`, the standalone snapshot for opening with
+no dev server running (`--backlog-dir` when the site moved its board — it took the default and
+printed `0 ticket(s)` until 2026-09-22). It renders from the same module and is **read-only** — the
+board is writable exactly when `renderBoard` is given an endpoint, and a `file://` page has nothing
+listening behind it.
+
+**The board's corner links** are an option (`links`), not the hardcoded `/` and `/lab` they were
+until 2026-09-22. Through `orbytesLab()` they are filled in from the lab's own resolved `subpath`,
+so the "Lab" link is derived from the value the routes are injected at rather than agreeing with it
+by luck.
+
+## The write path
+
+One endpoint, `POST <route>/api/ticket`, registered in `astro:server:setup` — which does not exist
+in a build, so it cannot reach `dist/`.
+
+**`route` shadows a host page at the same path.** The board and this endpoint are middleware,
+installed ahead of Astro's own request handler, so a site with its own `src/pages/pin.astro` gets
+the board instead of its page — in dev only, and with nothing on screen to explain it. The default
+stays `/pin`: it is the address every document here names. A site that owns
+that path sets `pin: { route: "/__pin" }`.
+
+```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
+`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
+file plus a rename, so a reader never sees half a ticket.
+
+**Measured on the real ticket, 2026-09-22, and the numbers name the command that produced them.**
+`pin-001` was dragged with a real mouse from `Ready for agent` into `Ready for review` and back on
+a live `/pin`. Its body — everything from the closing `---` on — stayed at **685 bytes, sha256
+`92270bdc2a4c…`**, before the first drag, between the two, and after the second; `parseTicket`
+returned all nine pin fields unchanged each time; the whole-file diff of a single drag was **one
+line**, and after the round trip `diff` had nothing to say about the file at all.
+
+```sh
+# the probe: byte length and sha256 of the slice from the closing `---` onward
+node -e 'const {createHash}=require("node:crypto"),t=require("node:fs").readFileSync(f,"utf8"), \
+  b=t.slice(t.indexOf("\n---",4)); console.log(Buffer.byteLength(b), createHash("sha256").update(b).digest("hex"))'
+```
+
+**The control.** A green check that cannot go red measures nothing, so the same probe was run over
+the same ticket against a naive round-trip writer — `js-yaml` load, set the field, `dump` — which
+is exactly what backlog.md did and exactly what `updateTicket` refuses to do. It turned the check
+red: the body went **685 → 686 bytes** with a different hash, and the frontmatter's
+`labels: [pin, sample, hero]` was rewritten as a three-line block sequence on the way past.
+
+Every refusal is a refusal, never a warning, and answers with a sentence the board puts on screen:
+
+| Refused | Why |
+|---|---|
+| a status or priority off the allowlist | a closed set is what lets the value be written bare, with no YAML emitter. A legacy `To Do` / `Done` is normalised first, not refused |
+| an id that names no readable ticket | the ticket is found by id through `collectTickets`, so no caller path ever reaches disk |
+| a missing key, or one held as a YAML block scalar | a single-line replace would orphan its continuation lines |
+| an `expect` that disagrees with disk | the board was stale; refusing beats one drop overwriting another |
+| the file changing between the read and the rename | compare-and-swap |
+| a non-POST, a cross-origin POST, a non-JSON body, a body over 16 KB | before a byte of the body is parsed |
+
+## Wiring
+
+Nothing is wired separately: the board comes with the lab, through the one integration the site
+already configures.
+
+```js
+import orbytesLab from "./packages/astro-lab/index.mjs";
+
+const includeLab =
+  process.argv.includes("dev") || process.env.PUBLIC_DEPLOY_ENV === "staging";
+
+export default defineConfig({
+  integrations: [
+    includeLab ? orbytesLab({ css: ["./src/styles/global.css"] }) : null,
+  ],
+});
+```
+
+`pin: false` omits the board and leaves the lab; `pin: { … }` is the option table below. The board
+gates itself on `command === "dev"`, so including the lab in a staging build registers it and it
+does nothing there.
+
+`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,
+or pass `pin: { shots: false }` and never load it.
+
+## Options
+
+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`. |
+| `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. |
+| `project` | the checkout's folder name | The folder under `archiveDir` this project's screenshots live in. Two clones of **different** repos under one folder name share an archive silently, one overwriting the other's `pin-007.png` — set it where that is possible. |
+| `shots` | `true` | `false` writes tickets and takes no screenshots. |
+| `route` | `"/pin"` | Where the board is served. `<route>/assets/*` serves its screenshots, `<route>/api/ticket` is the write endpoint. **It shadows a host page at that path** — see *The write path*. Trailing slashes are stripped. The toolbar app reads the resolved value too (it fetches the ticket list from it and its **Board ↗** button opens it), through the virtual module below — until 2026-09-22 it carried a literal `/pin`, so setting this left the panel fetching a path nothing serves. |
+| `links` | the lab's resolved subpath | The board's corner links, `[{ href, label }]`. `[]` draws none. |
+| `appId` / `appName` / `icon` | `"orbytes-pin"` / `"Pin"` / `"bug"` | The dev-toolbar app's identity. |
+
+## What a ticket looks like
+
+`<repo>/backlog/tasks/pin-<NNN>-<slug>.md`. `<NNN>` is max+1 of the numbers already on disk,
+zero-padded to 3; `<slug>` is the title lowercased, non-alphanumerics collapsed to `-`, cut to 40.
+
+```markdown
+---
+id: PIN-001
+title: Hero headline sits too low against the image
+status: Ready for agent
+assignee: []
+created_date: '2026-09-21'
+labels: [pin, hero]
+dependencies: []
+priority: medium
+---
+
+## Description
+
+The comment, verbatim, unedited.
+
+![](/assets/pin-001.png)
+
+```yaml pin
+dispatch: queue
+source: site/src/lab/sections/Section01Hero/V1/HeroSection.astro
+selector: 'section.hero > div > h1'
+selector_matches: 1
+url: /
+viewport: { width: 1440, height: 960, dpr: 2 }
+scroll: { x: 0, y: 2840 }
+rect: { x: 120, y: 340, width: 800, height: 96 }
+shot: backlog/assets/pin-001.png
+outer_html: '<h1 class="hero__title">Clarity, not more noise</h1>'
+```
+```
+
+**Why the pin data is in the body and not in frontmatter.** Any write through backlog.md — the
+CLI, or dragging a card in its web UI — re-serialises frontmatter to its own schema and silently
+drops every key it does not know. Measured 2026-09-21: `backlog task edit 1 -s Done` on a
+frontmatter-shaped ticket erased `dispatch`, `source`, `selector`, `rect`, `shot` and
+`outer_html`, so the first time a card was moved the ticket stopped being actionable. The body
+and its image survive that write untouched.
+
+backlog.md is retired now and `updateTicket` is careful, so the format is no longer defending
+against a live threat — **but do not flatten it back into frontmatter.** It costs nothing to keep,
+the tickets on disk are already in this shape, and it is what makes a careless future writer (a
+hand edit, a script, backlog.md itself if anyone runs it again) survivable rather than fatal.
+The heading stays `## Description` for the same reason it was chosen: it is what backlog.md
+rendered, every ticket on disk uses it, and `parseTicket` refuses any other.
+
+Read a ticket with the reader, never by hand-parsing frontmatter:
+
+```js
+import { isAgentReady, listTickets } from "@orbytes/astrolab/pin/tickets";
+
+// Live tickets only — `Cancelled` is not in this list, by default and on purpose.
+for (const t of listTickets(repoRoot)) console.log(t.id, t.status, t.pin.source, t.pin.rect);
+
+// What an agent picking up work actually asks. `status` is raw, so never compare it to a literal.
+const mine = listTickets(repoRoot).filter((t) => isAgentReady(t.status));
+
+// The archive, when you explicitly want it.
+listTickets(repoRoot, { includeCancelled: true });
+```
+
+`status`, `title`, `labels` and `priority` come from frontmatter — in either the inline or the
+block-sequence shape a previous backlog.md write may have left them in — and every `pin.*` field
+comes from the fenced block. A ticket whose fence is missing or unparseable is a hard error naming
+the file, never a half-filled object.
+
+**`status` comes back raw**, exactly as the file says it, which on a ticket written before
+2026-09-22 is `To Do` or `Done`. The reader stays honest so that something can still tell you what
+the file actually holds; every *question* about a status normalises first. The board does this
+once, in `collectTickets`, and shows the raw value in the detail panel when the two differ.
+
+## `selector_matches` — whether the selector survives a reload
+
+The picking page cannot tell you whether a selector still works, because it *is* the load the
+selector was written against. `cssPathOf` verifies uniqueness before it sends, so every selector
+looks healthy at pick time — including the ones that are already dead.
+
+Measured 2026-09-21 on `Home05FounderIntro`: Swiper mints `id="swiper-wrapper-<random hex>"` when
+it initialises and a **different** one on every load, so a pin inside the carousel wrote
+`#swiper-wrapper-2a2469caeb1c8a14 > … > blockquote` — **1 node when written, 0 on each of the two
+next loads**, with the wrapper coming back as `…54d9ec0d44549cd5` then `…78419b56f1752d81`. The
+ticket's source file, screenshot and `outer_html` were all correct, so nothing looked wrong.
+
+Two rules now keep a selector off that ground, both in
+[`src/pin/toolbar.js`](../src/pin/toolbar.js):
+
+- **An id anchors a selector only if a human plausibly typed it** (`isTrustworthyId`) — an
+  allowlist of authored shapes (words, separators, small counters), not a blocklist of one
+  library's garbage. An untrustworthy id is skipped and the walk keeps climbing.
+- **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
+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` |
+| `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.
+
+## 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.
+
+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
+with no screenshot yet is valid.
+
+The PNG is written to `~/.orbytes/feedback-archive/<project>/pin-<NNN>.png` and **hardlinked** to
+`<repo>/backlog/assets/pin-<NNN>.png` — the same bytes under two names, zero extra storage. If the
+link fails because the two live on different filesystems it falls back to a copy and says so in
+the dev log. A failed shot leaves no file behind under either name, so a stale PNG can never read
+as a success.
+
+The capture settings are not defaults — each was worked out against a real site, and each is there
+because its absence produced a wrong picture: freeze motion both ways, settle every lazy image
+before the shutter, hide the dev toolbar, delete the destination first.
+
+## The source attribute
+
+Astro 7 emits no `data-astro-source-file`, so this package injects `data-orbytes-src` at section
+granularity: a dev-only Vite `load` hook adds it to the first top-level element of every `.astro`
+file under `stamp`, and the picker walks up from the clicked node to the nearest ancestor carrying
+it. No ancestor found → `source` is `unresolved`, and the CSS selector plus `outer_html` still
+make the ticket actionable.
+
+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.
+
+**A matched file with no element to stamp is a hard failure**, not a warning — it throws, naming
+the repo-relative path. Two templates reach that throw: one with no tag at all, and one whose
+first top-level tag is a *component* (`<HeroSection />`), because Astro passes an attribute on a
+component as a prop and a component that does not spread its props drops it silently. Because the
+hook is lazy, the throw lands only when that one file is actually requested, not at server start.
+Clear it by wrapping the template in an element, or name the file in `stampSkip`.
+
+The case that reaches it in practice is a superseded shim: a file whose whole template is a single
+component tag (`<HeroSection />`), whose rendered DOM already carries that component's own stamp.
+Exempt it by naming it, **site-relative** — the same base as `stamp` beside it:
+
+```js
+orbytesLab({
+  pin: {
+    stampSkip: ["src/lab/sections/HeroShim/V1/HeroShim.astro"],
+  },
+})
+```
+
+## The browser ↔ server channel
+
+Astro's dev toolbar, over the existing Vite HMR socket. No HTTP endpoint, no port, no CORS.
+
+| 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 }` |
+
+On failure the reply is `{ id: null, file: null, shot: null, error: "why, in one plain sentence" }`.
+
+**Options reach the toolbar app a different way**, because Astro instantiates a dev-toolbar app
+entrypoint with `(canvas, app, server)` and no options at all. The integration registers a
+`apply: "serve"` Vite plugin that generates `virtual:orbytes-pin/config.mjs`, and
+[`src/pin/toolbar.js`](../src/pin/toolbar.js) imports it — the same pattern the lab uses for
+`virtual:orbytes-lab/config.mjs`. It carries `route` today. Nothing else about the app is
+configurable from a site, and anything that becomes so goes through this module rather than a
+second mechanism.
+
+## What the panel tells you
+
+One status line, `#pin-status`, not a log — decided 2026-09-22. A failure (a refused ticket,
+a screenshot that did not happen, a selector that dies on reload) shows and **stays** until it is
+clicked away or replaced; an acknowledgement, including *"PIN-00n written to …"*, clears itself.
+The running commentary the panel used to keep was deleted, not hidden: the mode badge, the hint
+line and the target box already said all of it. Reasons, and the rule for adding a line back, are in
+[the contract](./PIN-CONTRACT.md) › *The status line*.
+
+The panel's head carries two controls that are easy to confuse. **Tickets** toggles the in-page rail
+over the page you are on. **Board ↗** opens the full kanban at `route` in its own tab — a named
+window, so clicking it again focuses that tab instead of opening another.
+
+## Dev only, asserted four times
+
+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
+   registered.
+3. `astro:server:setup`, where every write lives — the ticket writer, the board and the
+   `/pin/api/ticket` endpoint — does not run in a build at all.
+4. That hook returns early anyway when `astro:config:setup` stood down, so a host that runs the
+   hooks in an order this package did not choose still gets nothing.
+
+The first one matters more since the merge than it did before: the lab is deliberately included in
+**staging** builds, and `orbytesLab()` returns this integration beside it — so it is now registered
+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.
+
+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.