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

package/src/shell/live-files.mjs

@@ -1,9 +1,8 @@
 // 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.
+// Dependency-free Node (fs + path only) on purpose: it is imported by the build-time index
+// (./lab-index.ts) and by the chrome's page views (../chrome/site-data.ts,
+// ../chrome/views/Pages.astro). One parser, so they 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
@@ -15,7 +14,7 @@
 // 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 { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 
 export const PAGES_DIR = "src/pages";
@@ -37,9 +36,212 @@ export const templateOf = (source) => {
   return m ? m[1] : source;
 };
 
+// A page may mount a section through a tsconfig path alias (`@/lab/sections/…`) or a root-relative
+// path (`/src/lab/sections/…`) as well as a relative one, and Vite resolves all three. Following only
+// the relative kind reported such a section as not live (ASTROL-23). The alias reading below was
+// written for the cull (ASTROL-21), which was removed before it merged.
+
+/** tsconfig.json's dialect: JSON with comments and trailing commas. @param {string} file */
+const readJsonc = (file) => {
+  const src = readFileSync(file, "utf8").replace(/^\uFEFF/, "");
+  let out = "";
+  for (let i = 0; i < src.length; i++) {
+    const ch = src[i];
+    if (ch === '"') {
+      let j = i + 1;
+      while (j < src.length && src[j] !== '"' && src[j] !== "\n") j += src[j] === "\\" ? 2 : 1;
+      out += src.slice(i, j + 1);
+      i = j;
+    } else if (ch === "/" && src[i + 1] === "/") {
+      while (i + 1 < src.length && src[i + 1] !== "\n") i++;
+    } else if (ch === "/" && src[i + 1] === "*") {
+      const close = src.indexOf("*/", i + 2);
+      i = close < 0 ? src.length : close + 1;
+    } else out += ch;
+  }
+  return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
+};
+
+/** @param {string} specifier */
+const packageNameOf = (specifier) =>
+  specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
+
+/** The installed package's directory, looking up from fromDir. @param {string} fromDir @param {string} name */
+function packageDir(fromDir, name) {
+  for (let dir = fromDir; ; dir = path.dirname(dir)) {
+    if (existsSync(path.join(dir, "node_modules", name))) return path.join(dir, "node_modules", name);
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+/** An `exports` value → the path it names under the conditions TypeScript reads a config with. @param {unknown} value @returns {string | null} */
+const exportTarget = (value) => {
+  if (typeof value === "string") return value;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  for (const [condition, inner] of Object.entries(value)) {
+    if (!["node", "require", "types", "default"].includes(condition)) continue;
+    const hit = exportTarget(inner);
+    if (hit) return hit;
+  }
+  return null;
+};
+
+/**
+ * The file an `extends` entry names: a path from the extending config's folder, or a package
+ * found from that folder — through the package's `exports` map (or its `tsconfig` field, for a
+ * bare name) when one matches, otherwise the path as written, with `.json` or `/tsconfig.json`.
+ * @param {string} dir folder of the config doing the extending @param {string} name
+ * @returns {string | null}
+ */
+function extendsTarget(dir, name) {
+  /** @param {string} base */
+  const asFile = (base) =>
+    [base, `${base}.json`, path.join(base, "tsconfig.json")].find((c) => existsSync(c) && statSync(c).isFile()) ?? null;
+  if (name.startsWith(".") || path.isAbsolute(name)) return asFile(path.resolve(dir, name));
+  const pkgName = packageNameOf(name);
+  const pkg = packageDir(dir, pkgName);
+  if (!pkg) return null;
+  const subpath = name.slice(pkgName.length);
+  const manifestFile = path.join(pkg, "package.json");
+  const manifest = existsSync(manifestFile) ? readJsonc(manifestFile) : {};
+  const { exports } = manifest;
+  if (exports !== undefined && exports !== null) {
+    const bySubpath =
+      typeof exports === "object" && !Array.isArray(exports) && Object.keys(exports).some((k) => k.startsWith("."))
+        ? exports
+        : { ".": exports };
+    /** @type {[string, unknown][]} */
+    const rules = Object.entries(bySubpath).map(([key, value]) => [key, [exportTarget(value)].filter(Boolean)]);
+    const mapped = aliasTargets({ rules }, `.${subpath}`)?.[0];
+    const file = mapped && asFile(path.join(pkg, mapped));
+    if (file) return file;
+  }
+  if (!subpath && typeof manifest.tsconfig === "string") return asFile(path.join(pkg, manifest.tsconfig));
+  return asFile(path.join(pkg, subpath));
+}
+
+/**
+ * tsconfig.json's `compilerOptions.paths`, following `extends` (a relative path or a package, one
+ * or several), the child overriding the parent as TypeScript does. `base` is what the targets are
+ * relative to: `baseUrl` when set, otherwise the directory of the config that declared `paths`.
+ * `${configDir}` in either means the site's own tsconfig folder, wherever it was written.
+ * Throws when the config cannot be read: every alias would silently stop resolving, and a section
+ * mounted through one would lose its live pill with nothing to say why.
+ * @param {string} rootDir absolute repo root
+ * @returns {{ base: string; rules: [string, unknown][] }}
+ */
+export function readAliases(rootDir) {
+  const file = path.join(rootDir, "tsconfig.json");
+  if (!existsSync(file)) return { base: rootDir, rules: [] };
+  /** @param {string} value */
+  const withConfigDir = (value) => value.replaceAll("${configDir}", path.dirname(file));
+  /** @type {string | null} */
+  let baseUrl = null;
+  /** @type {Record<string, unknown> | null} */
+  let paths = null;
+  /** @type {string | null} */
+  let pathsDir = null;
+  const seen = new Set();
+  /** @param {string} configFile */
+  const load = (configFile) => {
+    if (seen.has(configFile)) return;
+    seen.add(configFile);
+    const config = readJsonc(configFile);
+    const dir = path.dirname(configFile);
+    for (const parent of config.extends === undefined ? [] : [].concat(config.extends)) {
+      const name = String(parent);
+      const target = extendsTarget(dir, name);
+      if (!target) throw new Error(`its "extends": "${name}" resolves to no file`);
+      load(target);
+    }
+    const options = config.compilerOptions ?? {};
+    if (typeof options.baseUrl === "string") baseUrl = path.resolve(dir, withConfigDir(options.baseUrl));
+    if (options.paths && typeof options.paths === "object") {
+      paths = options.paths;
+      pathsDir = dir;
+    }
+  };
+  try {
+    load(file);
+  } catch (error) {
+    throw new Error(
+      `astrolab: ${toRepoRelative(rootDir, file)} could not be read (${error instanceof Error ? error.message : error}), ` +
+        "so no path alias can be followed and a section a page mounts through one would not show as live",
+    );
+  }
+  const rules = Object.entries(paths ?? {}).map(([key, targets]) =>
+    /** @type {[string, unknown]} */ ([key, Array.isArray(targets) ? targets.map((t) => withConfigDir(String(t))) : targets]),
+  );
+  return { base: baseUrl ?? pathsDir ?? rootDir, rules };
+}
+
+/**
+ * The targets `specifier` maps to under the tsconfig aliases, TypeScript's way: an exact key wins,
+ * then the wildcard key with the longest prefix. Null when no key matches.
+ * @param {{ rules: [string, unknown][] }} aliases @param {string} specifier
+ * @returns {string[] | null}
+ */
+export function aliasTargets(aliases, specifier) {
+  /** @type {{ prefix: string; targets: string[] } | null} */
+  let best = null;
+  for (const [key, targets] of aliases.rules) {
+    if (!Array.isArray(targets)) continue;
+    const star = key.indexOf("*");
+    if (star < 0) {
+      if (key === specifier) return targets.map(String);
+      continue;
+    }
+    const prefix = key.slice(0, star);
+    const suffix = key.slice(star + 1);
+    if (specifier.length < prefix.length + suffix.length) continue;
+    if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix)) continue;
+    if (best && prefix.length <= best.prefix.length) continue;
+    const middle = specifier.slice(prefix.length, specifier.length - suffix.length);
+    best = { prefix, targets: targets.map((t) => String(t).replace("*", middle)) };
+  }
+  return best ? best.targets : null;
+}
+
+/** An absolute path → the file it names, the way the bundler would try it, or null. @param {string} base */
+export function fileAt(base) {
+  const candidates = [base];
+  for (const ext of [".ts", ".mts", ".tsx", ".mjs", ".js", ".jsx", ".astro", ".mdx"]) 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(path.join(base, index));
+  for (const c of candidates) if (existsSync(c) && statSync(c).isFile()) return c;
+  return null;
+}
+
+/**
+ * The absolute file an import specifier names, or null when it names none in this repo (a
+ * package, a virtual module, a `#` subpath import, an alias with no file behind it).
+ * A relative specifier that matches no file keeps its plain resolved path, as it always has.
+ * @param {string} rootDir absolute repo root
+ * @param {string} fromAbs absolute path of the importing file
+ * @param {string} specifier
+ * @param {{ base: string; rules: [string, unknown][] }} [aliases] from readAliases, when reading many
+ * @returns {string | null}
+ */
+export function resolveImport(rootDir, fromAbs, specifier, aliases = readAliases(rootDir)) {
+  if (specifier.startsWith("#")) return null;
+  const clean = specifier.replace(/[?#].*$/, "");
+  if (clean === "." || clean === ".." || clean.startsWith("./") || clean.startsWith("../")) {
+    const base = path.resolve(path.dirname(fromAbs), clean);
+    return fileAt(base) ?? base;
+  }
+  if (clean.startsWith("/")) return fileAt(path.join(rootDir, clean)) ?? fileAt(clean);
+  for (const target of aliasTargets(aliases, clean) ?? []) {
+    const file = fileAt(path.resolve(aliases.base, target));
+    if (file) return file;
+  }
+  return null;
+}
+
 /**
- * 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
+ * Every `import Name from "<specifier>"` in a source file that names a file here — relative,
+ * root-relative (`/src/…`) or through a tsconfig path alias (`@/…`) — 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
@@ -50,14 +252,14 @@ export function defaultImports(rootDir, fileRel) {
   if (!existsSync(abs)) return [];
   const source = readFileSync(abs, "utf8");
   const code = fileRel.endsWith(".astro") ? frontmatterOf(source) : source;
+  const aliases = readAliases(rootDir);
   /** @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)) });
+    const file = resolveImport(rootDir, abs, m[2], aliases);
+    if (file) out.push({ name: m[1], file: toRepoRelative(rootDir, file) });
   }
   return out;
 }

package/src/shell/marks.mjs

@@ -1,12 +1,11 @@
-// 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.
+// The lab's hand-set marks — everything a person ticks rather than something the lab derives,
+// plus the path rule every mark obeys.
 //
 //   <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.
+// Keyed by the story module's repo-relative path (`<directory>/<tier>/…/<Name>.stories.ts`, or any
+// extension in STORY_EXTENSIONS below) — one row means one key everywhere — and validated through
+// `pathOffence` below.
 //
 // 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
@@ -14,16 +13,24 @@
 // 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.
+// (./lab-index.ts, at build) and by a plain Vite middleware (../../index.mjs). One parser, two
+// runtimes.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 
 /** @typedef {import("../../defaults.mjs").LabConfig} LabConfig */
 
+/**
+ * Every extension the core finds a stories file by — the `*.stories.{…}` glob in
+ * src/core/virtual-module/get-story-modules.ts. A file the lab lists must be one it can mark.
+ */
+export const STORY_EXTENSIONS = ["ts", "tsx", "js", "jsx", "mts", "mtsx", "mjs", "mjsx"];
+
 /** 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$`);
+  new RegExp(
+    `^${directory.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/(?:[\\w.-]+/)*[\\w.-]+\\.stories\\.(?:${STORY_EXTENSIONS.join("|")})$`,
+  );
 
 /**
  * Why `entry` is not a markable story module under `tier`, or null when it is.
@@ -37,7 +44,7 @@ export const storiesPattern = (directory) =>
 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`;
+    return `not a ${config.directory}/**/*.stories.{${STORY_EXTENSIONS.join(",")}} path`;
   if (!tier) return tierReason;
   if (!entry.startsWith(tier)) return tierReason;
   if (!existsSync(path.join(rootDir, entry))) return "no such file";
@@ -54,10 +61,6 @@ export const responsiveOffence = (rootDir, config, entry) =>
     "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") : [];
@@ -107,30 +110,3 @@ export function writeResponsive(rootDir, config, done, approved) {
   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/ui/components/preview-layout.astro

@@ -24,6 +24,16 @@
 //     this meta has to be here as well as in LabHead.astro. Do not make it conditional.
 //   · Feedbucket, when the consumer configured a key — a bare story page is a lab page you can
 //     open full screen, and it carried the widget before this split.
+//   · the FRAMED flag, which hides Astro's dev toolbar inside a lab frame (decided 2026-09-24).
+//     Every preview is an <iframe> of this document, and the dev server injects its toolbar into
+//     every page it serves, so a component page carried two: the lab page's own and a second,
+//     scaled with the canvas, sitting over the story. The outer one is enough — its pin picker
+//     already descends into same-origin frames. So an inline script marks <html> before first
+//     paint when `window.frameElement` is set (a same-origin parent, which every lab frame is),
+//     and one rule on that mark hides the toolbar. It stays on this route opened in its own tab,
+//     and on the site's own pages, which never render through this layout. The cost: a ticket
+//     left on a bare story draws its marker only there, because the outer toolbar places markers
+//     for its own page's url and a framed toolbar can no longer be opened to draw them.
 import 'virtual:astrobook/user-css.mjs'
 
 import { ClientRouter } from 'astro:transitions'
@@ -55,6 +65,9 @@ const feedbucketKey = labConfig.feedbucketKey
     <meta name="generator" content={Astro.generator} />
     <title>{config.title}</title>
     <meta name="robots" content="noindex, nofollow" />
+    <script is:inline>
+      if (window.frameElement) document.documentElement.setAttribute('data-lab-framed', '')
+    </script>
     <ThemeScript />
     <script>
       import { initThemeMessage } from './theme-message.ts'
@@ -95,6 +108,10 @@ const feedbucketKey = labConfig.feedbucketKey
         min-width: 0;
         overflow: auto;
       }
+
+      html.lab-preview-shell[data-lab-framed] astro-dev-toolbar {
+        display: none !important;
+      }
     </style>
   </head>
   <body class="lab-preview-shell">

package/src/ui/components/theme-script.astro

@@ -6,9 +6,10 @@
 //
 //   1. The whole point of the pass is that the lab depends on nothing but Astro. One npm package
 //      left behind for a sun/moon button is the one that would surprise the next reader.
-//   2. `.dark` on <html> is a DOM contract this package leans on hard — LabHead.astro styles the
-//      live pill, the cull switch and the row error against it. A contract that load-bearing
-//      should be owned here, not read off a third party's minified inline script.
+//   2. `.dark` on <html> is a DOM contract this package leans on hard — the stylesheet LabHead.astro
+//      loads (../lab.css) swaps every chrome token against it, and the sidebars, the device switch
+//      and the parameters drawer with them. A contract that load-bearing should be owned here, not
+//      read off a third party's minified inline script.
 //   3. What was left after dropping the ripple `startViewTransition` animation — presentation,
 //      and phase 2's business if it wants it back — was about forty lines.
 //