@orbytes/astrolab 0.3.0 → 0.4.0-next.2

package/src/pin/index.mjs

@@ -6,18 +6,19 @@
 // ONE integration and gets both:
 //
 //   import orbytesLab from "@orbytes/astrolab";
-//   integrations: [ includeLab ? orbytesLab({ css: [...] }) : null ]   // /lab and /pin
+//   integrations: [ includeLab ? orbytesLab({ css: [...] }) : null ]   // /lab and /lab/tasks
 //   integrations: [ includeLab ? orbytesLab({ pin: false }) : null ]   // /lab alone
 //
 // `orbytesLab()` returns an array Astro flattens, and this integration is one of its entries — see
 // ../../index.mjs, which also hands it the lab's RESOLVED subpath so the board's "Lab" link points
-// at wherever the lab actually is. Calling this module directly still works and is what the tests
-// do; nothing about it assumes the lab is present.
+// at wherever the lab actually is. Calling this module directly still works — it is exported as
+// `orbytesPin` from the package root and at `@orbytes/astrolab/pin` — and nothing about it assumes
+// the lab is present.
 //
 // No cloud, no API key, no MCP, no second process — ../../docs/PIN-CONTRACT.md. It replaces the
 // hosted-widget → issue-tracker feedback chain for a solo build pass, and only for that.
 //
-// Three jobs:
+// Four jobs:
 //   1. stamp `data-orbytes-src="<repo-relative path>"` on the first top-level element of every
 //      `.astro` file under the configured directories, so the picker can name the file an element
 //      came from (./source-stamp.mjs — Astro 7 emits no source attribute of its own).
@@ -28,19 +29,28 @@
 //   4. serve the KANBAN at `<route>` — every ticket in `backlog/tasks`, read fresh on each
 //      request — its screenshots at `<route>/assets/*`, and the one write endpoint at
 //      `<route>/api/ticket`, all from the dev server you are already on (./board.mjs, which
-//      `orbytes-pin-gallery` renders the standalone file with too).
+//      `orbytes-pin-gallery` renders the standalone file with too). Inside the lab the kanban
+//      itself is not this middleware's: it is ../chrome/views/Tasks.astro, injected at
+//      `<route>` and `<route>/all`, and the middleware keeps the screenshots and the endpoint.
 //
-// `route` DEFAULTS TO `/pin` AND SHADOWS ANY HOST PAGE AT THAT PATH. This middleware is installed
-// before Astro's own request handler, so a site with its own `src/pages/pin.astro` would serve the
-// board instead of its page, in dev only, with nothing on screen to say why. The default stays —
-// `/pin` is the chosen address and the one every doc names — and the collision is a
-// one-liner to avoid: `pin: { route: "/__pin" }`. Said here, in ../../docs/PIN.md and in
-// ../../README.md, because a silent shadow is only findable if somebody wrote it down.
+// WHERE `<route>` IS, AND WHAT IT SHADOWS. On its own this integration defaults `route` to `/pin`
+// and draws the board there as middleware. Through `orbytesLab()` it is `<subpath>/tasks`
+// (`/lab/tasks` by default), and the middleware answers `/pin` — the board's address until
+// 2026-09-24 — with a 302 to it, unless `route` is itself `/pin`. The middleware is installed
+// before Astro's own request handler, so a site with its own `src/pages/pin.astro` gets the board
+// (alone) or the redirect (in the lab) instead of its page, in dev only, with nothing on screen to
+// say why. On its own the collision is a one-liner to avoid: `pin: { route: "/__pin" }`. Inside
+// the lab that is not enough: the redirect fires for every `route` except `/pin`, and a `route` of
+// `/pin` injects the Tasks views there instead, so only `pin: false` frees the path. Said here, in
+// ../../docs/PIN.md and in ../../README.md, because a silent shadow is only findable if somebody
+// wrote it down.
 //
-// The board is MIDDLEWARE, not an injected route, and the choice is deliberate. The lab injects its
+// On its own the board is MIDDLEWARE, not an injected route, and the choice is deliberate. (Inside
+// the lab it is an injected route after all — the Tasks views, injected in `astro:config:setup`
+// past the dev-only assertion, so they are no more able to reach a build.) The lab injects its
 // pages because they are prerendered; this one is generated per request from files outside the
 // site, so it belongs with the lab's other half — the mark APIs it serves from `astro:server:setup`.
