@volter/editor-core 0.5.57

package/src/stories/story-declared-medium.ts

@@ -0,0 +1,126 @@
+/**
+ * A story's MEDIUM is a declaration, never a mount.
+ *
+ * ARCHITECTURE-CORE §Zero inference: the system answers a question by reading
+ * a declaration, walking ground truth, or diagnosing declared-vs-measured
+ * drift loudly. Mounting a story to guess whether it is a DOM / three /
+ * canvas member is the third thing that section forbids.
+ *
+ * The ONE rung: **the story file's region** — `resolveFileRegion` over the
+ * project's adapter `include` / `mounts` and the manifest root entries. Prefab
+ * stories match the adapter's `src/prefabs` include glob because that glob is
+ * an adapter-selected finder, not because a sibling file exists.
+ *
+ * Anything it cannot place is {@link DeclaredStoryMedium.via}
+ * `'undeclared'` — a named gap, never a candidate on any board, never a
+ * mount. Presence names it; board membership skips it.
+ */
+
+import type { ProjectRegionEntry } from '../asset-workflow/project-source-index';
+import {
+  type FileRegionAnswer,
+  type RegionBinding,
+  resolveFileRegion,
+} from '../ui-source/file-region-resolver';
+
+/** The three boards a declared story can belong to. */
+export type StoryMedium = 'three' | 'canvas' | 'dom';
+
+export type DeclaredStoryVia = 'declared-include' | 'root-entry' | 'undeclared';
+
+export interface DeclaredStoryMedium {
+  readonly medium?: StoryMedium;
+  readonly via: DeclaredStoryVia;
+  /** Set only when {@link DeclaredStoryVia} is `'undeclared'`. */
+  readonly reason?: string;
+}
+
+function normalizeRelative(path: string): string {
+  return path.replaceAll('\\', '/').replace(/^\.\//, '').replace(/^\//, '');
+}
+
+function regionOfEntryLookup(
+  regions: readonly ProjectRegionEntry[],
+): (file: string) => RegionBinding | undefined {
+  const byEntry = new Map<string, ProjectRegionEntry>();
+  for (const region of regions) {
+    if (region.entry) byEntry.set(normalizeRelative(region.entry), region);
+  }
+  return (file) => byEntry.get(normalizeRelative(file));
+}
+
+function resolvePath(
+  projectRelative: string,
+  regions: readonly ProjectRegionEntry[],
+): FileRegionAnswer {
+  const file = normalizeRelative(projectRelative);
+  return resolveFileRegion({
+    file,
+    projectRelative: file,
+    regions,
+    regionOfEntry: regionOfEntryLookup(regions),
+  });
+}
+
+function surfaceAsMedium(surface: FileRegionAnswer['surface']): StoryMedium | undefined {
+  return surface === 'three' || surface === 'canvas' || surface === 'dom' ? surface : undefined;
+}
+
+function viaForAnswer(
+  answer: FileRegionAnswer,
+): Exclude<DeclaredStoryVia, 'undeclared'> | undefined {
+  if (answer.via === 'declared-include') return 'declared-include';
+  if (answer.via === 'root-entry') return 'root-entry';
+  return undefined;
+}
+
+/**
+ * Read the declared medium of one story. Pure: regions and the CSF identity
+ * are the only inputs. Does not import, compose, or mount anything.
+ */
+export function declaredStoryMedium(input: {
+  readonly modulePath?: string | undefined;
+  readonly regions?: readonly ProjectRegionEntry[] | undefined;
+}): DeclaredStoryMedium {
+  const regions = input.regions ?? [];
+  const modulePath = input.modulePath ? normalizeRelative(input.modulePath) : '';
+  if (!modulePath) {
+    return { via: 'undeclared', reason: 'story has no module path' };
+  }
+
+  const own = resolvePath(modulePath, regions);
+  const ownMedium = surfaceAsMedium(own.surface);
+  const ownVia = viaForAnswer(own);
+  if (ownMedium && ownVia) return { medium: ownMedium, via: ownVia };
+
+  return {
+    via: 'undeclared',
+    reason: `${modulePath} is not named by a region include/mount and is not a manifest root entry`,
+  };
+}
+
+const reportedUndeclared = new Set<string>();
+
+/** Name an undeclared story once. Nothing may mount it to guess a medium. */
+export function reportUndeclaredStoryMedium(modulePath: string, reason?: string): void {
+  const key = normalizeRelative(modulePath);
+  if (reportedUndeclared.has(key)) return;
+  reportedUndeclared.add(key);
+  // biome-ignore lint/suspicious/noConsole: declared-vs-measured gap — the doctrine's third arm, same instrument as reportUnreadableRegions.
+  console.warn(
+    `[story-media] ${key} has no declared medium` +
+      (reason ? ` — ${reason}` : '') +
+      '. It is not a candidate on any board. Declare it via ' +
+      '`vgai.adapter.ts` regionIncludes or a manifest root entry.',
+  );
+}
+
+/** Forget which gaps have already been named — project switch, or a test. */
+export function resetUndeclaredStoryMediumReports(): void {
+  reportedUndeclared.clear();
+}
+
+/** Test-only alias. */
+export function __resetUndeclaredStoryMediumReportsForTest(): void {
+  resetUndeclaredStoryMediumReports();
+}

package/src/stories/story-discovery.ts

@@ -0,0 +1,176 @@
+/**
+ * Story discovery — C3 (spec §9, "Add CSF Discovery and Portable Story
+ * Mounting"). The story sibling of `tool-loader.ts`: conventional
+ * `src/**\/*.stories.tsx` / `*.stories.ts` files of the open project are found
+ * via the editor server's folder scan (`GET /__editor/story-files`,
+ * `editor-server.ts`) — the SAME "discovery IS a live folder scan, never a
+ * cached manifest" physics `tool-loader.ts`/ `DataPanel.tsx` already use.
+ *
+ * Deliberately paths-only, same reasoning as tool discovery: the CSF MODULE
+ * itself is loaded client-side through Vite's `/@fs/` dynamic-import path
+ * (`compose-project-stories.ts` calls `load()` below), so it arrives
+ * transpiled with HMR and the editor never stores a duplicate story
+ * definition anywhere — the CSF module on disk stays the single source of
+ * truth (spec §9 C3 "Story source remains the CSF module").
+ *
+ * A HOST THAT DOES NOT SERVE `/__editor/story-files` is recognised by the
+ * ANSWER's content type, never by `res.ok`: a host with an SPA fallback
+ * answers any unmatched path `200` with HTML, so `res.ok` is TRUE and the only
+ * failure is `res.json()` throwing into a `catch` that returned `undefined`.
+ * Discovery then resolved to `[]`,
+ * which the Stories panel renders as "this root has no portable CSF previews"
+ * — a claim about the PROJECT, produced by a build that never read it.
+ *
+ * The browser (server-less) tier discovers and loads stories from STORAGE:
+ * the scan is a `StorageBackend` walk for the same `*.stories.tsx?` shape the
+ * server route matches, regions come from the project's own manifest/adapter
+ * through the session's own route, and `load()` imports the CSF module the
+ * way every project module loads.
+ */
+
+import type { ProjectRegionEntry } from '../asset-workflow/project-source-index';
+import { editorServerJson } from '../editor-server-response';
+import { setProjectStoryRegions } from './project-story-regions';
+
+/**
+ * Why this session could not discover stories, or `null` when discovery
+ * genuinely ran (in which case an empty list IS "no stories").
+ *
+ * Set by every path that returns early, so no caller has to tell "the project
+ * has none" apart from "nobody looked" by inspecting an empty array.
+ */
+let _unavailable: string | null = null;
+
+/** Why story discovery could not run this session, or `null` when it did.
+ *  An empty module list with `null` here is a real "no stories" answer. */
+export function storyDiscoveryUnavailable(): string | null {
+  return _unavailable;
+}
+
+/** One discovered story module — path only; the module is loaded on demand. */
+export interface DiscoveredStoryModule {
+  /** Project-relative path, e.g. `src/ui/Button.stories.tsx`. */
+  modulePath: string;
+  /** Dynamically imports the CSF module via Vite's `/@fs/` path, cache-busted
+   *  so a re-discover (or an explicit re-load) always gets fresh code — same
+   *  contract as `tool-loader.ts`'s `refreshProjectTools`. Returns the raw
+   *  module namespace (default export = Meta, named exports = stories). */
+  load: () => Promise<unknown>;
+}
+
+/** Minimal shape `discoverProjectStories` needs from the open project — the
+ *  same fields `getCurrentProject()` (`project-manager.ts`) already returns,
+ *  kept as a narrow parameter so this module doesn't need to import the
+ *  whole project-manager (and stays trivially testable with a fixture). */
+export interface StoryDiscoveryProject {
+  rootPath: string;
+}
+
+/** Shape of `/__editor/story-files` (editor-server.ts) — a live folder scan,
+ *  never a cached manifest (D3), plus a server-truthed existence check for
+ *  the project's optional `.storybook/preview.ts(x)`. */
+interface StoryFilesPayload {
+  files: Array<{ path: string }>;
+  /** Project-relative path to whichever preview-config candidate exists on
+   *  disk, or `null` when the project has no `.storybook/` folder at all
+   *  (the common case — this repo's own template ships none). */
+  previewModulePath?: string | null;
+  /** Adapter + manifest regions the server already read — story medium is
+   *  declared from these, never from a mount. Absent on older payloads. */
+  regions?: ProjectRegionEntry[];
+}
+
+// No project param: the editor server is single-project (`projectRoot` is
+// server-side session state — `/__editor/open-project`), so this GET is
+// never parameterized by project, same as `/__editor/tool-files`/
+// `/__editor/data-files`.
+async function fetchStoryFilesPayload(): Promise<StoryFilesPayload | undefined> {
+  try {
+    const res = await fetch('/__editor/story-files');
+    // Content type BEFORE parsing — see `editor-server-response.ts` for why
+    // `res.ok` cannot tell a real scan apart from this origin's page fallback.
+    const payload = await editorServerJson<StoryFilesPayload>(
+      res,
+      'Scanning this project for stories failed',
+    );
+    if (Array.isArray(payload.regions)) setProjectStoryRegions(payload.regions);
+    return payload;
+  } catch (error) {
+    _unavailable = error instanceof Error ? error.message : String(error);
+    return undefined;
+  }
+}
+
+/**
+ * Scan the open project for `*.stories.tsx` / `*.stories.ts` files (via the
+ * editor server's `/__editor/story-files` route) and return one
+ * `DiscoveredStoryModule` per file, each carrying a lazy `load()`.
+ *
+ * Never throws: a missing/unreachable route or no project open resolves to
+ * `[]`, mirroring `refreshProjectTools`'s "keep the editor alive" discipline —
+ * a broken discovery pass must not crash the Stories panel. Every early return
+ * records {@link storyDiscoveryUnavailable} first, so an empty list is only
+ * ever read as "this project has no stories" when discovery actually ran.
+ */
+export async function discoverProjectStories(
+  project: StoryDiscoveryProject | null,
+): Promise<DiscoveredStoryModule[]> {
+  _unavailable = null;
+  if (!project) return [];
+
+  // Guard the REALM, not the response — the server-less tier scans storage
+  // and bundles in-browser; the dev/packaged tier asks its server and loads
+  // through `/@fs/`. Same split as `tool-loader.ts`'s contribution catalog.
+
+  const payload = await fetchStoryFilesPayload();
+  if (!payload) return [];
+
+  return payload.files.map(({ path: modulePath }) => ({
+    modulePath,
+    load: () =>
+      import(
+        /* @vite-ignore */ `/@fs/${project.rootPath}/${modulePath}?t=${Date.now()}`
+      ) as Promise<unknown>,
+  }));
+}
+
+/**
+ * Load the open project's `.storybook/preview.ts(x)` module namespace, if it
+ * has one — the project-level annotations `setProjectAnnotations` applies
+ * once per session (`compose-project-stories.ts`'s `ensureProjectAnnotations`,
+ * called from `story-registry.ts`'s `refreshProjectStories`). Resolves to
+ * `undefined` when the project has no `.storybook/` folder (this repo's own
+ * template ships none — Storybook's own documented default project
+ * annotations apply, same as running with no preview config at all) or when
+ * the file fails to import for any other reason; never throws — a project
+ * config error here must not block story discovery from working.
+ *
+ * Asks the server (`/__editor/story-files`'s `previewModulePath`) which
+ * candidate, if any, actually exists on disk BEFORE importing anything — no
+ * more blind `/@fs/` probing of a path that almost always isn't there. A
+ * project with no `.storybook/` folder now costs zero network requests here
+ * instead of one guaranteed-to-fail one (that failure was invisible to this
+ * function's own try/catch, since a browser reports a failed `/@fs/` fetch
+ * as a page-level network error regardless of how the JS that triggered it
+ * handles the rejection — see `check-vgai-generated-project-p2p.ts`, which
+ * caught this as a generated-project "browser error").
+ */
+export async function loadProjectPreviewAnnotations(
+  project: StoryDiscoveryProject | null,
+): Promise<unknown> {
+  if (!project) return undefined;
+  // Same realm split as `discoverProjectStories`. Deliberately does NOT touch
+  // `_unavailable` — discovery owns that record, and this runs beside it.
+  const payload = await fetchStoryFilesPayload();
+  const modulePath = payload?.previewModulePath;
+  if (!modulePath) return undefined;
+  try {
+    return await import(
+      /* @vite-ignore */ `/@fs/${project.rootPath}/${modulePath}?t=${Date.now()}`
+    );
+  } catch {
+    // Reported as present but failed to import for some other reason (a
+    // genuine config error) — degrade the same way as "not present".
+    return undefined;
+  }
+}

package/src/stories/story-document-openers.ts

@@ -0,0 +1,36 @@
+/**
+ * The ADDRESSES a portable CSF story opens under, and the request shape that
+ * carries one — the story kind's half of `document-open-registry.ts`.
+ *
+ * It lives here, in the host's story estate (the registry, discovery, the
+ * declared medium, the arg descriptors, the three mount), and NOT in the
+ * documents, because the documents are a contribution: `@vgai/game` registers
+ * openers for these ids, the host asks for them, and neither side imports the
+ * other. A build that does not carry that package simply has no opener, which
+ * every call site already handles — `null` is the same answer an undeclared
+ * medium has always given.
+ *
+ * Three ids, because a story opens on three genuinely different surfaces and
+ * the CHOICE between them is made in three different places: by the story's
+ * declared medium (`story-opener.ts`'s `story` opener), by the owning component's
+ * surface (the Content grid), and by the caller asking for Docs explicitly.
+ */
+
+/** A story rendered on the Object3D document surface — the turntable. */
+export const THREE_STORY_DOCUMENT_OPENER = 'story:three';
+/** A story rendered in its own isolated DOM/canvas preview root. */
+export const ISOLATED_STORY_DOCUMENT_OPENER = 'story:isolated';
+/** The Storybook Docs companion for one story. */
+export const STORY_DOCS_DOCUMENT_OPENER = 'story:docs';
+
+export interface StoryDocumentOpenRequest {
+  /** Project-relative CSF module path. */
+  readonly modulePath: string;
+  /** The story's authored export name. */
+  readonly storyName: string;
+  /** Tab title; the export name when absent. */
+  readonly title?: string;
+  /** Whether opening also FOCUSES the tab. A click-through opens and focuses;
+   *  the Edit tab row offers a standing tab instead and passes `false`. */
+  readonly activate?: boolean;
+}

package/src/stories/story-dom-runtime.ts

@@ -0,0 +1,78 @@
+/** Storybook/React-DOM primitives selected from the graph that owns a
+ *  project's CSF modules — the DOM-mount sibling of
+ *  `story-three-preview-runtime.ts`, same seam, same reason (see
+ *  `vite-plugin-module-doorways.ts`'s doc comment for the dual-React failure
+ *  this closes). */
+
+import {
+  composeStories as staticComposeStories,
+  setProjectAnnotations as staticSetProjectAnnotations,
+} from '@storybook/react';
+// The doorway's ADDRESS is the host's own statement about what it serves, and
+// it is spelled ONCE — in `@volter/editor-sdk/host`, the published door. It used
+// to be read from the plugin that SERVES it through a `@editor/../` specifier
+// that stepped out of the editor's `src/` into its build tier, which is a
+// reach no package gets; the plugin now imports the same constant.
+import { STORY_RUNTIME_PATH } from '@volter/editor-sdk/host';
+import { flushSync as staticFlushSync } from 'react-dom';
+import { createRoot as staticCreateRoot } from 'react-dom/client';
+import { isPackagedRuntime } from '../packaged-runtime';
+
+export interface StoryDomRuntime {
+  readonly packaged: boolean;
+  readonly composeStories: typeof staticComposeStories;
+  readonly setProjectAnnotations: typeof staticSetProjectAnnotations;
+  readonly createRoot: typeof staticCreateRoot;
+  readonly flushSync: typeof staticFlushSync;
+}
+
+const STATIC_RUNTIME: StoryDomRuntime = {
+  packaged: false,
+  composeStories: staticComposeStories,
+  setProjectAnnotations: staticSetProjectAnnotations,
+  createRoot: staticCreateRoot,
+  flushSync: staticFlushSync,
+};
+
+let cachedPackagedRuntime: Promise<StoryDomRuntime> | null = null;
+
+async function loadPackagedRuntime(): Promise<StoryDomRuntime> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(/* @vite-ignore */ STORY_RUNTIME_PATH)) as Record<string, unknown>;
+  } catch (err) {
+    // The one legitimate cause besides a server bug: the opened project has
+    // CSF files but no installed `@storybook/react` (the virtual module's
+    // re-export then fails to resolve). Name it — this error surfaces
+    // per-module through composeProjectStories/mountIsolatedStory callers.
+    throw new Error(
+      'The story runtime failed to load from the project module graph — is `@storybook/react` ' +
+        `installed in the project? (${String(err instanceof Error ? err.message : err)})`,
+    );
+  }
+  for (const name of ['composeStories', 'setProjectAnnotations', 'createRoot', 'flushSync']) {
+    if (typeof mod[name] !== 'function') {
+      throw new Error(
+        `The packaged story runtime did not export ${name} as a function — see ` +
+          'vite-plugin-module-doorways.ts.',
+      );
+    }
+  }
+  return {
+    packaged: true,
+    composeStories: mod['composeStories'] as typeof staticComposeStories,
+    setProjectAnnotations: mod['setProjectAnnotations'] as typeof staticSetProjectAnnotations,
+    createRoot: mod['createRoot'] as typeof staticCreateRoot,
+    flushSync: mod['flushSync'] as typeof staticFlushSync,
+  };
+}
+
+export async function resolveStoryDomRuntime(): Promise<StoryDomRuntime> {
+  if (!(await isPackagedRuntime())) return STATIC_RUNTIME;
+  if (!cachedPackagedRuntime) cachedPackagedRuntime = loadPackagedRuntime();
+  return cachedPackagedRuntime;
+}
+
+export function resetStoryDomRuntimeCacheForTest(): void {
+  cachedPackagedRuntime = null;
+}

