@orbytes/astrolab 0.3.0

package/src/shell/live-files.mjs

@@ -0,0 +1,164 @@
+// Which lab components are LIVE on the site — derived from the pages under src/pages/, never declared.
+//
+// Dependency-free Node (fs + path only) on purpose: it is imported by three consumers that cannot
+// share a runtime — the build-time index (./lab-index.ts, inside Vite), the dev-only mark APIs
+// (../../index.mjs, a Vite middleware) and the cull binary (../../bin/lab-cull.mjs, plain Node).
+// One parser, so the three can never disagree about what "live" means.
+//
+// The rule: a component file is live when a page imports it AND mounts it as a tag. Slot is its
+// 1-based position among the mounted tags in that page's document order (the Footer sits outside
+// <main>, so the whole template is scanned, not just <main>). The page layout (src/layouts/) is a
+// wrapper, not a section, and is excluded — everything else the page mounts counts.
+//
+// EVERY page is walked, not just the home page (2026-09-06). orbytes.io is one page, but the lab
+// is a shared package every orbytes Astro site installs, and on a site with an /about page a
+// home-page-only reader reports nothing, or the wrong slot, for everything that is not on the
+// home page. Pages come home first, then alphabetically, so a component mounted on
+// several pages reports the home page's slot as its primary one.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+export const PAGES_DIR = "src/pages";
+export const HOME_PAGE = "src/pages/index.astro";
+
+/** @param {string} rootDir @param {string} absFile */
+export const toRepoRelative = (rootDir, absFile) =>
+  path.relative(rootDir, absFile).split(path.sep).join("/");
+
+/** The `---` fenced frontmatter of an .astro source, or "" when there is none. @param {string} source */
+export const frontmatterOf = (source) => {
+  const m = source.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return m ? m[1] : "";
+};
+
+/** Everything after the frontmatter fence (the template). @param {string} source */
+export const templateOf = (source) => {
+  const m = source.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
+  return m ? m[1] : source;
+};
+
+/**
+ * Every `import Name from "<relative>"` in a source file, resolved to repo-relative paths.
+ * For .astro files only the frontmatter is read; for .ts/.mjs the whole file. Package and
+ * virtual-module imports are skipped — they are not files in this repo.
+ * @param {string} rootDir absolute repo root
+ * @param {string} fileRel repo-relative path of the file to read
+ * @returns {{ name: string; file: string }[]}
+ */
+export function defaultImports(rootDir, fileRel) {
+  const abs = path.join(rootDir, fileRel);
+  if (!existsSync(abs)) return [];
+  const source = readFileSync(abs, "utf8");
+  const code = fileRel.endsWith(".astro") ? frontmatterOf(source) : source;
+  /** @type {{ name: string; file: string }[]} */
+  const out = [];
+  const re = /^\s*import\s+([A-Za-z_$][\w$]*)\s+from\s+["']([^"']+)["']/gm;
+  let m;
+  while ((m = re.exec(code))) {
+    const spec = m[2];
+    if (!spec.startsWith(".")) continue;
+    out.push({ name: m[1], file: toRepoRelative(rootDir, path.resolve(path.dirname(abs), spec)) });
+  }
+  return out;
+}
+
+/**
+ * Every routable page under src/pages, repo-relative, home page first then alphabetical.
+ * A name starting with `_` (or `.`) is skipped, file or directory, exactly as Astro's own router
+ * skips it — `src/pages/_partials/Card.astro` is not a route and must never claim a slot.
+ * @param {string} rootDir absolute repo root
+ * @returns {string[]}
+ */
+export function sitePages(rootDir) {
+  /** @type {string[]} */
+  const out = [];
+  /** @param {string} rel */
+  const walk = (rel) => {
+    const abs = path.join(rootDir, rel);
+    if (!existsSync(abs)) return;
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      if (entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+      const child = `${rel}/${entry.name}`;
+      if (entry.isDirectory()) walk(child);
+      else if (entry.name.endsWith(".astro")) out.push(child);
+    }
+  };
+  walk(PAGES_DIR);
+  return out.sort((a, b) => (a === HOME_PAGE ? -1 : b === HOME_PAGE ? 1 : a.localeCompare(b)));
+}
+
+/**
+ * The route a page file serves: index.astro → "/", about.astro → "/about", blog/index.astro →
+ * "/blog". A dynamic route keeps its brackets ("/[slug]") — this is a label for a pill, not a URL.
+ * @param {string} pageRel repo-relative path under src/pages
+ */
+export const pageRoute = (pageRel) => {
+  const rel = pageRel.slice(PAGES_DIR.length + 1).replace(/\.astro$/, "");
+  const route = rel.replace(/(^|\/)index$/, "");
+  return `/${route}`.replace(/\/{2,}/g, "/");
+};
+
+/**
+ * The component files one page mounts, in document order.
+ * @param {string} rootDir absolute repo root
+ * @param {string} pageRel repo-relative path of the page
+ * @returns {string[]}
+ */
+export function pageComponentFiles(rootDir, pageRel) {
+  const abs = path.join(rootDir, pageRel);
+  if (!existsSync(abs)) return [];
+  const source = readFileSync(abs, "utf8");
+  const byName = new Map(
+    defaultImports(rootDir, pageRel)
+      .filter((i) => i.file.endsWith(".astro") && !i.file.startsWith("src/layouts/"))
+      .map((i) => [i.name, i.file]),
+  );
+  // HTML and JSX comments name components in prose (the order table does) — strip them first.
+  const template = templateOf(source)
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/\{\/\*[\s\S]*?\*\/\}/g, "");
+  /** @type {string[]} */
+  const mounted = [];
+  const re = /<([A-Z][\w$]*)(?=[\s/>])/g;
+  let m;
+  while ((m = re.exec(template))) {
+    const file = byName.get(m[1]);
+    if (file && !mounted.includes(file)) mounted.push(file);
+  }
+  return mounted;
+}
+
+/**
+ * Every live mount on the site: one entry per (page, component), pages in `sitePages` order and
+ * components in each page's document order. `of` is how many components that page mounts, so a
+ * slot reads "slot 3 of 12" without a second pass, and a two-page site never mixes the two counts.
+ * @param {string} rootDir absolute repo root
+ * @returns {{ file: string; page: string; slot: number; of: number }[]}
+ */
+export function liveComponentFiles(rootDir) {
+  /** @type {{ file: string; page: string; slot: number; of: number }[]} */
+  const out = [];
+  for (const pageRel of sitePages(rootDir)) {
+    const files = pageComponentFiles(rootDir, pageRel);
+    const page = pageRoute(pageRel);
+    files.forEach((file, i) => out.push({ file, page, slot: i + 1, of: files.length }));
+  }
+  return out;
+}
+
+/**
+ * The .astro file a stories module renders — the identifier on `component:` in its default
+ * export, followed back to its import. Null when the file is missing or the shape is unfamiliar.
+ * @param {string} rootDir absolute repo root
+ * @param {string} storiesRel repo-relative path of the *.stories.ts file
+ * @returns {string | null}
+ */
+export function storyComponentFile(rootDir, storiesRel) {
+  const abs = path.join(rootDir, storiesRel);
+  if (!existsSync(abs)) return null;
+  const source = readFileSync(abs, "utf8");
+  const m = source.match(/export\s+default\s*\{[\s\S]*?\bcomponent\s*:\s*([A-Za-z_$][\w$]*)/);
+  if (!m) return null;
+  const hit = defaultImports(rootDir, storiesRel).find((i) => i.name === m[1]);
+  return hit ? hit.file : null;
+}

package/src/shell/marks.mjs

@@ -0,0 +1,136 @@
+// The lab's hand-set marks — everything a person ticks in the sidebar rather than something the
+// lab derives, plus the one path rule both mark files obey.
+//
+//   <directory>/responsive.json   { "done": string[], "approved": string[], "updated": string|null }
+//   <directory>/cull.json         { "marked": string[], "updated": string|null }
+//
+// Both are keyed by the story module's repo-relative path
+// (`<directory>/<tier>/…/<Name>.stories.ts`) — one row means one key everywhere — and both are
+// validated through `pathOffence` below, so they can never disagree about what a markable row is.
+//
+// Why the responsive state is marked and not measured: responsive work is approval-gated and
+// final-versions-only (ruled 2026-09-06) — a version is worked on only once it has been approved
+// for responsiveness, approval is NOT the same as the version being final, and that approval can
+// be withdrawn later. Neither fact is readable from the code, so both are ticked here.
+//
+// Dependency-free Node (fs + path only) on purpose: this module is imported inside Vite
+// (./lab-index.ts, at build), by a plain Vite middleware (../../index.mjs) and by the cull binary
+// (../../bin/lab-cull.mjs, plain Node). One parser, three runtimes.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** @typedef {import("../../defaults.mjs").LabConfig} LabConfig */
+
+/** A story module inside the lab directory: the only thing any mark may name. */
+export const storiesPattern = (directory) =>
+  new RegExp(`^${directory.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/(?:[\\w.-]+/)*[\\w.-]+\\.stories\\.ts$`);
+
+/**
+ * Why `entry` is not a markable story module under `tier`, or null when it is.
+ * @param {string} rootDir absolute repo root
+ * @param {LabConfig} config
+ * @param {unknown} entry
+ * @param {string | null} tier repo-relative directory prefix the mark is restricted to
+ * @param {string} tierReason what to say when the entry is outside that tier
+ * @returns {string | null}
+ */
+export const pathOffence = (rootDir, config, entry, tier, tierReason) => {
+  if (typeof entry !== "string") return "not a string";
+  if (!storiesPattern(config.directory).test(entry) || entry.includes(".."))
+    return `not a ${config.directory}/**/*.stories.ts path`;
+  if (!tier) return tierReason;
+  if (!entry.startsWith(tier)) return tierReason;
+  if (!existsSync(path.join(rootDir, entry))) return "no such file";
+  return null;
+};
+
+/** @param {string} rootDir @param {LabConfig} config @param {unknown} entry */
+export const responsiveOffence = (rootDir, config, entry) =>
+  pathOffence(
+    rootDir,
+    config,
+    entry,
+    config.responsiveDir,
+    "only section versions can be marked responsive",
+  );
+
+/** @param {string} rootDir @param {LabConfig} config @param {unknown} entry */
+export const cullOffence = (rootDir, config, entry) =>
+  pathOffence(rootDir, config, entry, config.cullDir, "only the explorations tier can be marked");
+
+/** @param {unknown} value */
+const stringList = (value) =>
+  Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+
+/** @param {string} rootDir @param {string} file */
+const readJson = (rootDir, file) => {
+  const abs = path.join(rootDir, file);
+  if (!existsSync(abs)) return null;
+  try {
+    return JSON.parse(readFileSync(abs, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The responsive marks as written. Missing or unreadable file → empty, never a throw: the lab
+ * renders the same either way, it just shows everything as not responsive.
+ * @param {string} rootDir absolute repo root
+ * @param {LabConfig} config
+ * @returns {{ done: string[]; approved: string[]; updated: string | null }}
+ */
+export function readResponsive(rootDir, config) {
+  const data = readJson(rootDir, config.responsiveFile);
+  if (!data) return { done: [], approved: [], updated: null };
+  return {
+    done: stringList(data.done),
+    approved: stringList(data.approved),
+    updated: typeof data.updated === "string" ? data.updated : null,
+  };
+}
+
+/**
+ * Replace the responsive marks. Both lists are de-duplicated and sorted so the tracked file's diff
+ * is the change and nothing else.
+ * @param {string} rootDir absolute repo root
+ * @param {LabConfig} config
+ * @param {string[]} done
+ * @param {string[]} approved
+ */
+export function writeResponsive(rootDir, config, done, approved) {
+  const data = {
+    done: [...new Set(done)].sort(),
+    approved: [...new Set(approved)].sort(),
+    updated: new Date().toISOString(),
+  };
+  writeFileSync(path.join(rootDir, config.responsiveFile), JSON.stringify(data, null, 2) + "\n");
+  return data;
+}
+
+/**
+ * The cull marks as written.
+ * @param {string} rootDir absolute repo root
+ * @param {LabConfig} config
+ * @returns {{ marked: string[]; updated: string | null }}
+ */
+export function readCull(rootDir, config) {
+  const data = readJson(rootDir, config.cullFile);
+  if (!data) return { marked: [], updated: null };
+  return {
+    marked: stringList(data.marked),
+    updated: typeof data.updated === "string" ? data.updated : null,
+  };
+}
+
+/**
+ * Replace the cull marks.
+ * @param {string} rootDir absolute repo root
+ * @param {LabConfig} config
+ * @param {string[]} marked
+ */
+export function writeCull(rootDir, config, marked) {
+  const data = { marked: [...new Set(marked)].sort(), updated: new Date().toISOString() };
+  writeFileSync(path.join(rootDir, config.cullFile), JSON.stringify(data, null, 2) + "\n");
+  return data;
+}

package/src/types/index.ts

@@ -0,0 +1,6 @@
+// Vendored from astrobook 0.13.3 (packages/types/lib/index.d.ts + index.js) — see
+// ../core/LICENSE-astrobook. Upstream splits this into a `.d.ts` that re-exports and an
+// `index.js` that is `export {}`; one `.ts` does both jobs here, because nothing bundles.
+/// <reference path="./virtual.d.ts" />
+
+export type * from './types.ts'

package/src/types/types.ts

@@ -0,0 +1,239 @@
+// Vendored from astrobook 0.13.3 (packages/types/lib/types.d.ts) — see ../core/LICENSE-astrobook.
+// Divergence: `.d.ts` → `.ts`, so the vendored core can import these by relative path without
+// `allowImportingTsExtensions` gymnastics. The body is interfaces and one `declare global` only,
+// so it emits nothing at runtime and every importer uses `import type`.
+// Divergence: the option doc comments upstream carries for options this package does not expose
+// are kept verbatim — they document the vendored core's own behaviour, which is unchanged.
+
+export interface IntegrationOptions {
+  /**
+   * The directory to scan for stories.
+   *
+   * @default '.'
+   */
+  directory?: string
+
+  /**
+   * The subpath to deploy Astrobook to relative to the [base
+   * URL](https://docs.astro.build/en/reference/configuration-reference/#base)
+   * of your Astro project.
+   */
+  subpath?: string
+
+  /**
+   * The subpath for dashboard pages relative to the main subpath.
+   * A dashboard page has a sidebar for navigation between components.
+   *
+   * @default '/dashboard/'
+   */
+  dashboardSubpath?: string
+
+  /**
+   * The subpath for preview pages relative to the main subpath.
+   * A preview page displays an individual component without the sidebar.
+   *
+   * @default '/stories/'
+   */
+  previewSubpath?: string
+
+  /**
+   * Set the title for your website. Will be used in metadata and in the browser tab title.
+   *
+   * @default 'Astrobook'
+   */
+  title?: string
+
+  /**
+   * Provide CSS files to customize the look and feel of your Astrobook project.
+   *
+   * Supports local CSS files relative to the root of your project,
+   * e.g. `'./src/custom.css'`, and CSS you installed as an npm
+   * module, e.g. `'@fontsource/roboto'`.
+   *
+   * In this package these files reach the PREVIEW only — the story render — never the lab's own
+   * chrome (decided 2026-09-22). See src/ui/lab.css.
+   */
+  css?: string[]
+
+  /**
+   * The path to an Astro component to provide custom tags in the `<head>`.
+   * It can be an `.astro` or `.html` file.
+   */
+  head?: string
+
+  /**
+   * Controls which Astro component is rendered on the dashboard homepage.
+   *
+   * - Pass a string (relative path or package identifier) to fully replace
+   *   the built-in home page with a custom Astro component.
+   * - Pass `false` to render an empty home page.
+   * - Omit the option to use Astrobook's built-in home.
+   *
+   * @default 'astrobook/components/home.astro'
+   */
+  home?: string | false
+
+  /**
+   * Customize the content of Astrobook's built-in home page (title, subtitle,
+   * version badge, GitHub badge).
+   */
+  homeContent?: HomeContentOptions
+}
+
+/**
+ * Options for customizing the content of the built-in home page.
+ */
+export interface HomeContentOptions {
+  /**
+   * The main title shown on the home page. Set to `false` to hide.
+   * @default 'Astrobook'
+   */
+  title?: string | false
+
+  /**
+   * The subtitle shown beneath the title. Set to `false` to hide.
+   * @default 'The minimal UI component playground'
+   */
+  subtitle?: string | false
+
+  /** Configuration for the version badge. Set to `false` to hide. */
+  version?: HomeVersionOptions | false
+
+  /** Configuration for the GitHub repository badge. Set to `false` to hide. */
+  repo?: HomeRepoOptions | false
+}
+
+export interface HomeVersionOptions {
+  /** The URL the version badge links to. */
+  href?: string
+
+  /** The label rendered inside the version badge. */
+  label?: string
+}
+
+export interface HomeRepoOptions {
+  /** The URL the repository badge links to. */
+  href?: string
+
+  /**
+   * The label rendered inside the repository badge.
+   * @default 'Star on GitHub'
+   */
+  label?: string
+}
+
+export interface StoryModule {
+  /**
+   * The id of the story module.
+   *
+   * @example 'components/ui/button'
+   */
+  id: string
+
+  /**
+   * The name of the story module.
+   *
+   * @example 'Button'
+   */
+  name: string
+
+  /**
+   * The directory of the story module. It might be an empty string.
+   *
+   * @example 'components/ui'
+   */
+  directory: string
+
+  /**
+   * The import path of the story module.
+   *
+   * @example '/Users/john/projects/my-project/components/ui/Button.stories.js'
+   * @example '../ui/Button.stories.ts'
+   */
+  importPath: string
+
+  /** All stories in the story module. */
+  stories: Story[]
+}
+
+export interface Story {
+  /**
+   * The id of the story.
+   *
+   * @example 'components/ui/button/primary-button'
+   */
+  id: string
+
+  /**
+   * The name of the story.
+   *
+   * @example 'PrimaryButton'
+   */
+  name: string
+}
+
+export interface GlobalConfig {
+  /**
+   * The computed base URL path for Astrobook, combining the Astro base URL with
+   * the optional subpath.
+   */
+  astrobookBase: string
+  dashboardBase: string
+  storyBase: string
+
+  /** The path to an Astro component to provide custom tags in the `<head>`. */
+  head: string
+
+  /**
+   * The path to an Astro component to render on dashboard homepage.
+   * @default astrobook/components/home.astro
+   */
+  home: string
+
+  /**
+   * The fully resolved content for the built-in home page. When the user
+   * provides a custom `home` component path or `home: false`, this still
+   * holds the default values but is not consumed by the rendered component.
+   */
+  homeContent: {
+    title: string | false
+    subtitle: string | false
+    version: { href: string; label: string } | false
+    repo: { href: string; label: string } | false
+  }
+
+  /** Array of CSS file paths to import into the PREVIEW. */
+  css: string[]
+
+  /** The title for the Astrobook website. */
+  title: string
+
+  trailingSlash: import('astro').AstroConfig['trailingSlash']
+}
+
+/** @internal */
+export interface StoryDecorator {
+  /** The component to use as a decorator. */
+  component: unknown
+
+  /** The props to pass to the decorator. */
+  props?: object | null | undefined
+}
+
+/** @internal */
+export interface StoryNamedExport {
+  /** The decorators to apply to the story. */
+  decorators?: StoryDecorator[] | null | undefined
+
+  /** The arguments to pass to the story. */
+  args?: object | null | undefined
+}
+
+declare global {
+  interface Window {
+    astrobook?: {
+      setTheme?: (theme: 'dark' | 'light') => void
+      getTheme?: () => 'dark' | 'light'
+    }
+  }
+}

package/src/types/virtual.d.ts

@@ -0,0 +1,29 @@
+// Vendored from astrobook 0.13.3 (packages/types/lib/virtual.d.ts) — see ../core/LICENSE-astrobook.
+// Divergence: `./types` → `./types.js`, which is how TypeScript's node16/bundler resolution names
+// the sibling `types.ts` module.
+//
+// THE IDS BELOW ARE UPSTREAM'S, BYTE FOR BYTE, AND MUST STAY THAT WAY. The vendored core emits
+// them (src/core/virtual-module/virtual-module-ids.ts) and the vendored UI imports them by name;
+// renaming both sides is possible now that we own both, but it is pure churn with silent-breakage
+// risk, so it is later cleanup and not part of this pass.
+declare module 'virtual:astrobook/story-modules.mjs' {
+  const entries: import('./types.js').StoryModule[]
+  export default entries
+}
+
+declare module 'virtual:astrobook/global-config.mjs' {
+  const config: import('./types.js').GlobalConfig
+  export default config
+}
+
+declare module 'virtual:astrobook/components/head.mjs' {
+  const Head: (props: unknown) => unknown
+  export default Head
+}
+
+declare module 'virtual:astrobook/components/home.mjs' {
+  const Home: (props: unknown) => unknown
+  export default Home
+}
+
+declare module 'virtual:astrobook/user-css.mjs' {}

package/src/ui/components/app.astro

@@ -0,0 +1,13 @@
+---
+// Vendored from astrobook 0.13.3 (packages/ui/src/components/app.astro) — see
+// ../../core/LICENSE-astrobook. Unchanged apart from the .astro extension on the relative import.
+//
+// The `/lab` home page: pure chrome, so it renders through ./layout.astro and gets no consumer
+// CSS at all (ruled 2026-09-22 — ../lab.css).
+import Layout from './layout.astro'
+import Home from 'virtual:astrobook/components/home.mjs'
+---
+
+<Layout story={undefined} hasSidebar={true}>
+  <Home />
+</Layout>

package/src/ui/components/build-path.ts

@@ -0,0 +1,13 @@
+// Vendored from astrobook 0.13.3 (packages/ui/src/components/build-path.ts) — see
+// ../../core/LICENSE-astrobook.
+// Divergence: `@astrobook/core/client` → the vendored core's own path-builder, by relative path
+// with the .ts extension. The `import '@astrobook/types'` side-effect line is gone: the ambient
+// declarations it pulled in now live in ../../types/virtual.d.ts, referenced from the package's
+// own virtual.d.ts.
+import config from 'virtual:astrobook/global-config.mjs'
+
+import { createPathBuilder } from '../../core/utils/path-builder.ts'
+
+export const buildPath: (...parts: string[]) => string = createPathBuilder({
+  trailingSlash: config.trailingSlash,
+})