@volter/editor-core 0.5.57

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

@@ -0,0 +1,255 @@
+/**
+ * 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.
+ *
+ * WHICH `@storybook/react` (and therefore which `react`) does the composing
+ * is `story-dom-runtime.ts`'s question, not this module's: under the
+ * packaged runtime the CSF module's own hooks resolve against the PROJECT's
+ * react, so the compose/mount machinery must come from that same graph or
+ * every story dies on "Invalid hook call" (see
+ * `vite-plugin-module-doorways.ts`). That seam is why both entry points below
+ * are async.
+ */
+
+import type { ComposedStoryFn } from 'storybook/internal/types';
+import { resolveStoryDomRuntime } from './story-dom-runtime';
+
+let projectAnnotationsApplied: Promise<void> | null = null;
+
+/**
+ * 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): Promise<void> {
+  // The latch holds the IN-FLIGHT promise, not a boolean: a second caller
+  // arriving while the first is still resolving the story runtime must wait
+  // on the SAME application (compose-after-await ordering), not sail past a
+  // `true` flag and compose before any annotations landed.
+  projectAnnotationsApplied ??= resolveStoryDomRuntime().then((runtime) => {
+    // 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.
+    runtime.setProjectAnnotations((previewAnnotations ?? []) as any);
+  });
+  return projectAnnotationsApplied;
+}
+
+/** 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 = null;
+}
+
+/** 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;
+  /** Name/display identity of CSF `meta.component`, when the module declared
+   *  one. This is the ONLY join between a story and the component it renders —
+   *  the asset browser matches a `three` prefab to its thumbnail story on it,
+   *  and a React root matches its own entry component to its composed default
+   *  preview (both via `story-registry.ts`'s `pickComponentPreviewStory`).
+   *  Absent for a story whose meta names no component. */
+  componentName?: string;
+  /** Storybook's own composed CSF tags. The editor may use ordinary custom
+   *  tags to project one project registry into distinct design boards; the
+   *  story module remains the sole source of truth. */
+  tags?: readonly string[];
+  /** Fully-composed Storybook parameters. VGAI only reads the namespaced
+   * `parameters.vgai` association; every other parameter remains Storybook's. */
+  parameters: Record<string, unknown>;
+  /** Storybook's fully-composed globals. Viewport selection is read from
+   *  here exactly as the viewport addon reads it; no editor-side story
+   *  metadata is introduced. */
+  globals?: Record<string, unknown>;
+  /** Whether this CSF meta/story explicitly authors `globals.viewport`.
+   *  Storybook treats that as a locked viewport for the story. Project
+   *  `initialGlobals` still chooses a default without disabling the toolbar. */
+  viewportLocked?: boolean;
+  /** 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 };
+
+/** The display/name identity of a React component — a function/class (its
+ *  `displayName` or `.name`); anything else names nothing. Exported because
+ *  BOTH sides of the story↔component join must compute the identity the same
+ *  way: this file reads it off a CSF `meta.component`, and
+ *  `design-time-layers.ts` reads it off a root entry's default export before
+ *  asking `story-registry.ts`'s `getComponentPreviewStory` for that
+ *  component's story. */
+export function componentIdentityName(component: unknown): string | undefined {
+  if (!component || (typeof component !== 'function' && typeof component !== 'object')) {
+    return undefined;
+  }
+  const displayName = (component as Record<string, unknown>)['displayName'];
+  if (typeof displayName === 'string') return displayName;
+  return typeof component === 'function' && component.name ? component.name : undefined;
+}
+
+/**
+ * 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 async function composeProjectStories(
+  modulePath: string,
+  mod: unknown,
+): Promise<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 {
+    const runtime = await resolveStoryDomRuntime();
+    // 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 = runtime.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 componentName = componentIdentityName(meta['component']);
+  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 authoredStoryRecord =
+        authoredStory && typeof authoredStory === 'object'
+          ? (authoredStory as Record<string, unknown>)
+          : null;
+      const metaGlobals =
+        meta['globals'] && typeof meta['globals'] === 'object'
+          ? (meta['globals'] as Record<string, unknown>)
+          : null;
+      const storyGlobals =
+        authoredStoryRecord?.['globals'] && typeof authoredStoryRecord['globals'] === 'object'
+          ? (authoredStoryRecord['globals'] as Record<string, unknown>)
+          : null;
+      const explicitLabel = authoredStoryRecord?.['name'];
+      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 } : {}),
+        ...(componentName ? { componentName } : {}),
+        tags: Array.isArray(portable['tags'])
+          ? portable['tags'].filter((tag): tag is string => typeof tag === 'string')
+          : [],
+        parameters:
+          portable['parameters'] && typeof portable['parameters'] === 'object'
+            ? (portable['parameters'] as Record<string, unknown>)
+            : {},
+        globals:
+          portable['globals'] && typeof portable['globals'] === 'object'
+            ? { ...(portable['globals'] as Record<string, unknown>) }
+            : {},
+        viewportLocked:
+          Object.hasOwn(metaGlobals ?? {}, 'viewport') ||
+          Object.hasOwn(storyGlobals ?? {}, 'viewport'),
+        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/pixi-story-model.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared, headless facts about a CANVAS story: whether a mounted story holds
+ * Pixi content. The exact counterpart of `three-story-model.ts`'s
+ * `mountedStoryHasThreeContent`, kept pure and off the React tree.
+ *
+ * Membership is DECLARED (`story-declared-medium.ts`). This module does not
+ * classify a story by mounting it.
+ */
+
+import type { Container } from 'pixi.js';
+
+/**
+ * Whether a mounted story's stage actually holds Pixi content.
+ *
+ * A story can mount a `<Application>` successfully and render nothing into it —
+ * a gate whose condition never became true, a component that returns `null`.
+ * That is a successful mount with nothing in it, and a surface shows a story
+ * that rendered SOMETHING; "the mount succeeded" alone is not the test. Exactly
+ * the rule (and exactly the expression) `mountedStoryHasThreeContent` states
+ * for the three surface.
+ */
+export function mountedStoryHasPixiContent(stage: Container): boolean {
+  if (stage.children.length === 0) return false;
+  // An empty wrapper (`<pixiContainer>` around a still-loading piece) is
+  // a child and not content. Isolation and IsolatedPiece both land pixels
+  // after an async asset load; a 0×0 stage is the same "gate never true"
+  // case the header names.
+  const bounds = stage.getBounds();
+  return bounds.width > 1 && bounds.height > 1;
+}

