@weasel-js/forge 1.5.2 → 1.6.0

package/dist/shell/index.js

@@ -1,77 +1,19 @@
-import { schemaFromDescription, openChannel } from '../chunk-2JDYOBWM.js';
-import { stableStringify, PORT_HANDOFF, PROTOCOL_VERSION } from '../chunk-FTFR2YPM.js';
+import { isIndexId, indexId, indexEntries, schemaFromDescription, openChannel, IndexPage } from '../chunk-PO5JLVYT.js';
+import { useTrialFrame, createTrialFrames, labGlobals, StoryGlobalsContext, TrialFramesContext, withGlobals, StoryTrial, storyConfig, GLOBALS_KEY, effectiveGlobals, useCssOverrides, TrialHost, isGlobalsPath } from '../chunk-A4JOEGYQ.js';
+export { StoryGlobalsContext, StoryTrial, TrialFramesContext, TrialHost, useTrialFrame } from '../chunk-A4JOEGYQ.js';
+import { loadStories, indexRenderOf } from '../chunk-FWPBKKYB.js';
+import '../chunk-2GXKNXTJ.js';
+import '../chunk-HRGPFQBW.js';
+import { stableStringify, PORT_HANDOFF, FRAME_HELLO, PROTOCOL_VERSION } from '../chunk-VEKEBILL.js';
 import { useTrialId, Button, Lab, useLabContext, TrialIdContext, usePersistedState, Select, inferTokenType, ToggleBar as ToggleBar$1, Input, TokenPanel, refitScale } from '@weasel-js/labkit';
-import { createContext, useContext, useCallback, useSyncExternalStore, useState, useRef, useEffect, useMemo, useLayoutEffect, useId } from 'react';
+import { createContext, useState, useRef, useEffect, useCallback, useMemo, useLayoutEffect, useId, useContext } from 'react';
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import { createRoot } from 'react-dom/client';
-import { InfoIcon, ToggleBar, Checkbox, Dialog } from '@weasel-js/ui';
-import { TOKEN_MANIFEST, THEME_SOURCES } from '@weasel-js/theme';
-import { scale } from '@weasel-js/theme/engine';
+import { InfoIcon, ToggleBar, Checkbox, Dialog, Badge, DisclosureMark, Button as Button$1, TuneIcon, Callout } from '@weasel-js/ui';
+import { TOKEN_MANIFEST, THEME_SOURCES, isByAxis } from '@weasel-js/theme';
+import { scale, httpThemeApi } from '@weasel-js/theme/engine';
 import { f, valueAtPath, isConfigBranch } from '@weasel-js/labkit/config';
 
