@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/stories/StoryPreviewMount.tsx

@@ -0,0 +1,265 @@
+/**
+ * Isolated story preview mount — C3 (spec §9 "A story may be opened in an
+ * isolated editor preview"). Renders one composed story (`ComposedProjectStory`
+ * from `compose-project-stories.ts`) into a SEPARATE `react-dom/client` root,
+ * not a child of the editor's own React tree: the preview container div is
+ * handed to its own `createRoot`, so a story's own React version/context/
+ * error state can never leak into (or be affected by) the editor shell's
+ * tree — the same isolation a Storybook iframe gives you, achieved here with
+ * a dedicated root instead (this editor has no existing iframe-preview
+ * pattern to reuse — see the module doc comment on `StoriesPanel.tsx`).
+ *
+ * Error handling (spec §9 "Errors identify the source module and story
+ * export"): a story that throws while rendering is caught by
+ * `StoryPreviewErrorBoundary` (mirrors `ToolHost.tsx`'s `ToolErrorBoundary`)
+ * and reported with BOTH the module path and the story export name — one
+ * throwing story never takes down the panel or another story's preview.
+ *
+ * Play functions (spec §9 "supported play functions mount... optional but
+ * nice"): `runPlay` below calls the composed story's own `.play()` (Storybook
+ * populates it via `composeStories` when the CSF export declares one) inside
+ * the SAME error containment, so a throwing play function reports the same
+ * module+export naming instead of crashing the preview. `play()` is called
+ * with `{ canvasElement }` set to the isolated preview root's own container —
+ * without it, Storybook's portable-story `play()` defaults `canvasElement` to
+ * `document.body` (confirmed in `storybook/dist/preview-api/index.cjs`'s
+ * `composeStory`: `g.canvasElement ??= globalThis?.document?.body`), which
+ * would let a story's play() query/interact with the ENTIRE page instead of
+ * just its own isolated preview.
+ *
+ * Loaders (spec §9 "loaders ... mount through Storybook portable-story
+ * APIs"): a composed story only runs its `loaders` when `.load()` is
+ * explicitly awaited before render. Confirmed directly in Storybook 9's own
+ * `composeStory` (`storybook/dist/preview-api/index.cjs`): the render
+ * function reads a module-closure variable (`x`) for `loaded` data, and that
+ * variable is populated ONLY inside `load: async () => { ...; f.loaded =
+ * await c.applyLoaders(f); ...; x = f; }` — i.e. `applyLoaders` (which runs
+ * every `loaders` entry) never runs unless `.load()` itself runs first.
+ * Rendering the composed component directly (no `.load()`) leaves `loaded`
+ * as `{}`. `mountIsolatedStory` below is therefore async and awaits
+ * `StoryComponent.load()` before calling `root.render(...)`.
+ */
+
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import type { ComposedStoryFn } from 'storybook/internal/types';
+import { themeVars } from '../design-system';
+
+interface StoryPreviewErrorBoundaryProps {
+  modulePath: string;
+  storyName: string;
+  children: ReactNode;
+}
+
+interface StoryPreviewErrorBoundaryState {
+  error: Error | null;
+}
+
+/** Crash containment for one mounted story — names both the source module
+ *  AND the story export in the fallback UI and the console, per spec §9. */
+export class StoryPreviewErrorBoundary extends Component<
+  StoryPreviewErrorBoundaryProps,
+  StoryPreviewErrorBoundaryState
+> {
+  override state: StoryPreviewErrorBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: Error): StoryPreviewErrorBoundaryState {
+    return { error };
+  }
+
+  override componentDidCatch(error: Error, info: ErrorInfo): void {
+    // biome-ignore lint/suspicious/noConsole: deliberate, greppable — a crashed story preview must be diagnosable from the console (spec §9 "errors identify the source module and story export"), mirroring ToolHost.tsx's ToolErrorBoundary
+    console.error(
+      `[stories] ${this.props.modulePath} — story "${this.props.storyName}" crashed while rendering:`,
+      error,
+      info.componentStack,
+    );
+  }
+
+  override render(): ReactNode {
+    if (this.state.error) {
+      return (
+        <div style={{ padding: 12, fontSize: 12, color: themeVars.semantic.danger, maxWidth: 640 }}>
+          <div style={{ fontWeight: 600, marginBottom: 4 }}>
+            Story crashed: <code>{this.props.modulePath}</code> — export{' '}
+            <code>{this.props.storyName}</code>
+          </div>
+          <div style={{ whiteSpace: 'pre-wrap' }}>{String(this.state.error)}</div>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
+
+/** One container's isolated root plus a generation counter — see
+ *  `mountIsolatedStory` below for why the counter (not just the `Root`
+ *  object's identity) is what a stale `unmount()` must check. `root` is
+ *  `undefined` for the brief window between a mount call CLAIMING a
+ *  generation (synchronously) and that same call's `await
+ *  StoryComponent.load()` resolving — no `Root` exists yet for a container
+ *  that has never been rendered into before (the very first mount), so the
+ *  reservation itself can't supply one. */
+interface ContainerMount {
+  root: Root | undefined;
+  generation: number;
+}
+
+// One isolated `react-dom/client` root per container, reused across repeated
+// `mountIsolatedStory` calls (e.g. a story switch: `StoriesPanel.tsx`'s
+// `StoryPreviewHost` effect re-fires for the SAME DOM node with a new
+// `StoryComponent`). Calling `createRoot` twice on the SAME node is a hard
+// react-dom warning ("already been passed to createRoot() before") — this
+// map is the guard: a second `mountIsolatedStory` on the same container
+// `.render()`s onto the EXISTING root instead of creating a new one, exactly
+// react-dom's own documented fix for that warning.
+const mountsByContainer = new WeakMap<HTMLElement, ContainerMount>();
+
+/**
+ * Mount one composed story into `container` via its OWN `createRoot` —
+ * isolated from whatever React root `container` itself lives inside.
+ * Returns an `unmount` the caller runs on cleanup (e.g. story switch or
+ * panel close) — same lifecycle discipline every other editor mount point
+ * (`XStateMachineInspector.test.tsx`'s harness, `ToolHost`) uses. Safe to
+ * call again on the same `container` before a previous `unmount()` has
+ * landed (see `mountsByContainer` above) — the isolated root is reused, and
+ * `unmount()` (below) removes it from the container entirely rather than
+ * merely clearing its content, so callers who intend a REAL teardown (panel
+ * close) still get one.
+ *
+ * Async: awaits `StoryComponent.load()` (runs the story's `loaders`, per the
+ * module doc comment above) BEFORE the first render. The generation counter
+ * is claimed SYNCHRONOUSLY (before the `await`), exactly like the sync
+ * version did — so a second `mountIsolatedStory` call on the same container
+ * (e.g. the user switches stories again while this one's `.load()` is still
+ * in flight) still bumps the generation immediately and makes it visible to
+ * this in-flight call. After the await, this call re-reads the container's
+ * CURRENT generation and bails out (never creates/renders a root, never
+ * touches `mountsByContainer`) if it's no longer the current one — so a
+ * stale `.load()` resolving late can never win a render race against a
+ * newer story switch, even though nothing was mounted yet for it to
+ * unmount.
+ */
+export async function mountIsolatedStory(
+  container: HTMLElement,
+  modulePath: string,
+  storyName: string,
+  StoryComponent: ComposedStoryFn,
+  // W2 (story documents): optional per-mount prop overrides. Portable
+  // stories are plain React components whose composed args are DEFAULTS —
+  // Storybook's own documented portable-story contract lets a caller pass
+  // partial props over them (`<Story label="…" />`). The story-document
+  // Inspector's editable args and its action-logging spies ride this;
+  // omitted (every pre-W2 caller) the render is byte-identical to before.
+  overrideProps?: Record<string, unknown>,
+): Promise<{ root: Root; unmount: () => void } | null> {
+  const existing = mountsByContainer.get(container);
+  // Bumped on EVERY mount, including a reuse of the same `Root` object (a
+  // story switch) — this is the piece a same-root reuse needs that plain
+  // `Root`-identity checking (an earlier version of this function) doesn't
+  // give you: reusing the root means two DIFFERENT stories' mounts can share
+  // the exact same `Root` instance, so a stale `unmount()` comparing
+  // `Root`s would see "yes, that's still the registered root" and tear down
+  // the NEWER story's render a moment after it landed. Comparing the
+  // generation this specific `mountIsolatedStory` call captured against the
+  // container's CURRENT generation instead correctly recognizes "a newer
+  // mount has since claimed this container" even when the root itself
+  // didn't change. Claimed HERE, synchronously, before the `load()` await
+  // below — so a newer call arriving while this one awaits sees (and bumps
+  // past) this generation immediately, rather than racing to claim the same
+  // number once both awaits resolve.
+  const generation = (existing?.generation ?? 0) + 1;
+  mountsByContainer.set(container, { root: existing?.root, generation });
+
+  // Loaders (spec §9): must run — and their `loaded` data become part of the
+  // composed story's render-time context — before the story is ever
+  // rendered. See the module doc comment for why this can't be skipped.
+  await StoryComponent.load();
+
+  // Re-check AFTER the await: if a newer `mountIsolatedStory` call (story
+  // switch) has since claimed this container, its generation will have
+  // moved past `generation` above — this stale call must not create a root
+  // or render into a container a newer story already owns (or is about to).
+  const afterLoad = mountsByContainer.get(container);
+  if (!afterLoad || afterLoad.generation !== generation) return null;
+
+  const root = existing?.root ?? createRoot(container);
+  mountsByContainer.set(container, { root, generation });
+
+  root.render(
+    <StoryPreviewErrorBoundary modulePath={modulePath} storyName={storyName}>
+      {/* `ComposedStoryFn` is a callable React function component
+          (Storybook's portable-story contract) — its own composed
+          args/decorators are already baked in by `composeStories`;
+          `overrideProps` (when given) override individual args per that same
+          contract. */}
+      <StoryComponent {...(overrideProps ?? {})} />
+    </StoryPreviewErrorBoundary>,
+  );
+  return {
+    root,
+    // Deferred to a microtask, deliberately NOT called synchronously:
+    // `unmount` is returned as `StoryPreviewHost`'s effect cleanup, and
+    // React runs an effect's cleanup SYNCHRONOUSLY as part of its own
+    // render/commit pass whenever the OUTER tree unmounts (e.g. the whole
+    // Stories panel closing). React tracks "is any root currently
+    // rendering" as a single GLOBAL flag for the whole call stack
+    // (`executionContext`, react-dom-client.development.js) — so calling
+    // THIS (independent, inner) root's `.unmount()` synchronously from
+    // inside that outer pass trips "Attempted to synchronously unmount a
+    // root while React was already rendering" even though the inner root
+    // itself has nothing in flight. Queuing the call for the next microtask
+    // runs it once the outer commit has fully finished and cleared that
+    // flag, which is the documented fix for exactly this nested-root
+    // pattern (no functional delay — the isolated root is still torn down
+    // effectively immediately).
+    unmount: () => {
+      queueMicrotask(() => {
+        // Only the mount that's STILL the container's current generation
+        // actually tears the root down — see the `generation` doc comment
+        // above for why this can't just compare `Root` identity.
+        const current = mountsByContainer.get(container);
+        if (!current || current.generation !== generation || !current.root) return;
+        mountsByContainer.delete(container);
+        current.root.unmount();
+      });
+    },
+  };
+}
+
+/**
+ * Run a composed story's `.play()` if it declared one, inside the same
+ * module+export-naming error containment as render crashes. Returns whether
+ * a play function existed and ran ok — the caller (`StoriesPanel`) uses this
+ * to show a "no play function" state distinctly from a failure.
+ *
+ * `canvasElement` is passed through to `.play({ canvasElement })` — the
+ * composed story's own `play` accepts `Partial<StoryContext>` (confirmed in
+ * `storybook/dist/types/index.d.ts`: `play?: (context?: Partial<StoryContext<...>>)
+ * => Promise<void>`, and `StoryContext.canvasElement: TRenderer['canvasElement']`).
+ * Without it, Storybook's `composeStory` defaults `canvasElement` to
+ * `globalThis.document.body` (`storybook/dist/preview-api/index.cjs`:
+ * `g.canvasElement ??= globalThis?.document?.body`), which would let a
+ * story's play() query/interact with the WHOLE page instead of just its own
+ * isolated preview root.
+ */
+export async function runStoryPlay(
+  modulePath: string,
+  storyName: string,
+  StoryComponent: ComposedStoryFn,
+  canvasElement: HTMLElement,
+): Promise<{ ran: boolean; error?: string }> {
+  if (typeof StoryComponent.play !== 'function') return { ran: false };
+  try {
+    await StoryComponent.play({ canvasElement });
+    return { ran: true };
+  } catch (err) {
+    const message = String(err instanceof Error ? err.message : err);
+    // biome-ignore lint/suspicious/noConsole: deliberate, greppable — a throwing play() must be diagnosable from the console, same naming discipline as a render crash
+    console.error(`[stories] ${modulePath} — story "${storyName}"'s play() threw:`, err);
+    return {
+      ran: true,
+      error: `[stories] ${modulePath} — story "${storyName}"'s play() failed: ${message}`,
+    };
+  }
+}

package/src/stories/action-stories.fixture.tsx

@@ -0,0 +1,44 @@
+/**
+ * Fixture CSF module for `story-documents.test.tsx` — like
+ * `button-stories.fixture.tsx` but with a FUNCTION-valued arg (`onFire`), so
+ * the story-document action-logging spies (W2 — the actions-addon semantic:
+ * function args are wrapped at mount and calls from the story's own rendered
+ * component are logged) can be exercised against real composed CSF. Kept
+ * separate from the button fixture so `compose-project-stories.test.tsx`'s
+ * assertions over that module's args stay untouched.
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+interface FixtureActionButtonProps {
+  label: string;
+  onFire?: () => void;
+}
+
+function FixtureActionButton({ label, onFire }: FixtureActionButtonProps) {
+  return (
+    <button type="button" data-testid="fixture-action-button" onClick={() => onFire?.()}>
+      {label}
+    </button>
+  );
+}
+
+const meta = {
+  title: 'Fixture/ActionButton',
+  component: FixtureActionButton,
+  args: {
+    onFire: () => {
+      // Authored handler — the W2 spy must still call through to this.
+      (globalThis as { __fixtureActionFired?: number }).__fixtureActionFired =
+        ((globalThis as { __fixtureActionFired?: number }).__fixtureActionFired ?? 0) + 1;
+    },
+  },
+} satisfies Meta<typeof FixtureActionButton>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {
+  args: { label: 'Fire' },
+};

package/src/stories/button-stories.fixture.tsx

@@ -0,0 +1,50 @@
+/**
+ * Fixture CSF module for `compose-project-stories.test.tsx` — a minimal,
+ * real CSF3 file (title, component, args, a decorator, two named stories)
+ * mirroring `packages/editor/template/src/ui/Button.stories.tsx` in shape,
+ * kept local (rather than imported) so this test doesn't reach across into
+ * the template package and stays fast/isolated, same precedent
+ * `character-animation-machine.fixture.ts` sets for `XStateMachineInspector.test.tsx`.
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+interface FixtureButtonProps {
+  label: string;
+  disabled?: boolean;
+}
+
+function FixtureButton({ label, disabled = false }: FixtureButtonProps) {
+  return (
+    <button type="button" disabled={disabled} data-testid="fixture-button">
+      {label}
+    </button>
+  );
+}
+
+const meta = {
+  title: 'Fixture/Button',
+  component: FixtureButton,
+  parameters: {
+    vgai: { root: 'hud', defaultStory: 'Default' },
+  },
+  decorators: [
+    (Story) => (
+      <div data-testid="fixture-decorator">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof FixtureButton>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { label: 'Fire' },
+};
+
+export const DisabledStory: Story = {
+  args: { label: 'Fire', disabled: true },
+};

package/src/stories/compose-project-stories.ts

@@ -0,0 +1,182 @@
+/**
+ * Portable-story mounting — C3 (spec §9). Wraps the REAL Storybook 9
+ * portable-stories API (`composeStories`/`setProjectAnnotations` from
+ * `@storybook/react`, confirmed against `node_modules/@storybook/react/dist/
+ * index.d.ts`) so a dynamically-imported CSF module (`*.stories.tsx`/
+ * `*.stories.ts`, found by `story-discovery.ts`) becomes a map of named,
+ * fully-composed React components — args/decorators/play all applied by
+ * Storybook itself, never re-implemented here. `loaders` are ALSO applied by
+ * Storybook itself, but only once the caller awaits the composed story's own
+ * `.load()` — Storybook 9's portable-story contract requires that explicit
+ * call before render (confirmed in `storybook/dist/preview-api/index.cjs`'s
+ * `composeStory`: loader data is populated inside `load()`, and the render
+ * function only picks it up if `load()` already ran). `mountIsolatedStory`
+ * (`StoryPreviewMount.tsx`) is the caller that does this, awaiting `.load()`
+ * before its first render.
+ *
+ * `setProjectAnnotations` "should be run a single time" (its own doc
+ * comment) — `ensureProjectAnnotations` below does that exactly once per
+ * editor session, from the project's `.storybook/preview.ts(x)` if the
+ * project has one, else an empty array (Storybook's own default). This is
+ * the ONLY place project annotations are threaded; no VGAI-specific
+ * override.
+ *
+ * No duplicate story format anywhere: `composeProjectStories` takes the
+ * loaded module namespace as-is (whatever `story-discovery.ts`'s `load()`
+ * returned from Vite's `/@fs/` dynamic import) and hands it straight to
+ * `composeStories` — the CSF module on disk is read directly and is the only
+ * story definition that ever exists.
+ */
+
+import { composeStories, setProjectAnnotations } from '@storybook/react';
+import type { ComposedStoryFn } from 'storybook/internal/types';
+
+let projectAnnotationsApplied = false;
+
+/**
+ * Apply the project's `.storybook/preview` annotations to the portable-story
+ * runtime exactly once per session (repeat calls are no-ops — `composeStories`
+ * itself picks up whatever `setProjectAnnotations` last set, and re-calling
+ * with a DIFFERENT project mid-session would be a footgun, not a feature. A
+ * project switch reloads the whole editor page today, which resets this
+ * module-level flag along with everything else).
+ *
+ * `previewAnnotations` is `undefined` when the project has no
+ * `.storybook/preview.ts(x)` (this repo ships none — no `.storybook` folder
+ * anywhere, confirmed by search) — Storybook's own documented default is an
+ * empty project-annotations object, which `setProjectAnnotations([])`
+ * already models via `composeStories`'s own `?? []` fallback.
+ */
+export function ensureProjectAnnotations(previewAnnotations?: unknown): void {
+  if (projectAnnotationsApplied) return;
+  projectAnnotationsApplied = true;
+  // biome-ignore lint/suspicious/noExplicitAny: `setProjectAnnotations` accepts the project's raw preview module namespace, whose shape is Storybook's own (NamedOrDefaultProjectAnnotations) — not something this editor declares.
+  setProjectAnnotations((previewAnnotations ?? []) as any);
+}
+
+/** Test-only escape hatch: `ensureProjectAnnotations` is deliberately
+ *  once-per-session: this resets that latch so each test file gets a clean
+ *  slate rather than leaking a fixture's annotations into a later assertion. */
+export function _resetProjectAnnotationsForTest(): void {
+  projectAnnotationsApplied = false;
+}
+
+/** One successfully composed named story, ready for the preview UI to mount. */
+export interface ComposedProjectStory {
+  /** The CSF export name, e.g. `Primary`. */
+  name: string;
+  /** Storybook's stable composed id (title + export), when supplied. */
+  id: string;
+  /** Storybook's human-facing story name, falling back to the export name. */
+  label: string;
+  /** CSF meta title when explicitly authored (e.g. `Game/2048`). */
+  title?: string;
+  /** Fully-composed Storybook parameters. VGAI only reads the namespaced
+   * `parameters.vgai` association; every other parameter remains Storybook's. */
+  parameters: Record<string, unknown>;
+  /** Fully composed initial args. Kept as Storybook produced them so the
+   * editor can render idiomatic Controls for an active story without
+   * inventing a second fixture/state format. */
+  args: Record<string, unknown>;
+  /** The real Storybook portable-story component — args/decorators/loaders
+   *  already applied; `.play` present when the original story declared one. */
+  Component: ComposedStoryFn;
+}
+
+/** The result of composing one loaded CSF module. */
+export type ComposeResult =
+  | { ok: true; stories: ComposedProjectStory[] }
+  | { ok: false; error: string };
+
+/**
+ * Compose a dynamically-imported CSF module (`story-discovery.ts`'s
+ * `load()` result) into its named, portable-story components via the real
+ * `composeStories` (spec §9 "mount through Storybook portable-story APIs").
+ *
+ * Error handling (spec §9 "Errors identify the source module and story
+ * export"): a module with no default export (no Meta — every CSF file needs
+ * one), or a `composeStories` call that throws (e.g. a story referencing a
+ * component that itself throws on import), surfaces an error naming
+ * `modulePath`. A per-story failure is narrower still — `composeStories`
+ * composes every export independently, so one bad story doesn't take the
+ * rest of the module down; a story whose export isn't a valid CSF
+ * annotation is simply not a function/object Storybook recognizes and is
+ * skipped rather than crashing the whole module (mirrors `composeStories`'s
+ * own `Store_CSFExports`-keyed-mapped-type contract, which already excludes
+ * anything that isn't shaped like a story).
+ */
+export function composeProjectStories(modulePath: string, mod: unknown): ComposeResult {
+  const record = (mod ?? {}) as Record<string, unknown>;
+  if (record['default'] === null || typeof record['default'] !== 'object') {
+    return {
+      ok: false,
+      error:
+        `[stories] ${modulePath} has no default export — every CSF file exports ` +
+        `\`export default { title, component, ... } satisfies Meta<...>\` ` +
+        '(see the template example: src/ui/Button.stories.tsx). Skipped.',
+    };
+  }
+
+  let composed: Record<string, unknown>;
+  try {
+    // biome-ignore lint/suspicious/noExplicitAny: `composeStories` is generically typed over the module's own CSF export shape (Store_CSFExports<ReactRenderer, TModule>), which we can't name statically for an arbitrary dynamically-imported project module.
+    composed = composeStories(record as any) as Record<string, unknown>;
+  } catch (err) {
+    return {
+      ok: false,
+      error: `[stories] ${modulePath} failed to compose — ${String(err instanceof Error ? err.message : err)}`,
+    };
+  }
+
+  const meta = record['default'] as Record<string, unknown>;
+  const title = typeof meta['title'] === 'string' ? meta['title'] : undefined;
+  const humanizeStoryName = (name: string): string =>
+    name
+      .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+      .replace(/[-_]+/g, ' ')
+      .trim();
+
+  const stories: ComposedProjectStory[] = Object.entries(composed)
+    .filter((entry): entry is [string, ComposedStoryFn] => typeof entry[1] === 'function')
+    .map(([name, Component]) => {
+      const portable = Component as unknown as Record<string, unknown>;
+      const authoredStory = record[name];
+      const explicitLabel =
+        authoredStory && typeof authoredStory === 'object'
+          ? (authoredStory as Record<string, unknown>)['name']
+          : undefined;
+      return {
+        name,
+        id: typeof portable['id'] === 'string' ? portable['id'] : name,
+        label:
+          typeof explicitLabel === 'string'
+            ? explicitLabel
+            : humanizeStoryName(
+                typeof portable['storyName'] === 'string' ? portable['storyName'] : name,
+              ),
+        ...(title ? { title } : {}),
+        parameters:
+          portable['parameters'] && typeof portable['parameters'] === 'object'
+            ? (portable['parameters'] as Record<string, unknown>)
+            : {},
+        args:
+          portable['args'] && typeof portable['args'] === 'object'
+            ? { ...(portable['args'] as Record<string, unknown>) }
+            : {},
+        // Object.entries() loses the predicate's value refinement under the
+        // root build tsconfig; the filter above is the runtime proof.
+        Component: Component as ComposedStoryFn,
+      };
+    });
+
+  if (stories.length === 0) {
+    return {
+      ok: false,
+      error:
+        `[stories] ${modulePath} exports no named stories — a CSF file needs at least one ` +
+        'named export alongside the default Meta export (see src/ui/Button.stories.tsx). Skipped.',
+    };
+  }
+
+  return { ok: true, stories };
+}

package/src/stories/loader-stories.fixture.tsx

@@ -0,0 +1,53 @@
+/**
+ * Fixture CSF module for the C3 loaders regression test
+ * (`StoryPreviewMount.loaders.test.tsx`) — a minimal, real CSF3 file with a
+ * `loaders` entry whose resolved value is rendered into the DOM. This is the
+ * proof surface for "loaders mount through Storybook portable-story APIs"
+ * (spec §9): the loaded value can ONLY appear in the rendered output if the
+ * composed story's `.load()` actually ran before render (see
+ * `StoryPreviewMount.tsx`'s module doc comment for why — confirmed against
+ * Storybook 9's own `composeStory` implementation). Mirrors
+ * `button-stories.fixture.tsx`'s shape/precedent, kept local for the same
+ * "fast, isolated, no cross-package reach" reasons.
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+interface LoaderFixtureProps {
+  loaded?: { greeting: string };
+}
+
+function LoaderFixture({ loaded }: LoaderFixtureProps) {
+  // Storybook's own composed-story context defaults `loaded` to `{}` (an
+  // empty but truthy object) BEFORE `.load()` has ever run, and only
+  // replaces it with the loader's real return value once `.load()` resolves
+  // (see `StoryPreviewMount.tsx`'s module doc comment) — so this checks the
+  // actual KEY the loader supplies, not just object presence.
+  return (
+    <div data-testid="loader-fixture">
+      {loaded?.greeting ?? '(no loaded data — .load() did not run)'}
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Fixture/Loader',
+  component: LoaderFixture,
+} satisfies Meta<typeof LoaderFixture>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const WithLoader: Story = {
+  loaders: [
+    async () => {
+      // A real async loader — proves this isn't just a synchronous default
+      // arg. `composeStories` puts this return value on `context.loaded`,
+      // which the story below reads and renders.
+      await Promise.resolve();
+      return { greeting: 'hello from loader' };
+    },
+  ],
+  render: (_args, { loaded }) => <LoaderFixture loaded={loaded as { greeting: string }} />,
+};