@orbytes/astrolab 0.3.0

package/bin/lab-cull.mjs

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+// Turns the lab's cull marks into deletions — and never from the browser.
+//
+//   You mark lab items for deletion in the sidebar; the dev-only API saves the marks to
+//   <directory>/cull.json. This script is the only thing that deletes: it reads the marks, works
+//   out what can go, prints the plan, and removes files only when told to.
+//
+//   orbytes-lab-cull                dry run — print the plan, remove nothing
+//   orbytes-lab-cull --json         the same plan as JSON
+//   orbytes-lab-cull --yes          perform it: `git rm` (staged, NOT committed), clear the
+//                                   processed marks, print the build-log line to paste
+//   orbytes-lab-cull --dir=src/lab  where the lab lives, when it is not the default
+//
+//   exit 0 plan clean · 2 blockers · 1 error
+//
+// IT RUNS IN THE CONSUMER'S REPO, NOT ITS OWN. The root is `process.cwd()` — never this file's
+// location, which since the lab became a package is somewhere under node_modules. Everything it
+// reads is derived from that root plus the shared defaults in ../defaults.mjs, so a path this
+// script protects and a path the integration writes cannot drift apart.
+//
+// What goes: each marked stories file, the .astro it exports as `component` (same directory or
+// below), then any file under the lab directory that ONLY the removal set imports — closed
+// repeatedly, so a vendored library goes when its last importer goes. Never, whatever the marks
+// say: decorators/, shell/, vendor/*/LICENSE, the lab's own head and home components, the mark
+// files, anything outside the lab directory — reported as "kept (protected)".
+//
+// Blockers refuse an entry outright: the entry is outside the cullable tier (section versions are
+// the version history and components are shared chrome, so neither is ever culled), the component
+// is LIVE (any page under src/pages/ mounts it, or mounts something that imports it — derived from
+// the pages themselves, nothing declared), the path is not a stories file on disk, or an unmarked
+// file still imports the component.
+// --yes refuses to run while any blocker stands.
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { resolveLabOptions } from "../defaults.mjs";
+import { pageComponentFiles, sitePages } from "../src/shell/live-files.mjs";
+import { readCull } from "../src/shell/marks.mjs";
+
+const SOURCE_EXT = new Set([".astro", ".ts", ".mts", ".tsx", ".js", ".mjs", ".jsx", ".css"]);
+
+const args = process.argv.slice(2);
+const YES = args.includes("--yes");
+const JSON_OUT = args.includes("--json");
+const DIR = args.find((a) => a.startsWith("--dir="))?.slice("--dir=".length);
+for (const a of args)
+  if (!["--yes", "--json"].includes(a) && !a.startsWith("--dir="))
+    die(`unknown flag ${a} — use --yes, --json and/or --dir=<lab directory>`);
+
+// The repo the command was run in, never this file's own location: as a package binary it lives
+// under node_modules, and deriving the root from there would delete nothing or the wrong thing.
+const ROOT = process.cwd();
+const CONFIG = resolveLabOptions(DIR ? { directory: DIR } : {});
+const CULL = CONFIG.cullFile;
+const LAB = `${CONFIG.directory}/`;
+
+function die(message) {
+  console.error("  FAIL " + message);
+  process.exit(1);
+}
+
+const abs = (rel) => join(ROOT, rel);
+const rel = (absolute) => relative(ROOT, absolute).split(sep).join("/");
+const read = (relFile) => readFileSync(abs(relFile), "utf8");
+const git = (...argv) => execFileSync("git", argv, { cwd: ROOT, stdio: ["ignore", "pipe", "pipe"] }).toString();
+
+// ---- protection ------------------------------------------------------------------------------
+// Everything outside the lab directory is protected by the first clause, so the site's own source
+// can never be swept up. Inside it, the shell the lab needs and the marks themselves are named.
+const PROTECTED_DIRS = [`${LAB}decorators/`, `${LAB}shell/`];
+const PROTECTED_FILES = new Set([
+  `${LAB}Home.astro`,
+  `${LAB}LabHead.astro`,
+  `${LAB}integration.mjs`,
+  CONFIG.responsiveFile,
+  CULL,
+]);
+const vendorLicense = new RegExp(
+  `^${LAB.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}vendor/.*/LICENSE(\\.\\w+)?$`,
+);
+const isProtected = (f) =>
+  !f.startsWith(LAB) ||
+  PROTECTED_DIRS.some((d) => f.startsWith(d)) ||
+  PROTECTED_FILES.has(f) ||
+  vendorLicense.test(f);
+
+// ---- the import graph over all of src/ ------------------------------------------------------
+const walk = (dir, out = []) => {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, out);
+    else if (SOURCE_EXT.has(full.slice(full.lastIndexOf(".")))) out.push(full);
+  }
+  return out;
+};
+
+// Strips comments that could carry a stale `import … from "…"` line, then collects every
+// specifier: static imports and re-exports (multi-line, `type`, side-effect), dynamic import(),
+// and CSS @import. Bare packages and anything not starting ./ or ../ are ignored.
+const stripComments = (src) => src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+const SPECIFIER_PATTERNS = [
+  /\b(?:import|export)\s+(?:type\s+)?(?:[\w$*{}\s,]*?\s+from\s+)?["']([^"'\n]+)["']/g,
+  /\bimport\s*\(\s*["']([^"'\n]+)["']\s*\)/g,
+  /@import\s+(?:url\(\s*)?["']([^"'\n]+)["']/g,
+];
+const specifiersOf = (src) => {
+  const clean = stripComments(src);
+  const found = [];
+  for (const pattern of SPECIFIER_PATTERNS) for (const m of clean.matchAll(pattern)) found.push(m[1]);
+  return found;
+};
+
+// Relative specifier → existing file, or null for "not ours to follow" (bare package, /src/…
+// glob, alias), or undefined when a relative path resolves to nothing on disk.
+function resolveSpecifier(fromAbs, specifier) {
+  const clean = specifier.replace(/[?#].*$/, "");
+  if (!clean.startsWith("./") && !clean.startsWith("../")) return null;
+  const base = resolve(dirname(fromAbs), clean);
+  const candidates = [base];
+  for (const ext of [".ts", ".mts", ".tsx", ".mjs", ".js", ".astro"]) candidates.push(base + ext);
+  if (base.endsWith(".js")) candidates.push(base.slice(0, -3) + ".ts", base.slice(0, -3) + ".tsx");
+  if (base.endsWith(".mjs")) candidates.push(base.slice(0, -4) + ".mts");
+  for (const index of ["index.ts", "index.mts", "index.mjs", "index.js"]) candidates.push(join(base, index));
+  for (const c of candidates) if (existsSync(c) && statSync(c).isFile()) return c;
+  return undefined;
+}
+
+const imports = new Map(); // file → Set(files it imports)
+const importers = new Map(); // file → Set(files that import it)
+const unresolved = []; // { file, specifier } — relative paths that point at nothing
+for (const fileAbs of walk(abs("src"))) {
+  const file = rel(fileAbs);
+  const deps = new Set();
+  for (const specifier of specifiersOf(readFileSync(fileAbs, "utf8"))) {
+    const target = resolveSpecifier(fileAbs, specifier);
+    if (target === null) continue;
+    if (target === undefined) {
+      unresolved.push({ file, specifier });
+      continue;
+    }
+    const dep = rel(target);
+    deps.add(dep);
+    if (!importers.has(dep)) importers.set(dep, new Set());
+    importers.get(dep).add(file);
+  }
+  imports.set(file, deps);
+}
+const importersOf = (f) => importers.get(f) ?? new Set();
+
+// ---- LIVE: what any page mounts, and what those mount ---------------------------------------
+// "Live" has ONE definition, shared with the lab's own pill (../src/shell/live-files.mjs). This
+// block used to read src/pages/index.astro alone, which is correct for a one-page site and wrong
+// for every client build — the same defect the pill carried until 2026-09-06. A second copy of a
+// rule like this is how the two quietly disagree, so it imports the helper rather than repeat it.
+const pages = sitePages(ROOT);
+if (pages.length === 0) die("no pages found under src/pages — cannot tell what is live");
+const live = new Map(); // file → why
+for (const page of pages) {
+  for (const dep of pageComponentFiles(ROOT, page)) {
+    if (!live.has(dep)) live.set(dep, `imported by ${page}`);
+    for (const inner of imports.get(dep) ?? [])
+      if (!live.has(inner)) live.set(inner, `imported by ${dep}, which ${page} imports`);
+  }
+}
+
+// ---- the marks ---------------------------------------------------------------------------------
+if (!existsSync(abs(CULL))) {
+  finish({ marked: [], entries: [], removal: [], kept: [], protectedKept: [], blockers: [], notes: [`${CULL} does not exist — nothing is marked`] });
+}
+// Read through the same helper the mark API writes with, so the two cannot disagree about shape.
+const cull = readCull(ROOT, CONFIG);
+const marked = [...new Set(cull.marked.map((p) => String(p).replace(/^\.\//, "").replace(/\\/g, "/")))];
+
+// The `component:` identifier at the top level of `export default { … }`, ignoring nested
+// braces, then the `import X from "./X.astro"` that names it.
+function componentOf(storiesRel) {
+  const src = stripComments(read(storiesRel));
+  const start = src.search(/export\s+default\s*\{/);
+  if (start < 0) return { error: "no `export default { … }`" };
+  let depth = 0;
+  let topLevel = "";
+  for (let i = src.indexOf("{", start); i < src.length; i++) {
+    const ch = src[i];
+    if (ch === "{" || ch === "[") depth++;
+    else if (ch === "}" || ch === "]") {
+      depth--;
+      if (depth === 0) break;
+    } else if (depth === 1) topLevel += ch;
+  }
+  const name = topLevel.match(/\bcomponent\s*:\s*([A-Za-z_$][\w$]*)/)?.[1];
+  if (!name) return { error: "no `component: X` in the default export" };
+  const specifier = src.match(new RegExp(`\\bimport\\s+${name}\\s+from\\s+["']([^"'\\n]+\\.astro)["']`))?.[1];
+  if (!specifier) return { error: `no \`import ${name} from "…astro"\` to follow` };
+  const target = resolveSpecifier(abs(storiesRel), specifier);
+  if (!target) return { error: `component import "${specifier}" resolves to nothing` };
+  const inside = relative(dirname(abs(storiesRel)), target);
+  if (inside.startsWith("..")) return { error: `component "${specifier}" lives outside the stories file's directory` };
+  return { component: rel(target) };
+}
+
+const entries = []; // { stories, component?, blocker? }
+for (const stories of marked) {
+  const entry = { stories };
+  entries.push(entry);
+  if (!stories.startsWith(LAB) || !stories.endsWith(".stories.ts")) {
+    entry.blocker = `not a ${LAB}**/*.stories.ts path`;
+    continue;
+  }
+  // Ruled 2026-09-05: deletion is restricted to the explorations tier — section versions are the
+  // version history and components are shared chrome; neither is ever culled, whatever the marks say.
+  // Which tier that is comes from the consumer's `tiers` option, through the shared defaults.
+  if (!CONFIG.cullDir || !stories.startsWith(CONFIG.cullDir)) {
+    entry.blocker = `only the ${CONFIG.cullTier ?? "(none)"} tier can be culled — section versions and components stay`;
+    continue;
+  }
+  if (!existsSync(abs(stories)) || !statSync(abs(stories)).isFile()) {
+    entry.blocker = "file does not exist";
+    continue;
+  }
+  if (isProtected(stories)) {
+    entry.blocker = "protected path";
+    continue;
+  }
+  const parsed = componentOf(stories);
+  if (parsed.error) {
+    entry.blocker = parsed.error;
+    continue;
+  }
+  entry.component = parsed.component;
+  if (isProtected(entry.component)) entry.blocker = `component ${entry.component} is protected`;
+  else if (live.has(entry.component)) entry.blocker = `component ${entry.component} is LIVE — ${live.get(entry.component)}`;
+}
+
+// An unmarked importer outside the removal set blocks the entry. Blocking one entry shrinks the
+// set, which can expose another, so iterate to a fixed point.
+let changed = true;
+while (changed) {
+  changed = false;
+  const seeds = new Set(entries.filter((e) => !e.blocker).flatMap((e) => [e.stories, e.component]));
+  for (const entry of entries) {
+    if (entry.blocker) continue;
+    for (const seed of [entry.component, entry.stories]) {
+      const outside = [...importersOf(seed)].filter((i) => !seeds.has(i)).sort();
+      if (outside.length) {
+        entry.blocker = `${seed === entry.stories ? "stories file" : "component " + seed} is still imported by unmarked ${outside.join(", ")}`;
+        changed = true;
+        break;
+      }
+    }
+  }
+}
+
+// ---- closure: what only the removal set imports ------------------------------------------------
+// A `.d.ts` beside a `.js` of the same name is that file's type sidecar (the vendored
+// html-to-image ships one per module); nothing imports it, so it rides along with its .js.
+const companionsOf = (file) => {
+  const dts = file.replace(/\.m?js$/, ".d.ts");
+  return dts !== file && existsSync(abs(dts)) ? [dts] : [];
+};
+const removal = new Set(entries.filter((e) => !e.blocker).flatMap((e) => [e.stories, e.component]));
+const kept = new Map(); // file → importers outside the set
+const protectedKept = new Map(); // file → files in the set that import it
+changed = true;
+while (changed) {
+  changed = false;
+  for (const file of [...removal]) {
+    for (const dep of [...(imports.get(file) ?? []), ...companionsOf(file)]) {
+      if (removal.has(dep)) continue;
+      if (isProtected(dep)) {
+        if (!protectedKept.has(dep)) protectedKept.set(dep, new Set());
+        protectedKept.get(dep).add(file);
+        continue;
+      }
+      const outside = [...importersOf(dep)].filter((i) => !removal.has(i)).sort();
+      if (outside.length) kept.set(dep, outside);
+      else {
+        removal.add(dep);
+        kept.delete(dep);
+        changed = true;
+      }
+    }
+  }
+}
+
+// A vendored library whose every file goes leaves its LICENSE behind on purpose — say so.
+const notes = [];
+const vendorDir = abs(`${LAB}vendor`);
+if (existsSync(vendorDir))
+  for (const lib of readdirSync(vendorDir)) {
+    const libDir = join(vendorDir, lib);
+    if (!statSync(libDir).isDirectory()) continue;
+    const files = walkAll(libDir).map(rel);
+    const code = files.filter((f) => !isProtected(f));
+    if (code.length && code.every((f) => removal.has(f)))
+      notes.push(`${LAB}vendor/${lib}/ empties out — its LICENSE stays (protected); delete it by hand if the library is truly gone`);
+  }
+function walkAll(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    statSync(full).isDirectory() ? walkAll(full, out) : out.push(full);
+  }
+  return out;
+}
+
+const plan = {
+  marked,
+  entries,
+  removal: [...removal].sort(),
+  kept: [...kept].map(([file, by]) => ({ file, importedBy: by })).sort((a, b) => a.file.localeCompare(b.file)),
+  protectedKept: [...protectedKept].map(([file, by]) => ({ file, importedBy: [...by].sort() })).sort((a, b) => a.file.localeCompare(b.file)),
+  blockers: entries.filter((e) => e.blocker).map((e) => ({ entry: e.stories, reason: e.blocker })),
+  notes,
+};
+
+// ---- perform -----------------------------------------------------------------------------------
+if (YES && plan.blockers.length === 0 && plan.removal.length) {
+  const tracked = new Set(git("ls-files", "-z", "--", ...plan.removal).split("\0").filter(Boolean));
+  const viaGit = plan.removal.filter((f) => tracked.has(f));
+  const viaDisk = plan.removal.filter((f) => !tracked.has(f));
+  if (viaGit.length) git("rm", "-q", "--", ...viaGit);
+  for (const f of viaDisk) rmSync(abs(f));
+
+  const processed = new Set(entries.filter((e) => !e.blocker).map((e) => e.stories));
+  const remaining = cull.marked.filter((p) => !processed.has(String(p).replace(/^\.\//, "").replace(/\\/g, "/")));
+  writeFileSync(abs(CULL), JSON.stringify({ marked: remaining, updated: new Date().toISOString() }, null, 2) + "\n");
+  const cullTracked = git("ls-files", "--", CULL).trim() !== "";
+  if (cullTracked) git("add", "--", CULL);
+
+  const now = new Date();
+  const date = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+  const names = entries.filter((e) => !e.blocker).map((e) => e.component.replace(/^.*\//, "").replace(/\.astro$/, ""));
+  plan.performed = {
+    gitRm: viaGit,
+    deletedUntracked: viaDisk,
+    marksCleared: processed.size,
+    marksRemaining: remaining.length,
+    cullJsonStaged: cullTracked,
+    buildLogLine: `#### ${date} · [WILL] Lab cull — ${names.length} item${names.length === 1 ? "" : "s"} removed: ${names.join(", ")}`,
+  };
+}
+
+finish(plan);
+
+// ---- report ------------------------------------------------------------------------------------
+function finish(p) {
+  const exitCode = p.blockers.length ? 2 : 0;
+  if (JSON_OUT) {
+    console.log(JSON.stringify({ ok: exitCode === 0, dryRun: !p.performed, ...p, unresolved }, null, 2));
+    process.exit(exitCode);
+  }
+
+  const list = (items, render = (x) => x) => items.forEach((i) => console.log("  " + render(i)));
+  const header = p.performed
+    ? "lab cull — performed"
+    : YES && p.blockers.length
+      ? "lab cull — REFUSED (blockers below; nothing removed)"
+      : YES
+        ? "lab cull — nothing to perform"
+        : "lab cull — dry run (pass --yes to perform)";
+  console.log(header);
+  console.log(`marked: ${p.marked.length} entr${p.marked.length === 1 ? "y" : "ies"} in ${CULL}`);
+  if (p.marked.length === 0) {
+    p.notes.forEach((n) => console.log("  " + n));
+    console.log("  ok   nothing marked — nothing to do");
+    process.exit(0);
+  }
+
+  console.log(`\nremove (${p.removal.length}):`);
+  list(p.removal);
+  console.log(`\nkept — still imported by unmarked files (${p.kept.length}):`);
+  list(p.kept, (k) => `${k.file}  ← ${k.importedBy.join(", ")}`);
+  console.log(`\nkept (protected) (${p.protectedKept.length}):`);
+  list(p.protectedKept, (k) => `${k.file}  ← ${k.importedBy.join(", ")}`);
+  console.log(`\nblockers (${p.blockers.length}):`);
+  p.blockers.forEach((b) => console.error(`  FAIL ${b.entry} — ${b.reason}`));
+  if (p.notes.length) {
+    console.log("\nnotes:");
+    list(p.notes);
+  }
+  if (unresolved.length) {
+    console.log(`\nunresolved relative imports (${unresolved.length}) — treated as nothing, check them:`);
+    list(unresolved, (u) => `${u.file} → "${u.specifier}"`);
+  }
+
+  console.log("");
+  if (p.performed) {
+    const r = p.performed;
+    console.log(`  ok   git rm (staged, not committed): ${r.gitRm.length} file${r.gitRm.length === 1 ? "" : "s"}`);
+    if (r.deletedUntracked.length) console.log(`  ok   deleted from disk (were untracked): ${r.deletedUntracked.join(", ")}`);
+    console.log(`  ok   ${CULL}: ${r.marksCleared} mark${r.marksCleared === 1 ? "" : "s"} cleared, ${r.marksRemaining} left${r.cullJsonStaged ? ", staged" : " (untracked, not staged)"}`);
+    console.log("\nBuild-log line — paste it, this script edits no log and commits nothing:\n");
+    console.log(r.buildLogLine);
+  } else if (exitCode === 2) {
+    console.log(YES ? "  FAIL refusing --yes while blockers stand — clear them (unmark, or unmark the importer too) and rerun" : "  FAIL plan has blockers — --yes would be refused");
+  } else if (p.removal.length) {
+    console.log(`  ok   plan is clean — ${p.removal.length} file${p.removal.length === 1 ? "" : "s"} would be removed`);
+  } else {
+    console.log("  ok   nothing to remove");
+  }
+  process.exit(exitCode);
+}

package/bin/pin-gallery.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// pin-gallery — render every pin ticket as ONE standalone kanban on disk.
+//
+// The board itself lives at `/pin` on `astro dev` now, generated from `backlog/tasks/` on every
+// request, so looking at it is a refresh and this script is no longer part of that loop. What it
+// is still for is the file: a page that opens with no dev server running — on a plane, on another
+// machine, attached to a message — and a snapshot of the board at a moment in time.
+//
+// The snapshot is READ-ONLY, and that falls out of one argument rather than a flag: the board is
+// writable exactly when `renderBoard` is given an endpoint to write to, and a `file://` page has
+// nothing listening behind it. So this call passes none, the page renders with no drag handlers
+// and no status menus, and there is no second, quieter copy of the write path to keep in step.
+// Search and the detail panel still work offline, because both are pure client-side reads.
+//
+//   npx orbytes-pin-gallery                      # → backlog/gallery.html
+//   npx orbytes-pin-gallery --out x.html
+//   npx orbytes-pin-gallery --backlog-dir feedback   # a site that moved its board
+//
+// IT RUNS IN THE CONSUMER'S REPO, NOT ITS OWN — the same rule as ./lab-cull.mjs, and for the same
+// reason. The root is walked up from `process.cwd()`, never from this file's location, which since
+// the merge into @orbytes/astrolab (2026-09-22) is somewhere under the consumer's node_modules and,
+// when the package is workspace-linked, resolves to THIS repo instead of theirs. A gallery of the
+// lab's own (empty) backlog, written into the lab's own checkout, would exit 0 and look fine.
+//
+// EVERY line of the board — the parser, the cards, the columns, the CSS — comes from
+// `../src/pin/board.mjs`, which the `/pin` board renders with as well. Nothing about a ticket is read
+// or drawn here. That is the whole shape of this file, and it is not a preference: this script
+// carried its own copy of the parsing and rendering until 2026-09-21 and that copy produced three
+// separate bugs, each of them a drift from the package's own reader — a frontmatter parser that
+// went on reading frontmatter after the pin data moved into the body, a block-scalar reader that
+// mangled long titles, and a fence-stripping regex that ate every word after a quoted CSS rule.
+// A second implementation of this page would be the fourth. Add nothing here; add it to board.mjs.
+//
+// The page opens straight from file:// — image sources stay relative to the output file, so the
+// HTML stays a few KB and the (gitignored) PNGs are never inlined.
+
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+// `../src/pin/board.mjs` and not the package root: the root pulls in the lab, which imports
+// TypeScript the consumer's Vite compiles and plain Node cannot. The board module is dependency-
+// free by design, and it does not reach shot.mjs — so a static HTML renderer needs no browser and
+// no bundler to run.
+import { collectTickets, renderBoard, findRepoRoot } from "../src/pin/board.mjs";
+
+const REPO = findRepoRoot(process.cwd());
+
+/* -------------------------------------------------------------------- main */
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+	const at = args.indexOf(name);
+	return at !== -1 && args[at + 1] ? args[at + 1] : null;
+};
+
+// The board directory, and the reason this flag exists at all.
+//
+// A binary cannot read the integration's options — it runs in a different process, from a shell,
+// with nothing but a cwd. Until 2026-09-22 it did not try: `collectTickets(REPO)` took the
+// DEFAULT `backlog`, and the output path said `backlog` as a literal. A site that configured
+// `pin: { backlogDir: "feedback" }` therefore had its gallery read an empty directory, print
+// `0 ticket(s)`, write a page with nothing on it and EXIT 0 — the failure looked like a site with
+// no tickets, which is a thing that happens. So the directory is an argument now, it is used for
+// both the read and the default output path, and the two cannot drift.
+const backlogDir = flag("--backlog-dir") ?? "backlog";
+const outPath = flag("--out")
+	? resolve(process.cwd(), flag("--out"))
+	: join(REPO, backlogDir, "gallery.html");
+
+// `includeCancelled`: this file is the offline twin of `/pin`, so it shows what `/pin` shows —
+// archive rail included. The default is the other way round precisely because every OTHER reader
+// is agent-facing, and a cancelled ticket must not reach an agent's context (ruled 2026-09-22).
+const { tickets, broken, paths } = collectTickets(REPO, { backlogDir, includeCancelled: true });
+
+// The guard, and it runs BEFORE the write.
+//
+// Until 2026-09-21 this check sat *after* `writeFileSync`, so a run that hit an unreadable ticket
+// wrote a complete-looking wall to disk and then exited 1. The exit code is gone the moment the
+// shell moves on; the file stays, looking finished, silently short one ticket — for whoever opens
+// it next, and for anything that reads it. That is a warning wearing a guard's clothes, and the
+// build contract forbids it: a check that cannot pass writes nothing.
+//
+// Refusing means refusing outright. No partial page, no banner-only page. Any gallery.html already
+// on disk is left exactly as it was — stale, but the message below says so in as many words, which
+// is the difference between a stale file and a lie.
+//
+// The `/pin` board does the opposite and shows the panel instead, because a live page that refuses is a
+// blank screen with nothing to act on. A file that refuses is simply the file you already had.
+if (broken.length) {
+	console.error(`pin-gallery: refusing to write — ${broken.length} ticket(s) could not be read:`);
+	for (const b of broken) console.error(`  ${b.file}: ${b.reason}`);
+	console.error(`  ${tickets.length} readable ticket(s) were NOT written anywhere.`);
+	console.error(`  An agent reading the board hits the same wall: listTickets() throws on the first`);
+	console.error(`  of these and returns no tickets at all. Fix the ticket(s) and run again.`);
+	console.error(`  The /pin board lists them by name on the dev server, if it is running.`);
+	if (existsSync(outPath)) {
+		const stamp = statSync(outPath).mtime.toLocaleString("en-AU", { dateStyle: "medium", timeStyle: "short" });
+		console.error(`  ${relative(REPO, outPath) || outPath} was left untouched (written ${stamp}) and is now out of date.`);
+	}
+	process.exit(1);
+}
+
+// Relative to the OUTPUT FILE, not to backlog/ — the two are the same place by default, and this
+// is what makes `--out` somewhere else produce a page whose pictures still load.
+const outDir = dirname(outPath);
+const assetHref = (t) => (t.shotAbs ? relative(outDir, t.shotAbs).split(sep).join("/") : null);
+
+// The directory may not exist yet: on a fresh install `backlog/` is only created when the first
+// ticket is written, and this command can run before that — or be pointed somewhere else entirely
+// with `--out`. Measured 2026-09-22 on a clean project: without this the command died with a raw
+// `ENOENT ... open 'backlog/gallery.html'` stack trace. Its sibling `orbytes-lab-cull` already
+// handles the same case.
+mkdirSync(outDir, { recursive: true });
+writeFileSync(outPath, renderBoard(tickets, broken, { assetHref }), "utf8");
+
+const missing = tickets.filter((t) => !assetHref(t)).length;
+console.log(`pin-gallery: ${tickets.length} ticket(s), ${missing} without a screenshot`);
+console.log(`  → ${relative(REPO, outPath) || outPath}`);
+console.log(`  read from ${relative(REPO, paths.tasks)}`);
+console.log(`  the live board is /pin on the dev server; this file is the read-only standalone copy`);
+if (!existsSync(paths.assets)) console.log(`  note: ${relative(REPO, paths.assets)} does not exist yet`);

package/defaults.mjs

@@ -0,0 +1,120 @@
+// The lab's defaults and the one option resolver — imported by the integration (./index.mjs) and
+// by the cull binary (./bin/lab-cull.mjs), so a path the lab writes and a path the cull script
+// reads can never drift. Dependency-free: the binary runs in plain Node, outside Vite.
+//
+// Everything `resolveLabOptions` returns is JSON-serialisable on purpose. It is handed to the
+// package's own .astro pages through the `virtual:orbytes-lab/config.mjs` module the integration
+// defines, and a function could not survive that trip — which is why `previewUrlTemplate` is a
+// string with a {branch} placeholder rather than a callback.
+
+/** Where the consumer keeps its stories, repo-relative. */
+export const DEFAULT_DIRECTORY = "src/lab";
+
+/** Where the lab is served from. */
+export const DEFAULT_SUBPATH = "/lab";
+
+export const DEFAULT_TITLE = "Component lab";
+
+/**
+ * The orbytes convention: page sections, shared components, and throwaway experiments. Tier names
+ * are a convention, not a law — pass `tiers` to rename, reorder or drop them.
+ */
+export const DEFAULT_TIERS = ["sections", "components", "explorations"];
+
+/**
+ * What a tier NAMED like one of these does, unless the consumer says otherwise on the tier itself:
+ *
+ * - `responsive` — its stories are section versions: they carry the responsive mark (ticked by
+ *   hand in the sidebar, stored in `<directory>/responsive.json`) and they render at page width
+ *   in thumbnails and in the viewport configurator.
+ * - `cullable` — its stories may be marked for deletion (`<directory>/cull.json`, drained by
+ *   `orbytes-lab-cull`). Nothing else in the lab can be marked: version history and shared chrome
+ *   are never culled from a browser.
+ *
+ * At most one tier holds each role; the first one that claims it wins.
+ */
+export const TIER_ROLES = {
+  sections: { responsive: true },
+  explorations: { cullable: true },
+};
+
+/** `./src/lab/` and `src/lab` both mean `src/lab`. @param {string} value */
+export const normaliseDirectory = (value) =>
+  String(value)
+    .replace(/\\/g, "/")
+    .replace(/^\.\//, "")
+    .replace(/\/+$/, "");
+
+/** `lab`, `/lab` and `/lab/` all mean `/lab`; `""` means the site root. @param {string} value */
+export const normaliseSubpath = (value) => {
+  const trimmed = String(value).replace(/\\/g, "/").replace(/\/+$/, "");
+  if (!trimmed) return "";
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+};
+
+/**
+ * @typedef {object} LabTier
+ * @property {string} id             the first path segment under `directory`
+ * @property {string} label          shown on the tier card and the folder pages
+ * @property {boolean} responsive    section versions: responsive marks, page-width thumbnails
+ * @property {boolean} cullable      may be marked for deletion
+ */
+
+/** @param {string | Partial<LabTier>} tier @returns {LabTier} */
+const resolveTier = (tier) => {
+  const raw = typeof tier === "string" ? { id: tier } : { ...tier };
+  const id = String(raw.id ?? "");
+  const role = /** @type {Record<string, {responsive?: boolean, cullable?: boolean}>} */ (TIER_ROLES)[id] ?? {};
+  return {
+    id,
+    label: raw.label ?? (id ? id.charAt(0).toUpperCase() + id.slice(1) : "Root"),
+    responsive: raw.responsive ?? role.responsive ?? false,
+    cullable: raw.cullable ?? role.cullable ?? false,
+  };
+};
+
+/**
+ * @typedef {object} LabConfig
+ * @property {string} directory
+ * @property {string} subpath
+ * @property {string} title
+ * @property {string[]} css
+ * @property {string | null} stagingUrl
+ * @property {string | null} previewUrlTemplate
+ * @property {string | null} feedbucketKey
+ * @property {LabTier[]} tiers
+ * @property {string | null} sectionsTier   the id of the tier holding the responsive role
+ * @property {string | null} cullTier       the id of the tier holding the cull role
+ * @property {string | null} responsiveDir  `<directory>/<sectionsTier>/`, or null
+ * @property {string | null} cullDir        `<directory>/<cullTier>/`, or null
+ * @property {string} responsiveFile        `<directory>/responsive.json`
+ * @property {string} cullFile              `<directory>/cull.json`
+ */
+
+/**
+ * Fill in every default and derive the paths the lab reads and writes.
+ * @param {Record<string, unknown>} [options]
+ * @returns {LabConfig}
+ */
+export function resolveLabOptions(options = {}) {
+  const directory = normaliseDirectory(options.directory ?? DEFAULT_DIRECTORY);
+  const tiers = (Array.isArray(options.tiers) ? options.tiers : DEFAULT_TIERS).map(resolveTier);
+  const sections = tiers.find((tier) => tier.responsive) ?? null;
+  const cull = tiers.find((tier) => tier.cullable) ?? null;
+  return {
+    directory,
+    subpath: normaliseSubpath(options.subpath ?? DEFAULT_SUBPATH),
+    title: String(options.title ?? DEFAULT_TITLE),
+    css: Array.isArray(options.css) ? options.css.map(String) : [],
+    stagingUrl: options.stagingUrl ? String(options.stagingUrl) : null,
+    previewUrlTemplate: options.previewUrlTemplate ? String(options.previewUrlTemplate) : null,
+    feedbucketKey: options.feedbucketKey ? String(options.feedbucketKey) : null,
+    tiers,
+    sectionsTier: sections ? sections.id : null,
+    cullTier: cull ? cull.id : null,
+    responsiveDir: sections ? `${directory}/${sections.id}/` : null,
+    cullDir: cull ? `${directory}/${cull.id}/` : null,
+    responsiveFile: `${directory}/responsive.json`,
+    cullFile: `${directory}/cull.json`,
+  };
+}