@orbytes/astrolab 0.3.0

package/dist/core/virtual-module/vite-plugin.js

@@ -0,0 +1,98 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadStoryModules } from "./story-modules.js";
+import {
+  COMPONENT_HEAD_ID,
+  COMPONENT_HEAD_RESOLVED_ID,
+  COMPONENT_HOME_ID,
+  COMPONENT_HOME_RESOLVED_ID,
+  STORY_MODULES_ID,
+  STORY_MODULES_RESOLVED_ID,
+  GLOBAL_CONFIG_ID,
+  GLOBAL_CONFIG_RESOLVED_ID,
+  USER_CSS_RESOLVED_ID,
+  USER_CSS_ID
+} from "./virtual-module-ids.js";
+function createVirtualFilesPlugin(rootDir, config, astroConfig, logger) {
+  const root = astroConfig.root;
+  function resolveId(id, base = root) {
+    return JSON.stringify(
+      id.startsWith(".") ? resolve(fileURLToPath(base), id) : id
+    );
+  }
+  let storyModules;
+  let needToReload = false;
+  let watcherInitialized = false;
+  async function getStoryModules() {
+    const newStoryModules = await loadStoryModules(rootDir);
+    if (storyModules && newStoryModules !== storyModules) {
+      needToReload = true;
+    }
+    storyModules = newStoryModules;
+    return storyModules;
+  }
+  async function restartServerIfNeeded(server) {
+    await getStoryModules();
+    if (needToReload) {
+      needToReload = false;
+      logger.info(`Restarting`);
+      await server.restart();
+    }
+  }
+  function initializeNewFileWatcher(server) {
+    if (watcherInitialized || !server.watcher) return;
+    watcherInitialized = true;
+    server.watcher.on("add", async (filePath) => {
+      if (filePath.includes(".stories.")) {
+        logger.debug(`Potential story file added: ${filePath}`);
+        await restartServerIfNeeded(server);
+      }
+    });
+    server.watcher.on("unlink", async (filePath) => {
+      if (filePath.includes(".stories.")) {
+        logger.debug(`Potential story file deleted: ${filePath}`);
+        await restartServerIfNeeded(server);
+      }
+    });
+    logger.debug(`Initialized file watcher for story files`);
+  }
+  return {
+    name: "astrobook/virtual-files",
+    resolveId(id) {
+      switch (id) {
+        case STORY_MODULES_ID:
+          return STORY_MODULES_RESOLVED_ID;
+        case GLOBAL_CONFIG_ID:
+          return GLOBAL_CONFIG_RESOLVED_ID;
+        case COMPONENT_HEAD_ID:
+          return COMPONENT_HEAD_RESOLVED_ID;
+        case COMPONENT_HOME_ID:
+          return COMPONENT_HOME_RESOLVED_ID;
+        case USER_CSS_ID:
+          return USER_CSS_RESOLVED_ID;
+      }
+    },
+    load(id) {
+      switch (id) {
+        case STORY_MODULES_RESOLVED_ID:
+          return getStoryModules();
+        case GLOBAL_CONFIG_RESOLVED_ID:
+          return `const config = ${JSON.stringify(config)}; export default config;`;
+        case COMPONENT_HEAD_RESOLVED_ID:
+          return `export { default } from ${resolveId(config.head)};`;
+        case COMPONENT_HOME_RESOLVED_ID:
+          return `export { default } from ${resolveId(config.home)};`;
+        case USER_CSS_RESOLVED_ID:
+          return config.css.map((id2) => `import ${resolveId(id2)};`).join("");
+      }
+    },
+    async handleHotUpdate(ctx) {
+      const { server } = ctx;
+      initializeNewFileWatcher(server);
+      await restartServerIfNeeded(server);
+    }
+  };
+}
+export {
+  createVirtualFilesPlugin
+};

package/docs/PIN-CONTRACT.md

