@volter/editor-ui 0.5.211 → 0.5.212

package/src/react/design-time-react-mount.ts

@@ -0,0 +1,525 @@
+/** Mount project React components and portable stories in the UI board. The mounted root uses the project React instance and the source authoring adapter. */
+
+import { editorHost } from '@volter/sdk/host';
+import type {
+  DesignTimeMountContext,
+  DesignTimeRootDescriptor,
+  LayerMountResult,
+} from '@volter/sdk/authoring/design-time-mount-registry';
+import { rememberedPortableStory, rememberPortableStory } from '../host/portable-stories';
+import { formatMountFailureMessage } from '@volter/sdk/mount-failure-report';
+import type { ReactStoryBoardSelectionIntent } from '@volter/sdk/authoring/react-story-board';
+import { createReactStoryBoard } from '@volter/sdk/authoring/react-story-board';
+import {
+  getRootCanvasViewport,
+  setRootCanvasViewport,
+} from '@volter/sdk/world-canvas-viewport-state';
+import { recordAuthoringConsumerUse } from '@volter/sdk/authoring-seam-evidence';
+import { CrashNullBoundary } from '../host/crash-null-boundary';
+import { readProjectTextFile } from '@volter/sdk/api/project-source';
+import { editorConsole } from '@volter/sdk/editor-console';
+import { resolveReactRootMountRuntime } from '../host/react-mount-runtime';
+import { activeRealmServices } from '../host/realm-services';
+import { resolveReactAdapterRootComponent } from '../host/roots/react-root';
+import { scopedProjectStylesState } from '@volter/sdk/scoped-project-css';
+import { componentIdentityName } from '@volter/sdk/stories/compose-project-stories';
+import { mountIsolatedStory } from '@volter/sdk/stories/StoryPreviewMount';
+import {
+  createStoryPresentationIndex,
+  storyBoardPresentation,
+} from '../host/stories/story-presentation';
+import type { ProjectPreviewStory } from '@volter/sdk/stories/story-types';
+import { subscribeProjectModuleChange } from '@volter/sdk/project-module-changes';
+import { domStoryBoardMembers } from '@volter/editor-threejs/kit/stories/three-story-model';
+import { getDesignTokens } from '@volter/sdk/ui-source/inspect';
+import { tierSourceWriteBackend } from '@volter/sdk/ui-source/tier-source-write-backend';
+import { recordViewportFirstFrame } from '@volter/sdk/viewport-activation-timings';
+import { beginProjectMountEpoch } from '@volter/sdk/project-module-url';
+import type { ComponentType } from 'react';
+import { type OidElementLike, ReactRootAuthoringAdapter } from './react-world-authoring-adapter';
+import { paintedContentBounds } from './story-paint-bounds';
+
+/** Set by the DOM re-projection right before it remounts a
+ *  DOM candidate: the registry just published, so the mount reads it as is. */
+let skipStoryRefreshForRemount = false;
+
+/** Board chrome is also document navigation: apply the story and make its
+ * structural row the store selection so global editor surfaces route back to
+ * this React adapter rather than the previously selected world. */
+function selectPortableStory(adapter: ReactRootAuthoringAdapter | null, storyId: string): void {
+  if (!adapter) return;
+  recordAuthoringConsumerUse({
+    adapter,
+    seam: 'editor.stories.apply',
+    stage: 'effect',
+    detail: `the design board applied portable story ${storyId}`,
+    run: () => adapter.stories.apply(storyId, storyId),
+  });
+  recordAuthoringConsumerUse({
+    adapter,
+    seam: 'editor.selection.set',
+    stage: 'effect',
+    detail: `the design board selected portable story ${storyId}`,
+    run: () => adapter.selection.set([storyId]),
+  });
+}
+
+/**
+ * Seed the session's dom-story mount box from the project's DECLARED
+ * resolution, once — the same rung the story CAPTURE lane reads: the screen a
+ * UI story's anchors resolve against is a manifest declaration, not a magic
+ * "Fill". Seeded only while the session viewport is still untouched, so a
+ * size (or Fill) the user picked afterwards always stands, and a project
+ * declaring nothing keeps Fill.
+ */
+let rootViewportSeeded = false;
+async function seedRootViewportFromManifest(): Promise<void> {
+  if (rootViewportSeeded) return;
+  rootViewportSeeded = true;
+  const current = getRootCanvasViewport();
+  if (current.width !== null || current.height !== null) return;
+  try {
+    const text = await readProjectTextFile('volter.project.json');
+    if (!text) return;
+    const manifest = JSON.parse(text) as {
+      resolution?: { width?: unknown; height?: unknown };
+    };
+    const width = manifest.resolution?.width;
+    const height = manifest.resolution?.height;
+    if (typeof width !== 'number' || typeof height !== 'number') return;
+    if (width < 64 || height < 64 || width > 4096 || height > 4096) return;
+    setRootCanvasViewport(width, height);
+  } catch {
+    // An unreadable manifest declares nothing; Fill stands.
+  }
+}
+type EntryResolution = { ok: true; Entry: ComponentType } | { ok: false; error: unknown };
+
+/**
+ * Load a React root's entry component ONCE per layer mount, without throwing.
+ * Both of this layer's paths need it: the derived default story is joined
+ * against this component's identity, and the no-story fallback renders it.
+ * A failure is carried rather than thrown so the story board can still open
+ * over a project whose entry is broken; only the fallback (which has nothing
+ * else to render) rethrows it.
+ */
+async function resolveEntryComponent(
+  world: Parameters<typeof resolveReactAdapterRootComponent>[0],
+  projectRoot: string,
+): Promise<EntryResolution> {
+  try {
+    // Design-time preview layer: its own mount, therefore its own epoch —
+    // and therefore its own realm value over that epoch.
+    const realm = await activeRealmServices(projectRoot, beginProjectMountEpoch());
+    const Entry = await resolveReactAdapterRootComponent(world, realm);
+    return { ok: true, Entry };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+/** Mount portable stories as board frames, or the entry component when no
+ * story is assigned. flushSync commits the fallback before its source adapter
+ * adopts the DOM. The adapter observes mounted elements and never mounts them. */
+export async function mountReactDesignLayer(
+  candidate: DesignTimeRootDescriptor,
+  layer: HTMLElement,
+  context: DesignTimeMountContext,
+): Promise<LayerMountResult> {
+  const { projectRootPath: projectRoot, store, activationDocumentId } = context;
+  // Discover the project-wide story gallery before requiring an entry.
+  // Rootless UI boards use stories alone; Play mounts the manifest entry.
+  // Registry-driven remounts already have fresh story modules.
+  if (skipStoryRefreshForRemount) skipStoryRefreshForRemount = false;
+  else await editorHost().stories.refresh({ rootPath: projectRoot });
+  // …every story DECLARED as DOM. The registry is project-global and
+  // deliberately unfiltered, so THIS board filters its own membership the
+  // way the `3D` board filters its own — otherwise a
+  // three story is handed to `react-dom`, which renders `<group>`/`<primitive>`
+  // as unknown tags into an empty frame.
+  const previewStories = editorHost().stories.previewStories();
+  const portableStories = domStoryBoardMembers(previewStories);
+
+  // Join the entry to its default story by component name and source directory.
+  // Story imports and entry imports use different cache-busted URLs, so their
+  // component objects need not share identity.
+  const entryPath = candidate.path;
+  const entry: EntryResolution = entryPath
+    ? await resolveEntryComponent(
+        { id: candidate.worldId, entry: entryPath },
+        projectRoot,
+      )
+    : {
+        ok: false,
+        error: new Error(
+          `design-time react layer "${candidate.worldId}": no \`entry\` declared — nothing to mount.`,
+        ),
+      };
+  const entryComponentName = entry.ok ? componentIdentityName(entry.Entry) : undefined;
+  const derivedDefaultPortableStory = entryComponentName
+    ? editorHost().stories.componentPreviewStory(entryComponentName, candidate.path)
+    : null;
+  const defaultPortableStory =
+    portableStories.find((story) => story.id === derivedDefaultPortableStory?.id) ?? null;
+  // The board exists because the PROJECT has stories, never because the
+  // derivation matched: an entry that fails to import, or a project whose
+  // stories name other components, still gets its whole gallery (the entry
+  // is only what picks the INITIAL frame). Without this the derivation would
+  // silently gate the entire design surface — a broken entry would take every
+  // story down with it.
+  if (portableStories.length > 0) {
+    const rememberedStoryId = rememberedPortableStory(projectRoot, candidate.worldId);
+    // Prefer the remembered choice, then the derived default, then discovery order.
+    const initialPortableStory =
+      portableStories.find((story) => story.id === rememberedStoryId) ??
+      defaultPortableStory ??
+      portableStories[0]!;
+    // A rootless board has no entry component and opens on its first story.
+    if (candidate.path && !defaultPortableStory) {
+      editorConsole.warn(
+        `[design-time-layers] React root "${candidate.worldId}" has no story naming its entry ` +
+          `component${entryComponentName ? ` "${entryComponentName}"` : ''} — the board opens on ` +
+          `"${initialPortableStory.label}". Give a *.stories.tsx a \`meta.component\` of this ` +
+          "root's entry component to choose its default preview.",
+        'authoring',
+      );
+    }
+    let disposed = false;
+    let adapter: ReactRootAuthoringAdapter | null = null;
+    // A story apply can originate from either hierarchy navigation or board
+    // interaction. Hierarchy has no pending board intent and therefore
+    // recenters; board clicks explicitly choose highlight-only or zoom.
+    let pendingBoardSelectionIntent: ReactStoryBoardSelectionIntent | null = null;
+    const mountedByStory = new Map<
+      string,
+      NonNullable<Awaited<ReturnType<typeof mountIsolatedStory>>>
+    >();
+    const storyPresentationIndex = createStoryPresentationIndex(portableStories);
+    await seedRootViewportFromManifest();
+    const board = createReactStoryBoard(
+      layer,
+      portableStories.map((story) => ({
+        id: story.id,
+        label: story.label,
+        modulePath: story.modulePath,
+        ...(story.title ? { title: story.title } : {}),
+        parameters: story.parameters,
+        ...(story.globals ? { globals: story.globals } : {}),
+        ...(story.viewportLocked !== undefined ? { viewportLocked: story.viewportLocked } : {}),
+      })),
+      initialPortableStory.id,
+      (storyId, intent) => {
+        pendingBoardSelectionIntent = intent;
+        selectPortableStory(adapter, storyId);
+      },
+      // The board never reaches for the CSF implementation itself
+      // (`@volter/sdk/authoring/story-board-presentation`): this lane hands it
+      // one, reusing the index the React adapter is also constructed against.
+      storyBoardPresentation(storyPresentationIndex),
+    );
+
+    /** Frame the painted subject unless the story requests fullscreen or fills
+     * its viewport. Measure after commit and again after lazy content can settle. */
+    const measureContent = (story: ProjectPreviewStory): void => {
+      if (disposed) return;
+      const frame = board.frames.get(story.id);
+      if (!frame) return;
+      const layout = (story.parameters as { layout?: unknown } | undefined)?.layout;
+      if (layout === 'fullscreen') {
+        board.setMeasuredFrame(story.id, null);
+        return;
+      }
+      const mount = { width: frame.content.offsetWidth, height: frame.content.offsetHeight };
+      const bounds = mount.width > 0 ? paintedContentBounds(frame.content) : null;
+      if (!bounds) {
+        board.setMeasuredFrame(story.id, null);
+        return;
+      }
+      const PAD = 8;
+      const MIN = 48;
+      let x0 = Math.max(0, bounds.x - PAD);
+      let y0 = Math.max(0, bounds.y - PAD);
+      let x1 = Math.min(mount.width, bounds.x + bounds.width + PAD);
+      let y1 = Math.min(mount.height, bounds.y + bounds.height + PAD);
+      if (x1 - x0 < MIN) {
+        const grow = (MIN - (x1 - x0)) / 2;
+        x0 = Math.max(0, x0 - grow);
+        x1 = Math.min(mount.width, x0 + MIN);
+      }
+      if (y1 - y0 < MIN) {
+        const grow = (MIN - (y1 - y0)) / 2;
+        y0 = Math.max(0, y0 - grow);
+        y1 = Math.min(mount.height, y0 + MIN);
+      }
+      if (x1 - x0 >= mount.width * 0.9 && y1 - y0 >= mount.height * 0.9) {
+        board.setMeasuredFrame(story.id, null);
+        return;
+      }
+      board.setMeasuredFrame(story.id, {
+        frame: { width: Math.round(x1 - x0), height: Math.round(y1 - y0) },
+        mount,
+        offset: { x: Math.round(x0), y: Math.round(y0) },
+      });
+    };
+    const scheduleContentMeasure = (story: ProjectPreviewStory): void => {
+      setTimeout(() => measureContent(story), 0);
+      setTimeout(() => measureContent(story), 1_000);
+    };
+
+    const mountPortable = async (
+      story: ProjectPreviewStory,
+      args: Record<string, unknown> = story.args,
+    ): Promise<void> => {
+      const content = board.frames.get(story.id)?.content;
+      if (!content) return;
+      try {
+        const next = await mountIsolatedStory(
+          content,
+          story.modulePath,
+          story.name,
+          story.Component,
+          args,
+        );
+        // A newer args update may claim this story's frame while its loader is
+        // still in flight. The portable mount reports that supersession as
+        // null; keep the newer handle intact.
+        if (!next) return;
+        if (disposed) {
+          next.unmount();
+          return;
+        }
+        mountedByStory.set(story.id, next);
+        board.clearError(story.id);
+        scheduleContentMeasure(story);
+      } catch (error) {
+        const message = formatMountFailureMessage(error);
+        board.setError(story.id, message);
+        editorConsole.error(
+          `[design-time-layers] React root "${candidate.worldId}" failed mounting portable ` +
+            `story "${story.name}": ${message}`,
+          'authoring',
+        );
+      }
+      store.notifyIngestEdit();
+    };
+
+    // Each story owns its own React root and failure boundary. One broken
+    // loader therefore marks only its frame instead of blanking the board.
+    await Promise.all(portableStories.map((story) => mountPortable(story)));
+    // …and the board says so when the project's game CSS could not be applied.
+    // `mountIsolatedStory` has already resolved that state by now (it awaits
+    // the same per-project install before its first render), so this reads it
+    // rather than racing it. A first-party project reports nothing: `note` is
+    // non-null only where the host has EVIDENCE of missing page-level styling
+    // (`scoped-project-css.ts`).
+    board.setNote(scopedProjectStylesState().note);
+    // A root document opened because the user clicked a hierarchy story must
+    // arrive focused on that remembered frame. A first visit with no prior
+    // choice keeps the board's fit-all overview.
+    if (rememberedStoryId) board.activate(initialPortableStory.id, true);
+
+    const byId = new Map(portableStories.map((story) => [story.id, story]));
+    // The adapter deliberately walks only the focused story's live DOM. All
+    // frames stay rendered, but Inspector/OID selection has one unambiguous
+    // source tree for its source edits.
+    const focusedDomRoot: OidElementLike = {
+      tagName: 'DIV',
+      get children() {
+        return board.activeContent().children;
+      },
+      getAttribute: (name) => layer.getAttribute(name),
+      getBoundingClientRect: () => layer.getBoundingClientRect(),
+      get style() {
+        return layer.style;
+      },
+      get textContent() {
+        return board.activeContent().textContent;
+      },
+    };
+    // The serving route determines whether this mount has a source-write backend.
+    const boardWriteBackend = await tierSourceWriteBackend();
+    adapter = new ReactRootAuthoringAdapter(focusedDomRoot, store, {
+      ...(boardWriteBackend ? { writeBackend: boardWriteBackend } : {}),
+      // The facade root above is a plain object, so the adapter's own
+      // scope-root token lookup cannot run — resolve tokens from the ACTIVE
+      // frame's real element instead (its game-CSS scope root carries the
+      // project's custom properties; the editor page root never does).
+      designTokens: () => {
+        const content = board.activeContent();
+        const scopeElement =
+          content.closest('[data-volter-mount-styles]') ??
+          content.querySelector('[data-volter-mount-styles]') ??
+          content;
+        return getDesignTokens(
+          getComputedStyle(scopeElement),
+        );
+      },
+      portableStories: portableStories.map((story) => ({
+        id: story.id,
+        label: story.label,
+        args: story.args,
+        name: story.name,
+        modulePath: story.modulePath,
+      })),
+      portableHierarchy: storyPresentationIndex,
+      activePortableStoryId: initialPortableStory.id,
+      onPortableStoryApplied: (storyId) => {
+        const story = (storyId ? byId.get(storyId) : null) ?? initialPortableStory;
+        rememberPortableStory(projectRoot, candidate.worldId, story.id);
+        const intent = pendingBoardSelectionIntent;
+        pendingBoardSelectionIntent = null;
+        // Direct provider calls come from hierarchy navigation and retain
+        // auto-center. A board single-click only changes active/selection;
+        // its double-click is the explicit zoom gesture.
+        board.activate(story.id, intent === null || intent === 'zoom');
+      },
+      onPortableStoryArgsChanged: (storyId, args) => {
+        const story = byId.get(storyId);
+        if (!story) return;
+        void mountPortable(story, args).catch((error: unknown) => {
+          editorConsole.error(
+            `[design-time-layers] React root "${candidate.worldId}" failed updating portable ` +
+              `story "${story.name}" args: ${formatMountFailureMessage(error)}`,
+            'authoring',
+          );
+        });
+      },
+    });
+    if (activationDocumentId) {
+      requestAnimationFrame(() => recordViewportFirstFrame(activationDocumentId));
+    }
+
+    return {
+      adapter,
+      dispose: () => {
+        disposed = true;
+        adapter.disposeReactRootAdapter();
+        for (const mounted of mountedByStory.values()) mounted.unmount();
+        mountedByStory.clear();
+        board.dispose();
+      },
+    };
+  }
+
+  // Without stories, the entry is the document's sole renderable subject.
+  if (!entry.ok) throw entry.error instanceof Error ? entry.error : new Error(String(entry.error));
+
+  editorConsole.warn(
+    `[design-time-layers] React root "${candidate.worldId}" has no portable CSF preview — the ` +
+      'project declares no UI stories. Add a *.stories.tsx; give it a `meta.component` of ' +
+      `this root's entry component${entryComponentName ? ` (${entryComponentName}, ${candidate.path})` : ''} ` +
+      'to make it this root’s default preview. Falling back to rendering the entry bare.',
+    'authoring',
+  );
+
+  const Entry = entry.Entry;
+  // Entry hooks and mounting use the same project React runtime as reactMount
+  // in host/roots/react-root.ts.
+  const { createElement, createRoot, flushSync } = await resolveReactRootMountRuntime();
+  const root = createRoot(layer);
+  const render = (onCaught: (error: unknown) => void): void => {
+    root.render(
+      createElement(CrashNullBoundary, {
+        key: '__entry__',
+        onCaught,
+        children: createElement(Entry),
+      }),
+    );
+  };
+
+  let caught: unknown = null;
+  flushSync(() => {
+    render((error: unknown) => {
+      caught = error;
+    });
+  });
+  if (caught !== null) {
+    root.unmount();
+    throw caught instanceof Error ? caught : new Error(String(caught));
+  }
+
+  // Same route-decided recorder as the board branch above.
+  const writeBackend = await tierSourceWriteBackend();
+  const adapter = new ReactRootAuthoringAdapter(layer, store, {
+    ...(writeBackend ? { writeBackend } : {}),
+  });
+  if (activationDocumentId) {
+    requestAnimationFrame(() => recordViewportFirstFrame(activationDocumentId));
+  }
+  return {
+    adapter,
+    dispose: () => {
+      // Release the adapter's HMR reconcile subscription before dropping its DOM.
+      adapter.disposeReactRootAdapter();
+      root.unmount();
+    },
+  };
+}
+
+/** A cheap identity for the project's current story MEMBERSHIP — which
+ *  stories exist, not their content. An unreadable module counts as its own
+ *  member, so a `.stories.tsx` that starts and stops parsing still moves the
+ *  signature. */
+function storyMembershipSignature(): string {
+  return editorHost().stories.modules()
+    .map((module_) =>
+      module_.ok ? module_.stories.map((story) => story.id).join(',') : `!${module_.modulePath}`,
+    )
+    .join('|');
+}
+
+/** Reproject when story membership changes. Content changes use react-refresh
+ * when present; without it, a source write marks the next ready registry
+ * publication for reprojection. Ignore refresh-start notifications carrying
+ * the previous module set and preserve the old layer until its replacement settles. */
+export function reprojectWhenStoriesRepublish(invalidate: () => void): () => void {
+  // The module set the board was last mounted from, and — separately — the
+  // MEMBERSHIP of that set (which stories exist, not their content).
+  let mountedModules: readonly unknown[] | null = editorHost().stories.ready()
+    ? editorHost().stories.modules()
+    : null;
+  let mountedMembership = mountedModules === null ? null : storyMembershipSignature();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let contentWritten = false;
+  const stopWrites = subscribeProjectModuleChange((changed) => {
+    // (a project code module, wherever the project keeps its code: a std game's is in client/ and shared/)
+    const path = changed.replaceAll('\\', '/');
+    if (!/\.(?:[cm]?tsx?|jsx?)$/.test(path) || /(?:^|\/)node_modules\//.test(path)) return;
+    const page = globalThis as { $RefreshReg$?: unknown };
+    if (typeof page.$RefreshReg$ !== 'function') contentWritten = true;
+  });
+  const stop = editorHost().stories.subscribe(() => {
+    if (!editorHost().stories.ready()) return;
+    const modules = editorHost().stories.modules();
+    const membership = storyMembershipSignature();
+    if (mountedModules === null) {
+      // The mount's own publish: remember it, re-project nothing.
+      mountedModules = modules;
+      mountedMembership = membership;
+      return;
+    }
+    const membershipChanged = membership !== mountedMembership;
+    const contentChanged = contentWritten && modules !== mountedModules;
+    mountedModules = modules;
+    mountedMembership = membership;
+    if (!membershipChanged && !contentChanged) return;
+    contentWritten = false;
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      // The next mount consumes this publication before its first await.
+      // Suppress another discovery refresh, then clear the flag next task.
+      skipStoryRefreshForRemount = true;
+      invalidate();
+      setTimeout(() => {
+        skipStoryRefreshForRemount = false;
+      }, 0);
+    }, 250);
+  });
+  return () => {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    stop();
+    stopWrites();
+  };
+}