@weasel-js/forge 1.5.1 → 1.6.0

package/dist/test/index.d.ts

@@ -1,4 +1,4 @@
-import { F as FrameSetup } from '../FrameController-BPfCt4PJ.js';
+import { F as FrameSetup } from '../FrameController-BspC9Zr5.js';
 import '@weasel-js/labkit/config';
 import 'react';
 
@@ -9,8 +9,8 @@ interface RunStoryOptions {
     viewport?: (width: number, height: number) => Promise<void>;
 }
 /**
- * Renders one story the way the workshop's frame does — defaults, no state, no globals — then plays it.
- * Throws on any fault the frame reports, or a play function that fails.
+ * Renders one story in the test page the way the workshop does — defaults, no state, no globals — then plays it.
+ * Throws on a render the story's boundary caught, or a play function that fails.
  */
 declare function runStory(mod: Record<string, unknown>, exportName: string, file: string, autoTitle: string, { setup, viewport }?: RunStoryOptions): Promise<void>;
 

package/dist/test/index.js

@@ -1,72 +1,41 @@
-import { loadStories, startFrame } from '../chunk-2MADHLRA.js';
+import { StoryTrial } from '../chunk-A4JOEGYQ.js';
+import { loadStories } from '../chunk-FWPBKKYB.js';
 import '../chunk-2GXKNXTJ.js';
-import '../chunk-6SRQIHJQ.js';
-import { openChannel } from '../chunk-2JDYOBWM.js';
-import '../chunk-TLO6UHF2.js';
-import '../chunk-FTFR2YPM.js';
+import '../chunk-HRGPFQBW.js';
+import '../chunk-VEKEBILL.js';
+import { withValueAtPath } from '@weasel-js/labkit/config';
+import { useState, useEffect } from 'react';
+import { createRoot } from 'react-dom/client';
+import { jsx } from 'react/jsx-runtime';
 
-// src/test/runStory.ts
 function phased(phase, error) {
   const message = error instanceof Error ? error.message : String(error);
   const out = new Error(`${phase} fault: ${message}`, { cause: error });
   if (error instanceof Error && error.stack) out.stack = `${phase} fault: ${error.stack}`;
   return out;
 }
-function inbox(channel) {
-  const received = [];
-  let failure = null;
-  const wake = /* @__PURE__ */ new Set();
-  const off = channel.on((msg) => {
-    if (msg.type === "fault" && !failure) {
-      failure = new Error(`${msg.phase} fault: ${msg.message}`);
-      if (msg.stack) failure.stack = `${msg.phase} fault: ${msg.stack}`;
-    }
-    received.push(msg);
-    for (const fn of [...wake]) fn();
-  });
-  const check = () => {
-    if (failure) throw failure;
-  };
-  const next = (type) => new Promise((resolve, reject) => {
-    const poll = () => {
-      if (failure) {
-        wake.delete(poll);
-        reject(failure);
-        return;
-      }
-      const at = received.findIndex((m) => m.type === type);
-      if (at === -1) return;
-      wake.delete(poll);
-      resolve(received.splice(at, 1)[0]);
-    };
-    wake.add(poll);
-    poll();
-  });
-  const fault = () => new Promise((resolve) => {
-    const done = () => {
-      clearTimeout(timer);
-      wake.delete(onMessage);
-      resolve(failure);
-    };
-    const onMessage = () => {
-      if (failure) done();
-    };
-    const timer = setTimeout(done, 0);
-    wake.add(onMessage);
-    onMessage();
-  });
-  return { next, check, fault, close: off };
-}
 var settle = () => new Promise((resolve) => {
   requestAnimationFrame(() => setTimeout(resolve, 0));
 });
+function TestTrial({ story, setup, hostRef, onConfig, onRendered, onError }) {
+  const [config, setConfigState] = useState(() => story.config.defaults());
+  const [state, setState] = useState(null);
+  useEffect(() => onConfig(config), [config, onConfig]);
+  const ctx = {
+    config,
+    state,
+    setConfig: (path, value) => setConfigState((prev) => withValueAtPath(prev, path, value)),
+    setState
+  };
+  return /* @__PURE__ */ jsx(StoryTrial, { story, setup, ctx, hostRef, onRendered, onError });
+}
 var leftover = null;
 var pageSize = null;
