@vgai/editor 0.2.0 → 0.4.0-canary.20260715.1

package/src/components/story-documents.tsx

@@ -0,0 +1,1185 @@
+import { Checkbox, TextInput, themeVars } from '../design-system';
+/**
+ * Story DOCUMENTS (W2, docs/EDITOR-WORKSPACE-SHELL-TODO.md §4.2 / §9 W2 —
+ * inventory row B9): a selected CSF story opens as a CENTER workspace
+ * document (kind `'story'`, title = the story's export name as authored, §8),
+ * mounted through the SAME Storybook portable-story pipeline the Stories
+ * dock used (`stories/StoryPreviewMount.tsx`'s isolated `react-dom/client`
+ * root — never a child of the editor's own tree), with:
+ *
+ *   - **args → Inspector** (§5 "Storybook args | right Inspector"): a
+ *     story-scoped section registered through the EXISTING
+ *     inspector-section registry, live-editable for primitive args (string/
+ *     number/boolean — the Storybook-controls semantic); edits re-render the
+ *     SAME composed story with override props (portable stories accept
+ *     partial props over their composed args — Storybook's own API, not a
+ *     re-implementation);
+ *   - **addon results → utilities** (§5 "Actions/interactions … story-scoped
+ *     utility tabs"): `Actions` (function-valued args are wrapped with
+ *     logging spies at mount — the actions-addon behavior — and every call
+ *     from the story's own rendered component is logged) and `Interactions`
+ *     (the story's `play()` run results) are registered in the W0
+ *     workspace-utility registry, available only while a story document is
+ *     active. `WorkspaceDock` renders available registrations as movable
+ *     utility panels, defaulting to the bottom edge group.
+ *
+ * §4.2 Play interplay: a story document renders in its OWN isolated preview
+ * root — never the live React world root. During Play the live connector
+ * owns the React root (design-time layers are suspended, `design-time-
+ * layers.ts`); opening/activating a story document must NOT stop Play and
+ * does not pretend the story is mounted on the root — it only drops the T6.3
+ * input gate (`onActivate` writes the store's `'scene'` tab) exactly like
+ * activating any non-Game document. What Stop restores on the root stays
+ * owned by `design-time-layers.ts`'s remembered per-root story selection.
+ *
+ * Per-document runtime state (arg overrides, action log, play results, the
+ * live preview container) lives in a module-scope map in the house
+ * `useSyncExternalStore` shape; dropped on document dispose.
+ */
+
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import type { EditorAction } from '../action-registry';
+import { Button } from '../design-system';
+import { createHmrRegistrationGroup } from '../hmr-registration-group';
+import { registerInspectorSections } from '../inspector-section-registry';
+import type { ComposedProjectStory } from '../stories/compose-project-stories';
+import { mountIsolatedStory, runStoryPlay } from '../stories/StoryPreviewMount';
+import { getProjectStoryModules, subscribeProjectStoryModules } from '../stories/story-registry';
+import {
+  activeWorkspaceDocument,
+  openWorkspaceDocument,
+  type WorkspaceDocumentContentProps,
+} from '../workspace-document-registry';
+import { registerWorkspaceUtility } from '../workspace-utility-registry';
+import { type Resolution, ResolutionPicker } from './ResolutionPicker';
+
+/** One logged action-arg invocation (the actions-addon semantic). */
+export interface StoryActionEntry {
+  readonly name: string;
+  readonly args: readonly unknown[];
+  readonly time: number;
+}
+
+export interface StoryAccessibilityViolation {
+  readonly id: string;
+  readonly impact: string | null;
+  readonly help: string;
+  readonly helpUrl: string;
+  readonly nodes: readonly { readonly html: string; readonly target: readonly string[] }[];
+}
+
+export interface StoryDocumentState {
+  readonly modulePath: string;
+  readonly storyName: string;
+  readonly mode: 'preview' | 'docs';
+  readonly store: StoryDocumentStore;
+  argOverrides: Record<string, unknown>;
+  actionLog: StoryActionEntry[];
+  playResult: { ran: boolean; error?: string } | null;
+  accessibility:
+    | { status: 'idle' | 'running'; violations: StoryAccessibilityViolation[]; error?: undefined }
+    | { status: 'complete'; violations: StoryAccessibilityViolation[]; error?: undefined }
+    | { status: 'error'; violations: StoryAccessibilityViolation[]; error: string };
+  /** The live isolated preview container (set by the content on mount) —
+   *  what `play()` receives as its `canvasElement` scope. */
+  container: HTMLElement | null;
+  /** True only after the current composed story + loaders have mounted. */
+  previewReady: boolean;
+  /** Invalidates async play/accessibility results across remounts. */
+  previewRevision: number;
+  resolution: Resolution;
+  scale: number;
+}
+
+const _states = new Map<string, StoryDocumentState>();
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function notifyChanged(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to story-document state changes. Returns unsubscribe. */
+export function subscribeStoryDocuments(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function storyDocumentsVersion(): number {
+  return _version;
+}
+
+/** Stable §7.1 identity for one story document. */
+export function storyDocumentId(modulePath: string, storyName: string): string {
+  return `story:${modulePath}#${storyName}`;
+}
+
+/** Stable identity for the Storybook Docs companion document. */
+export function storyDocsDocumentId(modulePath: string, storyName: string): string {
+  return `story-docs:${modulePath}#${storyName}`;
+}
+
+/** The state behind an open story document id, or `undefined`. */
+export function storyDocumentState(id: string): StoryDocumentState | undefined {
+  return _states.get(id);
+}
+
+/** The ACTIVE center document's story state, or `null` when the active
+ *  document isn't a story (utilities/inspector section gate on this). */
+export function activeStoryDocumentState(): (StoryDocumentState & { id: string }) | null {
+  const active = activeWorkspaceDocument();
+  if (!active || active.descriptor.kind !== 'story') return null;
+  const state = _states.get(active.descriptor.id);
+  return state?.mode === 'preview' ? { ...state, id: active.descriptor.id } : null;
+}
+
+/** Set one arg override (Inspector Story Args section) — remounts the story
+ *  against the merged args. `value === undefined` CLEARS the override (the
+ *  `delete`-the-key convention used elsewhere, e.g. `MaterialSection.tsx`'s
+ *  `setField`) rather than storing `undefined`/`NaN` — the composed-args
+ *  spread merge (`composedStoryArgs`/`activeStoryDocumentState` callers) only
+ *  falls back to the authored value when the key is ABSENT, so a stored
+ *  `NaN` (e.g. from an emptied number input) would otherwise win over the
+ *  authored value and also make the input go from controlled to `NaN`. */
+export function setStoryArgOverride(id: string, key: string, value: unknown): void {
+  const state = _states.get(id);
+  if (!state) return;
+  if (value === undefined) {
+    const next = { ...state.argOverrides };
+    delete next[key];
+    state.argOverrides = next;
+  } else {
+    state.argOverrides = { ...state.argOverrides, [key]: value };
+  }
+  notifyChanged();
+}
+
+function logStoryAction(id: string, name: string, args: readonly unknown[]): void {
+  const state = _states.get(id);
+  if (!state) return;
+  state.actionLog = [...state.actionLog, { name, args, time: Date.now() }].slice(-200);
+  notifyChanged();
+}
+
+/** Clear the action log (Actions utility affordance). */
+export function clearStoryActionLog(id: string): void {
+  const state = _states.get(id);
+  if (!state || state.actionLog.length === 0) return;
+  state.actionLog = [];
+  notifyChanged();
+}
+
+/** The narrow store surface story documents need (T6.3 gate hand-off —
+ *  same contract as `asset-documents.tsx`). */
+export interface StoryDocumentStore {
+  setActiveViewportTab(tab: 'scene' | 'game'): void;
+}
+
+/**
+ * Open (or activate) the center document for one named story. §4.2: this
+ * never touches the play session — during Play it only opens a tab; the
+ * live connector keeps owning the React root.
+ */
+export function openStoryDocument(
+  store: StoryDocumentStore,
+  modulePath: string,
+  storyName: string,
+): string {
+  ensureStoryContributionsRegistered();
+  const id = storyDocumentId(modulePath, storyName);
+  if (!_states.has(id)) {
+    _states.set(id, {
+      modulePath,
+      storyName,
+      mode: 'preview',
+      store,
+      argOverrides: {},
+      actionLog: [],
+      playResult: null,
+      accessibility: { status: 'idle', violations: [] },
+      container: null,
+      previewReady: false,
+      previewRevision: 0,
+      resolution: { label: 'Fill', width: null, height: null },
+      scale: 1,
+    });
+    notifyChanged();
+  }
+  return openWorkspaceDocument({
+    id,
+    // §8 — the story's export name exactly as authored in the CSF module
+    // (`Default`, `Playing`), never a humanized/uppercased variant.
+    title: storyName,
+    kind: 'story',
+    provenance: { sourcePath: modulePath },
+    Content: StoryDocumentContent,
+    Toolbar: StoryDocumentToolbar,
+    closeable: true,
+    onActivate: () => store.setActiveViewportTab('scene'),
+    onDispose: (documentId) => {
+      if (_states.delete(documentId)) notifyChanged();
+    },
+  });
+}
+
+/** Open the composed story's Storybook Docs companion as a center document. */
+export function openStoryDocsDocument(
+  store: StoryDocumentStore,
+  modulePath: string,
+  storyName: string,
+): string {
+  const id = storyDocsDocumentId(modulePath, storyName);
+  if (!_states.has(id)) {
+    _states.set(id, {
+      modulePath,
+      storyName,
+      mode: 'docs',
+      store,
+      argOverrides: {},
+      actionLog: [],
+      playResult: null,
+      accessibility: { status: 'idle', violations: [] },
+      container: null,
+      previewReady: false,
+      previewRevision: 0,
+      resolution: { label: 'Fill', width: null, height: null },
+      scale: 1,
+    });
+    notifyChanged();
+  }
+  return openWorkspaceDocument({
+    id,
+    title: `${storyName} — Docs`,
+    kind: 'story',
+    provenance: { sourcePath: modulePath },
+    Content: StoryDocsDocumentContent,
+    closeable: true,
+    onActivate: () => store.setActiveViewportTab('scene'),
+    onDispose: (documentId) => {
+      if (_states.delete(documentId)) notifyChanged();
+    },
+  });
+}
+
+/**
+ * Open a story document from a hierarchy story ROW (§4.2 "story rows live
+ * beneath their React root"): resolves a composed story id
+ * (`ReactWorldAuthoringAdapter`'s portable-story node ids ARE Storybook's
+ * composed ids) back to its module + export through the live story registry.
+ * Returns `false` when no discovered portable story carries that id — the
+ * caller keeps its existing behavior (no fabricated documents).
+ */
+export function openStoryDocumentByStoryId(store: StoryDocumentStore, storyId: string): boolean {
+  for (const module_ of getProjectStoryModules()) {
+    if (!module_.ok) continue;
+    for (const story of module_.stories) {
+      if (story.id === storyId) {
+        openStoryDocument(store, module_.modulePath, story.name);
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/** Command-palette discovery for every valid CSF story, including modules
+ * that are not associated with a mounted React root. React-associated stories
+ * also remain available contextually through Hierarchy and Inspector. */
+export function buildStoryActions(store: StoryDocumentStore): EditorAction[] {
+  const actions: EditorAction[] = [];
+  for (const module_ of getProjectStoryModules()) {
+    if (!module_.ok) continue;
+    const moduleName = module_.modulePath.split('/').pop() ?? module_.modulePath;
+    for (const story of module_.stories) {
+      actions.push({
+        id: `story:${storyDocumentId(module_.modulePath, story.name)}`,
+        label: `Open Story: ${story.name} — ${moduleName}`,
+        category: 'action',
+        execute: () => void openStoryDocument(store, module_.modulePath, story.name),
+      });
+    }
+  }
+  return actions;
+}
+
+/** Test-only reset — drops all story-document state (pair with the document
+ *  registry's own reset). */
+export function __resetStoryDocumentsForTest(): void {
+  _states.clear();
+  notifyChanged();
+}
+
+// --- Story resolution against the live registry ---------------------------
+
+function findComposedStory(
+  modulePath: string,
+  storyName: string,
+): { story: ComposedProjectStory | undefined; moduleError: string | undefined } {
+  const module_ = getProjectStoryModules().find((m) => m.modulePath === modulePath);
+  if (!module_) return { story: undefined, moduleError: undefined };
+  if (!module_.ok) return { story: undefined, moduleError: module_.error };
+  return { story: module_.stories.find((s) => s.name === storyName), moduleError: undefined };
+}
+
+/** A composed story's own args (Storybook attaches them to the portable
+ *  component). Defensive read — `{}` when absent. */
+export function composedStoryArgs(story: ComposedProjectStory): Record<string, unknown> {
+  const args = (story.Component as unknown as Record<string, unknown>)['args'];
+  return args && typeof args === 'object' ? (args as Record<string, unknown>) : {};
+}
+
+/** Merge order: composed args ← wrapped action spies ← user overrides. The
+ *  spies re-wrap the ORIGINAL function so authored handlers still run. */
+function buildOverrideProps(id: string, story: ComposedProjectStory): Record<string, unknown> {
+  const state = _states.get(id);
+  const overrides: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(composedStoryArgs(story))) {
+    if (typeof value === 'function') {
+      overrides[key] = (...callArgs: unknown[]) => {
+        logStoryAction(id, key, callArgs);
+        return (value as (...a: unknown[]) => unknown)(...callArgs);
+      };
+    }
+  }
+  return { ...overrides, ...(state?.argOverrides ?? {}) };
+}
+
+// --- Document content + toolbar -------------------------------------------
+
+function StoryDocumentContent({ documentId }: WorkspaceDocumentContentProps) {
+  useSyncExternalStore(subscribeStoryDocuments, storyDocumentsVersion);
+  // Re-resolve the composed story on every registry refresh (project change,
+  // `story-files-changed` SSE) — same live-rescan physics as the Stories dock.
+  useSyncExternalStore(subscribeProjectStoryModules, () => getProjectStoryModules());
+  const state = _states.get(documentId);
+  const outerRef = useRef<HTMLDivElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [containerSize, setContainerSize] = useState({ width: 0, height: 0 });
+  const { story, moduleError } = state
+    ? findComposedStory(state.modulePath, state.storyName)
+    : { story: undefined, moduleError: undefined };
+  // Arg-override identity for the remount effect below.
+  const overridesKey = state ? JSON.stringify(state.argOverrides) : '';
+
+  useEffect(() => {
+    const element = outerRef.current;
+    if (!element) return;
+    if (typeof ResizeObserver === 'undefined') {
+      setContainerSize({ width: element.clientWidth, height: element.clientHeight });
+      return;
+    }
+    const observer = new ResizeObserver(([entry]) => {
+      if (!entry) return;
+      setContainerSize({ width: entry.contentRect.width, height: entry.contentRect.height });
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container || !state) return;
+    if (state.container !== container) {
+      state.container = container; // play()'s canvasElement scope
+      notifyChanged();
+    }
+    const previewRevision = state.previewRevision + 1;
+    state.previewRevision = previewRevision;
+    state.previewReady = false;
+    state.playResult = null;
+    state.accessibility = { status: 'idle', violations: [] };
+    notifyChanged();
+    if (!story) {
+      setLoading(false);
+      return;
+    }
+    let cancelled = false;
+    let unmountFn: (() => void) | undefined;
+    setLoading(true);
+    void mountIsolatedStory(
+      container,
+      state.modulePath,
+      state.storyName,
+      story.Component,
+      buildOverrideProps(documentId, story),
+    ).then((result) => {
+      if (cancelled) {
+        result?.unmount();
+        return;
+      }
+      if (!result) {
+        if (_states.get(documentId)?.previewRevision === previewRevision) setLoading(false);
+        return;
+      }
+      const current = _states.get(documentId);
+      if (!current || current.previewRevision !== previewRevision) {
+        result.unmount();
+        return;
+      }
+      unmountFn = result.unmount;
+      current.previewReady = true;
+      setLoading(false);
+      notifyChanged();
+    });
+    return () => {
+      cancelled = true;
+      unmountFn?.();
+    };
+    // `story.Component` identity changes on registry refresh; overridesKey on
+    // arg edits — both remount, which is exactly the wanted behavior.
+  }, [documentId, state, story, overridesKey]);
+
+  const isFill = state?.resolution.width === null;
+  const scale =
+    !state || isFill
+      ? 1
+      : Math.min(
+          containerSize.width / state.resolution.width!,
+          containerSize.height / state.resolution.height!,
+          1,
+        );
+  useEffect(() => {
+    if (!state || !Number.isFinite(scale) || scale <= 0 || state.scale === scale) return;
+    state.scale = scale;
+    notifyChanged();
+  }, [scale, state]);
+
+  if (!state) {
+    return (
+      <div
+        style={{ padding: 12, fontSize: 12, color: themeVars.content.muted, pointerEvents: 'auto' }}
+      >
+        This story document is no longer available.
+      </div>
+    );
+  }
+
+  return (
+    <div
+      style={{
+        flex: 1,
+        minHeight: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        pointerEvents: 'auto',
+        background: themeVars.surface.panel,
+      }}
+    >
+      {!story && (
+        <div
+          data-testid="story-document-missing"
+          style={{ padding: 12, fontSize: 12, color: themeVars.semantic.danger, maxWidth: 560 }}
+        >
+          <div style={{ fontWeight: 600, marginBottom: 4 }}>
+            {state.modulePath} — no story export named <code>{state.storyName}</code>
+          </div>
+          <div style={{ color: themeVars.content.muted, whiteSpace: 'pre-wrap' }}>
+            {moduleError ?? 'It may have been renamed or removed; close this document.'}
+          </div>
+        </div>
+      )}
+      {loading && (
+        <div
+          data-testid="story-loading"
+          style={{
+            padding: '4px 10px',
+            fontSize: 10,
+            color: themeVars.content.muted,
+            fontStyle: 'italic',
+          }}
+        >
+          loading…
+        </div>
+      )}
+      <div
+        ref={outerRef}
+        style={{
+          position: 'relative',
+          flex: 1,
+          minHeight: 0,
+          overflow: 'auto',
+          background: themeVars.surface.inset,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+      >
+        <div
+          style={
+            isFill
+              ? { position: 'absolute', inset: 0 }
+              : {
+                  position: 'relative',
+                  width: state.resolution.width! * scale,
+                  height: state.resolution.height! * scale,
+                  flex: '0 0 auto',
+                }
+          }
+        >
+          <div
+            data-testid="story-preview-root"
+            ref={containerRef}
+            // A story owns the whole selected device canvas. Containment
+            // keeps fixed/full-page UI inside that canvas, never over editor
+            // chrome.
+            style={{
+              position: 'absolute',
+              inset: 0,
+              isolation: 'isolate',
+              contain: 'layout paint',
+              overflow: 'auto',
+              background: themeVars.surface.inset,
+              ...(isFill
+                ? {}
+                : {
+                    width: state.resolution.width!,
+                    height: state.resolution.height!,
+                    transform: `scale(${scale})`,
+                    transformOrigin: 'top left',
+                  }),
+            }}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function docsDescription(story: ComposedProjectStory): { component?: string; story?: string } {
+  const docs = story.parameters['docs'];
+  if (!docs || typeof docs !== 'object') return {};
+  const description = (docs as Record<string, unknown>)['description'];
+  if (typeof description === 'string') return { story: description };
+  if (!description || typeof description !== 'object') return {};
+  const record = description as Record<string, unknown>;
+  return {
+    ...(typeof record['component'] === 'string' ? { component: record['component'] } : {}),
+    ...(typeof record['story'] === 'string' ? { story: record['story'] } : {}),
+  };
+}
+
+/** Storybook Docs companion: composed CSF metadata, canvas, and args table. */
+export function StoryDocsDocumentContent({ documentId }: WorkspaceDocumentContentProps) {
+  useSyncExternalStore(subscribeStoryDocuments, storyDocumentsVersion);
+  useSyncExternalStore(subscribeProjectStoryModules, () => getProjectStoryModules());
+  const state = _states.get(documentId);
+  const previewRef = useRef<HTMLDivElement | null>(null);
+  const { story, moduleError } = state
+    ? findComposedStory(state.modulePath, state.storyName)
+    : { story: undefined, moduleError: undefined };
+  useEffect(() => {
+    const container = previewRef.current;
+    if (!container || !state || !story) return;
+    let disposed = false;
+    let unmount: (() => void) | null = null;
+    void mountIsolatedStory(container, state.modulePath, state.storyName, story.Component).then(
+      (result) => {
+        if (!result) return;
+        if (disposed) result.unmount();
+        else unmount = result.unmount;
+      },
+    );
+    return () => {
+      disposed = true;
+      unmount?.();
+    };
+  }, [state, story]);
+
+  if (!state || !story) {
+    return (
+      <div style={{ padding: 16, color: themeVars.semantic.danger, fontSize: 12 }}>
+        {moduleError ?? 'This Storybook Docs document is no longer available.'}
+      </div>
+    );
+  }
+  const description = docsDescription(story);
+  const args = story.args;
+  return (
+    <article
+      data-testid="story-docs-document"
+      style={{
+        flex: 1,
+        minHeight: 0,
+        overflow: 'auto',
+        pointerEvents: 'auto',
+        background: themeVars.surface.panel,
+        padding: '24px clamp(18px, 5vw, 64px)',
+      }}
+    >
+      <div
+        style={{
+          maxWidth: 920,
+          margin: '0 auto',
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 22,
+        }}
+      >
+        <header>
+          <div style={{ color: themeVars.content.dim, fontSize: 11, marginBottom: 5 }}>
+            {story.title ?? state.modulePath}
+          </div>
+          <h1 style={{ color: themeVars.content.primary, fontSize: 24, margin: 0 }}>
+            {story.label}
+          </h1>
+          {(description.story ?? description.component) && (
+            <p
+              style={{
+                color: themeVars.content.primary,
+                lineHeight: 1.6,
+                maxWidth: 760,
+                whiteSpace: 'pre-wrap',
+              }}
+            >
+              {description.story ?? description.component}
+            </p>
+          )}
+        </header>
+        <section>
+          <h2 style={{ color: themeVars.content.primary, fontSize: 14 }}>Canvas</h2>
+          <div
+            ref={previewRef}
+            data-testid="story-docs-canvas"
+            style={{
+              position: 'relative',
+              isolation: 'isolate',
+              contain: 'layout paint',
+              minHeight: 180,
+              padding: 18,
+              overflow: 'auto',
+              background: themeVars.surface.inset,
+              border: `1px solid ${themeVars.boundary.default}`,
+              borderRadius: themeVars.shape.medium,
+            }}
+          />
+        </section>
+        <section>
+          <h2 style={{ color: themeVars.content.primary, fontSize: 14 }}>Args</h2>
+          <div
+            style={{
+              border: `1px solid ${themeVars.boundary.default}`,
+              borderRadius: themeVars.shape.medium,
+              overflow: 'hidden',
+            }}
+          >
+            {Object.entries(args).map(([name, value]) => (
+              <div
+                key={name}
+                style={{
+                  display: 'grid',
+                  gridTemplateColumns: 'minmax(120px, .4fr) minmax(140px, .6fr) 1fr',
+                  gap: 12,
+                  padding: '8px 10px',
+                  borderBottom: `1px solid ${themeVars.boundary.default}`,
+                  fontSize: 11,
+                }}
+              >
+                <code style={{ color: themeVars.accent.default }}>{name}</code>
+                <span style={{ color: themeVars.content.muted }}>
+                  {Array.isArray(value) ? 'array' : typeof value}
+                </span>
+                <code
+                  style={{
+                    color: themeVars.content.primary,
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                  }}
+                >
+                  {typeof value === 'function' ? 'function' : JSON.stringify(value)}
+                </code>
+              </div>
+            ))}
+            {Object.keys(args).length === 0 && (
+              <div style={{ padding: 10, color: themeVars.content.dim, fontSize: 11 }}>
+                This story declares no args.
+              </div>
+            )}
+          </div>
+        </section>
+        <footer style={{ color: themeVars.content.dim, fontSize: 10 }}>
+          {state.modulePath} · {state.storyName}
+        </footer>
+      </div>
+    </article>
+  );
+}
+
+/** Document-local toolbar (§7.1 contribution): source module + Run play(). */
+function StoryDocumentToolbar({ documentId }: WorkspaceDocumentContentProps) {
+  useSyncExternalStore(subscribeStoryDocuments, storyDocumentsVersion);
+  useSyncExternalStore(subscribeProjectStoryModules, () => getProjectStoryModules());
+  const state = _states.get(documentId);
+  if (!state) return null;
+  const { story } = findComposedStory(state.modulePath, state.storyName);
+  const hasPlay = typeof story?.Component.play === 'function';
+  const result = state.playResult;
+  return (
+    <div
+      data-testid="story-document-toolbar"
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 8,
+        padding: '3px 10px',
+        fontSize: 10,
+        color: themeVars.content.muted,
+        borderBottom: `1px solid ${themeVars.boundary.default}`,
+      }}
+    >
+      <span style={{ flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis' }}>
+        {state.modulePath} —{' '}
+        <code style={{ color: themeVars.accent.default }}>{state.storyName}</code>
+      </span>
+      <ResolutionPicker
+        resolution={state.resolution}
+        scale={state.scale}
+        onResolutionChange={(resolution) => {
+          state.resolution = resolution;
+          notifyChanged();
+        }}
+      />
+      <Button
+        size="compact"
+        data-testid="story-open-docs"
+        onClick={() => openStoryDocsDocument(state.store, state.modulePath, state.storyName)}
+        style={{ flexShrink: 0 }}
+      >
+        Docs
+      </Button>
+      {hasPlay && story && (
+        <Button
+          variant="outline"
+          size="compact"
+          data-testid="story-run-play"
+          onClick={async () => {
+            if (!state.container || !state.previewReady) return;
+            const previewRevision = state.previewRevision;
+            const playResult = await runStoryPlay(
+              state.modulePath,
+              state.storyName,
+              story.Component,
+              state.container,
+            );
+            const current = _states.get(documentId);
+            if (current?.previewReady && current.previewRevision === previewRevision) {
+              current.playResult = playResult;
+              notifyChanged();
+            }
+          }}
+          disabled={!state.previewReady}
+          style={{ flexShrink: 0 }}
+        >
+          Run play()
+        </Button>
+      )}
+      {result?.ran && !result.error && (
+        <span
+          data-testid="story-play-result"
+          style={{ color: themeVars.semantic.success, fontWeight: 600 }}
+        >
+          play() ran
+        </span>
+      )}
+      {result?.error && (
+        <span data-testid="story-play-result" style={{ color: themeVars.semantic.danger }}>
+          {result.error}
+        </span>
+      )}
+    </div>
+  );
+}
+
+// --- Inspector "Story Args" section (§5: Storybook args → right Inspector) -
+
+function ArgRow({ id, name, value }: { id: string; name: string; value: unknown }) {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 6, padding: '3px 0' }}>
+      <span
+        style={{
+          width: 90,
+          flexShrink: 0,
+          fontSize: 11,
+          color: themeVars.content.muted,
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+        }}
+        title={name}
+      >
+        {name}
+      </span>
+      {typeof value === 'boolean' ? (
+        <Checkbox
+          className="vgai-checkbox"
+          data-testid={`story-arg-${name}`}
+          checked={value}
+          onChange={(e) => setStoryArgOverride(id, name, e.target.checked)}
+        />
+      ) : typeof value === 'number' ? (
+        <TextInput
+          type="number"
+          className="vgai-input"
+          data-testid={`story-arg-${name}`}
+          value={value}
+          onChange={(e) => {
+            // Empty/unparseable input clears the override (falls back to the
+            // authored arg) instead of setting NaN — `Number.parseFloat('')`
+            // is NaN, and storing NaN would both win over the authored value
+            // in the composed-args merge (see `setStoryArgOverride`'s doc
+            // comment) and make this a controlled input whose displayed
+            // `value` is `NaN`, which React warns about.
+            const raw = e.target.value;
+            const parsed = Number.parseFloat(raw);
+            setStoryArgOverride(id, name, raw === '' || Number.isNaN(parsed) ? undefined : parsed);
+          }}
+          style={{ width: 80 }}
+        />
+      ) : typeof value === 'string' ? (
+        <TextInput
+          type="text"
+          className="vgai-input"
+          data-testid={`story-arg-${name}`}
+          value={value}
+          onChange={(e) => setStoryArgOverride(id, name, e.target.value)}
+          style={{ flex: 1, minWidth: 0 }}
+        />
+      ) : (
+        <span
+          style={{ fontSize: 11, color: themeVars.content.dim }}
+          data-testid={`story-arg-${name}`}
+        >
+          {typeof value === 'function' ? 'fn (logged to Actions)' : JSON.stringify(value)}
+        </span>
+      )}
+    </div>
+  );
+}
+
+/** Registered section: renders while the ACTIVE center document is a story —
+ *  the args of THAT story (composed args merged with live overrides). */
+export function StoryArgsSection() {
+  useSyncExternalStore(subscribeStoryDocuments, storyDocumentsVersion);
+  useSyncExternalStore(subscribeProjectStoryModules, () => getProjectStoryModules());
+  const active = activeStoryDocumentState();
+  if (!active) return null;
+  const { story } = findComposedStory(active.modulePath, active.storyName);
+  const args = story ? { ...composedStoryArgs(story), ...active.argOverrides } : {};
+  const names = Object.keys(args);
+  return (
+    <div
+      data-testid="inspector-story-args"
+      style={{
+        pointerEvents: 'auto',
+        padding: 8,
+        borderBottom: `1px solid ${themeVars.boundary.default}`,
+      }}
+    >
+      <div
+        style={{
+          fontSize: 11,
+          color: themeVars.content.dim,
+          textTransform: 'uppercase',
+          marginBottom: 4,
+        }}
+      >
+        Story Args
+      </div>
+      <div
+        style={{ fontSize: 11, color: themeVars.content.primary, fontWeight: 600, marginBottom: 4 }}
+      >
+        {active.storyName}
+      </div>
+      {names.length === 0 && (
+        <div style={{ fontSize: 11, color: themeVars.content.dim }}>
+          {story ? 'This story declares no args.' : 'Story source unavailable.'}
+        </div>
+      )}
+      {names.map((name) => (
+        <ArgRow key={name} id={active.id} name={name} value={args[name]} />
+      ))}
+    </div>
+  );
+}
+
+// --- Utilities: Actions + Interactions (§5 story-scoped utility tabs) ------
+
+/** Actions utility content: the wrapped-arg call log of the active story. */
+export function StoryActionsUtility() {
+  useSyncExternalStore(subscribeStoryDocuments, storyDocumentsVersion);
+  const active = activeStoryDocumentState();
+  if (!active) {
+    return (
+      <div style={{ padding: 12, fontSize: 12, color: themeVars.content.dim }}>
+        No active story.
+      </div>
+    );
+  }
+  return (
+    <div
+      data-testid="story-actions-utility"
+      style={{ flex: 1, minHeight: 0, overflowY: 'auto', padding: 8, fontSize: 11 }}
+    >
+      <Button
+        size="compact"
+        style={{ marginBottom: 6 }}
+        onClick={() => clearStoryActionLog(active.id)}
+      >
+        Clear
+      </Button>
+      {active.actionLog.length === 0 ? (
+        <div style={{ color: themeVars.content.dim }}>
+          No actions logged — function-valued args are wrapped with logging spies; interact with the
+          story preview to see calls here.
+        </div>
+      ) : (
+        active.actionLog.map((entry, i) => (
+          <div
+            key={i}
+            style={{ padding: '2px 0', borderBottom: `1px solid ${themeVars.boundary.default}` }}
+          >
+            <code style={{ color: themeVars.accent.default }}>{entry.name}</code>{' '}
+            <span style={{ color: themeVars.content.muted }}>
+              (
+              {entry.args
+                .map((a) => {
+                  try {
+                    return typeof a === 'object' ? JSON.stringify(a)?.slice(0, 80) : String(a);
+                  } catch {
+                    return String(a);
+                  }
+                })
+                .join(', ')}
+              )
+            </span>
+          </div>
+        ))
+      )}
+    </div>
+  );
+}
+
+/** Interactions utility content: the active story's play() run results. */
+export function StoryInteractionsUtility() {
+  useSyncExternalStore(subscribeStoryDocuments, storyDocumentsVersion);
+  const active = activeStoryDocumentState();
+  if (!active) {
+    return (
+      <div style={{ padding: 12, fontSize: 12, color: themeVars.content.dim }}>
+        No active story.
+      </div>
+    );
+  }
+  const result = active.playResult;
+  return (
+    <div
+      data-testid="story-interactions-utility"
+      style={{ flex: 1, minHeight: 0, overflowY: 'auto', padding: 12, fontSize: 12 }}
+    >
+      {!result && (
+        <div style={{ color: themeVars.content.dim }}>
+          No interaction run yet — use the story document's “Run play()”.
+        </div>
+      )}
+      {result && !result.ran && (
+        <div style={{ color: themeVars.content.dim }}>This story declares no play() function.</div>
+      )}
+      {result?.ran && !result.error && (
+        <div style={{ color: themeVars.semantic.success, fontWeight: 600 }}>
+          play() ran without errors.
+        </div>
+      )}
+      {result?.error && (
+        <div style={{ color: themeVars.semantic.danger, whiteSpace: 'pre-wrap' }}>
+          {result.error}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** Run axe-core against the active story's isolated preview root. */
+export async function runStoryAccessibility(id: string): Promise<void> {
+  const state = _states.get(id);
+  if (!state?.container || !state.previewReady) return;
+  const container = state.container;
+  const previewRevision = state.previewRevision;
+  state.accessibility = { status: 'running', violations: [] };
+  notifyChanged();
+  try {
+    const axe = (await import('axe-core')).default;
+    const result = await axe.run(container);
+    const current = _states.get(id);
+    if (
+      !current?.previewReady ||
+      current.previewRevision !== previewRevision ||
+      current.container !== container
+    )
+      return;
+    current.accessibility = {
+      status: 'complete',
+      violations: result.violations.map((violation) => ({
+        id: violation.id,
+        impact: violation.impact ?? null,
+        help: violation.help,
+        helpUrl: violation.helpUrl,
+        nodes: violation.nodes.map((node) => ({
+          html: node.html,
+          target: node.target.map(String),
+        })),
+      })),
+    };
+    notifyChanged();
+  } catch (reason) {
+    const current = _states.get(id);
+    if (
+      !current?.previewReady ||
+      current.previewRevision !== previewRevision ||
+      current.container !== container
+    )
+      return;
+    current.accessibility = {
+      status: 'error',
+      violations: [],
+      error: reason instanceof Error ? reason.message : String(reason),
+    };
+    notifyChanged();
+  }
+}
+
+/** Story-scoped accessibility results, powered by the same axe engine Storybook uses. */
+export function StoryAccessibilityUtility() {
+  useSyncExternalStore(subscribeStoryDocuments, storyDocumentsVersion);
+  const active = activeStoryDocumentState();
+  if (!active)
+    return (
+      <div style={{ padding: 12, fontSize: 12, color: themeVars.content.dim }}>
+        No active story.
+      </div>
+    );
+  const result = active.accessibility;
+  return (
+    <div
+      data-testid="story-accessibility-utility"
+      style={{ flex: 1, minHeight: 0, overflowY: 'auto', padding: 10, fontSize: 11 }}
+    >
+      <Button
+        variant="outline"
+        size="compact"
+        disabled={!active.container || !active.previewReady || result.status === 'running'}
+        onClick={() => void runStoryAccessibility(active.id)}
+        style={{ marginBottom: 8 }}
+      >
+        {result.status === 'running' ? 'Checking…' : 'Run accessibility check'}
+      </Button>
+      {result.status === 'idle' && (
+        <div style={{ color: themeVars.content.dim }}>
+          Run axe against the mounted story preview.
+        </div>
+      )}
+      {result.status === 'error' && (
+        <div style={{ color: themeVars.semantic.danger }}>{result.error}</div>
+      )}
+      {result.status === 'complete' && result.violations.length === 0 && (
+        <div style={{ color: themeVars.semantic.success, fontWeight: 600 }}>
+          No accessibility violations found.
+        </div>
+      )}
+      {result.violations.map((violation) => (
+        <details
+          key={violation.id}
+          style={{ borderBottom: `1px solid ${themeVars.boundary.default}`, padding: '6px 0' }}
+        >
+          <summary
+            style={{
+              color:
+                violation.impact === 'critical' || violation.impact === 'serious'
+                  ? themeVars.semantic.danger
+                  : themeVars.content.primary,
+              cursor: 'pointer',
+            }}
+          >
+            {violation.help} · {violation.nodes.length} node
+            {violation.nodes.length === 1 ? '' : 's'}
+          </summary>
+          <a
+            href={violation.helpUrl}
+            target="_blank"
+            rel="noreferrer"
+            style={{ color: themeVars.accent.default, display: 'inline-block', margin: '5px 0' }}
+          >
+            How to fix
+          </a>
+          {violation.nodes.map((node, index) => (
+            <pre
+              key={`${violation.id}:${index}`}
+              style={{
+                color: themeVars.content.muted,
+                fontFamily: 'var(--vgai-font-mono)',
+                fontSize: 10,
+                whiteSpace: 'pre-wrap',
+                overflowWrap: 'anywhere',
+              }}
+            >
+              {node.target.join(' ')}
+              {`\n`}
+              {node.html}
+            </pre>
+          ))}
+        </details>
+      ))}
+    </div>
+  );
+}
+
+const registrationGroup = createHmrRegistrationGroup(import.meta.hot, 'story-contributions');
+
+/**
+ * Idempotent one-time registration of the story-scoped shell contributions:
+ * the Inspector `Story Args` section and the `Actions`/`Interactions`
+ * utilities. Called from `openStoryDocument` (and importable directly) so
+ * merely importing this module in a test doesn't mutate the registries.
+ */
+export function ensureStoryContributionsRegistered(): void {
+  registrationGroup.ensure((track) => {
+    track(
+      registerInspectorSections({
+        match: () => activeWorkspaceDocument()?.descriptor.kind === 'story',
+        Section: StoryArgsSection,
+      }),
+    );
+    const storyActive = () => activeStoryDocumentState() !== null;
+    track(
+      registerWorkspaceUtility({
+        id: 'story-actions',
+        title: 'Actions',
+        Content: StoryActionsUtility,
+        available: storyActive,
+      }),
+    );
+    track(
+      registerWorkspaceUtility({
+        id: 'story-interactions',
+        title: 'Interactions',
+        Content: StoryInteractionsUtility,
+        available: storyActive,
+      }),
+    );
+    track(
+      registerWorkspaceUtility({
+        id: 'story-accessibility',
+        title: 'Accessibility',
+        Content: StoryAccessibilityUtility,
+        available: storyActive,
+      }),
+    );
+  });
+}
+
+/** Test-only: allow re-registration after a registry reset. */
+export function __resetStoryContributionsForTest(): void {
+  registrationGroup.reset();
+}