@@ -0,0 +1,263 @@
+# orbytes-pin — the contract
+
+The interfaces the parts of the pin board agree on. Four 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,
+and the citations were repointed with it (`../../docs/PIN-CONTRACT.md`); if you are
+moving them again, `grep -rn PIN-CONTRACT src/pin` is the list.
+
+**This describes what is, not what was planned.** Where a decision had a reason that is not obvious
+from the code, the reason is here — usually because it was learned by something breaking.
+
+## What this package is
+
+A dev-only Astro integration. You click a rendered element on `astro dev`, type a comment, and a
+markdown ticket plus a screenshot land on local disk for an agent to pick up. No cloud, no API key,
+no MCP, no second process.
+
+It serves a **solo pass** — your own review of a site in dev, before anyone else sees it. Whatever
+tool you use for review rounds with other people is untouched by it, and nothing syncs between the
+two (decided 2026-09-21). Two systems, and moving anything between them is a human's job.
+
+## Statuses
+
+Six, in board order, adopted 2026-09-22:
+
+```
+Backlog | Ready for agent | In Progress | Ready for review | Resolved | Cancelled
+```
+
+- **`Backlog`** — raised, but not ready for an agent to pick up.
+- **`Ready for agent`** — queued work; it replaces the usual *To Do*. **The only status an agent may
+  start work from.**
+- **`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.
+- **`Resolved`** — accepted by a human, and only a human sets it. The rule binds agents, not the
+  wire: the write endpoint deliberately does **not** refuse `Resolved`, because a person's own drag
+  arrives through that same path and the endpoint cannot tell a person from a script.
+- **`Cancelled`** — an archive for abandoned work, which must not take up an agent's context. So it
+  is **absent, not dimmed**: `listTickets()` and `collectTickets()` drop cancelled tickets unless
+  explicitly asked with `includeCancelled: true`.
+
+`To Do` reads as `Ready for agent` and `Done` as `Resolved`, so anything written before this
+vocabulary still parses. Neither is ever emitted, and a ticket carrying one is rewritten on its next
+write, whatever that write was for.
+
+The constants and the predicates (`isOpen`, `isCancelled`, `isAgentReady`, `OPEN_STATUSES`) live in
+[`../src/pin/tickets.mjs`](../src/pin/tickets.mjs) and are re-exported from the package root.
+Nothing should hardcode a status string.
+
+## Ticket format — `<repo>/backlog/tasks/pin-<NNN>-<slug>.md`
+
+```markdown
+---
+id: PIN-014
+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-014.png)
+
+```yaml pin
+dispatch: queue
+source: site/src/lab/sections/Section01Hero/V1/HeroSection.astro
+selector: 'section.hero > div > h1'
+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-014.png
+outer_html: '<h1 class="hero__title">Clarity, not more noise</h1>'
+selector_matches: 1
+```
+```
+
+**Why the pin data is in the body and not in frontmatter.** This format was shaped around
+backlog.md, which served as the board for one day. Any board that re-serialises frontmatter drops
+keys it does not recognise — measured twice, on real commands: a single `backlog task edit -s Done`
+deleted `dispatch`, `source`, `selector`, `rect`, `shot` and `outer_html` in one go, while the body
+survived untouched. backlog.md is retired here, but the constraint is worth keeping: the body is the
+half that survives a careless writer.
+
+**Why `## Description` and not `## Comment`.** Measured: under `## Comment`, backlog.md's detail
+view rendered neither the comment nor the screenshot.
+
+**Why titles cap at 70 characters.** js-yaml folds a scalar when its length exceeds the line width,
+which is 78 for a top-level key — measured at exactly 79 by generating 41 tickets across lengths
+55–95 and running a real status change on each. At the old 80-character cap every full-length title
+folded on its first status change and read back as `>-`.
+
+Match the fenced block on its info string, ```` ```yaml pin ````, never on position in the file. A
+ticket whose block is missing or unparseable is a hard error naming the file — never a partial
+ticket with empty fields.
+
+## Writing a ticket
+
+`updateTicket` ([`../src/pin/board.mjs`](../src/pin/board.mjs)) **never serialises.** It splits the
+file by index, so the slice from the closing
+`---` onward is the *same substring* going out as coming in, and a mangled body is not a thing the
+code can produce. It is asserted anyway, and the assertion has a negative control: a `js-yaml`
+load/dump round-trip over the same ticket turns it red — 685 → 686 bytes, different hash, and
+`labels: [pin, sample, hero]` exploded into a block sequence.
+
+Do not refactor that into a round-trip to make it tidier. Temp-file-plus-rename, compare-and-swap
+on `expect` before the rename, and refusals — never warnings — for a status off the allowlist, an id
+naming no readable ticket, or an `expect` that disagrees with disk.
+
+## Screenshots
+
+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.
+
+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.
+
+**`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
+`getBrowser()` is correct, `shots` defaults to `true`, and the one-sentence error the toolbar shows
+when the import fails names the command. The board was built in a repo where playwright was already
+a devDependency, and **the dependency did not travel with the code** when it moved here on
+2026-09-22 — so every ticket written in this repo before that day carries
+`selector_matches: pending` and no image. The answer to *"why are there no screenshots?"* is an
+uninstalled peer, not a missing feature.
+
+**The ordering above was finally exercised end to end on 2026-09-22**, which until then it never had
+been in this repo — the shot path had always failed fast, so a real two-second delay had never sat
+between the two replies. Driving the shipped toolbar with a real mouse on the testbed's home page:
+the status line showed *"PIN-004 written to … — screenshot pending"* **17.2ms** after the Create
+ticket click (stamped in the page, on the button's own click handler, so no automation latency is
+in the figure) and *"PIN-004 screenshot landed at …"* at **+1934ms**. A pin at document y=5108,
+well below the fold, produced a 1358×53 PNG — its rect to the pixel — showing the pinned heading
+and not the top of the page, and the repo copy and the archive copy shared one inode. The ordering
+holds.
+
+**`selector_matches` is counted on that fresh page**, immediately before the shutter, so the number
+and the picture describe one DOM. `1` healthy · `0` dead · `2+` ambiguous · `pending` never tested.
+A dead-selector ticket is **labelled, never discarded** — the screenshot, source file and
+`outer_html` still make it workable by hand. The defect this guards against is silence, not
+instability.
+
+## The browser ↔ server channel
+
+Over the Vite HMR socket. No HTTP endpoint for writes from the toolbar, no port, no CORS.
+
+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", …)`
+
+Server, inside `astro:server:setup({ server, toolbar })`:
+`toolbar.on("orbytes-pin:create", …)` · `toolbar.send(…)`
+
+**Ordering matters.** Write the ticket and reply on the same synchronous tick; take the screenshot
+after, and send a second event when it lands. A ticket with no screenshot yet is valid; a ticket
+someone waited two seconds for is not.
+
+The in-page panel does **not** parse tickets. It reads the JSON the board already emits per card and
+the write endpoint from the board's own markup. A second parser is how three earlier bugs here
+happened.
+
+**The toolbar app's options arrive as a virtual module**, `virtual:orbytes-pin/config.mjs`, written
+by a `apply: "serve"` Vite plugin the integration registers (`pinConfigPlugin`, `../src/pin/index.mjs`).
+Astro instantiates a dev-toolbar app entrypoint with `(canvas, app, server)` and nothing else, so
+there is no other channel; the lab solves the identical problem the identical way with
+`virtual:orbytes-lab/config.mjs`, and a second mechanism here would be a second thing to learn.
+Today it carries one key, `route`, which was a literal `'/pin'` in `toolbar.js` until 2026-09-22 — a
+site setting `pin: { route: "/__pin" }` got a panel that fetched a path the middleware does not
+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 status line — one line, not a log
+
+Decided 2026-09-22, replacing a running four-entry list that narrated every step. The log was
+redundant: a button that opens the board is the one thing it added that nothing else on the panel
+could say.
+
+- **One line replaces it**, `#pin-status`. A new message replaces the one before it. That is what
+  makes it a status line and not a shorter log.
+- **A failure has no timer.** `error` and `warn` show and stay — a refused ticket, a screenshot that
+  did not happen, a selector that dies on reload are the only things on this panel that nothing else
+  on screen can say. Click the line to dismiss it.
+- **An acknowledgement clears itself** after `ACK_MS`. The ticket-written confirmation is kept
+  because the contract makes a point of it landing on the same synchronous tick, and a confirmation
+  nobody can see is not a confirmation.
+- **Commentary was deleted at its call sites, not hidden here** — *"Sending to the dev server…"*,
+  *"Pick mode cancelled."*, *"Selection dropped."*, *"Scrolled back to the last pinned element."*
+  and the crumb's *"… comes from …"* are gone. Each described something the badge, the hint line,
+  the target box or the page itself had already shown. Do not add one back: if a new line is worth
+  saying, ask first whether the panel already shows it.
+
+**`Tickets` and `Board ↗` are two different controls.** `Tickets` toggles the in-page rail over the
+current page; `Board ↗` opens the full kanban at the resolved route in its own tab, under a named
+window so a second click focuses the tab already open rather than stacking another.
+
+## Source attribution
+
+Astro 7 does **not** emit `data-astro-source-file`, despite `compile.js` still passing
+`annotateSourceFile` and the dev toolbar's audit app still reading the attributes. Verified three
+ways, with a negative control: the legacy Go compiler's wasm on disk contains both strings; the Rust
+binding Astro 7 uses contains zero. So this package stamps its own `data-orbytes-src`, repo-relative,
+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
+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
+live document at each step. Ids anchor a selector only when they look authored — an allowlist, not a
+blocklist, because a blocklist has to predict the next library's generated garbage. Transient state
+classes are dropped by shape, not by name.
+
+## Dev only
+
+`astro:server:setup` does not exist in a build, which is what makes the write path safe. Asserted
+four times independently, and verified on real production builds — normal and staging — by grepping
+`dist/` for every marker this package emits.
+
+## Gotchas that cost real time
+
+- **`astro dev --ignore-lock` is refused in an agent environment** and the error reads as unrelated
+  to the flag. One background server per project; `astro dev status` finds it.
+- **Astro 7's dev server binds IPv6 only.** `curl 127.0.0.1:<port>` returns http_code 000 and looks
+  exactly like a crash. Use `localhost`.
+- **Restarting the dev server leaves the toolbar app 504ing until one hard page reload.** A Vite
+  re-optimize hazard, unfixed. A config touch restarts the server but Node's module cache keeps the
+  old integration — only a genuine stop and start reloads this package.
+- **A symlinked workspace package defeats Vite's `node_modules` optimizer skip**, because
+  `preserveSymlinks` is false. This 504'd the entire dev toolbar, Astro's own five apps included,
+  until `optimizeDeps.exclude` named the two offending specifiers.
+- **Testing the toolbar needs a real mouse hover to arm it.** Astro gates Escape-to-close on
+  `data-hidden` on `#dev-toolbar-root` *inside* the shadow root. A synthetic click leaves it
+  disarmed and the test cannot fail. `astro-dev-toolbar-button` elements can measure 0×0 — measure
+  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.
+
+## 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.
+
+**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
+NOT done while moving the code: a restyle and a move in one change means a visual difference nobody
+can attribute. The two namespaces cannot collide, so nothing is urgent about it.