-async function runStory(mod, exportName, file, autoTitle, { setup, viewport } = {}) {
+async function runStory(mod, exportName, file, autoTitle, { setup = {}, viewport } = {}) {
   leftover?.();
   let story;
   try {
-    story = loadStories(mod, autoTitle, setup?.parameters).find((s) => s.exportName === exportName);
+    story = loadStories(mod, autoTitle, setup.parameters).find((s) => s.exportName === exportName);
   } catch (error) {
     throw phased("load", error);
   }
@@ -76,49 +45,75 @@ async function runStory(mod, exportName, file, autoTitle, { setup, viewport } =
   if (viewport && (window.innerWidth !== size.width || window.innerHeight !== size.height)) {
     await viewport(size.width, size.height);
   }
-  const { port1, port2 } = new MessageChannel();
-  const shell = openChannel(port1);
-  const frame = openChannel(port2);
-  const messages = inbox(shell);
   const container = document.createElement("div");
   document.body.append(container);
-  let stopFrame;
+  let root;
   const cleanup = () => {
     if (leftover === cleanup) leftover = null;
     let thrown = null;
     try {
-      messages.close();
-      stopFrame?.();
+      root?.unmount();
     } catch (error) {
       thrown = { error };
     } finally {
-      stopFrame = void 0;
-      shell.close();
-      frame.close();
+      root = void 0;
       container.remove();
     }
     return thrown;
   };
   leftover = cleanup;
+  const hostRef = { current: null };
+  let config;
+  let renderError = null;
+  let markRendered = () => {
+  };
+  const rendered = new Promise((resolve) => {
+    markRendered = resolve;
+  });
+  const fail = (error) => {
+    renderError ??= { error };
+    markRendered();
+  };
+  const checkRender = () => {
+    if (renderError) throw phased("render", renderError.error);
+  };
   let failure = null;
   try {
     try {
-      stopFrame = startFrame({ story, channel: frame, container, setup });
+      await setup.prepare?.(story);
+      root = createRoot(container, { onUncaughtError: fail });
+      root.render(
+        /* @__PURE__ */ jsx(
+          TestTrial,
+          {
+            story,
+            setup,
+            hostRef,
+            onConfig: (next) => {
+              config = next;
+            },
+            onRendered: markRendered,
+            onError: fail
+          }
+        )
+      );
     } catch (error) {
       throw phased("mount", error);
     }
-    await messages.next("ready");
-    shell.send({ type: "init", config: story.config.defaults(), state: null, globals: {} });
-    await messages.next("answers");
+    await rendered;
     await settle();
-    messages.check();
+    checkRender();
+    const host = hostRef.current;
+    if (!host) throw new Error("render fault: the story host never mounted");
     if (story.play) {
-      shell.send({ type: "play" });
-      const played = await messages.next("played");
-      if (!played.ok) throw await messages.fault() ?? new Error(`play fault: ${played.message ?? "failed"}`);
+      try {
+        await story.play({ canvasElement: host, config, globals: {} });
+      } catch (error) {
+        throw phased("play", error);
+      }
       await settle();
+      checkRender();
     }
-    messages.check();
   } catch (error) {
     failure = { error };
   }

package/dist/test/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/test/runStory.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { type FrameSetup, startFrame } from '../frame/FrameController';\nimport { loadStories } from '../frame/mountFrame';\nimport { type Channel, openChannel } from '../protocol/channel';\nimport type { FromFrame, ToFrame, Viewport } from '../protocol/messages';\n\ntype Received<T extends FromFrame['type']> = Extract<FromFrame, { type: T }>;\n\n/** Prefixes `error` with the phase it came from, keeping its stack. */\nfunction phased(phase: string, error: unknown): Error {\n  const message = error instanceof Error ? error.message : String(error);\n  const out = new Error(`${phase} fault: ${message}`, { cause: error });\n  if (error instanceof Error && error.stack) out.stack = `${phase} fault: ${error.stack}`;\n  return out;\n}\n\nfunction inbox(channel: Channel<FromFrame, ToFrame>) {\n  const received: FromFrame[] = [];\n  let failure: Error | null = null;\n  const wake = new Set<() => void>();\n  const off = channel.on((msg) => {\n    if (msg.type === 'fault' && !failure) {\n      failure = new Error(`${msg.phase} fault: ${msg.message}`);\n      if (msg.stack) failure.stack = `${msg.phase} fault: ${msg.stack}`;\n    }\n    received.push(msg);\n    for (const fn of [...wake]) fn();\n  });\n\n  const check = () => {\n    if (failure) throw failure;\n  };\n\n  const next = <T extends FromFrame['type']>(type: T): Promise<Received<T>> =>\n    new Promise((resolve, reject) => {\n      const poll = () => {\n        if (failure) {\n          wake.delete(poll);\n          reject(failure);\n          return;\n        }\n        const at = received.findIndex((m) => m.type === type);\n        if (at === -1) return;\n        wake.delete(poll);\n        resolve(received.splice(at, 1)[0] as Received<T>);\n      };\n      wake.add(poll);\n      poll();\n    });\n\n  /** The first fault, if one arrives by the next macrotask. */\n  const fault = (): Promise<Error | null> =>\n    new Promise((resolve) => {\n      const done = () => {\n        clearTimeout(timer);\n        wake.delete(onMessage);\n        resolve(failure);\n      };\n      const onMessage = () => {\n        if (failure) done();\n      };\n      const timer = setTimeout(done, 0);\n      wake.add(onMessage);\n      onMessage();\n    });\n\n  return { next, check, fault, close: off };\n}\n\nconst settle = () =>\n  new Promise<void>((resolve) => {\n    requestAnimationFrame(() => setTimeout(resolve, 0));\n  });\n\nexport interface RunStoryOptions {\n  /** The frame config (`frameConfig`). */\n  setup?: FrameSetup;\n  /** Resizes the page, for a story that names a viewport. Without it, stories run at whatever size the page is. */\n  viewport?: (width: number, height: number) => Promise<void>;\n}\n\n/** Stops the story a timed-out test left mounted. */\nlet leftover: (() => unknown) | null = null;\n/** The page's size before any story resized it; a story with no viewport runs at this size. */\nlet pageSize: Viewport | null = null;\n\n/**\n * Renders one story the way the workshop's frame does — defaults, no state, no globals — then plays it.\n * Throws on any fault the frame reports, or a play function that fails.\n */\nexport async function runStory(\n  mod: Record<string, unknown>,\n  exportName: string,\n  file: string,\n  autoTitle: string,\n  { setup, viewport }: RunStoryOptions = {},\n): Promise<void> {\n  leftover?.();\n  let story: ReturnType<typeof loadStories>[number] | undefined;\n  try {\n    story = loadStories(mod, autoTitle, setup?.parameters).find((s) => s.exportName === exportName);\n  } catch (error) {\n    throw phased('load', error);\n  }\n  if (!story) throw new Error(`load fault: ${file} has no story export \"${exportName}\"`);\n\n  pageSize ??= { width: window.innerWidth, height: window.innerHeight };\n  const size = story.viewport ?? pageSize;\n  if (viewport && (window.innerWidth !== size.width || window.innerHeight !== size.height)) {\n    await viewport(size.width, size.height);\n  }\n\n  const { port1, port2 } = new MessageChannel();\n  const shell = openChannel<FromFrame, ToFrame>(port1);\n  const frame = openChannel<ToFrame, FromFrame>(port2);\n  const messages = inbox(shell);\n  const container = document.createElement('div');\n  document.body.append(container);\n  let stopFrame: (() => void) | undefined;\n  /** Returns what `stopFrame` threw, having released everything else regardless. */\n  const cleanup = (): { error: unknown } | null => {\n    if (leftover === cleanup) leftover = null;\n    let thrown: { error: unknown } | null = null;\n    try {\n      messages.close();\n      stopFrame?.();\n    } catch (error) {\n      thrown = { error };\n    } finally {\n      stopFrame = undefined;\n      shell.close();\n      frame.close();\n      container.remove();\n    }\n    return thrown;\n  };\n  leftover = cleanup;\n\n  let failure: { error: unknown } | null = null;\n  try {\n    try {\n      stopFrame = startFrame({ story, channel: frame, container, setup });\n    } catch (error) {\n      throw phased('mount', error);\n    }\n    await messages.next('ready');\n    shell.send({ type: 'init', config: story.config.defaults(), state: null, globals: {} });\n    await messages.next('answers');\n    await settle();\n    messages.check();\n    if (story.play) {\n      shell.send({ type: 'play' });\n      const played = await messages.next('played');\n      if (!played.ok) throw (await messages.fault()) ?? new Error(`play fault: ${played.message ?? 'failed'}`);\n      await settle();\n    }\n    messages.check();\n  } catch (error) {\n    failure = { error };\n  }\n  const cleanupError = cleanup();\n  if (failure) throw failure.error;\n  if (cleanupError) throw phased('cleanup', cleanupError.error);\n}\n"]}
+{"version":3,"sources":["../../src/test/runStory.tsx"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { withValueAtPath } from '@weasel-js/labkit/config';\nimport { type RefObject, useEffect, useState } from 'react';\nimport { createRoot, type Root } from 'react-dom/client';\nimport type { FrameSetup } from '../frame/FrameController';\nimport type { Viewport } from '../protocol/messages';\nimport { StoryTrial } from '../shell/StoryTrial';\nimport { loadStories } from '../story/load';\nimport type { LoadedStory } from '../story/types';\n\n/** Prefixes `error` with the phase it came from, keeping its stack. */\nfunction phased(phase: string, error: unknown): Error {\n  const message = error instanceof Error ? error.message : String(error);\n  const out = new Error(`${phase} fault: ${message}`, { cause: error });\n  if (error instanceof Error && error.stack) out.stack = `${phase} fault: ${error.stack}`;\n  return out;\n}\n\nconst settle = () =>\n  new Promise<void>((resolve) => {\n    requestAnimationFrame(() => setTimeout(resolve, 0));\n  });\n\ninterface TestTrialProps {\n  story: LoadedStory;\n  setup: FrameSetup;\n  hostRef: RefObject<HTMLElement | null>;\n  /** The config in force after each commit, so `play` reads what the story last wrote. */\n  onConfig: (config: unknown) => void;\n  onRendered: () => void;\n  onError: (error: unknown) => void;\n}\n\n/** The trial a story test runs in: its config and state, held the way a lab trial holds them. */\nfunction TestTrial({ story, setup, hostRef, onConfig, onRendered, onError }: TestTrialProps) {\n  const [config, setConfigState] = useState<unknown>(() => story.config.defaults());\n  const [state, setState] = useState<unknown>(null);\n  useEffect(() => onConfig(config), [config, onConfig]);\n  const ctx = {\n    config,\n    state,\n    setConfig: (path: string, value: unknown) => setConfigState((prev: unknown) => withValueAtPath(prev, path, value)),\n    setState,\n  };\n  return <StoryTrial story={story} setup={setup} ctx={ctx} hostRef={hostRef} onRendered={onRendered} onError={onError} />;\n}\n\nexport interface RunStoryOptions {\n  /** The frame config (`frameConfig`). */\n  setup?: FrameSetup;\n  /** Resizes the page, for a story that names a viewport. Without it, stories run at whatever size the page is. */\n  viewport?: (width: number, height: number) => Promise<void>;\n}\n\n/** Stops the story a timed-out test left mounted. */\nlet leftover: (() => unknown) | null = null;\n/** The page's size before any story resized it; a story with no viewport runs at this size. */\nlet pageSize: Viewport | null = null;\n\n/**\n * Renders one story in the test page the way the workshop does — defaults, no state, no globals — then plays it.\n * Throws on a render the story's boundary caught, or a play function that fails.\n */\nexport async function runStory(\n  mod: Record<string, unknown>,\n  exportName: string,\n  file: string,\n  autoTitle: string,\n  { setup = {}, viewport }: RunStoryOptions = {},\n): Promise<void> {\n  leftover?.();\n  let story: LoadedStory | undefined;\n  try {\n    story = loadStories(mod, autoTitle, setup.parameters).find((s) => s.exportName === exportName);\n  } catch (error) {\n    throw phased('load', error);\n  }\n  if (!story) throw new Error(`load fault: ${file} has no story export \"${exportName}\"`);\n\n  pageSize ??= { width: window.innerWidth, height: window.innerHeight };\n  const size = story.viewport ?? pageSize;\n  if (viewport && (window.innerWidth !== size.width || window.innerHeight !== size.height)) {\n    await viewport(size.width, size.height);\n  }\n\n  const container = document.createElement('div');\n  document.body.append(container);\n  let root: Root | undefined;\n  /** Returns what unmounting threw, having released everything else regardless. */\n  const cleanup = (): { error: unknown } | null => {\n    if (leftover === cleanup) leftover = null;\n    let thrown: { error: unknown } | null = null;\n    try {\n      root?.unmount();\n    } catch (error) {\n      thrown = { error };\n    } finally {\n      root = undefined;\n      container.remove();\n    }\n    return thrown;\n  };\n  leftover = cleanup;\n\n  const hostRef: RefObject<HTMLElement | null> = { current: null };\n  let config: unknown;\n  let renderError: { error: unknown } | null = null;\n  let markRendered: () => void = () => {};\n  const rendered = new Promise<void>((resolve) => {\n    markRendered = resolve;\n  });\n  const fail = (error: unknown) => {\n    renderError ??= { error };\n    // An error the boundary could not catch leaves nothing to announce `rendered`; the check below throws instead.\n    markRendered();\n  };\n  const checkRender = () => {\n    if (renderError) throw phased('render', renderError.error);\n  };\n\n  let failure: { error: unknown } | null = null;\n  try {\n    try {\n      await setup.prepare?.(story);\n      root = createRoot(container, { onUncaughtError: fail });\n      root.render(\n        <TestTrial\n          story={story}\n          setup={setup}\n          hostRef={hostRef}\n          onConfig={(next) => {\n            config = next;\n          }}\n          onRendered={markRendered}\n          onError={fail}\n        />,\n      );\n    } catch (error) {\n      throw phased('mount', error);\n    }\n    await rendered;\n    await settle();\n    checkRender();\n    const host = hostRef.current;\n    if (!host) throw new Error('render fault: the story host never mounted');\n    if (story.play) {\n      try {\n        await story.play({ canvasElement: host, config, globals: {} });\n      } catch (error) {\n        throw phased('play', error);\n      }\n      await settle();\n      checkRender();\n    }\n  } catch (error) {\n    failure = { error };\n  }\n  const cleanupError = cleanup();\n  if (failure) throw failure.error;\n  if (cleanupError) throw phased('cleanup', cleanupError.error);\n}\n"]}

package/dist/vite/index.js

@@ -1,5 +1,5 @@
-import { storyNameFromExport, storyId } from '../chunk-6SRQIHJQ.js';
-import { existsSync, readFileSync, mkdirSync, writeFileSync, globSync } from 'fs';
+import { storyNameFromExport, storyId } from '../chunk-HRGPFQBW.js';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, globSync, statSync } from 'fs';
 import { resolve, relative, sep, matchesGlob, dirname, join, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { parse } from '@babel/parser';
@@ -99,24 +99,31 @@ function indexProgram(program, file, autoTitle2) {
     }
   }
   let metaNode;
+  let metaDoc;
   const exported = [];
   for (const stmt of program.body) {
-    if (stmt.type === "ExportDefaultDeclaration") metaNode = stmt.declaration;
+    if (stmt.type === "ExportDefaultDeclaration") {
+      metaNode = stmt.declaration;
+      metaDoc = docOf(stmt);
+    }
     if (stmt.type !== "ExportNamedDeclaration" || stmt.exportKind === "type") continue;
+    const doc = docOf(stmt);
     const decl = stmt.declaration;
     if (decl?.type === "VariableDeclaration") {
       for (const d of decl.declarations) {
-        if (d.id.type === "Identifier") exported.push({ name: d.id.name, node: d.init ?? void 0 });
+        if (d.id.type === "Identifier") exported.push({ name: d.id.name, node: d.init ?? void 0, doc: docOf(d) ?? doc });
       }
     } else if (decl?.type === "FunctionDeclaration" && decl.id) {
-      exported.push({ name: decl.id.name, node: void 0 });
+      exported.push({ name: decl.id.name, node: void 0, doc });
     }
     for (const spec of stmt.specifiers) {
       if (spec.type !== "ExportSpecifier" || spec.exportKind === "type") continue;
       const name = exportedName(spec.exported);
       const node = stmt.source ? void 0 : bindings.get(spec.local.name);
-      if (name === "default") metaNode = node;
-      else exported.push({ name, node });
+      if (name === "default") {
+        metaNode = node;
+        metaDoc ??= doc;
+      } else exported.push({ name, node, doc });
     }
   }
   if (!metaNode && !program.body.some(isDefaultExport)) return [];
@@ -124,21 +131,50 @@ function indexProgram(program, file, autoTitle2) {
   const title = stringProp(meta, "title") ?? autoTitle2;
   const include = storyFilter(meta, "includeStories");
   const exclude = storyFilter(meta, "excludeStories");
-  return exported.filter(({ name }) => name !== "__namedExportsOrder").filter(({ name }) => (!include || include(name)) && (!exclude || !exclude(name))).map(({ name, node }) => {
+  const componentNode = prop(meta, "component");
+  const componentName = componentNode?.type === "Identifier" ? componentNode.name : void 0;
+  const metaIsolate = isolateOf(meta, bindings, wrappers, "default");
+  return exported.filter(({ name }) => name !== "__namedExportsOrder").filter(({ name }) => (!include || include(name)) && (!exclude || !exclude(name))).map(({ name, node, doc }) => {
     const spec = objectOf(node, bindings, wrappers);
+    const isolate = isolateOf(spec, bindings, wrappers, name) ?? metaIsolate;
     return {
       id: storyId(title, name),
       title,
       name: stringProp(spec, "name") ?? stringProp(spec, "storyName") ?? storyNameFromExport(name),
       exportName: name,
-      file
+      file,
+      ...doc === void 0 ? {} : { description: doc },
+      ...metaDoc === void 0 ? {} : { componentDescription: metaDoc },
+      ...componentName === void 0 ? {} : { componentName },
+      ...isolate === void 0 ? {} : { isolate }
     };
   });
 }
+function isolateOf(obj, bindings, wrappers, exportName) {
+  const parameters = objectOf(prop(obj, "parameters"), bindings, wrappers);
+  const forge2 = objectOf(prop(parameters, "forge"), bindings, wrappers);
+  const value = prop(obj, "isolate") ?? prop(forge2, "isolate");
+  if (value === void 0) return void 0;
+  const literal = stringLiteral(value);
+  if (literal === void 0) throw new Error(`${exportName}: isolate must be a string literal`);
+  return literal;
+}
+function stringLiteral(node) {
+  if (node.type === "StringLiteral") return node.value;
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis.map((q) => q.value.cooked ?? q.value.raw).join("");
+  return void 0;
+}
 function isDefaultExport(stmt) {
   if (stmt.type === "ExportDefaultDeclaration") return true;
   return stmt.type === "ExportNamedDeclaration" && stmt.specifiers.some((s) => s.type === "ExportSpecifier" && exportedName(s.exported) === "default");
 }
+function docOf(node) {
+  const comments = node.leadingComments;
+  const last = comments?.[comments.length - 1];
+  if (last?.type !== "CommentBlock" || !last.value.startsWith("*")) return void 0;
+  const text = last.value.slice(1).split("\n").map((line) => line.replace(/^\s*\*/, "").trim()).join("\n").trim();
+  return text || void 0;
+}
 function exportedName(node) {
   return node.type === "Identifier" ? node.name : node.value;
 }
@@ -224,7 +260,7 @@ function forge(options) {
   let logger;
   const glob = () => {
     const files2 = options.stories.flatMap(
-      (pattern) => globSync(pattern, { cwd: root, exclude: (name) => basename(String(name)) === "node_modules" }).map((f) => resolve(root, f)).sort()
+      (pattern) => globSync(pattern, { cwd: root, exclude: (name) => basename(String(name)) === "node_modules" }).map((f) => resolve(root, f)).filter((f) => statSync(f).isFile()).sort()
     );
     return [...new Set(files2)];
   };
@@ -266,15 +302,29 @@ ${lines.join("\n")}
 import '@weasel-js/labkit/styles.css';
 import '@weasel-js/forge/shell.css';
 import index from 'virtual:forge/index.js';
+import importers from 'virtual:forge/importers.js';
 import config from 'virtual:forge/shell-config.js';
+import setup from 'virtual:forge/frame-config.js';
 
 const workshop = mountWorkshop({
   index,
+  importers,
+  setup,
   config,
   frameUrl: ${JSON.stringify(`${base}frame.html`)},
   stories: ${JSON.stringify(options.stories)},
 });
 import.meta.hot?.on('forge:index', (next) => workshop.setIndex(next));
+// A story edit reaches here as an update of the importers module, whose fresh import() URLs carry the new
+// timestamps; the file it names arrives just before, so the reload waits for the importers that can fetch it.
+const stale = new Set();
+import.meta.hot?.on('forge:story', ({ file }) => stale.add(file));
+import.meta.hot?.accept('virtual:forge/importers.js', (next) => {
+  if (!next) return;
+  workshop.setImporters(next.default);
+  for (const file of stale) workshop.reloadStory(file);
+  stale.clear();
+});
 `,
     "frame-entry.js": () => `import { mountFrame } from '@weasel-js/forge/frame';
 import '@weasel-js/forge/frame.css';
@@ -283,10 +333,14 @@ import importers from 'virtual:forge/importers.js';
 import setup from 'virtual:forge/frame-config.js';
 
 mountFrame({ index, importers, setup });
+// The importers module is shared with the workshop page, which accepts a story edit in place; a frame document
+// showing the old module reloads instead, and without this the edit would dead-end here and reload every page.
+import.meta.hot?.accept('virtual:forge/importers.js', () => location.reload());
 `
   };
   function reindex(server, file, event) {
     const current = files();
+    if (event === "change" && current.has(file)) server.ws.send({ type: "custom", event: "forge:story", data: { file } });
     if (event === "change" && !current.has(file)) return;
     if (event === "add" && !matches(file)) return;
     if (event === "unlink" && !current.has(file)) return;
@@ -398,6 +452,8 @@ function forgeTest(options) {
           `import { test as __forge_test } from "vitest";`,
           `import { page as __forge_page } from "vitest/browser";`,
           `import { runStory as __forge_runStory } from "@weasel-js/forge/test";`,
+          // shell.css draws the story host; frame.css still holds the boundary's fault rule.
+          `import "@weasel-js/forge/shell.css";`,
           `import "@weasel-js/forge/frame.css";`,
           ...options.frameConfig ? [`import __forge_frame_config from ${q(resolve(root, options.frameConfig))};`] : [],
           `const __forge_file = ${q(id)};`,
@@ -408,8 +464,9 @@ function forgeTest(options) {
           "  viewport: (width, height) => __forge_page.viewport(width, height),",
           "};",
           "const __forge_run = async (exportName) => __forge_runStory(await import(/* @vite-ignore */ import.meta.url), exportName, __forge_file, __forge_title, __forge_options);",
+          // An isolated story asks for a document of its own, which the test page is not; its reason goes in the name.
           ...entries.map(
-            (entry) => `__forge_test(${q(entry.name)}, () => __forge_run(${q(entry.exportName)}), __forge_timeout);`
+            (entry) => entry.isolate === void 0 ? `__forge_test(${q(entry.name)}, () => __forge_run(${q(entry.exportName)}), __forge_timeout);` : `__forge_test.skip(${q(`${entry.name} (isolated: ${entry.isolate})`)}, () => {});`
           )
         ];
         return { code: `${code}