@orbytes/astrolab 0.3.0

package/index.d.ts

@@ -0,0 +1,279 @@
+import type { AstroIntegration } from "astro";
+
+/** One tier of the lab — the first path segment under `directory`. */
+export interface LabTierOption {
+  /** The folder name under `directory`. */
+  id: string;
+  /** Shown on the tier card and the folder pages. Defaults to `id`, capitalised. */
+  label?: string;
+  /**
+   * Section versions: this tier's stories carry the responsive mark and render at page width in
+   * thumbnails and in the viewport configurator. Defaults to true for a tier named "sections".
+   */
+  responsive?: boolean;
+  /**
+   * This tier's stories may be marked for deletion in the sidebar and removed by
+   * `orbytes-lab-cull`. Defaults to true for a tier named "explorations".
+   */
+  cullable?: boolean;
+}
+
+export interface OrbytesLabOptions {
+  /** Where the stories live, relative to the project root. Default `"src/lab"`. */
+  directory?: string;
+  /** Where the lab is served. Default `"/lab"`. */
+  subpath?: string;
+  /** The consumer's token/stylesheet files, as Astrobook takes them. Default `[]`. */
+  css?: string[];
+  /**
+   * A path to the consumer's own head component, rendered inside the lab's head — how fonts and
+   * anything else site-specific reach lab pages. Relative to the project root.
+   */
+  head?: string;
+  /** The lab's name, shown in the dashboard. Default `"Component lab"`. */
+  title?: string;
+  /**
+   * The deployed lab's base URL — the real minified build, which a dev server is not. Every card
+   * and the story header link to the same story there. Omit and those links do not appear.
+   */
+  stagingUrl?: string;
+  /**
+   * A branch preview URL with a `{branch}` placeholder, e.g.
+   * `"https://{branch}-my-site.workers.dev"`. Omit and the home page lists no branches.
+   */
+  previewUrlTemplate?: string;
+  /**
+   * The Feedbucket key. Set it and every lab page carries the widget; the consumer keeps its own
+   * staging gate, so the option takes a key or nothing.
+   */
+  feedbucketKey?: string;
+  /**
+   * The tiers, in reading order. Default `["sections", "components", "explorations"]`; a tier
+   * named "sections" takes the responsive role and one named "explorations" the cull role unless
+   * the entry says otherwise.
+   */
+  tiers?: (string | LabTierOption)[];
+  /**
+   * The pin board — the dev-only click-to-ticket feedback half of this package (`docs/PIN.md`).
+   *
+   * `true` or omitted ships it at `/pin` with its defaults; `false` omits it entirely, for a site
+   * that wants the component lab alone. An object is the pin integration's own options, and the
+   * lab fills in `links` from its RESOLVED `subpath` so the board's "Lab" link is derived rather
+   * than guessed — pass your own `links` to override that.
+   *
+   * @default true
+   */
+  pin?: boolean | null | OrbytesPinOptions;
+}
+
+/** The pin integration's options. Everything here is dev-only; none of it reaches a build. */
+export interface OrbytesPinOptions {
+  /**
+   * SITE-relative directories whose `.astro` files get `data-orbytes-src`.
+   * @default ["src/lab/sections", "src/components"]
+   */
+  stamp?: string[];
+  /**
+   * SITE-relative `.astro` paths exempt from the stamp's hard failure — the same base as `stamp`,
+   * which it was NOT until 2026-09-22 (it was repo-relative, so the two agreed only in a repo
+   * whose app sits in `site/` and the exemption silently lapsed everywhere else). A repo-relative
+   * path is still accepted, so a config written before that date keeps working.
+   * @default []
+   */
+  stampSkip?: string[];
+  /** Repo-relative board directory: tickets in `tasks/`, PNGs in `assets/`. @default "backlog" */
+  backlogDir?: string;
+  /** Canonical screenshot home; the repo copy is a hardlink into it. @default ~/.orbytes/feedback-archive */
+  archiveDir?: string;
+  /**
+   * The archive folder under `archiveDir` this project's screenshots live in. Omit and it is the
+   * checkout's own directory name — which two clones of DIFFERENT repos under the same folder name
+   * silently share, one overwriting the other's `pin-007.png`. Set it to be sure.
+   */
+  project?: string | null;
+  /** Write tickets but take no screenshots. `playwright` is then never loaded. @default true */
+  shots?: boolean;
+  /**
+   * Where the board is served, dev only. `<route>/assets/*` serves its screenshots and
+   * `<route>/api/ticket` is the one write endpoint.
+   *
+   * It is MIDDLEWARE, installed ahead of Astro's own request handler, so it SHADOWS a host page at
+   * the same path — in dev, silently. A site with its own `/pin` page sets something else here.
+   * @default "/pin"
+   */
+  route?: string;
+  /**
+   * The links in the board's top-right corner. `null` keeps the board's historical pair (the site
+   * root and `/lab`); `[]` draws none. Through `orbytesLab()` this is filled in from the lab's
+   * resolved subpath, so it rarely needs setting by hand.
+   */
+  links?: { href: string; label?: string }[] | null;
+  /** @default "orbytes-pin" */
+  appId?: string;
+  /** @default "Pin" */
+  appName?: string;
+  /** An Astro dev-toolbar icon name, or an inline `<svg…>` string. @default "bug" */
+  icon?: string;
+}
+
+/**
+ * The orbytes component lab AND the pin board: the Astrobook core vendored into this package
+ * (`src/core/`, 0.13.3), the lab shell around it, and the dev-only feedback board at `/pin`. Astro
+ * flattens the returned array, so one entry in `integrations` configures all three.
+ *
+ * `pin: false` returns the lab alone.
+ */
+export default function orbytesLab(options?: OrbytesLabOptions): AstroIntegration[];
+
+/**
+ * The pin board on its own, for a site that wants it without the lab. `orbytesLab()` returns this
+ * as one of its entries; calling it directly is the same integration with the same dev-only gates.
+ */
+export function orbytesPin(options?: OrbytesPinOptions): AstroIntegration;
+
+/* ── the pin board's own surface, re-exported from the root ────────────────────────────────────
+   The vocabulary and the readers, so an agent working tickets off disk imports from one place.
+   `docs/PIN-CONTRACT.md` is the interface these agree on; do not restate it here. */
+
+/** The six states a ticket can be in, in board order. Nothing else is ever WRITTEN to `status`. */
+export type PinStatus =
+  | "Backlog"
+  | "Ready for agent"
+  | "In Progress"
+  | "Ready for review"
+  | "Resolved"
+  | "Cancelled";
+
+/** Retired 2026-09-22 and still readable: `To Do` → `Ready for agent`, `Done` → `Resolved`. */
+export type PinLegacyStatus = "To Do" | "Done";
+
+/** What a `status:` line read off disk may say — today's vocabulary, or a legacy alias. */
+export type PinStatusOnDisk = PinStatus | PinLegacyStatus | (string & {});
+
+/** The three priorities a card may carry. */
+export type PinPriority = "high" | "medium" | "low";
+
+/** Per-ticket choice of whether an agent fires immediately or waits on the queue. */
+export type PinDispatch = "now" | "queue";
+
+/** One ticket, as `listTickets` reads it back. Pin fields come from the body's fenced block. */
+export interface PinTicket {
+  id: string;
+  title: string;
+  /** RAW — put it through `normaliseStatus()`, or ask `isOpen()` / `isCancelled()` /
+   *  `isAgentReady()`. Never compare it to a literal. */
+  status: PinStatusOnDisk;
+  labels: string[];
+  priority: string;
+  assignee: string[];
+  dependencies: string[];
+  created_date: string;
+  updated_date?: string;
+  /** Repo-relative path of the ticket file itself. */
+  file: string;
+  /** The reviewer's words, verbatim. */
+  comment: string;
+  pin: {
+    dispatch: PinDispatch;
+    /** Repo-relative, or the string `unresolved`. */
+    source: string;
+    selector: string;
+    url: string;
+    viewport: { width: number; height: number; dpr: number };
+    scroll: { x: number; y: number };
+    rect: { x: number; y: number; width: number; height: number };
+    /** Repo-relative path of the PNG on disk. */
+    shot: string;
+    outer_html: string;
+  };
+}
+
+export const STATUSES: readonly PinStatus[];
+export const BACKLOG: "Backlog";
+export const READY_FOR_AGENT: "Ready for agent";
+export const IN_PROGRESS: "In Progress";
+export const READY_FOR_REVIEW: "Ready for review";
+export const RESOLVED: "Resolved";
+export const CANCELLED: "Cancelled";
+/** What a freshly picked ticket is written as. */
+export const DEFAULT_STATUS: "Ready for agent";
+/** The two statuses that end a ticket's life: accepted, or abandoned. */
+export const CLOSED_STATUSES: readonly ("Resolved" | "Cancelled")[];
+/** Neither `Resolved` nor `Cancelled` — the one definition of "open", shared by every surface. */
+export const OPEN_STATUSES: readonly PinStatus[];
+
+/** Today's vocabulary for a status read off disk; an unknown status is never rounded to a known one. */
+export function normaliseStatus(status: unknown): string;
+/** Open — neither accepted nor cancelled. `isOpen("Done")` is `false`. */
+export function isOpen(status: unknown): boolean;
+/** Archived. Every agent-facing read drops these; `/pin` is the one place they are visible. */
+export function isCancelled(status: unknown): boolean;
+/** May an agent START work on this ticket? Exactly one status says yes. */
+export function isAgentReady(status: unknown): boolean;
+
+/** The first ancestor of `from` containing `.git`. Throws rather than guessing. */
+export function findRepoRoot(from: string): string;
+/** Throws, naming the file, on a ticket whose fenced pin block is missing or unparseable. */
+export function parseTicket(text: string, file?: string): PinTicket;
+/**
+ * Every LIVE ticket on disk — the agent-facing reader. `Cancelled` tickets are NOT in it unless
+ * `includeCancelled` is passed. Statuses come back raw; normalise before comparing.
+ */
+export function listTickets(
+  repoRoot: string,
+  options?: { backlogDir?: string; includeCancelled?: boolean },
+): PinTicket[];
+export function writeTicket(
+  repoRoot: string,
+  payload: {
+    comment: string;
+    dispatch: PinDispatch;
+    source: string | null;
+    selector: string;
+    url: string;
+    viewport: { width: number; height: number; dpr: number };
+    scroll: { x: number; y: number };
+    rect: { x: number; y: number; width: number; height: number };
+    outerHTML: string;
+  },
+  options?: { backlogDir?: string },
+): { id: string; num: number; file: string; shot: string; archiveName: string; absolute: string };
+/** Every ticket on disk, plus the ones that could not be read. Read fresh on every call. */
+export function collectTickets(
+  repoRoot: string,
+  options?: { backlogDir?: string; includeCancelled?: boolean },
+): { tickets: object[]; broken: { file: string; reason: string }[]; paths: { backlog: string; tasks: string; assets: string } };
+/**
+ * The ONE writer of a ticket's frontmatter. Rewrites only the lines named in `change` (plus
+ * `updated_date`) and returns the body byte for byte. Refuses rather than warns.
+ */
+export function updateTicket(
+  repoRoot: string,
+  change: {
+    id: string;
+    status?: PinStatus | PinLegacyStatus;
+    priority?: PinPriority;
+    /** What the caller believed; a mismatch refuses the write rather than overwriting it. */
+    expect?: { status?: string | null; priority?: string | null };
+  },
+  options?: { backlogDir?: string; now?: Date },
+): { id: string; file: string; status: PinStatus; priority: string | null; changed: string[]; bodyUnchanged: true };
+/**
+ * The kanban, as one HTML document. Passing no `apiHref` is what makes a page read-only — the
+ * standalone `orbytes-pin-gallery` file passes none. `links` draws the corner nav.
+ */
+export function renderBoard(
+  tickets: object[],
+  broken?: { file: string; reason: string }[],
+  options?: {
+    assetHref?: (ticket: object) => string | null;
+    apiHref?: string | null;
+    generatedAt?: Date;
+    links?: { href: string; label?: string }[] | null;
+  },
+): string;
+/** One card on its own — what the write endpoint hands back after a successful change. */
+export function renderCard(
+  ticket: object,
+  options?: { assetHref?: (ticket: object) => string | null; live?: boolean },
+): string;

