@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/stories/story-discovery.ts

@@ -0,0 +1,130 @@
+/**
+ * Story discovery — C3 (spec §9, docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md
+ * "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 (docs/DATA-TOOLS-DESIGN.md §3.5 rule 2).
+ *
+ * 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").
+ *
+ * Browser mode (no Node dev server): `fetch('/__editor/story-files')` 404s
+ * or throws, so `discoverProjectStories` resolves to an empty list rather
+ * than throwing — same graceful no-op `refreshProjectTools` uses.
+ */
+
+/** 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;
+}
+
+// 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');
+    if (!res.ok) return undefined; // no dev server route (e.g. browser mode)
+    return (await res.json()) as StoryFilesPayload;
+  } catch {
+    return undefined; // server unreachable
+  }
+}
+
+/**
+ * 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 (browser mode, or no project
+ * open) resolves to `[]`, mirroring `refreshProjectTools`'s "keep the editor
+ * alive" discipline — a broken discovery pass must not crash the Stories
+ * panel.
+ */
+export async function discoverProjectStories(
+  project: StoryDiscoveryProject | null,
+): Promise<DiscoveredStoryModule[]> {
+  if (!project) return [];
+
+  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;
+  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-registry.ts

@@ -0,0 +1,146 @@
+/**
+ * Story registry (C3, spec §9) — the story sibling of `tool-loader.ts`'s
+ * registry half: ties `story-discovery.ts` (find modules) and
+ * `compose-project-stories.ts` (portable-mount one loaded module) together
+ * into a live, `useSyncExternalStore`-shaped list consumed by React design-time
+ * world mounting and its document/story hierarchy.
+ *
+ * Same discipline as the tool registry: discovery is a live rescan (never a
+ * cached manifest, D3), re-run on project open/change and on the server's
+ * `story-files-changed` SSE broadcast (a new/removed `*.stories.tsx`).
+ * Per-module failures (a module that fails to import, or fails to compose)
+ * are collected alongside successes rather than dropped — the panel shows a
+ * broken module's error inline, naming the module (spec §9 "errors identify
+ * the source module"), instead of silently omitting it.
+ */
+
+import {
+  type ComposedProjectStory,
+  composeProjectStories,
+  ensureProjectAnnotations,
+} from './compose-project-stories';
+
+/** One portable CSF story explicitly associated with a native React root.
+ * The association uses Storybook's standard custom-parameters seam:
+ * `parameters.vgai.root` (preferred) or `parameters.vgai.world` (migration
+ * alias). No story args/decorators/loaders are copied or reinterpreted. */
+export interface RootPreviewStory extends ComposedProjectStory {
+  modulePath: string;
+  rootId: string;
+  isDefault: boolean;
+}
+
+import { discoverProjectStories, loadProjectPreviewAnnotations } from './story-discovery';
+
+/** One discovered module's outcome after load + compose. */
+export type ProjectStoryModule =
+  | { modulePath: string; ok: true; stories: ComposedProjectStory[] }
+  | { modulePath: string; ok: false; error: string };
+
+interface StoryDiscoveryProjectLike {
+  rootPath: string;
+}
+
+let _modules: ProjectStoryModule[] = [];
+const _listeners = new Set<() => void>();
+
+/** Current story modules (stable reference between refreshes). */
+export function getProjectStoryModules(): ProjectStoryModule[] {
+  return _modules;
+}
+
+/** Subscribe to story-registry changes. Returns an unsubscribe function. */
+export function subscribeProjectStoryModules(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => _listeners.delete(fn);
+}
+
+function vgaiParameters(story: ComposedProjectStory): Record<string, unknown> | null {
+  const value = story.parameters['vgai'];
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : null;
+}
+
+/** Return the project's composed portable stories associated with `rootId`.
+ * This is the canonical React design-time source consumed by the main world
+ * viewport and hierarchy. `defaultStory` may be declared once
+ * at CSF meta level; `default: true` is accepted story-by-story. */
+export function getRootPreviewStories(rootId: string): RootPreviewStory[] {
+  const out: RootPreviewStory[] = [];
+  for (const module_ of _modules) {
+    if (!module_.ok) continue;
+    for (const story of module_.stories) {
+      const vgai = vgaiParameters(story);
+      if (!vgai) continue;
+      const associatedRoot =
+        typeof vgai['root'] === 'string'
+          ? vgai['root']
+          : typeof vgai['world'] === 'string'
+            ? vgai['world']
+            : null;
+      if (associatedRoot !== rootId) continue;
+      const defaultStory = typeof vgai['defaultStory'] === 'string' ? vgai['defaultStory'] : null;
+      out.push({
+        ...story,
+        modulePath: module_.modulePath,
+        rootId,
+        isDefault: vgai['default'] === true || defaultStory === story.name,
+      });
+    }
+  }
+  return out;
+}
+
+/** Deterministic stopped-mode preview: explicit default first, otherwise the
+ * first story in discovery/export order (the same order the hierarchy
+ * presents). */
+export function getDefaultRootPreviewStory(rootId: string): RootPreviewStory | null {
+  const stories = getRootPreviewStories(rootId);
+  return stories.find((story) => story.isDefault) ?? stories[0] ?? null;
+}
+
+function publish(next: ProjectStoryModule[]): void {
+  _modules = next;
+  for (const fn of _listeners) fn();
+}
+
+/**
+ * Re-run the whole discovery + load + compose pass. Never throws: a broken
+ * module (import failure, or a `composeProjectStories` failure) becomes an
+ * `{ ok: false, error }` entry naming the module, and every other module
+ * still loads — the same "one bad file never takes the rest down" physics
+ * `refreshProjectTools` uses.
+ *
+ * Applies the project's `.storybook/preview.ts(x)` annotations (if the
+ * project has one — `loadProjectPreviewAnnotations`) via
+ * `ensureProjectAnnotations` before composing anything, exactly once per
+ * session. `explicitPreviewAnnotations` is a test/caller override — pass it
+ * to skip the `/@fs/` discovery and thread a fixture's annotations directly.
+ */
+export async function refreshProjectStories(
+  project: StoryDiscoveryProjectLike | null,
+  explicitPreviewAnnotations?: unknown,
+): Promise<void> {
+  const previewAnnotations =
+    explicitPreviewAnnotations ?? (await loadProjectPreviewAnnotations(project));
+  ensureProjectAnnotations(previewAnnotations);
+
+  const discovered = await discoverProjectStories(project);
+  const next: ProjectStoryModule[] = [];
+  for (const { modulePath, load } of discovered) {
+    let mod: unknown;
+    try {
+      mod = await load();
+    } catch (err) {
+      next.push({
+        modulePath,
+        ok: false,
+        error: `[stories] failed to load ${modulePath} — ${String(err instanceof Error ? err.message : err)}`,
+      });
+      continue;
+    }
+    const result = composeProjectStories(modulePath, mod);
+    if (result.ok) next.push({ modulePath, ok: true, stories: result.stories });
+    else next.push({ modulePath, ok: false, error: result.error });
+  }
+  publish(next);
+}