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

package/src/chrome/views/Pages.astro

@@ -15,7 +15,9 @@ import Tree from "../Tree.astro";
 import Icon from "../Icon.astro";
 import ViewportControls from "../ViewportControls.astro";
 import ViewportStage from "../ViewportStage.astro";
-import { hrefs, type Crumb, type FilterOption } from "../model";
+import Properties from "../Properties.astro";
+import ActionsMenu from "../ActionsMenu.astro";
+import { hrefs, tasksBase, type Crumb, type FilterOption } from "../model";
 import { componentsOf } from "../trees";
 import { pagesTree, rootDir, sitePagesModel, type SitePage } from "../site-data";
 import { pinCounts } from "../pins-data";
@@ -52,86 +54,116 @@ const filters: FilterOption[] = [
 // the build writes `/about/index.html`, so the bare route resolves either way.
 const base = import.meta.env.BASE_URL.replace(/\/+$/, "");
 const src = page ? `${base}${page.route}` : "";
+
+// The listing's title bar (Figma `Lab / Listing`): title, counts, and chips that set the same
+// filter as level 2's menu.
+const facetOf = (p: SitePage) => (p.dynamic ? "dynamic" : p.mounts.length ? "mounts" : "static");
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const tally = (facet: string) => pages.filter((p) => facetOf(p) === facet).length;
+const counts = [
+  plural(pages.length, "page"),
+  tally("mounts") ? `${tally("mounts")} with components` : null,
+  tally("dynamic") ? plural(tally("dynamic"), "dynamic route") : null,
+].filter(Boolean);
+const chips = [
+  { value: "", label: "All", n: pages.length },
+  { value: "mounts", label: "Components", n: tally("mounts") },
+  { value: "static", label: "None", n: tally("static") },
+  ...(tally("dynamic") ? [{ value: "dynamic", label: "Dynamic", n: tally("dynamic") }] : []),
+];
 ---
 
 <Shell
   title={page ? page.label : "Pages"}
   active="pages"
+  navbarClass={page ? undefined : "lab-navbar--listing"}
   panel={{ label: "Pages", crumbs, filters, filterLabel: "Show pages", searchPlaceholder: "Search pages" }}
 >
   <Tree slot="panel" nodes={pagesTree(pages, page?.route)} />
 
   {
     page ? (
-      <Fragment slot="navbar">
-        <div class="lab-navbar__id">
-          <h1 class="lab-navbar__title" title={page.title ?? undefined}>
-            {page.label}
-            <small>{page.route}</small>
-          </h1>
-          <button class="lab-status-btn" type="button" popovertarget="lab-mounts-menu" title="What this page mounts">
-            <span class="lab-pill">{page.mounts.length} component{page.mounts.length === 1 ? "" : "s"}</span>
-            {pins.openFor(page.file) > 0 && <span class="lab-pill lab-pill--brand">{pins.openFor(page.file)} open pins</span>}
-            <Icon name="chevron-down" size="sm" />
-          </button>
-          <div class="lab-menu" id="lab-mounts-menu" popover role="menu">
-            <p class="lab-menu__label">On this page, in order</p>
-            {page.mounts.length === 0 && <p class="lab-status-menu__fact">It mounts no components of its own.</p>}
+      <div class="lab-nb lab-nb--page" slot="navbar" data-lab-nb>
+        <div class="lab-nb__id">
+          <div class="lab-nb__line">
+            <h1 class="lab-nb__name" title={page.title ?? page.label}>{page.label}</h1>
+            <span class="lab-nb__tag lab-nb__tag--route">{page.route}</span>
+            <Properties
+              site={[{ text: `Served at ${page.route}`, live: true }]}
+              pins={tasksBase ? { ...pins.forUrl(page.route), href: `${tasksBase}/all` } : null}
+              responsive={null}
+              source={page.file}
+            />
+          </div>
+          <span class="lab-nb__facts">
+            <span class="lab-nb__source" title="The page's source file">
+              <Icon name="page" size="sm" />
+              {page.file}
+            </span>
+            <span aria-hidden="true">·</span>
+            <button class="lab-nb__chip" type="button" popovertarget="lab-mounts-menu" title="The components this page mounts">
+              <Icon name="sections" size="sm" />
+              {page.mounts.length} component{page.mounts.length === 1 ? "" : "s"}
+              <Icon name="chevron-down" size="sm" />
+            </button>
+          </span>
+          <div class="lab-menu lab-menu--components" id="lab-mounts-menu" popover role="menu">
+            <p class="lab-menu__label">
+              {page.mounts.length} component{page.mounts.length === 1 ? "" : "s"} on {page.route}
+            </p>
+            {page.mounts.length === 0 && <p class="lab-menu__note">It mounts no components of its own.</p>}
             {page.mounts.map((file, i) => {
               const mod = byFile.get(file);
               return mod ? (
                 <a class="lab-menu__item" role="menuitem" href={mod.stories[0]!.dashboardUrl}>
-                  <span class="lab-slots__n">{i + 1}</span>
-                  {mod.moduleName}
-                  {mod.version && <span class="lab-menu__hint">{mod.version}</span>}
+                  <span class="lab-menu__mark"><Icon name="sections" size="sm" /></span>
+                  <span class="lab-menu__text">
+                    {mod.moduleName}
+                    {mod.version && <span class="lab-menu__sub"> {mod.version}</span>}
+                  </span>
+                  <span class="lab-menu__hint">slot {i + 1}</span>
                 </a>
               ) : (
-                <span class="lab-menu__item" aria-disabled="true" title="Not in the lab — no stories file for it">
-                  <span class="lab-slots__n">{i + 1}</span>
-                  {file.split("/").pop()}
+                <span class="lab-menu__item" role="menuitem" aria-disabled="true" title="Not in the lab — no *.stories.ts file for it">
+                  <span class="lab-menu__mark"><Icon name="component" size="sm" /></span>
+                  <span class="lab-menu__text">{file.split("/").pop()}</span>
+                  <span class="lab-menu__hint">slot {i + 1}</span>
                 </span>
               );
             })}
-            <hr />
-            <p class="lab-status-menu__fact lab-mono">{page.file}</p>
           </div>
         </div>
-        <div class="lab-navbar__tools">
-          <button class="lab-btn lab-btn--sm" type="button" data-lab-reload title="Reload the page in the frame">
-            <Icon name="reload" />
-            Reload
+        <div class="lab-nb__variants">
+          <button class="lab-tool lab-tool--icon" type="button" data-lab-reload title="Reload the page in the frame">
+            <Icon name="reload-page" size="sm" />
+            <span class="lab-visually-hidden">Reload</span>
           </button>
-          <a class="lab-btn lab-btn--sm" href={src} target="_blank" rel="noopener" title="Open the real page in a new tab">
-            <Icon name="external" />
-            Open
+          <a class="lab-tool lab-tool--outline" href={src} target="_blank" rel="noopener" title="Open the real page in a new tab">
+            <Icon name="external" size="sm" />
+            <span class="lab-tool__label">Open page</span>
           </a>
         </div>
-        <ViewportControls defaultW={1440} defaultH={900} kind="page" />
-        <div class="lab-navbar__tools">
-          <button class="lab-btn lab-btn--sm lab-btn--icon" type="button" popovertarget="lab-actions-menu" title="More">
-            <Icon name="more" />
-            <span class="lab-visually-hidden">More actions</span>
-          </button>
-        </div>
-        <div class="lab-menu" id="lab-actions-menu" popover role="menu" data-lab-align="end">
-          {import.meta.env.DEV && (
-            <a class="lab-menu__item" role="menuitem" href={`vscode://file${rootDir.startsWith("/") ? "" : "/"}${rootDir}/${page.file}`}>
-              <Icon name="code" />
-              Open in VS Code
-            </a>
-          )}
-          <button class="lab-menu__item" type="button" role="menuitem" data-lab-copy-link>
-            <Icon name="link" />
-            <span data-lab-copy-label>Copy link to this size</span>
-          </button>
+        <ViewportControls defaultW={1440} defaultH={900} kind="page" comment={Boolean(tasksBase)} parameters={false} />
+        <div class="lab-nb__actions">
+          <ActionsMenu
+            editorUrl={import.meta.env.DEV ? `vscode://file${rootDir.startsWith("/") ? "" : "/"}${rootDir}/${page.file}` : null}
+            pins={Boolean(tasksBase)}
+          />
         </div>
-      </Fragment>
+      </div>
     ) : (
       <Fragment slot="navbar">
-        <div class="lab-navbar__id">
-          <h1 class="lab-navbar__title">Pages</h1>
-          <div class="lab-navbar__meta">
-            <span class="lab-pill">{pages.length} page{pages.length === 1 ? "" : "s"}</span>
+        <div class="lab-listing-bar">
+          <h1 class="lab-listing-bar__title">Pages</h1>
+          <p class="lab-listing-bar__counts">{counts.join(" · ")}</p>
+          <div class="lab-chips" role="radiogroup" aria-label="Show">
+            {
+              chips.map((chip) => (
+                <button class="lab-chip" type="button" role="radio" aria-checked={String(chip.value === "")} data-lab-filter={chip.value}>
+                  {chip.label} {chip.n}
+                </button>
+              ))
+            }
           </div>
         </div>
       </Fragment>
@@ -140,7 +172,7 @@ const src = page ? `${base}${page.route}` : "";
 
   {
     page ? (
-      <ViewportStage src={src} title={page.title ?? page.label} />
+      <ViewportStage src={src} title={page.title ?? page.label} pins={Boolean(tasksBase)} tasksHref={tasksBase ? `${tasksBase}/all` : null} />
     ) : (
       <div class="lab-page">
         <div class="lab-cards">
@@ -176,3 +208,7 @@ const src = page ? `${base}${page.route}` : "";
     )
   }
 </Shell>
+
+<script>
+  import "../navbar-client";
+</script>

package/src/chrome/views/Placeholder.astro

@@ -15,10 +15,10 @@ type Props = InferGetStaticPropsType<typeof getStaticPaths>;
 const { key, title, icon } = Astro.props as Props;
 ---
 
-<Shell title={title} active={key}>
+<Shell title={title} active={key} navbarClass="lab-navbar--listing">
   <Fragment slot="navbar">
-    <div class="lab-navbar__id">
-      <h1 class="lab-navbar__title">{title}</h1>
+    <div class="lab-listing-bar">
+      <h1 class="lab-listing-bar__title">{title}</h1>
     </div>
   </Fragment>
   <div class="lab-placeholder">

package/src/chrome/views/Tasks.astro

@@ -9,11 +9,14 @@
 // lab's chrome and maps their palette onto the lab's tokens (`.pin-board--lab`). The Astro dev
 // toolbar's ticket panel reads this page the way it read /pin: by the `[data-board]` and
 // `script.card-data` payloads it carries, so the two cannot disagree about what a ticket is.
+//
+// NO LEVEL 2 (decided 2026-09-24): Kanban Board and All Tasks have no secondary panel. The board's
+// own toolbar already filters by status, so a status tree beside it only took width from the
+// columns; main takes the whole width beside level 1.
 import type { GetStaticPaths, InferGetStaticPropsType } from "astro";
 import Shell from "../Shell.astro";
-import Tree from "../Tree.astro";
-import { labConfig, type TreeNode } from "../model";
-import { BOARD_CSS, BOARD_SCRIPT, boardParts, collectTickets, READY_FOR_REVIEW, STATUSES } from "../../pin/board.mjs";
+import { labConfig } from "../model";
+import { BOARD_CSS, BOARD_SCRIPT, boardParts, collectTickets } from "../../pin/board.mjs";
 
 export const getStaticPaths = (() => [
   { params: { view: undefined }, props: { view: "board" as const } },
@@ -39,47 +42,16 @@ const assetHref = (t: Ticket) =>
   tasks && t.shotName ? tasks.assets + t.shotName.split("/").map(encodeURIComponent).join("/") : null;
 const parts = boardParts(tickets, broken, { assetHref, apiHref: tasks?.api ?? null, links: [], view });
 
-const base = tasks?.base ?? "";
-const here = view === "table" ? `${base}/all` : base;
-let wanted: string | null = null;
-try {
-  wanted = Astro.url.searchParams.get("status");
-} catch {
-  wanted = null;
-}
-const statusNodes: TreeNode[] = [
-  { id: "status:all", label: "All tickets", href: here, icon: "tasks", count: tickets.length, current: !wanted },
-  ...[...STATUSES, ...new Set(tickets.map((t) => t.status).filter((s) => !STATUSES.includes(s)))].map((status) => {
-    const n = tickets.filter((t) => t.status === status).length;
-    return {
-      id: `status:${status}`,
-      label: status,
-      href: `${here}?status=${encodeURIComponent(status)}`,
-      icon: "check" as const,
-      count: n,
-      dot: status === READY_FOR_REVIEW && n > 0 ? ("open" as const) : undefined,
-      current: wanted === status,
-    };
-  }),
-];
 const title = view === "table" ? "All Tasks" : "Kanban Board";
 ---
 
-<Shell
-  title={title}
-  active={view === "table" ? "tasks-all" : "tasks-board"}
-  panel={{ label: "Tasks", crumbs: [{ label: "Tasks" }, { label: title }], search: false }}
->
-  <Tree slot="panel" nodes={statusNodes} />
-
+<Shell title={title} active={view === "table" ? "tasks-all" : "tasks-board"} navbarClass="lab-navbar--listing">
   <Fragment slot="navbar">
-    <div class="lab-navbar__id">
-      <h1 class="lab-navbar__title">{title}</h1>
-      <div class="lab-navbar__meta">
-        {parts.counts.waiting > 0 && <span class="lab-pill lab-pill--brand">{parts.counts.waiting} ready for your review</span>}
-        <span class="lab-pill">{parts.counts.total} ticket{parts.counts.total === 1 ? "" : "s"}</span>
-        {parts.counts.needsHuman > 0 && <span class="lab-pill lab-pill--error">{parts.counts.needsHuman} needing a human</span>}
-      </div>
+    <div class="lab-listing-bar">
+      <h1 class="lab-listing-bar__title">{title}</h1>
+      {/* Amber: what waits on you (the design's own use of it). */}
+      {parts.counts.waiting > 0 && <span class="lab-pill lab-pill--waiting">{parts.counts.waiting} ready for your review</span>}
+      {parts.counts.needsHuman > 0 && <span class="lab-pill lab-pill--error">{parts.counts.needsHuman} needing a human</span>}
     </div>
   </Fragment>
 

package/src/core/LICENSE-astrobook

@@ -115,6 +115,11 @@ Every deliberate divergence in src/ui/ (all of it added 2026-09-22)
     preview-layout.astro, theme-script.astro, theme-message.ts, theme.ts and index.ts. lab.css
     was never upstream's (9) and is the redesign's stylesheet. `theme-script.astro` gained a
     `storageKey` prop, so the chrome and the preview each keep their own light/dark.
+17. `preview-layout.astro` hides Astro's dev toolbar when the story is framed (2026-09-24). Every
+    preview is an <iframe> of the bare story, and the dev server puts its toolbar in every page,
+    so a component page showed two. An inline script marks <html> when `window.frameElement` is
+    set and one rule on that mark sets the toolbar to `display: none`; opened in its own tab the
+    bare story keeps its toolbar.
 
 --------------------------------------------------------------------------------
 Every deliberate divergence in src/types/ (all of it added 2026-09-22)

package/src/core/utils/kebab-case.ts

@@ -3,8 +3,8 @@
 // Upstream's get-story-modules.ts imports `just-kebab-case`, but @astrobook/core declares it as a
 // DEV dependency only: tsdown bundles the function into the published dist, so the package never
 // installs it. This package ships source with no bundler, so the function has to come from
-// somewhere — and it decides every story id, which is what lab URLs and the cull/responsive
-// mark files are keyed on. The three regexes below were extracted from the bundle that shipped in
+// somewhere — and it decides every story id, which is what lab URLs and the responsive mark file
+// are keyed on. The three regexes below were extracted from the bundle that shipped in
 // @astrobook/core 0.13.3 (dist/index.js, its `just-kebab-case@4.2.0` region) so the ids cannot
 // drift.
 //

package/src/pin/board.mjs

@@ -1,14 +1,17 @@
 // orbytes-pin — the pin board: one reader, one writer, one renderer, two surfaces.
 //
-// Two things consume this module and NOTHING here knows which:
-//   · the `/pin` route on `astro dev` (index.mjs, dev-only middleware) — generated per request,
-//     and the only surface where the writer is reachable;
-//   · `npx orbytes-pin-gallery` (../../bin/pin-gallery.mjs) — one standalone file on disk.
+// Three things consume this module and NOTHING here knows which:
+//   · the lab's Tasks views at `<subpath>/tasks` on `astro dev` (../chrome/views/Tasks.astro,
+//     through `boardParts`) — generated per request, with the writer reachable;
+//   · the pin half's own board at `<route>` when it runs without the lab (index.mjs, dev-only
+//     middleware, through `renderBoard`) — the same, standalone;
+//   · `npx orbytes-pin-gallery` (../../bin/pin-gallery.mjs) — one standalone file on disk, and the
+//     only one of the three with no writer.
 //
 // It exists because a second copy is how this system's last three bugs happened, all of them in
 // the gallery script and all of them the same shape: a local parser that drifted from the one in
 // tickets.mjs (see `collectTickets` below). A live route rendering its own cards would have been
-// the fourth. So the route and the script share this file and differ in exactly two arguments —
+// the fourth. So every surface shares this file and they differ in exactly two arguments —
 // where a screenshot is fetched from (`assetHref`) and whether the page is live (`apiHref`).
 //
 // ── backlog.md is retired (2026-09-22) ──────────────────────────────────────────────────────
@@ -209,8 +212,8 @@ export const TICKET_FILE = /^pin-\d+.*\.md$/;
 
 /**
  * Every ticket in `<backlogDir>/tasks`, plus the ones that could not be read. Read fresh from disk
- * on every call — that is what makes the `/pin` route live and `orbytes-pin-gallery` a snapshot of the
- * same moment.
+ * on every call — that is what makes the dev-server board live and `orbytes-pin-gallery` a snapshot of
+ * the same moment.
  *
  * ONE reader: `parseTicket`, which owns the whole file — the frontmatter as much as the ```yaml
  * pin block and the comment. It spreads the frontmatter keys at the top level of what it returns,
@@ -237,9 +240,11 @@ export const TICKET_FILE = /^pin-\d+.*\.md$/;
  *
  * `Cancelled` tickets are EXCLUDED unless `includeCancelled` is passed, for the same reason
  * `listTickets` excludes them (ruled 2026-09-22: they must not take up context space for an
- * agent). The default is the safe one everywhere, and the three callers that genuinely need the
- * archive — the `/pin` route, `orbytes-pin-gallery`, and `updateTicket`, which must be able to move a
- * ticket back OUT of Cancelled — each say so explicitly at the call site.
+ * agent). The default is the safe one everywhere, and the callers that genuinely need the archive
+ * each say so explicitly at the call site: the three human-facing surfaces (the lab's Tasks views,
+ * the pin half's standalone board, `orbytes-pin-gallery`), the write endpoint's re-read of the card
+ * it just moved (index.mjs), and `updateTicket`, which must be able to move a ticket back OUT of
+ * Cancelled.
  *
  * A ticket that cannot be READ is still collected into `broken` whatever its status, because a
  * file the parser rejects has no trustworthy status to filter on.
@@ -387,7 +392,7 @@ export function collectTickets(repoRoot, { backlogDir = "backlog", includeCancel
  * deliberate: this endpoint is the board's own write path and the board is the surface a person
  * drags on, so it cannot tell that drop from a script's POST and must not try. Refusing
  * `Resolved` here would break the one person the rule exists for. An agent finishing a ticket
- * writes `Ready for Review` and stops.
+ * writes `Ready for review` and stops.
  *
  * ── Refusals, not warnings ───────────────────────────────────────────────────────────────────
  * Every one of these throws with a sentence naming the ticket, and nothing is written:
@@ -423,7 +428,7 @@ export function updateTicket(repoRoot, change, { backlogDir = "backlog", now = n
   if (change?.status !== undefined) {
     // Normalised BEFORE the allowlist, so a caller written against the old three-column board —
     // or a hand-rolled curl — sends `Done` and gets `Resolved` written, rather than a refusal on a
-    // word this package still understands. The allowlist itself stays the four current statuses:
+    // word this package still understands. The allowlist itself stays the six current statuses:
     // it is the entire input sanitiser here, and `Done` is never written to a file again.
     const wanted = normaliseStatus(change.status);
     if (!STATUSES.includes(wanted)) {
@@ -588,14 +593,19 @@ const slug = (s) => String(s ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").re
  *
  *   1            → yes. The overwhelming majority, and this returns null for it: a healthy card
  *                  emits no extra element at all, so a healthy board looks exactly as it did.
- *   0            → no. The element could not be found on reload. Everything else on the ticket is
- *                  still correct — the picture, the source file, the outer_html — so it is perfectly
- *                  workable by hand, and that is what the banner says. It is not an error.
+ *   0            → no. The selector finds nothing on reload, so the flag's note says an agent
+ *                  cannot locate the element. Everything else on the ticket is still correct — the picture,
+ *                  the source file, the outer_html — so a person can work it from those. It is not
+ *                  an error.
  *   2 or more    → no. Several elements match, so an agent might edit the wrong one.
  *   "pending"    → never tested (shots off, or the screenshot failed). Not a problem; a quiet line
  *                  in the meta list, no banner.
  *   undefined    → the ticket predates the field. Nothing is shown, because nothing is known.
  *
+ * The flag is a label and nothing more. It changes no status, and neither `isAgentReady` nor
+ * `listTickets` (tickets.mjs) reads `selector_matches`, so a flagged ticket left in `Ready for agent`
+ * is still handed to an agent. Only its status keeps an agent off it.
+ *
  * The comparison is `=== 0`, on a value that is already a number. Writing this as a truthiness test
  * is the one mistake the field was shaped to prevent — see the note on `selectorMatches` above.
  */

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",
   /**
@@ -425,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 {
@@ -544,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.