package/index.mjs

@@ -0,0 +1,347 @@
+// @orbytes/astrolab — the component lab AND the pin board, as one Astro integration.
+//
+//   import orbytesLab from "@orbytes/astrolab";
+//   integrations: [ includeLab ? orbytesLab({ css: ["./src/styles/global.css"] }) : null ]
+//
+// The consumer configures ONE integration, not three: this module builds the Astrobook integration
+// from the copy of its core vendored at ./src/core (0.13.3 — src/core/LICENSE-astrobook) and
+// returns it alongside the lab shell and the pin board, which Astro flattens into its integration
+// list. The vendored core is unforked apart from the divergences each file's header names —
+// everything the lab adds is layered beside it rather than patched into it.
+//
+// ── the pin board (./src/pin/, moved in 2026-09-22) ─────────────────────────────────────────────
+// Decided 2026-09-22: the lab and the pin board are ONE app, bundled and working as one — not two
+// packages a site installs separately. So `/lab` and `/pin` come from one call, one install, one
+// dev server. `pin: false` omits it entirely — a site may want the lab alone — and `pin: {…}` passes
+// options straight through (ops/standalone-plan.md › The pin board merges in; docs/PIN.md).
+//
+// The pin half is DEV ONLY and gates itself four times over; it is registered in staging builds
+// along with the lab and does nothing there, because its first assertion is `command === "dev"`.
+// Nothing in this file may gate it instead — a caller that reaches ./src/pin/index.mjs directly
+// must be as safe as one that comes through here.
+//
+// Three jobs:
+//   1. configure Astrobook — directory, subpath, css, title, and this package's own head and home
+//      components (which render the consumer's head inside them).
+//   2. inject the shell's routes, prerendered like every Astrobook route:
+//        <subpath>/browse/[...path]   folder pages          → ./src/shell/Browse.astro
+//        <subpath>/viewport/[...id]   viewport configurator → ./src/shell/Viewport.astro
+//        <subpath>/index.json         the lab index         → ./src/shell/index.json.ts
+//      and define `virtual:orbytes-lab/*` so those pages can read the resolved options, the
+//      consumer's head component and the consumer's CSS without importing anything by path.
+//   3. serve the two mark APIs on the Vite dev server only (astro:server:setup never runs in a
+//      build, so a deployed lab has no write path and the switches hide themselves):
+//        GET /__lab/cull         { marked: string[], updated: string | null }
+//        PUT /__lab/cull         body { marked: string[] } — every entry must be an existing
+//                                stories file in the CULLABLE tier AND not live on any page;
+//                                otherwise 400 with the offenders. Writes <directory>/cull.json.
+//        GET /__lab/responsive   { done: string[], approved: string[], updated: string | null }
+//        PUT /__lab/responsive   body { done: string[], approved?: string[] } — every entry must
+//                                be an existing stories file in the RESPONSIVE tier; otherwise 400
+//                                with the offenders. Writes <directory>/responsive.json.
+//      Marks only. NOTHING HERE DELETES A FILE — that is `orbytes-lab-cull`, a separate command,
+//      run by hand and with a dry run first.
+//
+// Gotcha (2026-09-06): Astro re-imports astro.config.mjs on a config change, but this module and
+// its ./src/shell/*.mjs imports stay in Node's ESM cache for the life of the process — so an edit
+// here is NOT picked up by the config-change restart. Stop and start the dev server after editing.
+import { fileURLToPath } from "node:url";
+// GENERATED, not source — `scripts/build-core.mjs` compiles src/core/ into dist/core/ and the
+// package's `prepack`/`prepare` scripts run it. It cannot be `./src/core/index.ts`: Node loads
+// astro.config.mjs through its own ESM loader, and Node's type-stripping is hard-disabled under
+// node_modules, so an INSTALLED copy of this package could not be loaded at all. Measured
+// 2026-09-22 against a packed tarball in a clean project. Editing src/core/ means re-running
+// `npm run build:core`.
+import { createAstrobookIntegration } from "./dist/core/index.js";
+import { resolveLabOptions } from "./defaults.mjs";
+import orbytesPin from "./src/pin/index.mjs";
+import { defaultImports, liveComponentFiles, storyComponentFile } from "./src/shell/live-files.mjs";
+import {
+  cullOffence,
+  readCull,
+  readResponsive,
+  responsiveOffence,
+  writeCull,
+  writeResponsive,
+} from "./src/shell/marks.mjs";
+
+const file = (relative) => fileURLToPath(new URL(relative, import.meta.url));
+
+const VIRTUAL = {
+  config: "virtual:orbytes-lab/config.mjs",
+  head: "virtual:orbytes-lab/user-head.mjs",
+  css: "virtual:orbytes-lab/user-css.mjs",
+};
+// Resolved ids carry no leading NUL, the same choice Astrobook makes: Astro's SSR externalisation
+// and its .astro pipeline both handle plain ids, and a NUL-prefixed one has to be special-cased.
+const RESOLVED = {
+  [VIRTUAL.config]: "__virtual_orbytes_lab_config__.mjs",
+  [VIRTUAL.head]: "__virtual_orbytes_lab_user_head__.mjs",
+  [VIRTUAL.css]: "__virtual_orbytes_lab_user_css__.mjs",
+};
+
+/**
+ * Why an entry may not be marked for deletion, or null when it may. `importedByLive` maps a
+ * component file to the live section that imports it, so an exploration a live section uses is
+ * refused here with the same reason the cull script would give later.
+ */
+const cullEntryOffence = (rootDir, config, entry, liveByFile, importedByLive) => {
+  const bad = cullOffence(rootDir, config, entry);
+  if (bad) return bad;
+  const component = storyComponentFile(rootDir, entry);
+  const mount = component ? liveByFile.get(component) : undefined;
+  if (mount) return `live on ${mount.page} (slot ${mount.slot}: ${component})`;
+  const user = component ? importedByLive.get(component) : undefined;
+  if (user) return `used by live section ${user}`;
+  return null;
+};
+
+const readBody = (req) =>
+  new Promise((resolve, reject) => {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      try {
+        resolve(body ? JSON.parse(body) : {});
+      } catch (e) {
+        reject(e);
+      }
+    });
+    req.on("error", reject);
+  });
+
+const send = (res, status, payload) => {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json");
+  res.setHeader("Cache-Control", "no-store");
+  res.end(JSON.stringify(payload));
+};
+
+/** The virtual modules the package's own pages read. Everything in them is JSON-serialisable. */
+const virtualModulesPlugin = (config, headEntrypoint) => ({
+  name: "orbytes-lab/virtual",
+  resolveId: (id) => RESOLVED[id],
+  load(id) {
+    switch (id) {
+      case RESOLVED[VIRTUAL.config]:
+        return `export default ${JSON.stringify(config)};`;
+      case RESOLVED[VIRTUAL.head]:
+        return `export { default } from ${JSON.stringify(headEntrypoint)};`;
+      case RESOLVED[VIRTUAL.css]:
+        return config.css.map((css) => `import ${JSON.stringify(css)};`).join("\n");
+    }
+  },
+});
+
+/** @param {Record<string, unknown>} [options] */
+function labShell(options) {
+  const config = resolveLabOptions(options);
+  let rootDir = process.cwd();
+  return {
+    name: "orbytes-lab",
+    hooks: {
+      "astro:config:setup": ({ config: astroConfig, injectRoute, updateConfig, logger }) => {
+        rootDir = fileURLToPath(astroConfig.root);
+        // The consumer's head component, resolved the way Astrobook resolves its own `head`:
+        // a relative path against the project root, anything else left alone. No head → a
+        // component that renders nothing, so the package's head has something to mount either way.
+        const head = options?.head
+          ? String(options.head).startsWith(".")
+            ? fileURLToPath(new URL(String(options.head), astroConfig.root))
+            : String(options.head)
+          : file("./src/Empty.astro");
+
+        for (const [pattern, entrypoint] of [
+          [`${config.subpath}/browse/[...path]`, "./src/shell/Browse.astro"],
+          [`${config.subpath}/viewport/[...id]`, "./src/shell/Viewport.astro"],
+          [`${config.subpath}/index.json`, "./src/shell/index.json.ts"],
+        ]) {
+          injectRoute({ pattern, entrypoint: file(entrypoint), prerender: true });
+        }
+
+        updateConfig({
+          vite: {
+            plugins: [virtualModulesPlugin(config, head)],
+            // This package ships SOURCE — .astro and .ts compiled by the consumer's Vite, the way
+            // Starlight ships its components. Vite externalises node_modules for SSR by default,
+            // and an externalised .astro file is handed to Node, which cannot read it. The
+            // consumer should need one line in its config and nothing more, so the exemption is
+            // declared here rather than there.
+            ssr: { noExternal: ["@orbytes/astrolab"] },
+            // Marking writes JSON files under src/; keep Vite from treating those as source
+            // changes and reloading the lab mid-triage.
+            server: {
+              watch: { ignored: [`**/${config.cullFile}`, `**/${config.responsiveFile}`] },
+            },
+          },
+        });
+        logger.info(
+          `folder pages at ${config.subpath}/browse, viewport at ${config.subpath}/viewport, index at ${config.subpath}/index.json`,
+        );
+      },
+      "astro:server:setup": ({ server, logger }) => {
+        server.middlewares.use(async (req, res, next) => {
+          const url = new URL(req.url ?? "/", "http://x");
+          if (url.pathname !== "/__lab/cull") return next();
+          try {
+            if (req.method === "GET") return send(res, 200, readCull(rootDir, config));
+            if (req.method === "PUT") {
+              const body = await readBody(req);
+              if (!Array.isArray(body.marked))
+                return send(res, 400, { error: "body must be { marked: string[] }" });
+              const live = liveComponentFiles(rootDir);
+              // First mount wins, so the refusal names the page a reader would look at first.
+              const liveByFile = new Map();
+              for (const l of live) if (!liveByFile.has(l.file)) liveByFile.set(l.file, l);
+              const importedByLive = new Map();
+              for (const l of live) {
+                for (const dep of defaultImports(rootDir, l.file)) {
+                  if (!importedByLive.has(dep.file)) importedByLive.set(dep.file, l.file);
+                }
+              }
+              const offenders = body.marked
+                .map((entry) => ({
+                  path: entry,
+                  reason: cullEntryOffence(rootDir, config, entry, liveByFile, importedByLive),
+                }))
+                .filter((o) => o.reason !== null);
+              if (offenders.length > 0) {
+                return send(res, 400, { error: "some entries cannot be marked", offenders });
+              }
+              const data = writeCull(rootDir, config, body.marked);
+              logger.info(`cull marks saved: ${data.marked.length} → ${config.cullFile}`);
+              return send(res, 200, { ok: true, file: config.cullFile, ...data });
+            }
+            return send(res, 405, { error: "GET or PUT" });
+          } catch (e) {
+            return send(res, 500, { error: String(e?.message ?? e) });
+          }
+        });
+
+        // The responsive marks — same shape of API as the cull one above, and deliberately its
+        // sibling rather than a second mechanism: a section version is marked responsive (and,
+        // separately, approved for that work) by hand, because neither fact is in the code.
+        server.middlewares.use(async (req, res, next) => {
+          const url = new URL(req.url ?? "/", "http://x");
+          if (url.pathname !== "/__lab/responsive") return next();
+          try {
+            if (req.method === "GET") return send(res, 200, readResponsive(rootDir, config));
+            if (req.method === "PUT") {
+              const body = await readBody(req);
+              const done = body.done;
+              const approved = body.approved ?? readResponsive(rootDir, config).approved;
+              if (!Array.isArray(done) || !Array.isArray(approved)) {
+                return send(res, 400, {
+                  error: "body must be { done: string[], approved?: string[] }",
+                });
+              }
+              const offenders = [...done, ...approved]
+                .map((entry) => ({ path: entry, reason: responsiveOffence(rootDir, config, entry) }))
+                .filter((o) => o.reason !== null);
+              if (offenders.length > 0) {
+                return send(res, 400, { error: "some entries cannot be marked", offenders });
+              }
+              const data = writeResponsive(rootDir, config, done, approved);
+              logger.info(
+                `responsive marks saved: ${data.done.length} done, ${data.approved.length} approved → ${config.responsiveFile}`,
+              );
+              return send(res, 200, { ok: true, file: config.responsiveFile, ...data });
+            }
+            return send(res, 405, { error: "GET or PUT" });
+          } catch (e) {
+            return send(res, 500, { error: String(e?.message ?? e) });
+          }
+        });
+
+        logger.info("mark APIs at /__lab/cull and /__lab/responsive (dev only)");
+      },
+    },
+  };
+}
+
+/**
+ * The pin half, or nothing.
+ *
+ * `pin: false` (or `null`) omits it — a site that wants the component lab and no feedback board
+ * gets exactly that, with no middleware, no toolbar app and no source stamp. Anything else is
+ * passed to the pin integration as its options, so `pin: { route: "/__pin", shots: false }` reads
+ * the way every other nested option in this file does. Default ON: the two are ruled one app, and
+ * an off-by-default half is one nobody would remember to turn on.
+ *
+ * The one value this function supplies rather than passes through is `links`. The board draws a
+ * "Lab" link in its corner, and until today that href was the string `/lab` written into the
+ * markup — correct only while the lab sits at its default subpath. Here the RESOLVED subpath is
+ * already in hand, derived from the same `resolveLabOptions` call that injects the routes, so the
+ * link and the routes cannot disagree. A consumer that passes its own `links` still wins.
+ *
+ * @param {Record<string, unknown>} [options] the lab's options
+ * @param {import("./defaults.mjs").LabConfig} config the RESOLVED lab config
+ */
+const pinHalf = (options, config) => {
+  const pin = options?.pin;
+  if (pin === false || pin === null) return [];
+  const given = typeof pin === "object" ? pin : {};
+  return [
+    orbytesPin({
+      // `subpath` is "" when the lab is mounted at the site root, and a link to "" is not a link —
+      // fall back to "/" there rather than emitting a dead href.
+      links: [
+        { href: "/", label: "Site" },
+        { href: config.subpath || "/", label: "Lab" },
+      ],
+      ...given,
+    }),
+  ];
+};
+
+/**
+ * The lab: the vendored Astrobook core, configured, plus the orbytes shell around it — and the pin
+ * board beside them unless `pin: false`. Astro flattens the array, so this is one entry in a
+ * consumer's `integrations`.
+ * @param {Record<string, unknown>} [options]
+ */
+export default function orbytesLab(options = {}) {
+  const config = resolveLabOptions(options);
+  return [
+    createAstrobookIntegration({
+      directory: config.directory,
+      subpath: config.subpath,
+      title: config.title,
+      css: config.css,
+      // Both are this package's own components; each renders the consumer's contribution inside
+      // it (the head mounts `head`, the home reads the resolved config).
+      head: "@orbytes/astrolab/head",
+      home: "@orbytes/astrolab/home",
+    }),
+    labShell(options),
+    ...pinHalf(options, config),
+  ];
+}
+
+// The pin board's own surface, for anything that wants it without the lab — the gallery binary,
+// an agent reading tickets off disk, a test. `orbytesPin` is the integration itself.
+export { default as orbytesPin } from "./src/pin/index.mjs";
+export {
+  BACKLOG,
+  CANCELLED,
+  CLOSED_STATUSES,
+  DEFAULT_STATUS,
+  IN_PROGRESS,
+  OPEN_STATUSES,
+  READY_FOR_AGENT,
+  READY_FOR_REVIEW,
+  RESOLVED,
+  STATUSES,
+  collectTickets,
+  findRepoRoot,
+  isAgentReady,
+  isCancelled,
+  isOpen,
+  listTickets,
+  normaliseStatus,
+  parseTicket,
+  renderBoard,
+  renderCard,
+  updateTicket,
+  writeTicket,
+} from "./src/pin/index.mjs";