package/src/stories/prefabs-finder.ts

@@ -0,0 +1,54 @@
+/**
+ * The `prefabsFromStories` FINDER — the name a project's `vgai.adapter.ts`
+ * selects, registered beside the story registry it reads.
+ *
+ * WHY IT READS ITS OWN LEDGER. The algorithm used to be an ENGINE finder
+ * (`packages/editor/src/finders/prefabs-from-stories.ts`) whose
+ * `input.stories` the editor's adapter loader filled, which is how the loader
+ * came to reach the story registry through a contract field nothing else ever
+ * filled. `FinderInput.stories` is gone; the finder gathers its own
+ * registrations here, and `input.components` is the only project fact it is
+ * handed.
+ *
+ * Registered by `project-adapter.ts`, the ONE sanctioned importer of the
+ * engine's finder namespace (that file's header states the rule).
+ */
+
+import { z } from 'zod';
+import { prefabsFromStories, type StoryRegistration } from './prefabs-from-stories';
+import { getProjectStoryModules, isDeclaredDefaultStory } from './story-registry';
+
+/** Every story the project's registry has composed, in the finder's
+ *  vocabulary. */
+function storyRegistrations(): StoryRegistration[] {
+  const out: StoryRegistration[] = [];
+  for (const module_ of getProjectStoryModules()) {
+    if (!module_.ok) continue;
+    for (const story of module_.stories) {
+      out.push({
+        modulePath: module_.modulePath,
+        storyId: story.id,
+        label: story.label,
+        ...(story.componentName === undefined ? {} : { componentName: story.componentName }),
+        isDefault: isDeclaredDefaultStory(story),
+      });
+    }
+  }
+  return out;
+}
+
+export const storyPrefabsFinder = {
+  name: 'prefabsFromStories',
+  schema: z.object({ finder: z.literal('prefabsFromStories') }).strict(),
+  run(
+    selection: { finder: 'prefabsFromStories' },
+    input: {
+      components?: readonly { name: string; path: string; region?: string | null }[];
+    },
+  ) {
+    return prefabsFromStories(selection, {
+      stories: storyRegistrations(),
+      ...(input.components === undefined ? {} : { components: input.components }),
+    });
+  },
+};