package/src/stories/story-grouping.ts

@@ -0,0 +1,111 @@
+/**
+ * Story grouping — the ONE optional grouping model for stories, shared by
+ * every story surface. The React design-time board and hierarchy both turn
+ * this path into Storybook's Category → Folder → Component → Story tree;
+ * later surfaces reuse it rather than deriving a second organization.
+ *
+ * It is PRESENTATION-ONLY. A group never affects story↔component
+ * association, default-story picking, mounting, or any other runtime
+ * meaning — it decides layout and labels and nothing else. Nothing here is
+ * a new authored vgai parameter either: the two inputs are facts the story
+ * already carries.
+ *
+ * The group path is Storybook's own convention, in Storybook's own order of
+ * precedence:
+ *   1. the CSF meta `title` when the module authored one (slash-separated),
+ *      parsed by Storybook's exported `parseKind` rather than a local split
+ *      so the separator semantics stay theirs;
+ *   2. otherwise DERIVED from the module's own project-relative path — the
+ *      same thing Storybook does for an untitled CSF file (its automatic
+ *      title comes from the file path) — relative to the project's `src/`
+ *      and with the `*.stories.*` suffix stripped.
+ *
+ * `segments` is the category/folder ancestry (empty for an ungrouped story);
+ * `leaf` is the component name inside that ancestry.
+ */
+
+import { parseKind } from 'storybook/internal/csf';
+import { userOrAutoTitleFromSpecifier } from 'storybook/internal/preview-api';
+import type { NormalizedStoriesSpecifier } from 'storybook/internal/types';
+
+/** One story module's place in the grouping model. */
+export interface StoryGroupPath {
+  /** Ancestor group segments. EMPTY means ungrouped — the flat case, which
+   *  every surface must render exactly as it did before grouping existed. */
+  readonly segments: readonly string[];
+  /** The component/document name within {@link segments}. */
+  readonly leaf: string;
+}
+
+/** Only `.stories.ts(x)` files are discovered (`story-discovery.ts`); the
+ *  `j` variants cost nothing and keep a JS project's derivation honest. */
+const STORY_MODULE_SUFFIX = /\.stories\.[jt]sx?$/i;
+
+/** A project's story modules live under its `src/`, so that prefix is the
+ *  derivation's root — it is shared by every module and would only ever be a
+ *  group everything belongs to. */
+function titleSegments(title: string): string[] {
+  // Storybook's own parse. `rootSeparator`/`groupSeparator` are its documented
+  // defaults; `root` is simply the first segment for our purposes, since a
+  // group path here has no separate "root" concept.
+  const { root, groups } = parseKind(title, { rootSeparator: '|', groupSeparator: '/' });
+  return [...(root ? [root] : []), ...groups].map((part) => part.trim()).filter(Boolean);
+}
+
+function conventionalStorySpecifier(modulePath: string): NormalizedStoriesSpecifier {
+  const normalized = modulePath.replaceAll('\\', '/').replace(/^\.\//, '');
+  const nestedSource = normalized.lastIndexOf('/src/');
+  const directory = normalized.startsWith('src/')
+    ? 'src'
+    : nestedSource >= 0
+      ? normalized.slice(0, nestedSource + 4)
+      : normalized.slice(0, Math.max(0, normalized.lastIndexOf('/')));
+  return {
+    directory,
+    files: '**/*.stories.@(js|jsx|mjs|ts|tsx)',
+    titlePrefix: '',
+    importPathMatcher: STORY_MODULE_SUFFIX,
+  };
+}
+
+/**
+ * The group path of one composed story module: its authored CSF title when
+ * it has one, else its module path relative to the project `src/`.
+ */
+export function deriveStoryGroupPath(input: {
+  modulePath: string;
+  title?: string | undefined;
+}): StoryGroupPath {
+  const modulePath = input.modulePath.replaceAll('\\', '/').replace(/^\.\//, '');
+  const userTitle = input.title && titleSegments(input.title).length > 0 ? input.title : undefined;
+  const nativeTitle = userOrAutoTitleFromSpecifier(
+    modulePath,
+    conventionalStorySpecifier(modulePath),
+    userTitle,
+  );
+  // Storybook's auto-title only speaks for files its own specifier matches, so
+  // it returns nothing for a row that is not a discovered CSF module at all —
+  // the `2D` board's ghost slots, which name a COMPONENT that has no story yet
+  // (`canvas-board/canvas-board-model.ts`). An explicitly supplied title is the
+  // caller's own statement about where the row belongs and stands either way;
+  // without this, such a row falls back to its raw path and every ghost lands
+  // in a district of its own.
+  const parts = nativeTitle
+    ? titleSegments(nativeTitle)
+    : userTitle
+      ? titleSegments(userTitle)
+      : [modulePath];
+  return { segments: parts.slice(0, -1), leaf: parts.at(-1) ?? input.modulePath };
+}
+
+/** The clustering key of a group path — the ancestors alone, so every story
+ *  of one group shares it. `''` is the ungrouped/flat case. */
+export function storyGroupKey(group: StoryGroupPath): string {
+  return group.segments.join('/');
+}
+
+/** The full, human-facing group path (`UI/Button`) — what a surface labels a
+ *  story document with. */
+export function formatStoryGroupPath(group: StoryGroupPath): string {
+  return [...group.segments, group.leaf].join('/');
+}

package/src/stories/story-lane.ts

@@ -0,0 +1,88 @@
+/**
+ * PORTABLE CSF's page-side lane, installed by the kit itself.
+ *
+ * WHAT IT INSTALLS, and which registry each piece reaches: the Content
+ * scope's story-backed entries (`content-entry-source-registry.ts`), the named
+ * states a component has (`component-states-registry.ts`), the addresses a
+ * story opens under (`document-open-registry.ts`, through `story-opener.ts`),
+ * the palette's one action per composed story (`chrome-registry.ts`), the
+ * `capture-story-variants` session verb (`command-registry.ts`) and the
+ * discovery lifecycle that finds a project's `*.stories.ts(x)` modules and
+ * re-composes them on project switches, CSF file add/remove events and content
+ * writes under `src/` (`project-story-discovery.ts`).
+ *
+ * WHY THE KIT AND NOT A PACKAGE. Portable CSF is the design-time state the
+ * three, DOM and canvas surfaces all read — a file three siblings import lives
+ * in none of them — so it is the kit's, not an integration's
+ * (ARCHITECTURE-CORE §The target shape, "`stories` is NOT React"). The kit's
+ * own CSF therefore needs no contribution to exist: these are direct
+ * registrations, at the registries a contribution would have reached.
+ *
+ * THE COST, stated rather than rounded away: `story-registry.ts` imports
+ * `storybook/internal/preview-api`, so the kit's boot closure carries
+ * Storybook's preview API and every product pays for it — the closure meter's
+ * bridge pin names the number.
+ *
+ * WHY EVERYTHING HERE IS EAGER. There is no lazy half to find: the content
+ * source, the states source and the opener each reach `story-registry.ts`
+ * directly, so deferring the discovery scan alone would move no file out of
+ * the closure and would only make the install order harder to read.
+ *
+ * WHAT IS NOT HERE, and why. `@volter/editor-project/adapter`'s `StoriesProvider` is the
+ * CONTRACT — an adapter says which named states a node has, in its own
+ * vocabulary, and answers `unavailable()` itself — so it and
+ * `components/InspectorStoriesSection.tsx` (the section that DRAWS a contract)
+ * stay where they are, with `components/inspector-stories-gating.ts` and
+ * `authoring/stories-scope.ts`. The `prefabsFromStories` finder is registered
+ * by `project-adapter.ts`, the one sanctioned importer of the engine's finder
+ * namespace.
+ */
+
+import { registerContributedActions } from '../chrome-registry';
+import { registerContributedCommands } from '../command-registry';
+import { registerComponentStatesSource } from '../component-states-registry';
+import { registerContentEntrySource } from '../content-entry-source-registry';
+import { refreshProjectAdapter } from '../project-adapter';
+import { storyComponentContentSource } from './component-content-source';
+import { componentStatesSource } from './component-states-source';
+import { startProjectStoryDiscovery } from './project-story-discovery';
+import { storyPaletteActions } from './story-actions';
+import { STORY_CAPTURE_COMMAND_SOURCE, storyCaptureCommands } from './story-capture-command';
+import { registerStoryOpener } from './story-opener';
+import { subscribeProjectStoryModules } from './story-registry';
+
+/** Install the whole lane. Returns the teardown, in reverse order. */
+export function installStoryLane(): () => void {
+  const stopSource = registerContentEntrySource(storyComponentContentSource);
+  // The SIBLING question: the content source says what a component LOOKS
+  // LIKE, this one what named STATES it has. Three authoring adapters used to
+  // construct the second answer inside their own constructors, which is why
+  // the story registry could not be reached through a seam at all.
+  const stopStates = registerComponentStatesSource(componentStatesSource);
+  const stopOpener = registerStoryOpener();
+  const stopActions = registerContributedActions(storyPaletteActions);
+  const stopCommands = registerContributedCommands(
+    STORY_CAPTURE_COMMAND_SOURCE,
+    storyCaptureCommands,
+  );
+  // The scan's own first step is to await the first authored viewport frame
+  // (`waitForFirstViewportFrame`, for the recorded reason that a cold GPU must
+  // not spend its first context on prefab thumbnails), so starting it at boot
+  // costs nothing before that frame.
+  const stopDiscovery = startProjectStoryDiscovery();
+  // A SETTLED LEDGER IS ANNOUNCED HERE. The document table holds prefab rows
+  // the `prefabsFromStories` finder produced, and the table re-resolves when
+  // the finder SET changes — not when one finder's own data does.
+  const stopTableRefresh = subscribeProjectStoryModules(() => {
+    void refreshProjectAdapter();
+  });
+  return () => {
+    stopTableRefresh();
+    stopDiscovery();
+    stopCommands();
+    stopActions();
+    stopOpener();
+    stopStates();
+    stopSource();
+  };
+}

package/src/stories/story-mount-turn.ts

@@ -0,0 +1,27 @@
+/**
+ * THE ONE process-wide story-mount turn queue, shared by every medium.
+ *
+ * Extracted verbatim from `story-three-preview.ts`'s own `storyMountTurn`
+ * (which owned it alone until the canvas surface got a preview mount too) for
+ * the reason that module already states: portable-story LOADERS are allowed to
+ * touch process-global state, so two mounts running at once interleave their
+ * setup and collide. That reason is not three-specific — a canvas story's
+ * loader initializes Pixi's global `Assets` cache and its component catalogue —
+ * and two queues would not serialize a three mount against a canvas mount at
+ * all, which is exactly the pair that now runs over the same project.
+ *
+ * Every caller takes a turn either for ONE mount or for a compound operation
+ * (a whole board build). A rejected turn never poisons its successor.
+ */
+
+let storyMountTurn: Promise<unknown> = Promise.resolve();
+
+/** Run one story-mount operation with no other mount interleaving it. */
+export function runInStoryMountTurn<T>(task: () => Promise<T>): Promise<T> {
+  const turn = storyMountTurn.then(task, task);
+  storyMountTurn = turn.then(
+    () => undefined,
+    () => undefined,
+  );
+  return turn;
+}