-// That hook does not exist in a build, so `/pin` cannot leak into `dist/` even by accident, and
+// That hook does not exist in a build, so `<route>` cannot leak into `dist/` even by accident, and
 // nothing has to be marked `prerender: false` in a project with `output: "static"` and no adapter.
 // ── backlog.md is retired (2026-09-22) ──────────────────────────────────────────────────────────
 // Until today `<route>` was read-only and pointed at backlog.md's own web UI — a second server on
@@ -188,7 +198,8 @@ const DEFAULTS = {
   /** Site-relative directories whose `.astro` files get the source stamp. */
   stamp: ["src/lab/sections", "src/components"],
   /**
-   * Repo-relative `.astro` paths exempt from the stamp's hard failure. A file whose template has
+   * Site-relative `.astro` paths exempt from the stamp's hard failure (a repo-relative path is
+   * accepted too — ./source-stamp.mjs resolves each entry both ways). A file whose template has
    * no element to stamp throws by design; this is the only way past it, and it is a deliberate,
    * named decision per file rather than a warning that lets every such file through silently.
    */
@@ -216,10 +227,12 @@ const DEFAULTS = {
   shots: true,
   /**
    * Where the board is served, dev only. `<route>/assets/*` serves its screenshots and
-   * `<route>/api/ticket` is the one write endpoint.
+   * `<route>/api/ticket` is the one write endpoint. `orbytesLab()` sets it to `<subpath>/tasks`;
+   * `/pin` is the default only when this integration is used on its own.
    *
    * It is MIDDLEWARE and it shadows a host page at the same path (see the note at the top of this
-   * file). A site with its own `/pin` page sets something else here.
+   * file). Used on its own, a site with its own `/pin` page sets something else here; inside the
+   * lab no value frees `/pin` (see the note at the top of this file).
    */
   route: "/pin",
   /**
@@ -232,6 +245,14 @@ const DEFAULTS = {
   appId: "orbytes-pin",
   appName: "Pin",
   icon: "bug",
+  /**
+   * Set by `orbytesLab()` (../../index.mjs), never by a consumer: `{ shared }`, the object the two
+   * halves talk through. When present, the board is drawn IN THE LAB'S CHROME at `<route>` and
+   * `<route>/all` (../chrome/views/Tasks.astro, injected here, dev only) instead of as this
+   * middleware's standalone page, and `/pin` — the board's address until 2026-09-24 — redirects
+   * there. Absent, the pin half behaves exactly as it did on its own.
+   */
+  lab: null,
 };
 
 /** The dev server's own origin, read from Vite. Never hardcode 4321 — Astro picks a free port. */
@@ -257,7 +278,7 @@ export default function orbytesPin(options = {}) {
   return {
     name: "orbytes-pin",
     hooks: {
-      "astro:config:setup": ({ config: astroConfig, command, updateConfig, addDevToolbarApp, logger }) => {
+      "astro:config:setup": ({ config: astroConfig, command, updateConfig, addDevToolbarApp, injectRoute, logger }) => {
         // Assertion one. In `build`, `preview` or `sync` this integration registers nothing at
         // all — no plugin, no toolbar app, no stamp.
         if (command !== "dev") {
@@ -288,6 +309,21 @@ export default function orbytesPin(options = {}) {
         }
         project = String(config.project ?? projectName(repoRoot));
 
+        // Inside the lab: the Tasks views are Astro pages in the lab's chrome, injected HERE — past
+        // assertion one, so they exist in `astro dev` and in no build — and the lab is told where
+        // they are through the shared object, which is how its Tasks group knows to appear.
+        if (config.lab && config.lab.shared) {
+          const route = boardRoute(config.route);
+          injectRoute({ pattern: `${route}/[...view]`, entrypoint: file("../chrome/views/Tasks.astro"), prerender: true });
+          config.lab.shared.tasks = {
+            base: route,
+            api: `${route}/api/ticket`,
+            assets: `${route}/assets/`,
+            repoRoot,
+            backlogDir: config.backlogDir,
+          };
+        }
+
         addDevToolbarApp({
           id: config.appId,
           name: config.appName,
@@ -402,7 +438,7 @@ export default function orbytesPin(options = {}) {
         // The wall, and its screenshots. Registered here rather than as an injected route (see the
         // note at the top of this file), which also puts it ahead of Astro's own request handler:
         // Astro installs that in a Vite post hook, after every integration's middleware is in
-        // place, so `/pin` reaches this and never reaches Astro's 404.
+        // place, so every path this answers reaches it and never reaches Astro's 404.
         server.middlewares.use((req, res, next) => {
           let url;
           try {
@@ -411,7 +447,15 @@ export default function orbytesPin(options = {}) {
             return next();
           }
           const path = url.pathname;
-          const wall = path === route || path === `${route}/`;
+          // The board's old address, kept as a redirect for bookmarks and muscle memory.
+          if (config.lab && route !== "/pin" && (path === "/pin" || path === "/pin/")) {
+            res.statusCode = 302;
+            res.setHeader("Location", route + url.search);
+            return res.end();
+          }
+          // Inside the lab the board itself is an Astro page (injected above), so the wall is not
+          // this middleware's to draw — only its screenshots and its one write endpoint are.
+          const wall = !config.lab && (path === route || path === `${route}/`);
           const api = path === apiPath;
           if (!wall && !api && !path.startsWith(assetPrefix)) return next();
 
@@ -513,9 +557,10 @@ export default function orbytesPin(options = {}) {
             // Read from disk on every request — that is the whole point of the route, and why
             // `orbytes-pin-gallery` is no longer part of looking at the board.
             try {
-              // `includeCancelled`: `/pin` is the ONE surface where the archive is visible. Every
-              // agent-facing read drops cancelled tickets by default — a cancelled ticket must not
-              // take up context space for an agent — and an archive nobody can open is a delete.
+              // `includeCancelled`: the human-facing surfaces — this wall, the lab's Tasks views and
+              // the gallery file — are where the archive is visible. Every agent-facing read drops
+              // cancelled tickets by default — a cancelled ticket must not take up context space for
+              // an agent — and an archive nobody can open is a delete.
               const { tickets, broken } = collectTickets(repoRoot, { backlogDir: config.backlogDir, includeCancelled: true });
               const html = renderBoard(tickets, broken, {
                 // The presence of an endpoint is what makes the page writable. The standalone

package/src/pin/tickets.mjs

@@ -120,8 +120,9 @@ export function isOpen(status) {
  * Is this ticket archived — cancelled, and therefore invisible to every agent-facing read?
  *
  * Ruled 2026-09-22: items in here must not override anything or take up context space for an
- * agent. `listTickets` drops these unless explicitly asked for them; `/pin` is the one place
- * they are still visible, because an archive nobody can open is a delete.
+ * agent. `listTickets` drops these unless explicitly asked for them. The human-facing surfaces
+ * still show them — the lab's Tasks views, the pin half's standalone board and
+ * `orbytes-pin-gallery` — because an archive nobody can open is a delete.
  *
  * @param {unknown} status
  */
@@ -672,9 +673,9 @@ export function parseTicket(text, file = "<unknown file>") {
  * that never heard of the rule still cannot be handed a dead ticket, and one that wants the
  * archive has to say so in the call.
  *
- * `includeCancelled: true` returns them, and the only callers that pass it are the two surfaces
- * that draw the archive — `/pin` and `orbytes-pin-gallery` — plus `updateTicket`, which has to be able to
- * find a cancelled ticket in order to move it back out.
+ * `includeCancelled: true` returns them. Nothing in this package passes it here: the surfaces that
+ * draw the archive and `updateTicket`, which has to be able to find a cancelled ticket in order to
+ * move it back out, pass it to `collectTickets` (./board.mjs) instead.
  *
  * Statuses come back RAW (› `parseTicket`), so the filter normalises before it compares: a ticket
  * whose file still says `Done` is `Resolved`, and is live.

package/src/pin/toolbar.js

@@ -698,7 +698,7 @@ const BOARD_ROUTE = (pinConfig && pinConfig.route) || '/pin';
  * The panel has exactly TWO tabs, which is fixed and not a preference, so the six map onto them:
  * **Open is everything that is not `Resolved` and not `Cancelled`**, `Resolved` is its own tab, and
  * `Cancelled` appears in neither and draws no marker — drawing an archived ticket on the page is
- * precisely the "taking up space" the status exists to stop. It stays reachable on `/pin`.
+ * precisely the "taking up space" the status exists to stop. It stays reachable on the board.
  *
  * These names are for CLASSIFYING and LABELLING only. Every write sends the status string the
  * board itself reported (› `setStatus`), never a string from this list, because `expect` is
@@ -860,6 +860,10 @@ export default defineToolbarApp({
 		}
 
 		let mode = 'idle'; // idle | picking | selected
+		/** Whether Astro has this app toggled on — the lab's Comment button shows it as pressed. */
+		let appActive = false;
+		/** Set by the lab's Comment: the element whose box confines the pick (› the lab channel). */
+		let scope = null;
 		let hoverEl = null;
 		let selectedEl = null;
 		/**
@@ -1633,6 +1637,7 @@ export default defineToolbarApp({
 				syncMarkers();
 				// The count on the toolbar button is read from the same list, so it moves with it.
 				updateTicketsButton();
+				publish();
 			}
 		}
 
@@ -2280,6 +2285,7 @@ export default defineToolbarApp({
 
 			if (next === 'picking') {
 				if (!surface.isConnected) canvas.append(surface);
+				fitSurface();
 				hideChrome(hoverHighlight);
 				// The picker owns clicks while it is armed — a marker must not swallow one that
 				// was meant to pin the element underneath it.
@@ -2300,6 +2306,18 @@ export default defineToolbarApp({
 				clearCrumbs();
 				hideChrome(selectedHighlight);
 			}
+			publish();
+		}
+
+		/** The surface covers the page — or only the scope's box, when the lab's Comment set one. */
+		function fitSurface() {
+			const r = scope && scope.isConnected ? scope.getBoundingClientRect() : null;
+			Object.assign(
+				surface.style,
+				r
+					? { left: `${r.left}px`, top: `${r.top}px`, width: `${r.width}px`, height: `${r.height}px`, right: 'auto', bottom: 'auto' }
+					: { left: '0', top: '0', right: '0', bottom: '0', width: '', height: '' },
+			);
 		}
 
 		function hideChrome(el) {
@@ -2362,6 +2380,7 @@ export default defineToolbarApp({
 		}
 
 		function reposition() {
+			if (mode === 'picking') fitSurface();
 			if (mode === 'picking' && hoverEl) {
 				place(hoverHighlight, hoverEl, hoverFrames);
 				const { source } = resolveSource(hoverEl);
@@ -2424,6 +2443,10 @@ export default defineToolbarApp({
 		 * @returns {{ el: Element|null, frames: Element[], note: string|null }}
 		 */
 		function hitTest(x, y) {
+			if (scope) {
+				const r = scope.getBoundingClientRect();
+				if (x < r.left || x > r.right || y < r.top || y > r.bottom) return { el: null, frames: [], note: null };
+			}
 			let doc = document;
 			let px = x;
 			let py = y;
@@ -2439,7 +2462,8 @@ export default defineToolbarApp({
 				}
 
 				const frame = frameUnder(el, px, py);
-				if (!frame) return { el, frames: frames.slice(), note: null };
+				// A scoped pick (the lab's Comment) pins what is IN the frame, never the lab around it.
+				if (!frame) return scope && !frames.length ? { el: null, frames: [], note: null } : { el, frames: frames.slice(), note: null };
 
 				const inner = frameDocument(frame);
 				if (!inner) {
@@ -2881,6 +2905,19 @@ export default defineToolbarApp({
 		// box constantly — and a dictated paragraph cannot be retyped from memory. So Escape
 		// never discards text: with anything in the box it holds the selection, the words and
 		// the caret, and points at Cancel, which is the one control that discards on purpose.
+		//
+		// Inside the lab, Escape ends Comment mode rather than stopping at idle. Decided
+		// 2026-09-24: the lab's Comment is one mode — pick, write, send — so wherever Escape would
+		// leave this app on and idle ("Nothing selected", with Comment still pressed), it turns the
+		// app off instead, exactly as pressing Comment again does. Only a pick the lab started has a
+		// `scope`; the toolbar's own button keeps the steps above. The branch that holds a comment
+		// still runs first, and turning the app off never empties the box, so a word typed here
+		// survives every Escape.
+		function leaveOrIdle() {
+			if (scope) app.toggleState({ state: false });
+			else setMode('idle');
+		}
+
 		function onKeydown(event) {
 			// The climb. Capture phase and preventDefault, because ⌥↑ in a textarea is
 			// "move the caret to the start of the paragraph" on macOS and would otherwise
@@ -2904,7 +2941,8 @@ export default defineToolbarApp({
 				swallowEscapeKeyup = true;
 				// The badge and the hint line both change on setMode — saying it again in words
 				// was the log talking to itself.
-				setMode(selectedEl ? 'selected' : 'idle');
+				if (selectedEl) setMode('selected');
+				else leaveOrIdle();
 			} else if (mode === 'selected') {
 				event.preventDefault();
 				event.stopPropagation();
@@ -2915,7 +2953,7 @@ export default defineToolbarApp({
 					return;
 				}
 				clearSelection();
-				setMode('idle');
+				leaveOrIdle();
 			} else if (panelOpen) {
 				// Idle, with the panel open. Escape peels one layer at a time — the expanded entry,
 				// then the panel — and only once both are shut does it reach Astro's own
@@ -2936,6 +2974,13 @@ export default defineToolbarApp({
 				} else {
 					closePanel();
 				}
+			} else if (scope && appActive) {
+				// Idle in the lab, with nothing left to peel: close the app here rather than hope
+				// Astro's own Escape handler is armed, which it is only after a real hover.
+				event.preventDefault();
+				event.stopPropagation();
+				swallowEscapeKeyup = true;
+				leaveOrIdle();
 			}
 		}
 
@@ -2951,6 +2996,8 @@ export default defineToolbarApp({
 		/* ---------- lifecycle ---------- */
 
 		app.onToggled(({ state }) => {
+			appActive = Boolean(state);
+			if (!state) scope = null;
 			if (state) {
 				setMode(selectedEl ? 'selected' : 'picking');
 				// Astro hides an app's whole canvas when the app is toggled off, so the markers go
@@ -3129,6 +3176,37 @@ export default defineToolbarApp({
 			}
 		});
 
+		/* ---------- the lab's channel ---------- */
+
+		/**
+		 * The component lab drives this app from its own navbar — the Comment button, and the pins
+		 * it draws over its framed preview — and imports nothing from this file, so the door in and
+		 * the window out are plain window events:
+		 *
+		 *   in   `orbytes-pin:command`  { action: 'pick', within?: Element } | { action: 'stop' }
+		 *   out  `orbytes-pin:state`    { active, mode, tickets } after every mode change, toggle and
+		 *        board read; the same snapshot sits on `window.__orbytesPin` for a late listener.
+		 *
+		 * `within` confines the pick to that element's box, and to what lies inside a frame there,
+		 * so Comment pins the previewed page and never the lab's chrome around it. The toolbar's own
+		 * button still opens the app unscoped, exactly as before.
+		 */
+		function publish() {
+			const detail = { active: appActive, mode, tickets: panelTickets };
+			window.__orbytesPin = detail;
+			window.dispatchEvent(new CustomEvent('orbytes-pin:state', { detail }));
+		}
+		window.addEventListener('orbytes-pin:command', (event) => {
+			const { action, within } = (event && event.detail) || {};
+			if (action === 'pick') {
+				scope = within instanceof Element ? within : null;
+				if (appActive) setMode(selectedEl ? 'selected' : 'picking');
+				else app.toggleState({ state: true });
+			} else if (action === 'stop') {
+				app.toggleState({ state: false });
+			}
+		});
+
 		setMode('idle');
 		restoreAfterReload();
 		// Read the board once at start-up so the markers are on the page the moment the app is