package/src/stories/prefabs-from-stories.ts

@@ -0,0 +1,182 @@
+/**
+ * FINDER — prefabs from colocated portable-CSF story registrations.
+ *
+ * IT LIVES HERE, and not in the engine's finder namespace, since 2026-09-18
+ * (phase 1 unit 11, edge 8). It was `packages/project/src/adapter/finders/
+ * prefabs-from-stories.ts`, a host-owned discovery algorithm the engine
+ * registered and whose `input.stories` the editor's adapter loader FILLED from
+ * the story registry — which is how `project-adapter.ts` came to import the
+ * registry, and through it Storybook, into every editor boot. The finder
+ * CONTRIBUTION point (`.finder`, `tool-loader.ts`) already collects
+ * package-shipped modules, so the algorithm and its data now arrive together
+ * and the host fills nothing: `FinderInput.stories` is gone with it.
+ *
+ * The finder NAME is unchanged, because it is a project's own declaration
+ * (`{ finder: 'prefabsFromStories' }` in every `vgai.adapter.ts`). A build
+ * without this package leaves that selection unregistered, which the host
+ * already reports as a standing note rather than a throw.
+ *
+ * The function itself is untouched — pure over its inputs, structurally typed
+ * exactly as `@volter/editor-blender`'s `modelsFromBlendFiles` finder is, importing no
+ * engine module.
+ *
+ * ARCHITECTURE-CORE §Roots: "A prefab is an ordinary source component that a
+ * designer independently places, duplicates, or reuses, explicitly registered
+ * for Content by a colocated portable story whose `meta.component` names it."
+ * The registration is the load-bearing reference — delete the story and the
+ * declaration is gone — which is why source SHAPE alone never admits a prefab.
+ *
+ * EXTRACTION, not a new rule. The join implemented here is the one the editor
+ * already runs:
+ *   - the match + same-source-directory tiebreak:
+ *     `packages/editor/src/stories/story-registry.ts:162-186`
+ *     (`componentPreviewStories`) and `:148-159` (`pickComponentPreviewStory`);
+ *   - the default-story preference: `story-registry.ts:118-123`
+ *     (`isDeclaredDefaultStory`);
+ *   - the admission rule "a component with no story is not a Content entry at
+ *     all": `packages/editor/src/components/AssetBrowser.tsx`, the
+ *     `browserEntries` content scope (`if (!previewStory) return []`).
+ * `meta.component`'s identity NAME is read live by
+ * `packages/editor/src/stories/compose-project-stories.ts:130` /
+ * `:185` (`componentIdentityName`) — this finder consumes that answer rather
+ * than re-deriving it, so both sides of the join agree by construction.
+ *
+ * Pure over its inputs: the host hands in the registrations the story registry
+ * already produced and the component index it already has.
+ */
+
+/** What a finder hands back, structurally (`@editor/finders`'s
+ *  `FinderResult`): entries for the document table, plus notes the host
+ *  surfaces. Spelled here rather than imported, the way every other
+ *  package-shipped finder spells it — the engine's finder namespace has
+ *  exactly ONE sanctioned importer and this is not it. */
+interface DocumentEntry {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: string;
+  readonly region?: string | null;
+  readonly authorable?: boolean;
+  readonly reach?: { readonly kind: 'story'; readonly storyId: string };
+  readonly source?: { readonly path: string; readonly export?: string };
+  readonly finder?: string;
+}
+interface FinderResult {
+  readonly entries: readonly DocumentEntry[];
+  readonly notes: readonly string[];
+  readonly defaultId?: string | null;
+}
+interface PrefabsFromStoriesParams {
+  readonly finder: 'prefabsFromStories';
+}
+
+/** One composed portable-CSF story, as the host's story registry reports it. */
+export interface StoryRegistration {
+  /** Project-relative path of the CSF module (`src/prefabs/HeroBox.stories.tsx`). */
+  readonly modulePath: string;
+  /** The composed story's stable id. */
+  readonly storyId: string;
+  /** Human label for the story. */
+  readonly label: string;
+  /**
+   * `meta.component`'s identity name. Absent ⇒ this story is joined to nothing
+   * and declares no prefab — an ordinary story document, not a defect.
+   */
+  readonly componentName?: string;
+  /** Whether the module declares this story as its component's default. */
+  readonly isDefault?: boolean;
+}
+
+/** One entry of the host's project component index. */
+export interface ProjectComponentRef {
+  readonly name: string;
+  /** Project-relative source path of the component's own module. */
+  readonly path: string;
+  /** Region this component's surface belongs to, when the host knows it. */
+  readonly region?: string | null;
+}
+
+export interface PrefabsFromStoriesInput {
+  readonly stories: readonly StoryRegistration[];
+  /**
+   * The project's component index. Supplies each prefab's own source path and
+   * region; absent, entries still exist (the story IS the declaration) and
+   * simply carry no `source`.
+   */
+  readonly components?: readonly ProjectComponentRef[];
+}
+
+/** Directory portion of a project-relative path — `story-registry.ts:126`'s `sourceDir`. */
+function sourceDir(path: string): string {
+  const normalized = path.replaceAll('\\', '/').replace(/^\.\//, '');
+  const slash = normalized.lastIndexOf('/');
+  return slash >= 0 ? normalized.slice(0, slash) : '';
+}
+
+/** Group the registrations by the component their meta NAMES. A story naming
+ *  none is joined to nothing and declares no prefab. */
+function storiesByComponent(
+  stories: readonly StoryRegistration[],
+): Map<string, StoryRegistration[]> {
+  const byComponent = new Map<string, StoryRegistration[]>();
+  for (const story of stories) {
+    const name = story.componentName;
+    if (name === undefined || name === '') continue;
+    const bucket = byComponent.get(name);
+    if (bucket) bucket.push(story);
+    else byComponent.set(name, [story]);
+  }
+  return byComponent;
+}
+
+/**
+ * The story that speaks for a component: colocated beats distant
+ * (story-registry.ts:177-180 — two files can export a same-named component),
+ * and within that set the module's own declared default wins
+ * (story-registry.ts:118-123).
+ */
+function chooseStory(
+  stories: readonly StoryRegistration[],
+  component: ProjectComponentRef | undefined,
+): { chosen: StoryRegistration | undefined; colocated: boolean } {
+  const sameDir = component
+    ? stories.filter((story) => sourceDir(story.modulePath) === sourceDir(component.path))
+    : [];
+  const pool = sameDir.length > 0 ? sameDir : stories;
+  return {
+    chosen: pool.find((story) => story.isDefault === true) ?? pool[0],
+    colocated: sameDir.length > 0,
+  };
+}
+
+export function prefabsFromStories(
+  _params: PrefabsFromStoriesParams,
+  input: PrefabsFromStoriesInput,
+): FinderResult {
+  const entries: DocumentEntry[] = [];
+  const notes: string[] = [];
+  for (const [componentName, stories] of storiesByComponent(input.stories)) {
+    const component = input.components?.find((candidate) => candidate.name === componentName);
+    const { chosen, colocated } = chooseStory(stories, component);
+    if (!chosen) continue;
+    if (component && !colocated) {
+      notes.push(
+        `prefabsFromStories: "${componentName}" is declared by ${chosen.modulePath}, which is not ` +
+          `colocated with ${component.path}. The join is by name; confirm it names this component.`,
+      );
+    }
+    entries.push({
+      id: componentName,
+      label: componentName,
+      kind: 'prefab',
+      region: component?.region ?? null,
+      authorable: true,
+      reach: { kind: 'story', storyId: chosen.storyId },
+      ...(component ? { source: { path: component.path, export: component.name } } : {}),
+      finder: 'prefabsFromStories',
+    });
+  }
+
+  // Prefabs are sibling documents, never the default scene — a finder that
+  // cannot settle a default says nothing rather than nominating one.
+  return { entries, notes };
+}

package/src/stories/project-story-discovery.ts

@@ -0,0 +1,78 @@
+/**
+ * Project Storybook discovery lifecycle. Story navigation is a project
+ * capability, not a side effect of mounting a particular React world or
+ * opening a Story document.
+ *
+ * `story-lane.ts` starts it, as one piece of the kit's own CSF install, and
+ * never `EditorContext.tsx`: the editor's first render is not what decides
+ * whether a project's stories are scanned.
+ */
+
+import { connectStoryFileEvents } from '../asset-events';
+import { getCurrentProject, onProjectChange } from '../project-manager';
+import { subscribeProjectModuleChange } from '../project-module-changes';
+import { waitForFirstViewportFrame } from '../viewport-activation-timings';
+import { resetUndeclaredStoryMediumReports } from './story-declared-medium';
+import { refreshProjectStories } from './story-registry';
+
+/** Discover after the first authored frame, then re-discover on project
+ * switches, CSF file add/remove events, and CONTENT writes to `src/**`.
+ * The content trigger exists because a story renders the project's own
+ * components: Apply-to-Component rewrote a prefab's default and the board
+ * kept exhibiting the old one — the registry only ever heard about
+ * added/removed story FILES, never a changed module (runhuman pass 43).
+ * Dev tier: the HMR module-change channel. Browser tier: the storage
+ * backend's own watch. A newer refresh supersedes an in-flight older pass. */
+export function startProjectStoryDiscovery(): () => void {
+  let refreshGeneration = 0;
+  let stopped = false;
+  const refresh = (changedPaths?: ReadonlySet<string>): void => {
+    const generation = ++refreshGeneration;
+    resetUndeclaredStoryMediumReports();
+    // Story discovery feeds the Content panel and design boards; none of those
+    // may hold the opening world behind evaluation of every prefab's CSF graph.
+    // Wait for the first honest authored frame. There is deliberately no timer:
+    // on a slow cold GPU, a five-second fallback fired while the Scene was still
+    // constructing and moved the entire story graph back onto its critical path.
+    // A genuinely broken viewport is not a reason to import every asset story in
+    // the background; explicitly opening a Story/board calls
+    // `refreshProjectStories` directly and remains its recovery door.
+    void waitForFirstViewportFrame().then(() => {
+      if (stopped || generation !== refreshGeneration) return;
+      return refreshProjectStories(getCurrentProject(), undefined, {
+        deferUndeclared: true,
+        ...(changedPaths ? { changedPaths } : {}),
+      });
+    });
+  };
+  refresh();
+  // Content writes arrive per keystroke-ish (autosave); coalesce a burst into
+  // one rescan rather than re-importing every CSF module per write.
+  let contentTimer: ReturnType<typeof setTimeout> | null = null;
+  let pendingContentPaths = new Set<string>();
+  const refreshOnContentWrite = (path: string): void => {
+    // Dev reports absolute paths, storage reports project-relative ones; the
+    // filter is the same fact both ways: a source module under src/.
+    const match = /(?:^|\/)(src\/.+\.(?:[cm]?tsx?|jsx?))$/.exec(path);
+    if (!match) return;
+    pendingContentPaths.add(match[1] ?? path);
+    if (contentTimer !== null) clearTimeout(contentTimer);
+    contentTimer = setTimeout(() => {
+      contentTimer = null;
+      const changed = pendingContentPaths;
+      pendingContentPaths = new Set();
+      refresh(changed);
+    }, 1_000);
+  };
+  const stopModuleWatch = subscribeProjectModuleChange(refreshOnContentWrite);
+  const stopProjectWatch = onProjectChange(() => refresh());
+  const stopStoryFileWatch = connectStoryFileEvents(refresh);
+  return () => {
+    stopped = true;
+    refreshGeneration += 1;
+    if (contentTimer !== null) clearTimeout(contentTimer);
+    stopModuleWatch();
+    stopProjectWatch();
+    stopStoryFileWatch();
+  };
+}

package/src/stories/project-story-regions.ts

@@ -0,0 +1,24 @@
+/**
+ * The open project's regions, as story classification reads them.
+ *
+ * Filled from `/__editor/story-files` (the same fetch that lists CSF modules)
+ * so presence and board membership answer from the adapter + manifest the
+ * server already read, not from a second walk. Tests inject a table directly.
+ */
+
+import type { ProjectRegionEntry } from '../asset-workflow/project-source-index';
+
+let _regions: readonly ProjectRegionEntry[] = [];
+
+export function getProjectStoryRegions(): readonly ProjectRegionEntry[] {
+  return _regions;
+}
+
+export function setProjectStoryRegions(regions: readonly ProjectRegionEntry[]): void {
+  _regions = regions;
+}
+
+/** Test-only. */
+export function __resetProjectStoryRegionsForTest(): void {
+  _regions = [];
+}