-var NO_FRAME = { send: null, vars: [], audit: null, a11y: null, capture: null, size: null };
-function createTrialFrames() {
-  const frames = /* @__PURE__ */ new Map();
-  const hosts = /* @__PURE__ */ new Map();
-  const listeners = /* @__PURE__ */ new Set();
-  const changed = () => {
-    for (const listener of [...listeners]) listener();
-  };
-  const patch = (trialId, next) => {
-    const frame = frames.get(trialId);
-    if (!frame) return;
-    frames.set(trialId, { ...frame, ...next });
-    changed();
-  };
-  return {
-    connect(trialId, calls) {
-      const held = frames.get(trialId);
-      frames.set(trialId, {
-        send: calls.send,
-        vars: [],
-        audit: calls.audit,
-        a11y: null,
-        capture: calls.capture,
-        size: held?.size ?? null
-      });
-      changed();
-      return () => {
-        if (frames.get(trialId)?.send !== calls.send) return;
-        frames.delete(trialId);
-        changed();
-      };
-    },
-    report: (trialId, vars) => patch(trialId, { vars }),
-    reportA11y: (trialId, a11y) => patch(trialId, { a11y }),
-    reportSize(trialId, size) {
-      const frame = frames.get(trialId) ?? NO_FRAME;
-      if (frame.size?.width === size.width && frame.size?.height === size.height) return;
-      frames.set(trialId, { ...frame, size });
-      changed();
-    },
-    hostRef(trialId) {
-      let ref = hosts.get(trialId);
-      if (!ref) {
-        ref = { current: null };
-        hosts.set(trialId, ref);
-      }
-      return ref;
-    },
-    get: (trialId) => frames.get(trialId) ?? NO_FRAME,
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => listeners.delete(listener);
-    }
-  };
-}
-var TrialFramesContext = createContext(null);
-function useTrialFrame(trialId) {
-  const frames = useContext(TrialFramesContext);
-  const subscribe = useCallback((listener) => frames?.subscribe(listener) ?? (() => {
-  }), [frames]);
-  const read = () => frames?.get(trialId) ?? NO_FRAME;
-  return useSyncExternalStore(subscribe, read, read);
-}
 function Finding({ finding }) {
   return /* @__PURE__ */ jsxs("li", { className: "fg-a11y__finding", children: [
     /* @__PURE__ */ jsxs("p", { className: "fg-a11y__help", children: [
@@ -149,17 +91,137 @@ var A11Y_SECTION = {
   region: "aside",
   item: { title: "Accessibility", body: /* @__PURE__ */ jsx(FocusedA11y, {}) }
 };
-var NONE = {};
-function useCssOverrides() {
-  return usePersistedState("fg-css-overrides", NONE, { scope: "trial" });
+
+// src/shell/storyChanges.ts
+function createStoryChanges() {
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    emit(file) {
+      for (const listener of [...listeners]) listener(file);
+    }
+  };
+}
+var SEED_REF = /^\{seeds\.([^}]+)\}$/;
+var RULE_KEYS = { factors: "factors", ratio: "ratio", step: "step" };
+function selectionFor(axes, globals) {
+  const out = {};
+  for (const [axis, def] of Object.entries(axes)) {
+    const value = globals[axis];
+    if (value === void 0) out[axis] = def.default;
+    else if (typeof value === "string" && value in def.values) out[axis] = value;
+  }
+  return out;
+}
+var EditError = class extends Error {
+};
+function slotOf(root, holder, key, where, selection, depth = 0) {
+  if (depth > 16) throw new EditError(`${where} references itself`);
+  let h = holder;
+  let k = key;
+  let w = where;
+  let value = h[k];
+  while (isByAxis(value)) {
+    const axis = value.by;
+    const picked = selection[axis];
+    if (picked === void 0 || picked === "by" || !(picked in value)) {
+      throw new EditError(`${w} differs by ${axis}, and which ${axis} this trial shows is not known`);
+    }
+    h = value;
+    k = picked;
+    w = `${w}.${picked}`;
+    value = h[k];
+  }
+  if (typeof value === "number") return { holder: h, key: k, where: w };
+  if (typeof value === "string") {
+    const ref = SEED_REF.exec(value);
+    if (!ref) throw new EditError(`${w} is "${value}", which is not a number or a seed`);
+    const name = ref[1];
+    const seeds = root.seeds;
+    if (!seeds || !(name in seeds)) throw new EditError(`${w} names the seed "${name}", which this theme inherits rather than defines`);
+    return slotOf(root, seeds, name, `seeds.${name}`, selection, depth + 1);
+  }
+  throw new EditError(`${w} is not a number`);
+}
+function factorsOf(holder, where, selection) {
+  let value = holder.factors;
+  let w = `${where}.factors`;
+  while (isByAxis(value)) {
+    const picked = selection[value.by];
+    if (picked === void 0 || !(picked in value)) {
+      throw new EditError(`${w} differs by ${value.by}, and which ${value.by} this trial shows is not known`);
+    }
+    w = `${w}.${picked}`;
+    value = value[picked];
+  }
+  if (!Array.isArray(value)) throw new EditError(`${w} is not a list`);
+  return { list: value, where: w };
+}
+var kindOf = (scale) => scale.factors !== void 0 ? "factors" : scale.ratio !== void 0 ? "ratio" : scale.step !== void 0 ? "step" : null;
+var plainLiteral = (value) => typeof value === "number" || Array.isArray(value) && value.every((v) => typeof v === "number");
+function swapRule(scale, from, to, value) {
+  const entries = Object.entries(scale);
+  for (const [k] of entries) delete scale[k];
+  for (const [k, v] of entries) scale[k === from ? to : k] = k === from ? value : v;
+  if (from === null) scale[to] = value;
+}
+function applyScaleEdits(definition, edits, selection) {
+  const root = structuredClone(definition);
+  const writes = /* @__PURE__ */ new Map();
+  const write = (slot, value) => {
+    let byKey = writes.get(slot.holder);
+    if (!byKey) writes.set(slot.holder, byKey = /* @__PURE__ */ new Map());
+    const pending = byKey.get(slot.key);
+    if (pending !== void 0 && pending !== value) throw new EditError(`${slot.where} would need to be both ${pending} and ${value}`);
+    byKey.set(slot.key, value);
+  };
+  try {
+    for (const [name, edit] of Object.entries(edits)) {
+      const scales = root.scales;
+      const scale = scales?.[name];
+      if (!scales || !scale) throw new EditError(`the theme defines no scale "${name}"`);
+      const where = `scales.${name}`;
+      write(slotOf(root, scale, "base", `${where}.base`, selection), edit.base);
+      const { rule } = edit;
+      const had = kindOf(scale);
+      if (had !== rule.kind) {
+        const from = had ? RULE_KEYS[had] : null;
+        if (from && !plainLiteral(scale[from])) {
+          throw new EditError(`${where} would lose its ${from} to become a ${rule.kind} scale, and its ${from} is not a plain number`);
+        }
+        const value = rule.kind === "factors" ? [...rule.factors] : rule.kind === "ratio" ? rule.ratio : rule.step;
+        swapRule(scale, from, RULE_KEYS[rule.kind], value);
+        continue;
+      }
+      if (rule.kind === "factors") {
+        const { list, where: at } = factorsOf(scale, where, selection);
+        if (list.length !== rule.factors.length) {
+          throw new EditError(`${at} has ${list.length} factors, and the edit ${rule.factors.length}`);
+        }
+        rule.factors.forEach((factor, i) => write(slotOf(root, list, i, `${at}.${i}`, selection), factor));
+      } else {
+        const key = RULE_KEYS[rule.kind];
+        write(slotOf(root, scale, key, `${where}.${key}`, selection), rule.kind === "ratio" ? rule.ratio : rule.step);
+      }
+    }
+  } catch (e) {
+    if (e instanceof EditError) return { ok: false, message: `Cannot save: ${e.message}.` };
+    throw e;
+  }
+  for (const [holder, byKey] of writes) for (const [key, value] of byKey) holder[key] = value;
+  return { ok: true, definition: root };
 }
 var TABS = [
   { value: "theme", label: "Theme" },
   { value: "story", label: "Story" }
 ];
 var MANIFEST = new Map(TOKEN_MANIFEST.map((token) => [token.name, token]));
+var THEME_NAME = "weasel";
 var literal = (v) => typeof v === "number";
-var SCALE_SOURCES = Object.entries(THEME_SOURCES.weasel?.scales ?? {}).flatMap(([name, def]) => {
+var SCALE_SOURCES = Object.entries(THEME_SOURCES[THEME_NAME]?.scales ?? {}).flatMap(([name, def]) => {
   if (!Array.isArray(def.steps)) return [];
   const steps = def.steps;
   const tokens = steps.map((step) => `--wzl-${name}-${step}`);
@@ -169,6 +231,18 @@ var SCALE_SOURCES = Object.entries(THEME_SOURCES.weasel?.scales ?? {}).flatMap((
   const rule = def.factors !== void 0 ? factors ? { kind: "factors", factors } : "factors" : def.ratio !== void 0 ? literal(def.ratio) ? { kind: "ratio", ratio: def.ratio } : "ratio" : literal(def.step) ? { kind: "step", step: def.step } : "step";
   return [{ name, group, steps, tokens, rule }];
 });
+function scaleValues(source, next) {
+  const { rule } = next;
+  const values = scale(source.steps, {
+    base: next.base,
+    ...rule.kind === "factors" ? { factors: rule.factors } : rule.kind === "ratio" ? { ratio: rule.ratio } : { step: rule.step }
+  });
+  return source.steps.flatMap((step, i) => {
+    const value = values[step];
+    const name = source.tokens[i];
+    return value !== void 0 && name !== void 0 ? [[name, value]] : [];
+  });
+}
 function standingScale(source, amounts) {
   const seed = { tokens: source.tokens, base: amounts[0] ?? 0, rule: { kind: "step", step: 0 } };
   if (typeof source.rule === "string") return refitScale(seed, source.rule, amounts);
@@ -185,7 +259,8 @@ function groupOf(name) {
   const segments = name.replace(/^--/, "").split("-");
   return segments.length > 1 ? segments.slice(0, -1).join("-") : name.replace(/^--/, "");
 }
-function CssVarsPanel() {
+var NO_GLOBALS = {};
+function CssVarsPanel({ globals = NO_GLOBALS, themeApi } = {}) {
   const trialId = useTrialId();
   const frame = useTrialFrame(trialId);
   const [overrides, setOverrides] = useCssOverrides();
@@ -246,19 +321,63 @@ function CssVarsPanel() {
       const source = SCALE_SOURCES.find((sc) => sc.group === group);
       if (!source) return;
       setEdited((prev) => ({ ...prev, [group]: next }));
-      const { rule } = next;
-      const values = scale(source.steps, {
-        base: next.base,
-        ...rule.kind === "factors" ? { factors: rule.factors } : rule.kind === "ratio" ? { ratio: rule.ratio } : { step: rule.step }
-      });
-      source.steps.forEach((step, i) => {
-        const value = values[step];
-        const name = source.tokens[i];
-        if (value !== void 0 && name !== void 0) write(name, value);
-      });
+      for (const [name, value] of scaleValues(source, next)) write(name, value);
     },
     [setEdited, write]
   );
+  const unsaved = useMemo(
+    () => SCALE_SOURCES.flatMap((source) => {
+      const edit = edited[source.group];
+      if (!edit || !source.tokens.some((name) => overrides[name] !== void 0)) return [];
+      const values = scaleValues(source, edit);
+      return values.every(([name, value]) => overrides[name] === value) ? [{ source, edit }] : [];
+    }),
+    [edited, overrides]
+  );
+  const [saving, setSaving] = useState(false);
+  const [held, setHeld] = useState(null);
+  const notice = held?.trialId === trialId ? held : null;
+  const setNotice = (next) => setHeld(next && { ...next, trialId });
+  const save = async () => {
+    setSaving(true);
+    setNotice(null);
+    try {
+      const api = themeApi ?? httpThemeApi();
+      const stored = await api.get(THEME_NAME);
+      const file = `themes/${THEME_NAME}.json`;
+      if (JSON.stringify(stored.definition) !== JSON.stringify(THEME_SOURCES[THEME_NAME])) {
+        setNotice({ tone: "error", text: `${file} has changed since this page loaded. Reload to edit against it.` });
+        return;
+      }
+      const edits = Object.fromEntries(
+        unsaved.map(({ source, edit }) => [source.name, { base: edit.base, rule: edit.rule }])
+      );
+      const next = applyScaleEdits(stored.definition, edits, selectionFor(stored.definition.axes ?? {}, globals));
+      if (!next.ok) {
+        setNotice({ tone: "error", text: next.message });
+        return;
+      }
+      const result = await api.put(THEME_NAME, next.definition, stored.hash);
+      if (result.status === "conflict") {
+        setNotice({ tone: "error", text: `${file} changed on disk while saving. Nothing was written; reload to edit against it.` });
+        return;
+      }
+      if (result.status === "invalid") {
+        setNotice({ tone: "error", text: result.message });
+        return;
+      }
+      for (const { source } of unsaved) for (const name of source.tokens) write(name, null);
+      const groups = new Set(unsaved.map(({ source }) => source.group));
+      setEdited((prev) => Object.fromEntries(Object.entries(prev).filter(([group]) => !groups.has(group))));
+      setNotice(
+        result.regenerated || result.problems.length === 0 ? { tone: "saved", text: `Saved to ${file}.` } : { tone: "error", text: `Saved to ${file}, but the tokens were not regenerated: ${result.problems.join("; ")}` }
+      );
+    } catch (e) {
+      setNotice({ tone: "error", text: `Saving needs forge's dev server, which did not answer: ${e.message}` });
+    } finally {
+      setSaving(false);
+    }
+  };
   const onCollapsedChange = useCallback(
     (category, collapsed) => setFolds((prev) => ({ ...prev, [category]: collapsed })),
     [setFolds]
@@ -277,7 +396,18 @@ function CssVarsPanel() {
           }
         }
       ),
-      /* @__PURE__ */ jsx(Input, { "aria-label": "Filter", placeholder: "Filter by name or value", value: filter, onChange: setFilter })
+      /* @__PURE__ */ jsx(Input, { "aria-label": "Filter", placeholder: "Filter by name or value", value: filter, onChange: setFilter }),
+      tab === "theme" && (unsaved.length > 0 || notice) ? /* @__PURE__ */ jsxs("div", { className: "fg-css-vars__save", children: [
+        unsaved.length > 0 ? /* @__PURE__ */ jsx(Button$1, { variant: "primary", size: "sm", loading: saving, disabled: saving, onClick: () => void save(), children: "Save scales to theme" }) : null,
+        notice ? /* @__PURE__ */ jsx(
+          "p",
+          {
+            className: `fg-css-vars__notice fg-css-vars__notice--${notice.tone}`,
+            role: notice.tone === "error" ? "alert" : "status",
+            children: notice.text
+          }
+        ) : null
+      ] }) : null
     ] }),
     shown.length === 0 ? /* @__PURE__ */ jsx("p", { className: "fg-css-vars__empty", children: tokens.length === 0 ? "The story\u2019s frame has reported no variables." : "No variables match." }) : /* @__PURE__ */ jsx(
       TokenPanel,
@@ -294,12 +424,14 @@ function CssVarsPanel() {
 }
 function FocusedCssVars() {
   const { focusedTrialId, trials, instruments } = useLabContext();
+  const labGlobals2 = useContext(StoryGlobalsContext);
   const record = trials.find((trial) => trial.id === focusedTrialId);
   if (!record) return null;
+  const pins = record.config?.[GLOBALS_KEY];
   const instrument = instruments.find((i) => i.name === record.instrumentName);
   return /* @__PURE__ */ jsxs("section", { className: "fg-css-vars-focus", "aria-label": "CSS Vars", children: [
     /* @__PURE__ */ jsx("p", { className: "fg-css-vars__trial", children: record.title ?? instrument?.title ?? record.instrumentName }),
-    /* @__PURE__ */ jsx(TrialIdContext.Provider, { value: record.id, children: /* @__PURE__ */ jsx(CssVarsPanel, {}) })
+    /* @__PURE__ */ jsx(TrialIdContext.Provider, { value: record.id, children: /* @__PURE__ */ jsx(CssVarsPanel, { globals: effectiveGlobals(labGlobals2, pins) }) })
   ] });
 }
 var CSS_VARS_SECTION = {
@@ -308,9 +440,15 @@ var CSS_VARS_SECTION = {
   item: { title: "CSS Vars", body: /* @__PURE__ */ jsx(FocusedCssVars, {}) }
 };
 
+// src/shell/breadcrumb.ts
+function breadcrumb(title, name) {
+  const segments = [...title.split("/"), name].filter((segment, i) => i === 0 || segment.toLowerCase() !== "index");
+  return segments.join(" > ");
+}
+
 // src/shell/tree/buildComponents.ts
 var LIBRARIES = [
-  ["/packages/ui/", "weasel-ui"],
+  ["/packages/ui/", "ui"],
   ["/packages/labkit/", "labkit"],
   ["/packages/forge/", "forge"],
   ["/apps/draw/", "draw"],
@@ -333,6 +471,7 @@ function buildComponents(index) {
         path: entry.title,
         label: segments[segments.length - 1],
         library: libraryOf(entry),
+        index: indexEntries([entry])[0],
         entries: []
       };
       byTitle.set(entry.title, row);
@@ -348,9 +487,10 @@ function buildComponents(index) {
 function disambiguate(rows) {
   const byLabel = /* @__PURE__ */ new Map();
   for (const row of rows) {
-    const group = byLabel.get(row.label);
+    const key = `${row.library}\0${row.label}`;
+    const group = byLabel.get(key);
     if (group) group.push(row);
-    else byLabel.set(row.label, [row]);
+    else byLabel.set(key, [row]);
   }
   for (const group of byLabel.values()) {
     if (group.length < 2) continue;
@@ -373,20 +513,39 @@ function filterComponents(rows, query) {
       continue;
     }
     const entries = row.entries.filter((entry) => entry.name.toLowerCase().includes(needle));
-    if (entries.length > 0) out.push({ ...row, entries });
+    if (entries.length > 0) out.push({ path: row.path, label: row.label, library: row.library, entries });
   }
   return out;
 }
 function componentNodes(rows) {
-  return rows.map(
-    (row) => row.entries.length === 1 ? { kind: "story", entry: row.entries[0], tag: row.library, label: row.label } : {
+  const root = [];
+  const folders = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const labels = row.label.split("/");
+    const title = row.path.split("/");
+    let siblings = root;
+    let tag = row.library;
+    for (let i = 0; i < labels.length - 1; i++) {
+      const path = title.slice(0, title.length - labels.length + i + 1).join("/");
+      let folder = folders.get(path);
+      if (!folder) {
+        folder = { kind: "folder", label: labels[i], path, tag, children: [] };
+        folders.set(path, folder);
+        siblings.push(folder);
+      }
+      siblings = folder.children;
+      tag = void 0;
+    }
+    siblings.push({
       kind: "folder",
-      label: row.label,
+      label: labels[labels.length - 1],
       path: row.path,
-      tag: row.library,
+      tag,
+      ...row.index ? { index: row.index } : {},
       children: row.entries.map((entry) => ({ kind: "story", entry }))
-    }
-  );
+    });
+  }
+  return root;
 }
 function librariesIn(index) {
   return [...new Set(index.map(libraryOf))].sort((a, b) => a.localeCompare(b));
@@ -501,51 +660,73 @@ function StoryInfoDialog({ index, isReady, isOpen, onOpenChange }) {
     {
       isOpen,
       onOpenChange,
-      title: `${dossier.title} / ${dossier.name}`,
+      title: breadcrumb(dossier.title, dossier.name),
       className: "fg-info-dialog",
       children: /* @__PURE__ */ jsx(StoryDossier, { dossier })
     }
   );
 }
-var GLOBALS_KEY = "$globals";
-var FOLLOW_LAB = "lab";
-var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-var isGlobalsPath = (path) => path === GLOBALS_KEY || path.startsWith(`${GLOBALS_KEY}.`);
-function labGlobals(declarations, stored) {
-  const from = isRecord(stored) ? stored : {};
-  return Object.fromEntries(
-    Object.entries(declarations).map(([key, declaration]) => {
-      const value = from[key];
-      return [key, declaration.options.some((option) => option.value === value) ? value : declaration.default];
-    })
-  );
+function canMoveFrames() {
+  return typeof Element !== "undefined" && "moveBefore" in Element.prototype;
 }
-function effectiveGlobals(lab, pins) {
-  if (!isRecord(pins)) return lab;
-  const pinned = Object.entries(pins).filter(([key, value]) => key in lab && value !== FOLLOW_LAB);
-  return pinned.length === 0 ? lab : { ...lab, ...Object.fromEntries(pinned) };
-}
-function storyConfig(config, previous) {
-  if (!isRecord(config) || !(GLOBALS_KEY in config)) return config;
-  const rest = Object.fromEntries(Object.entries(config).filter(([key]) => key !== GLOBALS_KEY));
-  if (isRecord(previous)) {
-    const keys = Object.keys(rest);
-    if (keys.length === Object.keys(previous).length && keys.every((key) => rest[key] === previous[key])) return previous;
-  }
-  return rest;
+function moveFrame(host, frame) {
+  host.moveBefore(frame, host.firstChild);
 }
-function withGlobals(schema, declarations) {
-  const entries = Object.entries(declarations);
-  if (entries.length === 0) return schema;
-  const leaves2 = Object.fromEntries(
-    entries.map(([key, declaration]) => [
-      key,
-      f.enum(FOLLOW_LAB, [{ value: FOLLOW_LAB, label: "Lab" }, ...declaration.options]).label(declaration.label)
-    ])
-  );
-  const group = f.group(leaves2).label("").section("Globals", { layout: "inline", pack: "pairs" });
-  return f.schema({ ...schema.nodes, [GLOBALS_KEY]: group });
+var whenIdle = (fn) => {
+  if (typeof requestIdleCallback === "function") {
+    const handle2 = requestIdleCallback(fn, { timeout: 500 });
+    return () => cancelIdleCallback(handle2);
+  }
+  const handle = setTimeout(fn, 200);
+  return () => clearTimeout(handle);
+};
+function createFramePool(frameUrl, size = 2) {
+  const shelf = document.createElement("div");
+  shelf.className = "fg-frame-pool";
+  shelf.setAttribute("aria-hidden", "true");
+  document.body.append(shelf);
+  const warm = [];
+  let loading = 0;
+  let cancelRefill = null;
+  let disposed = false;
+  const load = () => {
+    loading += 1;
+    const frame = document.createElement("iframe");
+    frame.tabIndex = -1;
+    frame.src = frameUrl;
+    const onMessage = (event) => {
+      if (event.source !== frame.contentWindow || event.origin !== location.origin) return;
+      if (event.data?.type !== FRAME_HELLO) return;
+      window.removeEventListener("message", onMessage);
+      loading -= 1;
+      warm.push(frame);
+    };
+    window.addEventListener("message", onMessage);
+    shelf.append(frame);
+  };
+  const refill = () => {
+    if (disposed || cancelRefill) return;
+    cancelRefill = whenIdle(() => {
+      cancelRefill = null;
+      while (!disposed && warm.length + loading < size) load();
+    });
+  };
+  if (canMoveFrames()) refill();
+  return {
+    claim() {
+      if (!canMoveFrames()) return null;
+      const frame = warm.shift() ?? null;
+      refill();
+      return frame;
+    },
+    dispose() {
+      disposed = true;
+      cancelRefill?.();
+      shelf.remove();
+    }
+  };
 }
+var FramePoolContext = createContext(null);
 var RECORD = "fg-globals";
 function useLabGlobals(declarations) {
   const [stored, setStored] = usePersistedState(RECORD, null, { scope: "lab" });
@@ -556,19 +737,65 @@ function useLabGlobals(declarations) {
   );
   return [values, set];
 }
-function GlobalsToolbar({ declarations }) {
-  const [values, set] = useLabGlobals(declarations);
-  return /* @__PURE__ */ jsx("div", { className: "fg-globals", role: "toolbar", "aria-label": "Globals", children: Object.entries(declarations).map(([key, declaration]) => /* @__PURE__ */ jsx(
+function GlobalSelect({ name, declaration, values, set, labeled = false }) {
+  return /* @__PURE__ */ jsx(
     Select,
     {
-      "aria-label": declaration.label,
-      width: "fit",
-      selectedKey: String(values[key]),
-      onSelectionChange: (value) => set(key, value),
+      ...labeled ? { label: declaration.label } : { "aria-label": declaration.label },
+      width: labeled ? "fill" : "fit",
+      selectedKey: String(values[name]),
+      onSelectionChange: (value) => set(name, value),
       options: declaration.options
-    },
-    key
-  )) });
+    }
+  );
+}
+function GlobalsToolbar({ declarations }) {
+  const [values, set] = useLabGlobals(declarations);
+  const entries = Object.entries(declarations);
+  return /* @__PURE__ */ jsx("div", { className: "fg-globals", role: "toolbar", "aria-label": "Globals", children: entries.filter(([, declaration]) => declaration.under === void 0).map(([key, declaration]) => {
+    const nested = entries.filter(([, other]) => other.under === key);
+    return /* @__PURE__ */ jsxs("div", { className: "fg-globals__item", children: [
+      /* @__PURE__ */ jsx(GlobalSelect, { name: key, declaration, values, set }),
+      nested.length > 0 ? /* @__PURE__ */ jsx(NestedGlobals, { label: declaration.label, nested, values, set }) : null
+    ] }, key);
+  }) });
+}
+function NestedGlobals({
+  label,
+  nested,
+  values,
+  set
+}) {
+  const anchor = useRef(null);
+  const [open, setOpen] = useState(false);
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      Button$1,
+      {
+        ref: anchor,
+        variant: "ghost",
+        size: "sm",
+        iconOnly: true,
+        ariaLabel: `More ${label} settings`,
+        pressed: open,
+        onClick: () => setOpen((was) => !was),
+        children: /* @__PURE__ */ jsx(TuneIcon, { size: 16 })
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      Callout,
+      {
+        triggerRef: anchor,
+        isOpen: open,
+        onOpenChange: setOpen,
+        placement: "bottom end",
+        showCloseButton: false,
+        title: label,
+        className: "fg-globals__popover",
+        children: nested.map(([key, declaration]) => /* @__PURE__ */ jsx(GlobalSelect, { name: key, declaration, values, set, labeled: true }, key))
+      }
+    )
+  ] });
 }
 function LabGlobals({
   declarations,
@@ -578,7 +805,6 @@ function LabGlobals({
   useEffect(() => onChange(values), [values, onChange]);
   return null;
 }
-var StoryGlobalsContext = createContext({});
 
 // src/shell/revealTrial.ts
 var FLASH_MS = 600;
@@ -605,33 +831,51 @@ function readRoute() {
   if (!hash.startsWith("#/")) return null;
   return decodeURIComponent(hash.slice(2)) || null;
 }
+function readRouteEntry() {
+  const state = history.state;
+  const entry = state?.forgeRoute;
+  return typeof entry?.step === "number" ? entry : null;
+}
+function crossesInPlace(from, to) {
+  if (!from || !to || from.step === to.step) return false;
+  return to.step < from.step ? from.inPlace : to.inPlace;
+}
+function stamp(entry, hash) {
+  history.replaceState({ ...history.state ?? {}, forgeRoute: entry }, "", hash);
+}
+function setRoute(id, options = {}) {
+  const hash = `#/${encodeURIComponent(id)}`;
+  if (readRoute() === id) {
+    history.replaceState(history.state, "", hash);
+    return;
+  }
+  const from = readRouteEntry() ?? { step: 0, inPlace: false };
+  stamp(from, location.hash);
+  location.hash = hash;
+  stamp({ step: from.step + 1, inPlace: options.inPlace ?? false }, hash);
+}
 function useRoute() {
-  const [route, setRoute] = useState(readRoute);
+  const [route, setCurrent] = useState(readRoute);
   useEffect(() => {
-    const sync = () => setRoute(readRoute());
+    const sync = () => setCurrent(readRoute());
     window.addEventListener("hashchange", sync);
     sync();
     return () => window.removeEventListener("hashchange", sync);
   }, []);
-  const go = useCallback((id) => {
-    const hash = `#/${encodeURIComponent(id)}`;
-    if (readRoute() === id) history.replaceState(null, "", hash);
-    else location.hash = hash;
-  }, []);
-  return [route, go];
+  return [route, setRoute];
 }
 
 // src/shell/tree/buildTree.ts
 function sortFolder(nodes) {
   const folders = nodes.filter((n) => n.kind === "folder");
-  const stories = nodes.filter((n) => n.kind === "story");
   folders.sort((a, b) => a.label.localeCompare(b.label));
   for (const folder of folders) folder.children = sortFolder(folder.children);
-  return [...folders, ...stories];
+  return [...folders, ...nodes.filter((n) => n.kind === "story")];
 }
 function buildTree(index) {
   const root = [];
   const folders = /* @__PURE__ */ new Map();
+  const pages = new Map(indexEntries(index).map((page) => [page.title, page]));
   for (const entry of index) {
     let siblings = root;
     let path = "";
@@ -639,7 +883,8 @@ function buildTree(index) {
       path = path ? `${path}/${label}` : label;
       let folder = folders.get(path);
       if (!folder) {
-        folder = { kind: "folder", label, path, children: [] };
+        const page = pages.get(path);
+        folder = { kind: "folder", label, path, children: [], ...page ? { index: page } : {} };
         folders.set(path, folder);
         siblings.push(folder);
       }
@@ -657,7 +902,9 @@ function filterTree(nodes, query) {
       return `${node.entry.title}/${node.entry.name}`.toLowerCase().includes(needle) ? [node] : [];
     }
     const children = walk(node.children);
-    return children.length > 0 ? [{ ...node, children }] : [];
+    if (children.length === 0) return [];
+    const { index: page, ...folder } = node;
+    return [page && node.path.toLowerCase().includes(needle) ? { ...folder, children, index: page } : { ...folder, children }];
   });
   return walk(nodes);
 }
@@ -676,12 +923,21 @@ function ancestorsOf(entry) {
   }
   return paths;
 }
+var LIBRARY_TONES = {
+  ui: "color-mix(in oklab, var(--wzl-swatch-blue), var(--wzl-fg) 35%)",
+  labkit: "color-mix(in oklab, var(--wzl-swatch-teal), var(--wzl-fg) 45%)",
+  forge: "color-mix(in oklab, var(--wzl-swatch-amber), var(--wzl-fg) 40%)",
+  draw: "color-mix(in oklab, var(--wzl-swatch-rose), var(--wzl-fg) 35%)"
+};
+function LibraryBadge({ library }) {
+  return /* @__PURE__ */ jsx(Badge, { status: "muted", tone: LIBRARY_TONES[library], variant: "subtle", size: "sm", className: "fg-tree__tag", children: library });
+}
 function StoryTree({ ctx, index }) {
   const headingId = useId();
-  const [route, setRoute] = useRoute();
+  const [route, setRoute2] = useRoute();
   const [query, setQuery] = useState("");
   const [folds, setFolds] = usePersistedState("fg-tree-open", {}, { scope: "lab" });
-  const [view, setView] = usePersistedState("fg-tree-view", "tree", { scope: "lab" });
+  const [view, setView] = usePersistedState("fg-tree-view", "components", { scope: "lab" });
   const [hidden, setHidden] = usePersistedState("fg-tree-libraries", {}, { scope: "lab" });
   const [focusKey, setFocusKey] = useState(null);
   const items = useRef(/* @__PURE__ */ new Map());
@@ -693,10 +949,11 @@ function StoryTree({ ctx, index }) {
     () => view === "components" ? componentNodes(filterComponents(components, query)) : filterTree(tree, query),
     [view, components, tree, query]
   );
-  const routed = kept.find((entry) => entry.id === route);
+  const routable = useMemo(() => [...kept, ...indexEntries(kept)], [kept]);
+  const routed = routable.find((entry) => entry.id === route);
   const routeAncestors = useMemo(() => ancestorsOf(routed), [routed]);
   const filtering = query.trim() !== "";
-  const isOpen = (path) => filtering || (folds[path] ?? (view === "tree" && routeAncestors.has(path)));
+  const isOpen = (path) => filtering || (folds[path] ?? routeAncestors.has(path));
   const rows = [];
   const collect = (nodes, parent) => {
     for (const node of nodes) {
@@ -719,8 +976,22 @@ function StoryTree({ ctx, index }) {
     const focused = ctx.trials.find((trial) => trial.id === ctx.focusedTrialId);
     if (another || !focused) ctx.addTrial(entry.id);
     else if (focused.instrumentName === entry.id) revealTrial(focused.id);
-    else ctx.swapTrial(focused.id, entry.id);
-    setRoute(entry.id);
+    else {
+      ctx.swapTrial(focused.id, entry.id);
+      setRoute2(entry.id, { inPlace: true });
+      return;
+    }
+    setRoute2(entry.id);
+  };
+  const openFolder = (node, another) => {
+    if (!node.index) {
+      setOpen(node.path, !isOpen(node.path));
+      return;
+    }
+    if (folds[node.path] === false) {
+      setFolds(({ [node.path]: _dropped, ...rest }) => rest);
+    }
+    activate(node.index, another);
   };
   const onKeyDown = (event) => {
     const at = rows.findIndex((row2) => row2.key === active);
@@ -751,8 +1022,8 @@ function StoryTree({ ctx, index }) {
         break;
       case "Enter":
       case " ":
-        if (node.kind === "folder") setOpen(node.path, !isOpen(node.path));
-        else activate(node.entry, event.shiftKey);
+        if (node.kind === "story") activate(node.entry, event.shiftKey);
+        else openFolder(node, event.shiftKey);
         break;
       default:
         return;
@@ -784,12 +1055,35 @@ function StoryTree({ ctx, index }) {
           ...itemProps(node, level),
           "aria-expanded": open,
           "aria-label": node.label,
+          "aria-current": node.index && openIds.has(node.index.id) ? "true" : void 0,
           className: "fg-tree__node",
           children: [
-            /* @__PURE__ */ jsxs("div", { className: "fg-tree__item fg-tree__folder", onClick: () => setOpen(node.path, !open), children: [
-              /* @__PURE__ */ jsx("span", { className: "fg-tree__label", children: node.label }),
-              node.tag ? /* @__PURE__ */ jsx("span", { className: "fg-tree__tag", children: node.tag }) : null
-            ] }),
+            /* @__PURE__ */ jsxs(
+              "div",
+              {
+                className: "fg-tree__item fg-tree__folder",
+                onClick: (event) => {
+                  setFocusKey(keyOf(node));
+                  openFolder(node, event.shiftKey);
+                },
+                children: [
+                  /* @__PURE__ */ jsx(
+                    "span",
+                    {
+                      "aria-hidden": "true",
+                      className: "fg-tree__fold",
+                      onClick: (event) => {
+                        event.stopPropagation();
+                        setOpen(node.path, !open);
+                      },
+                      children: /* @__PURE__ */ jsx(DisclosureMark, { open })
+                    }
+                  ),
+                  /* @__PURE__ */ jsx("span", { className: "fg-tree__label", children: node.label }),
+                  node.tag ? /* @__PURE__ */ jsx(LibraryBadge, { library: node.tag }) : null
+                ]
+              }
+            ),
             open ? /* @__PURE__ */ jsx("div", { role: "group", className: "fg-tree__group", children: renderNodes(node.children, level + 1) }) : null
           ]
         },
@@ -812,7 +1106,7 @@ function StoryTree({ ctx, index }) {
         },
         children: [
           /* @__PURE__ */ jsx("span", { className: "fg-tree__label", children: node.label ?? entry.name }),
-          node.tag ? /* @__PURE__ */ jsx("span", { className: "fg-tree__tag", children: node.tag }) : null
+          node.tag ? /* @__PURE__ */ jsx(LibraryBadge, { library: node.tag }) : null
         ]
       },
       keyOf(node)
@@ -843,7 +1137,7 @@ function StoryTree({ ctx, index }) {
         {
           isSelected: !hidden[library],
           onChange: (on) => setHidden((prev) => ({ ...prev, [library]: !on })),
-          children: library
+          children: /* @__PURE__ */ jsx(LibraryBadge, { library })
         },
         library
       ))
@@ -905,10 +1199,90 @@ function createAnswerBook() {
     }
   };
 }
+function IndexTrial({ bundle, setup, config }) {
+  const lab = useLabContext();
+  const trialId = useContext(TrialIdContext);
+  const open = (id) => {
+    if (!trialId || !lab.instruments.some((instrument) => instrument.name === id)) return;
+    lab.swapTrial(trialId, id);
+    setRoute(id, { inPlace: true });
+  };
+  const render = (globals) => {
+    const env = {
+      title: bundle.title,
+      ...bundle.description === void 0 ? {} : { description: bundle.description },
+      stories: bundle.stories,
+      descriptions: bundle.descriptions,
+      globals,
+      decorators: setup.decorators ?? [],
+      open,
+      // A story that throws shows its error in its own cell; the rest of the page is still worth reading.
+      onError: (error) => console.error(error)
+    };
+    return /* @__PURE__ */ jsx(IndexPage, { env, render: bundle.render });
+  };
+  return /* @__PURE__ */ jsx(TrialHost, { layout: "fullscreen", setup, config, children: render });
+}
+function annotationsOn(frames) {
+  return {
+    targets: (_state, _config, trial) => {
+      const ref = frames.hostRef(trial.id);
+      const frame = frames.get(trial.id);
+      const box = frame.size ?? { width: ref.current?.clientWidth ?? 0, height: ref.current?.clientHeight ?? 0 };
+      const capture = frame.capture;
+      return [
+        {
+          id: "story",
+          ref,
+          content: { w: Math.max(1, box.width), h: Math.max(1, box.height) },
+          ...capture ? { base: () => capture() } : {}
+        }
+      ];
+    }
+  };
+}
+function documentInstrument(options) {
+  const { entry, loaded, setup, globals = {}, frames } = options;
+  const schema = loaded.kind === "story" ? loaded.story.config : f.schema({});
+  const config = withGlobals(schema, globals);
+  const initialState = loaded.kind === "story" ? loaded.story.initialState : null;
+  return {
+    name: entry.id,
+    title: breadcrumb(entry.title, entry.name),
+    config,
+    defaultConfig: () => config.defaults(),
+    initialState: (c) => initialState?.(c) ?? null,
+    render: (ctx) => loaded.kind === "story" ? /* @__PURE__ */ jsx(StoryTrial, { story: loaded.story, setup, ctx }) : /* @__PURE__ */ jsx(IndexTrial, { bundle: loaded.bundle, setup, config: ctx.config }),
+    ...frames ? { annotations: annotationsOn(frames) } : {},
+    ...loaded.kind === "story" && loaded.story.viewport ? { stage: { size: { width: loaded.story.viewport.width, height: loaded.story.viewport.height } } } : {}
+  };
+}
+function StoryLoad({ entry, load, fault }) {
+  useEffect(() => {
+    if (!fault) load(entry);
+  }, [entry, load, fault]);
+  return /* @__PURE__ */ jsx("div", { className: "fg-story fg-story--loading", "data-fg-layout": "fullscreen", children: fault ? /* @__PURE__ */ jsxs("div", { className: "fg-fault", role: "alert", children: [
+    /* @__PURE__ */ jsx("span", { className: "fg-fault__phase", children: "import" }),
+    /* @__PURE__ */ jsx("p", { className: "fg-fault__message", children: fault.message })
+  ] }) : null });
+}
+function pendingInstrument(options) {
+  const { entry, globals = {} } = options;
+  const config = withGlobals(f.schema({}), globals);
+  return {
+    name: entry.id,
+    title: breadcrumb(entry.title, entry.name),
+    config,
+    defaultConfig: () => config.defaults(),
+    initialState: () => null,
+    render: () => /* @__PURE__ */ jsx(StoryLoad, { ...options }, options.generation ?? 0)
+  };
+}
 
 // src/shell/readyKey.ts
 var readyKey = (ready) => stableStringify({ schema: ready.schema, layout: ready.layout, viewport: ready.viewport });
 var START_TIMEOUT_MS = 1e4;
+var HELLO_TIMEOUT_MS = 3e4;
 var requests = 0;
 var IN_VIEW_MARGIN = "50%";
 function useInView(ref) {
@@ -952,13 +1326,17 @@ function FrameView(props) {
   const trialId = useContext(TrialIdContext);
   const frames = useContext(TrialFramesContext);
   const [overrides] = useCssOverrides();
+  const pool = useContext(FramePoolContext);
+  const lab = useLabContext();
   const src = `${frameUrl}#${entry.id}`;
+  const title = breadcrumb(entry.title, entry.name);
   const iframeRef = useRef(null);
   const hostRef = useRef(null);
+  const slotRef = useRef(null);
   const inView = useInView(hostRef);
   const link = useRef(null);
-  const latest = useRef({ ...props, globals, overrides });
-  latest.current = { ...props, globals, overrides };
+  const latest = useRef({ ...props, globals, overrides, pool, lab, title });
+  latest.current = { ...props, globals, overrides, pool, lab, title };
   const [fault, setFault] = useState(null);
   const [pending, setPending] = useState(true);
   const init = (current) => {
@@ -1015,6 +1393,13 @@ function FrameView(props) {
         else current.pending.get(msg.id)?.fail(new Error(msg.message));
         current.pending.delete(msg.id);
         break;
+      case "open": {
+        const { lab: liveLab } = latest.current;
+        if (!trialId || !liveLab.instruments.some((instrument) => instrument.name === msg.id)) break;
+        liveLab.swapTrial(trialId, msg.id);
+        setRoute(msg.id, { inPlace: true });
+        break;
+      }
       case "fault":
         if (msg.phase === "render" && msg.seq !== void 0 && msg.seq < current.inputs) break;
         clearTimeout(current.timer);
@@ -1022,10 +1407,10 @@ function FrameView(props) {
         break;
     }
   };
-  const onLoad = () => {
+  const connect = (frame) => {
     closeLink(link);
     setPending(true);
-    const target = iframeRef.current?.contentWindow;
+    const target = frame.contentWindow;
     if (!target) return;
     const { port1, port2 } = new MessageChannel();
     const timer = setTimeout(() => setFault({ phase: null, message: `Frame did not start: ${src}` }), START_TIMEOUT_MS);
@@ -1077,15 +1462,53 @@ function FrameView(props) {
     };
     link.current = current;
     channel.on((msg) => receive(current, msg));
-    target.postMessage({ type: PORT_HANDOFF }, location.origin, [port2]);
+    target.postMessage({ type: PORT_HANDOFF, id: latest.current.entry.id }, location.origin, [
+      port2
+    ]);
   };
-  useEffect(() => () => closeLink(link), []);
+  const connectRef = useRef(connect);
+  connectRef.current = connect;
   useEffect(() => {
-    if (inView) return;
-    closeLink(link);
-    setPending(true);
-    setFault(null);
-  }, [inView]);
+    const slot = slotRef.current;
+    if (!inView || !slot) return;
+    const claimed = latest.current.pool?.claim() ?? null;
+    const frame = claimed ?? document.createElement("iframe");
+    frame.className = "fg-frame-view";
+    frame.title = latest.current.title;
+    frame.removeAttribute("tabindex");
+    frame.toggleAttribute("data-pending", true);
+    iframeRef.current = frame;
+    const unheard = claimed ? void 0 : setTimeout(() => setFault({ phase: null, message: `Frame did not start: ${src}` }), HELLO_TIMEOUT_MS);
+    const onMessage = (event) => {
+      if (event.source !== frame.contentWindow || event.origin !== location.origin) return;
+      if (event.data?.type !== FRAME_HELLO) return;
+      clearTimeout(unheard);
+      connectRef.current(frame);
+    };
+    window.addEventListener("message", onMessage);
+    if (claimed) {
+      moveFrame(slot, claimed);
+      connectRef.current(claimed);
+    } else {
+      frame.src = src;
+      slot.append(frame);
+    }
+    return () => {
+      window.removeEventListener("message", onMessage);
+      clearTimeout(unheard);
+      closeLink(link);
+      frame.remove();
+      iframeRef.current = null;
+      setPending(true);
+      setFault(null);
+    };
+  }, [inView, src]);
+  useEffect(() => {
+    iframeRef.current?.toggleAttribute("data-pending", pending && !fault);
+  }, [pending, fault, inView, src]);
+  useEffect(() => {
+    if (iframeRef.current) iframeRef.current.title = title;
+  }, [title]);
   useEffect(() => answers.hold(ctx.config), [answers, ctx.config]);
   useEffect(() => {
     const current = link.current;
@@ -1127,17 +1550,7 @@ function FrameView(props) {
       },
       className: "fg-frame-host",
       children: [
-        inView ? /* @__PURE__ */ jsx(
-          "iframe",
-          {
-            ref: iframeRef,
-            className: "fg-frame-view",
-            src,
-            title: `${entry.title} / ${entry.name}`,
-            onLoad,
-            "data-pending": pending && !fault ? "" : void 0
-          }
-        ) : null,
+        /* @__PURE__ */ jsx("div", { ref: slotRef, className: "fg-frame-slot" }),
         fault ? /* @__PURE__ */ jsxs("div", { className: "fg-fault", role: "alert", children: [
           fault.phase ? /* @__PURE__ */ jsx("span", { className: "fg-fault__phase", children: fault.phase }) : null,
           /* @__PURE__ */ jsx("p", { className: "fg-fault__message", children: fault.message })
@@ -1146,7 +1559,7 @@ function FrameView(props) {
     }
   );
 }
-function annotationsOn(frames) {
+function annotationsOn2(frames) {
   return {
     targets: (_state, _config, trial) => {
       const ref = frames.hostRef(trial.id);
@@ -1173,7 +1586,7 @@ function storyInstrument(options) {
   const descriptionKey = ready ? readyKey(ready) : null;
   return {
     name: entry.id,
-    title: `${entry.title} / ${entry.name}`,
+    title: breadcrumb(entry.title, entry.name),
     config,
     defaultConfig: () => config.defaults(),
     initialState: () => null,
@@ -1188,17 +1601,22 @@ function storyInstrument(options) {
         ctx
       }
     ),
-    ...frames ? { annotations: annotationsOn(frames) } : {},
+    ...frames ? { annotations: annotationsOn2(frames) } : {},
     ...ready?.viewport ? { stage: { size: { width: ready.viewport.width, height: ready.viewport.height } } } : {}
   };
 }
 
 // src/shell/useStoryRegistry.ts
-var NO_GLOBALS = {};
+var NO_GLOBALS2 = {};
+var NO_SETUP = {};
 var pruned = (map, ids) => [...map.keys()].every((id) => ids.has(id)) ? map : new Map([...map].filter(([id]) => ids.has(id)));
+var toError = (error) => error instanceof Error ? error : new Error(String(error));
 function useStoryRegistry(index, options) {
-  const { frameUrl, globals = NO_GLOBALS, frames } = options;
+  const { frameUrl, globals = NO_GLOBALS2, frames, importers, setup = NO_SETUP, load = loadStories } = options;
   const [readies, setReadies] = useState(() => /* @__PURE__ */ new Map());
+  const [loaded, setLoaded] = useState(() => /* @__PURE__ */ new Map());
+  const [faults, setFaults] = useState(() => /* @__PURE__ */ new Map());
+  const [generations, setGenerations] = useState(() => /* @__PURE__ */ new Map());
   const [revisions, setRevisions] = useState(() => /* @__PURE__ */ new Map());
   const onReady = useCallback((entry, ready) => {
     setReadies((prev) => {
@@ -1210,8 +1628,93 @@ function useStoryRegistry(index, options) {
   useEffect(() => {
     const ids = new Set(index.map((entry) => entry.id));
     setReadies((prev) => pruned(prev, ids));
+    setLoaded((prev) => pruned(prev, ids));
+    setFaults((prev) => pruned(prev, ids));
     setRevisions((prev) => pruned(prev, ids));
   }, [index]);
+  const imports = useRef(/* @__PURE__ */ new Map());
+  const live = useRef({ index, importers, setup, load });
+  live.current = { index, importers, setup, load };
+  const importOf = useCallback((file) => {
+    let loading = imports.current.get(file);
+    if (!loading) {
+      const importer = live.current.importers?.[file];
+      loading = importer ? importer() : Promise.reject(new Error(`No importer for ${file}`));
+      imports.current.set(file, loading);
+    }
+    return loading;
+  }, []);
+  const request = useCallback(
+    (entry) => {
+      const { setup: current, load: loadModule } = live.current;
+      const settle2 = (ids2, result) => {
+        setLoaded((prev) => {
+          const next = new Map(prev);
+          for (const [id, value] of result) next.set(id, value);
+          return next;
+        });
+        setFaults((prev) => ids2.some((id) => prev.has(id)) ? pruned(prev, new Set([...prev.keys()].filter((id) => !ids2.includes(id)))) : prev);
+      };
+      const fail = (ids2, error) => {
+        const fault = toError(error);
+        setFaults((prev) => {
+          const next = new Map(prev);
+          for (const id of ids2) next.set(id, fault);
+          return next;
+        });
+      };
+      if (isIndexId(entry.id)) {
+        const entries = live.current.index.filter((e) => !isIndexId(e.id) && indexId(e.title) === entry.id);
+        const files = [...new Set(entries.map((e) => e.file))];
+        void Promise.all(files.map(importOf)).then(async (mods) => {
+          const byFile = new Map(files.map((file, i) => [file, loadModule(mods[i] ?? {}, entry.title, current.parameters)]));
+          const stories = entries.flatMap(
+            (e) => byFile.get(e.file)?.find((s) => s.exportName === e.exportName) ?? []
+          );
+          for (const story of stories) await current.prepare?.(story);
+          const result = /* @__PURE__ */ new Map();
+          result.set(entry.id, {
+            kind: "index",
+            bundle: {
+              title: entry.title,
+              ...entry.componentDescription === void 0 ? {} : { description: entry.componentDescription },
+              stories,
+              descriptions: Object.fromEntries(entries.flatMap((e) => e.description ? [[e.id, e.description]] : [])),
+              render: mods.map(indexRenderOf).find((render) => render !== null) ?? null
+            }
+          });
+          settle2([entry.id], result);
+        }).catch((error) => fail([entry.id], error));
+        return;
+      }
+      const siblings = live.current.index.filter((e) => e.file === entry.file && !isIndexId(e.id));
+      const ids = siblings.map((e) => e.id);
+      void importOf(entry.file).then(async (mod) => {
+        const stories = loadModule(mod, entry.title, current.parameters);
+        const result = /* @__PURE__ */ new Map();
+        for (const sibling of siblings) {
+          const story = stories.find((s) => s.exportName === sibling.exportName);
+          if (!story) continue;
+          await current.prepare?.(story);
+          result.set(sibling.id, { kind: "story", story });
+        }
+        if (!result.has(entry.id)) throw new Error(`${entry.file} has no story export "${entry.exportName}"`);
+        settle2(ids, result);
+      }).catch((error) => fail(ids, error));
+    },
+    [importOf]
+  );
+  const reload = useCallback(
+    (file) => {
+      imports.current.delete(file);
+      const affected = live.current.index.filter((e) => e.file === file || isIndexId(e.id) && live.current.index.some((s) => s.file === file && indexId(s.title) === e.id));
+      const ids = new Set(affected.map((e) => e.id));
+      setLoaded((prev) => pruned(prev, new Set([...prev.keys()].filter((id) => !ids.has(id)))));
+      setFaults((prev) => pruned(prev, new Set([...prev.keys()].filter((id) => !ids.has(id)))));
+      setGenerations((prev) => new Map(prev).set(file, (prev.get(file) ?? 0) + 1));
+    },
+    []
+  );
   const committed = useRef({ built: /* @__PURE__ */ new Map(), books: /* @__PURE__ */ new Map(), list: [] });
   const cache = useMemo(() => {
     const previous = committed.current;
@@ -1219,26 +1722,35 @@ function useStoryRegistry(index, options) {
     const books = /* @__PURE__ */ new Map();
     const list = index.map((entry) => {
       const ready = readies.get(entry.id);
+      const inDocument = importers !== void 0 && entry.isolate === void 0;
+      const had = loaded.get(entry.id);
+      const fault = faults.get(entry.id);
+      const generation = generations.get(entry.file) ?? 0;
       const revision = revisions.get(entry.id) ?? 0;
       const entryKey = stableStringify(entry);
       const answers = previous.books.get(entry.id) ?? createAnswerBook();
       books.set(entry.id, answers);
       const held = previous.built.get(entry.id);
-      const kept = held && held.entryKey === entryKey && held.ready === ready && held.frameUrl === frameUrl && held.globals === globals && held.frames === frames && held.revision === revision ? held : {
+      const kept = held && held.entryKey === entryKey && held.ready === ready && held.loaded === had && held.fault === fault && held.frameUrl === frameUrl && held.globals === globals && held.frames === frames && held.setup === setup && held.inDocument === inDocument && held.generation === generation && held.revision === revision ? held : {
         entryKey,
         ready,
+        loaded: had,
+        fault,
         frameUrl,
         globals,
         frames,
+        setup,
+        inDocument,
+        generation,
         revision,
-        instrument: storyInstrument({ entry, ready, answers, frameUrl, onReady, globals, ...frames ? { frames } : {} })
+        instrument: !inDocument ? storyInstrument({ entry, ready, answers, frameUrl, onReady, globals, ...frames ? { frames } : {} }) : had ? documentInstrument({ entry, loaded: had, setup, globals, ...frames ? { frames } : {} }) : pendingInstrument({ entry, globals, load: request, generation, ...fault ? { fault } : {} })
       };
       built.set(entry.id, kept);
       return kept.instrument;
     });
     const unchanged = list.length === previous.list.length && list.every((i, n) => i === previous.list[n]);
     return { built, books, list: unchanged ? previous.list : list };
-  }, [index, readies, revisions, frameUrl, globals, frames, onReady]);
+  }, [index, readies, loaded, faults, generations, revisions, frameUrl, globals, frames, setup, importers, onReady, request]);
   useLayoutEffect(() => {
     committed.current = cache;
   }, [cache]);
@@ -1250,22 +1762,29 @@ function useStoryRegistry(index, options) {
       for (const off of offs) off();
     };
   }, [cache.books]);
-  const isReady = useCallback((id) => readies.has(id), [readies]);
-  return { instruments: cache.list, isReady, onReady };
+  const isReady = useCallback((id) => readies.has(id) || loaded.has(id), [readies, loaded]);
+  return { instruments: cache.list, isReady, onReady, reload };
 }
 var NO_DECLARATIONS = {};
-function initialStory(index, fallback) {
+function initialStory(entries, fallback) {
   const route = readRoute();
-  return route !== null && index.some((entry) => entry.id === route) ? route : fallback;
+  return route !== null && entries.some((entry) => entry.id === route) ? route : fallback;
 }
 function RouteOpener({ index }) {
   const lab = useLabContext();
   const [route] = useRoute();
   const handled = useRef(null);
+  const last = useRef({ route: readRoute(), entry: readRouteEntry() });
   useEffect(() => {
-    if (route === null || handled.current === route || !index.some((entry) => entry.id === route)) return;
+    const from = last.current;
+    if (route !== from.route) last.current = { route, entry: readRouteEntry() };
+    if (route === null || handled.current === route || !index.some((e) => e.id === route)) return;
     handled.current = route;
-    if (!lab.trials.some((trial) => trial.instrumentName === route)) lab.addTrial(route);
+    if (lab.trials.some((trial) => trial.instrumentName === route)) return;
+    const previous = lab.trials.find((trial) => trial.instrumentName === from.route);
+    const target = (previous && crossesInPlace(from.entry, last.current.entry) ? previous : void 0) ?? lab.trials.find((trial) => trial.id === lab.focusedTrialId) ?? lab.trials[0];
+    if (target) lab.swapTrial(target.id, route);
+    else lab.addTrial(route);
   }, [route, index, lab]);
   return null;
 }
@@ -1283,11 +1802,33 @@ function useInfoShortcut(open) {
     return () => window.removeEventListener("keydown", onKeyDown);
   }, [open]);
 }
-function Workshop({ index, frameUrl, config, stories = [], storageKey, storage }) {
+function Workshop({ index, frameUrl, importers, setup, changes, config, stories = [], storageKey, storage }) {
   const declarations = config?.globals ?? NO_DECLARATIONS;
   const [frames] = useState(createTrialFrames);
-  const registry = useStoryRegistry(index, { frameUrl, globals: declarations, frames });
+  const [pool, setPool] = useState(null);
+  const framed = importers === void 0 || index.some((entry) => entry.isolate !== void 0);
+  useEffect(() => {
+    if (!framed) return;
+    const next = createFramePool(frameUrl);
+    setPool(next);
+    return () => {
+      next.dispose();
+      setPool(null);
+    };
+  }, [frameUrl, framed]);
+  const entries = useMemo(() => [...index, ...indexEntries(index)], [index]);
+  const registry = useStoryRegistry(entries, {
+    frameUrl,
+    globals: declarations,
+    frames,
+    ...importers ? { importers } : {},
+    ...setup ? { setup } : {}
+  });
+  const reload = registry.reload;
+  useEffect(() => changes?.subscribe(reload), [changes, reload]);
   const [labValues, setLabValues] = useState(() => labGlobals(declarations, void 0));
+  const themeFor = config?.labTheme;
+  const labTheme = useMemo(() => themeFor?.(labValues), [themeFor, labValues]);
   const [infoOpen, setInfoOpen] = useState(false);
   useInfoShortcut(setInfoOpen);
   const reportLabValues = useCallback(
@@ -1316,13 +1857,14 @@ function Workshop({ index, frameUrl, config, stories = [], storageKey, storage }
       stories.length > 0 ? /* @__PURE__ */ jsx("ul", { className: "fg-empty__globs", "aria-label": "Story globs", children: stories.map((glob) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx("code", { children: glob }) }, glob)) }) : null
     ] });
   }
-  return /* @__PURE__ */ jsx(StoryGlobalsContext.Provider, { value: labValues, children: /* @__PURE__ */ jsx(TrialFramesContext.Provider, { value: frames, children: /* @__PURE__ */ jsxs(
+  return /* @__PURE__ */ jsx(StoryGlobalsContext.Provider, { value: labValues, children: /* @__PURE__ */ jsx(FramePoolContext.Provider, { value: pool, children: /* @__PURE__ */ jsx(TrialFramesContext.Provider, { value: frames, children: /* @__PURE__ */ jsxs(
     Lab,
     {
       title: "weaselforge",
       density: "roomy",
+      ...labTheme ? { theme: labTheme } : {},
       instruments: registry.instruments,
-      defaultInstrument: initialStory(index, first.id),
+      defaultInstrument: initialStory(entries, first.id),
       storageKey: storageKey ?? "weaselforge",
       ...storage ? { storage } : {},
       labChrome,
@@ -1331,7 +1873,7 @@ function Workshop({ index, frameUrl, config, stories = [], storageKey, storage }
       ...config?.pages ? { pages: config.pages } : {},
       ...config?.path !== void 0 ? { path: config.path } : {},
       children: [
-        /* @__PURE__ */ jsx(RouteOpener, { index }),
+        /* @__PURE__ */ jsx(RouteOpener, { index: entries }),
         /* @__PURE__ */ jsx(
           StoryInfoDialog,
           {
@@ -1344,23 +1886,29 @@ function Workshop({ index, frameUrl, config, stories = [], storageKey, storage }
         /* @__PURE__ */ jsx(LabGlobals, { declarations, onChange: reportLabValues })
       ]
     }
-  ) }) });
+  ) }) }) });
 }
 function mountWorkshop({ container, ...props }) {
   const target = container ?? document.getElementById("root");
   if (!target) throw new Error("mountWorkshop: no container given and no #root element");
   const root = createRoot(target);
-  let current = props;
+  const changes = createStoryChanges();
+  let current = { ...props, changes };
   root.render(/* @__PURE__ */ jsx(Workshop, { ...current }));
   return {
     setIndex(index) {
       current = { ...current, index };
       root.render(/* @__PURE__ */ jsx(Workshop, { ...current }));
     },
+    setImporters(importers) {
+      current = { ...current, importers };
+      root.render(/* @__PURE__ */ jsx(Workshop, { ...current }));
+    },
+    reloadStory: (file) => changes.emit(file),
     unmount: () => root.unmount()
   };
 }
 
-export { A11Y_SECTION, A11yPanel, StoryGlobalsContext, TrialFramesContext, Workshop, mountWorkshop, useStoryRegistry, useTrialFrame };
+export { A11Y_SECTION, A11yPanel, Workshop, mountWorkshop, useStoryRegistry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map