@orbytes/astrolab 0.3.0 → 0.4.0-next.2

package/src/shell/lab-index.ts

@@ -13,8 +13,8 @@
 //      survives a multi-page site.
 //   5. <directory>/responsive.json, through marks.mjs — the hand-set responsive marks. The one
 //      thing here that is ticked rather than derived, because approval cannot be read from code.
-//   6. The stories files themselves — the component they render, the leading comment (summary)
-//      and, through import.meta.glob, the default export's optional `meta.tags`.
+//   6. The stories files themselves, read as text — the component they render, the leading
+//      comment (summary) and the default export's optional `meta.tags`.
 //
 // Classification is by Astrobook `directory` (relative to its `directory` option):
 //   <tier>/<Section>/<Version>/…   tier = first segment; for the tier holding the RESPONSIVE role
@@ -75,13 +75,14 @@ export interface LabItem {
   livePage: string | null;
   /** every page that mounts it — one entry on a normal site, more for shared chrome */
   liveOn: LiveMount[];
-  /** section versions only (tier "sections"); null everywhere the mark does not apply */
+  /** section versions only (the tier holding the responsive role); null everywhere else */
   responsive: { done: boolean; approved: boolean } | null;
   /** the same story on the deployed lab; null when no `stagingUrl` is configured */
   stagingUrl: string | null;
   /** vscode://file/<absolute path> to the component; null in a build — the link is dev-only */
   editorUrl: string | null;
-  /** repo-relative files of LIVE section components that import this item's componentFile */
+  /** repo-relative files that import this item's componentFile and are live themselves (a page
+   *  mounts them, whatever their tier or folder) */
   usedBy: string[];
   tags: string[];
   summary: string | null;
@@ -108,17 +109,26 @@ export interface LabIndex {
   live: { file: string; page: string; slot: number; of: number }[];
 }
 
-// Only for the optional `meta` on a story module's default export — Astrobook ignores unknown
-// keys, so `export default { component, meta: { tags: [...] } }` is legal and this is where it is
-// read. Keys are root-relative (`/src/...`); the pattern covers both the current and target trees.
-const storyExports = import.meta.glob("/src/**/*.stories.ts", { eager: true }) as Record<
-  string,
-  { default?: { meta?: { tags?: unknown } } } | undefined
->;
-
-const tagsOf = (moduleFile: string): string[] => {
-  const tags = storyExports[`/${moduleFile}`]?.default?.meta?.tags;
-  return Array.isArray(tags) ? tags.filter((t): t is string => typeof t === "string") : [];
+// The optional `meta.tags` on a story module's default export — Astrobook ignores unknown keys, so
+// `export default { component, meta: { tags: ["cta", "v2"] } }` is legal and this is where it is
+// read.
+//
+// READ AS TEXT, NOT IMPORTED (2026-09-24, ASTROL-12). This used to be an EAGER
+// `import.meta.glob("/src/**/*.stories.ts")`, and importing a stories file imports the component it
+// renders — so every chrome page's module graph held every section, and Astro put every section's
+// scoped stylesheet on every chrome page (18 of them on the lab home). The tags are string
+// literals in the file, so a parse of its text gives the same answer and imports nothing. A tag
+// built at runtime is not seen, which a tag never needs to be.
+const tagsOf = (rootDir: string, moduleFile: string): string[] => {
+  let source = "";
+  try {
+    source = readFileSync(path.join(rootDir, moduleFile), "utf8");
+  } catch {
+    return [];
+  }
+  const list = source.match(/\bmeta\s*:\s*\{[^}]*?\btags\s*:\s*\[([^\]]*)\]/);
+  if (!list) return [];
+  return [...list[1]!.matchAll(/["'`]([^"'`\n]+)["'`]/g)].map((m) => m[1]!);
 };
 
 // First sentence of the leading `//` comment block — the stories files already open with the
@@ -140,7 +150,7 @@ const summaryOf = (rootDir: string, moduleFile: string): string | null => {
 const classify = (directory: string) => {
   const parts = directory ? directory.split("/") : [];
   const tier = parts[0] ?? "";
-  const sectional = tier === "sections";
+  const sectional = labConfig.sectionsTier !== null && tier === labConfig.sectionsTier;
   return {
     tier,
     section: sectional && parts[1] ? parts[1] : null,
@@ -200,7 +210,7 @@ export function buildLabIndex(): LabIndex {
     const liveOn = (componentFile ? mountsByFile.get(componentFile) : undefined) ?? [];
     const primary = liveOn[0];
     const { tier, section, version } = classify(mod.directory);
-    const tags = tagsOf(moduleFile);
+    const tags = tagsOf(rootDir, moduleFile);
     const summary = summaryOf(rootDir, moduleFile);
     const responsive = RESPONSIVE_DIR && moduleFile.startsWith(RESPONSIVE_DIR)
       ? { done: doneMarks.has(moduleFile), approved: approvedMarks.has(moduleFile) }
@@ -320,7 +330,7 @@ export const itemsUnder = (index: LabIndex, folderPath: string): LabItem[] =>
 /**
  * The live pill's text. A single-page site reads exactly as it always did — `live · slot 3 of 12`
  * — and only a page that is not the home page names itself: `live · /about, slot 3`.
- * The sidebar script in LabHead.astro carries the same three lines; keep the two in step.
+ * Every live pill in the chrome is built here; nothing else formats one.
  */
 export const livePillText = (item: LabItem): string | null => {
   if (!item.live) return null;

package/src/shell/lab-params.ts

@@ -10,9 +10,9 @@
    at all.
 
    So: a component that has something to tune DECLARES it here and renders nothing. The panel is
-   drawn by the viewport lab's chrome (./Viewport.astro), between the top bar and the
-   stage — and only there. The same story at <subpath>/stories/<id> (the bare render) and on the
-   dashboard shows no panel at all, because nothing in this module touches the DOM.
+   drawn by the lab's chrome (../chrome/params-client.ts) as a drawer on the right edge of the
+   component page's canvas — and only there. The same story at <subpath>/stories/<id> (the bare
+   render) shows no panel at all, because nothing in this module touches the DOM.
 
    HOW IT FITS TOGETHER. This module runs INSIDE the story document (the iframe). It keeps the
    registered groups on `window.__labParams` and announces each one with a `lab:params` event on
@@ -34,7 +34,7 @@
    with the restored values, so `apply` must tolerate being called before the thing it configures
    exists. Then:
 
-       import { registerLabParams } from "@orbytes/astrolab/params";
+       import { LAB_UNITS, parseLabLength, registerLabParams } from "@orbytes/astrolab/params";
 
        const shader = document.querySelector<HTMLCanvasElement>(".hero__shader");
        let uniforms: Uniforms | null = null;          // filled in below; apply() tolerates null
@@ -46,6 +46,7 @@
          note: "Uniforms are read every frame; nothing here is on the live page.",
          controls: [
            { kind: "range",  id: "speed", label: "Speed", min: 0, max: 4, step: 0.05, value: 1, unit: "×" },
+           { kind: "number", id: "warp",  label: "Warp",  value: 24, unit: "px", units: LAB_UNITS.size },
            { kind: "toggle", id: "grain", label: "Grain", value: true },
            { kind: "select", id: "blend", label: "Blend", value: "screen",
              options: [{ value: "screen", label: "screen" }, { value: "add", label: "add" }] },
@@ -54,6 +55,7 @@
          apply(values) {
            if (!uniforms) return;
            uniforms.speed = Number(values.speed);
+           uniforms.warp = parseLabLength(values.warp)?.value ?? 24;   // "24px" → 24
            uniforms.grain = Boolean(values.grain);
            uniforms.blend = String(values.blend);
            uniforms.tint = String(values.tint);
@@ -66,14 +68,55 @@
 
    That is all. Reset, Copy settings, the collapse chevron, the readouts, the units and the
    storage are the panel's job, not the component's.
+
+   ---------------------------------------------------------------------------------------------
+   SLIDER OR NUMBER? Decided 2026-09-24: a parameter that is a SIZE — a font size, a tracking, a
+   line height, a width, an offset, a blur radius — is never a slider. It is `kind: "number"`: a
+   field to type the value into, joined to a select of the units it can be expressed in (72 px,
+   4.5 rem, 12.5 vw). Unless it names its own `units`, it offers px · rem · em · vw · vh · %.
+   Sliders stay for unitless tuning values (speed, grain, scale, opacity).
+
+   A number control hands `apply` ONE CSS-READY STRING — the number and the unit joined, "72px",
+   "12.5rem", or "1.05" when the unit is "" — so it drops straight into a style:
+
+       el.style.setProperty("--headline-size", String(values.headlineSize));   // "72px"
+
+   and `parseLabLength` takes it apart again when the number itself is wanted (a shader uniform,
+   a calculation). Changing the unit keeps the number and changes what it means; the panel never
+   converts between units, because px → rem depends on a root size it cannot know.
+
+       { kind: "number", id: "headlineSize", label: "Headline size", value: 72, unit: "px",
+         units: LAB_UNITS.size },
+       { kind: "number", id: "tracking", label: "Tracking", value: -0.02, unit: "em",
+         units: LAB_UNITS.tracking, step: 0.01 },
+       { kind: "number", id: "lineHeight", label: "Line height", value: 1.05, unit: "",
+         units: LAB_UNITS.lineHeight, step: 0.01 },
    ============================================================================================= */
 
 export type LabParamValue = number | boolean | string;
 export type LabParamValues = Record<string, LabParamValue>;
 
+/**
+ * The unit sets a number control usually offers — pass one as `units`, or any list of your own.
+ * "" is "no unit" (the drawer shows it as "—"), which is what a line height is at its most
+ * useful. Figma writes tracking as a percentage; that is em × 100, so Figma's −2% is −0.02em.
+ */
+export const LAB_UNITS = {
+  /** Font sizes, widths, offsets, radii — and the set a number control gets when it names none. */
+  size: ["px", "rem", "em", "vw", "vh", "%"],
+  /** Letter spacing. */
+  tracking: ["em", "px"],
+  /** Line height: unitless first, because a unitless line height scales with the font. */
+  lineHeight: ["", "px"],
+} as const satisfies Record<string, readonly string[]>;
+
 /** One row of the panel. `id` is the key in `values`; `note` is shown on hover. */
 export type LabParamControl =
   | {
+      /**
+       * A slider, for a UNITLESS tuning value — speed, grain, scale. The value is a number and
+       * `unit` is only the readout's suffix ("×"). A size is a `number` control instead.
+       */
       kind: "range";
       id: string;
       label: string;
@@ -93,7 +136,59 @@ export type LabParamControl =
       options: { value: string; label: string }[];
       note?: string;
     }
-  | { kind: "color"; id: string; label: string; value: string; note?: string };
+  | { kind: "color"; id: string; label: string; value: string; note?: string }
+  | {
+      /**
+       * A SIZE — a number field joined to a unit select (72 px · 4.5 rem · 12.5 vw).
+       *
+       * The value in `values` is ONE CSS-ready STRING, the number and unit joined: "72px",
+       * "12.5rem", "-0.02em", or "1.05" when the unit is "". Put it straight into a style, or
+       * take it apart with `parseLabLength`. Changing the unit keeps the number; nothing is
+       * converted.
+       */
+      kind: "number";
+      id: string;
+      label: string;
+      /** The default number, bare: 72. */
+      value: number;
+      /** The default unit — "px", "em", or "" for none. Added to `units` if it is missing. */
+      unit: string;
+      /**
+       * What the unit select offers, in order. Defaults to `LAB_UNITS.size` (px · rem · em · vw ·
+       * vh · %); a tracking wants `LAB_UNITS.tracking`, a line height `LAB_UNITS.lineHeight`.
+       * A list of one shows the unit without a choice.
+       */
+      units?: readonly string[];
+      /** What ↑ / ↓ add. Defaults to 1. */
+      step?: number;
+      /** Optional bounds, applied to typed and stored values alike. */
+      min?: number;
+      max?: number;
+      note?: string;
+    };
+
+/** The units a number control offers: its declared `units`, with its default `unit` guaranteed. */
+export const labUnitsOf = (control: Extract<LabParamControl, { kind: "number" }>): string[] => {
+  const units = [...(control.units ?? LAB_UNITS.size)];
+  return units.includes(control.unit) ? units : [control.unit, ...units];
+};
+
+/**
+ * "72px" → { value: 72, unit: "px" }; "1.05" → { value: 1.05, unit: "" }. Null for anything that
+ * is not one number followed by an optional unit — so a value from a number control always
+ * parses, and a stray string never quietly becomes 0.
+ */
+export const parseLabLength = (raw: unknown): { value: number; unit: string } | null => {
+  if (typeof raw === "number") return Number.isFinite(raw) ? { value: raw, unit: "" } : null;
+  if (typeof raw !== "string") return null;
+  const match = /^\s*([-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?)\s*([a-z%]*)\s*$/i.exec(raw);
+  if (!match) return null;
+  const value = Number(match[1]);
+  return Number.isFinite(value) ? { value, unit: match[2]!.toLowerCase() } : null;
+};
+
+/** The inverse: 72 and "px" → "72px". `String()` already turns −0 into "0". */
+export const formatLabLength = (value: number, unit: string): string => `${String(value)}${unit}`;
 
 export interface LabParamGroup {
   /** Stable, and the localStorage key suffix. One group per thing being tuned. */
@@ -180,14 +275,26 @@ const coerce = (control: LabParamControl, raw: unknown): LabParamValue | undefin
       return typeof raw === "string" && control.options.some((o) => o.value === raw) ? raw : undefined;
     case "color":
       return typeof raw === "string" && /^#[0-9a-f]{3,8}$/i.test(raw) ? raw : undefined;
+    case "number": {
+      // A bare number is what a slider saved. Reading it in the default unit is what lets a size
+      // that used to be a `range` become a `number` without losing the tuning saved for it.
+      const parsed = typeof raw === "number" ? parseLabLength(`${raw}${control.unit}`) : parseLabLength(raw);
+      if (!parsed || !labUnitsOf(control).includes(parsed.unit)) return undefined;
+      const value = Math.min(control.max ?? Infinity, Math.max(control.min ?? -Infinity, parsed.value));
+      return formatLabLength(value, parsed.unit);
+    }
   }
 };
 
+/** A control's declared default, as `values` holds it. */
+const defaultOf = (control: LabParamControl): LabParamValue =>
+  control.kind === "number" ? formatLabLength(control.value, control.unit) : control.value;
+
 export function registerLabParams(group: LabParamGroup): LabParamHandle {
   const storageKey = group.storageKey ?? `${STORE_PREFIX}${group.id}`;
 
   const defaults: LabParamValues = {};
-  for (const control of group.controls) defaults[control.id] = control.value;
+  for (const control of group.controls) defaults[control.id] = defaultOf(control);
 
   const values: LabParamValues = { ...defaults };
   const stored = readStore(storageKey);

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/app.astro

@@ -1,13 +1,11 @@
 ---
 // 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.
+// ../../core/LICENSE-astrobook.
 //
-// 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'
+// The `/lab` home page. Divergence: upstream wrapped the `home` component in its layout; since the
+// redesign (2026-09-24) the home component IS the whole document — it renders through the
+// package's chrome shell (../../chrome/Shell.astro) itself, so this file only mounts it.
 import Home from 'virtual:astrobook/components/home.mjs'
 ---
 
-<Layout story={undefined} hasSidebar={true}>
-  <Home />
-</Layout>
+<Home />