@volter/editor-game 0.5.65

package/src/host/components/PixiIsolationSceneContent.tsx

@@ -0,0 +1,280 @@
+/**
+ * Canvas implementation of an adapter-declared isolation scene document.
+ * Loaded only when a Canvas scene document is actually rendered; the generic
+ * scene table registry must not make a Three project evaluate Pixi authoring.
+ */
+
+import { isolationImportUrl } from '@volter/editor-sdk/session/project-module-url';
+import { themeVars } from '@volter/editor-sdk/widgets';
+import { createPhysics2DRegistry } from '@volter/game-runtime/pixi/physics-registry';
+import { createPhysicsAdapter2D } from '@volter/game-runtime/pixi/system-adapters';
+import { useEffect, useRef, useState } from 'react';
+import {
+  type IsolatedPixiScreenCtor,
+  type MountedIsolatedPixiScreen,
+  mountIsolatedPixiScreen,
+} from '../authoring/mount-isolated-pixi-screen';
+import { PixiAuthoringAdapter } from '../authoring/pixi-authoring-adapter';
+import { createCreationSiteCanvasWriteTarget } from '../authoring/pixi-creation-site-write-target';
+import { installCanvasSceneNavigation } from '@volter/editor-core/authoring/react-canvas-navigation';
+import { createRootViewController } from '@volter/editor-core/authoring/world-pan-state';
+import { capturePixiDisplayObjectThumbnail } from '@volter/editor-core/canvas-preview-frames';
+import type { DocumentPreviewCaptureRequest } from '@volter/editor-core/document-preview-source';
+import { useEditorStore } from '@volter/editor-core/editor-runtime';
+import { authoringJournal } from '../history/json-history-resource';
+import { setActiveScope } from '@volter/editor-core/hotkeys';
+import { getCurrentProject } from '@volter/editor-core/project-manager';
+import { takeNamedExport } from '../take-named-export';
+import { registerWorkspaceDocumentSelection } from '@volter/editor-core/workspace-document-registry';
+import {
+  CANVAS_SCENE_BACKGROUND,
+  CanvasSceneBackdrop,
+  CanvasSceneControls,
+} from '@volter/editor-core/components/CanvasSceneViewport';
+import { RootSelectionOverlay } from '@volter/editor-core/components/RootSelectionOverlay';
+
+export interface PixiIsolationSceneContentProps {
+  readonly active: boolean;
+  readonly documentId: string;
+  readonly path: string;
+  readonly exportName: string | undefined;
+  readonly isolationSetup?: { readonly path: string; readonly export?: string };
+}
+
+async function loadSiblingAssetInitializer(
+  path: string,
+): Promise<{ initAssets?: () => Promise<void>; assetSourcePath?: string }> {
+  const assetsPath = path.replace(/\/screens\/[^/]+$/, '/assets.ts');
+  if (assetsPath === path) return {};
+  try {
+    const project = getCurrentProject();
+    if (!project) return {};
+    const assets = (await import(
+      /* @vite-ignore */ isolationImportUrl(project.rootPath, assetsPath)
+    )) as { initAssets?: () => Promise<void> };
+    return typeof assets.initAssets === 'function'
+      ? { initAssets: assets.initAssets, assetSourcePath: assetsPath }
+      : {};
+  } catch {
+    // A screen with no sibling assets.ts still mounts; missing textures surface
+    // as the constructor's own error.
+    return {};
+  }
+}
+
+export function PixiIsolationSceneContent({
+  active,
+  documentId,
+  path,
+  exportName,
+  isolationSetup: isolationSetupSpec,
+}: PixiIsolationSceneContentProps) {
+  const store = useEditorStore();
+  const containerRef = useRef<HTMLDivElement>(null);
+  const viewRef = useRef(createRootViewController());
+  const view = viewRef.current;
+  const [error, setError] = useState<string | null>(null);
+  const [ready, setReady] = useState(false);
+  const [adapter, setAdapter] = useState<PixiAuthoringAdapter | null>(null);
+  const adapterRef = useRef<PixiAuthoringAdapter | null>(null);
+  const mountedRef = useRef<MountedIsolatedPixiScreen | null>(null);
+  const [visited, setVisited] = useState(active);
+  useEffect(() => {
+    if (active) setVisited(true);
+  }, [active]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    return installCanvasSceneNavigation(container, view);
+  }, [view]);
+
+  useEffect(() => {
+    if (!adapter) return;
+    return registerWorkspaceDocumentSelection(documentId, () => ({
+      adapter,
+      nodeId: [...store.selectedEntityIds].find((id) => adapter.hierarchy.node(id)) ?? null,
+    }));
+  }, [adapter, documentId, store]);
+
+  useEffect(() => {
+    if (!visited) return;
+    const layer = containerRef.current;
+    if (!layer) return;
+    let cancelled = false;
+    setError(null);
+    setReady(false);
+    setAdapter(null);
+    void loadIsolatedSceneComponent(path, exportName)
+      .then(async (Ctor) => {
+        const assets = await loadSiblingAssetInitializer(path);
+        const isolationSetup = isolationSetupSpec
+          ? await loadIsolationSetup(isolationSetupSpec.path, isolationSetupSpec.export)
+          : undefined;
+        return mountIsolatedPixiScreen(Ctor, {
+          ...assets,
+          ...(isolationSetup ? { isolationSetup } : {}),
+          view,
+          layer,
+        });
+      })
+      .then((mounted) => {
+        if (cancelled) {
+          mounted.dispose();
+          return;
+        }
+        mountedRef.current = mounted;
+        const next = new PixiAuthoringAdapter(mounted.screen, store, {
+          // The mount already chose the namespace the game's own class was
+          // constructed in; taking it back is what keeps ONE per surface.
+          pixi: mounted.pixi,
+          // Journal ids are project-relative paths — `scene:TitleScreen` is
+          // read as a URI scheme and refused (`resource-registry.ts`).
+          journal: authoringJournal(`isolation/${documentId.slice('scene:'.length)}`),
+          target: createCreationSiteCanvasWriteTarget({
+            physics: createPhysicsAdapter2D(createPhysics2DRegistry()),
+            history: store.projectHistory,
+          }),
+          surface: () => mounted.canvas,
+          capturePreview: (object, size) =>
+            capturePixiDisplayObjectThumbnail(object, { ...size, pixi: mounted.pixi }),
+          pointFromClient: (clientX, clientY, surfaceRect) => {
+            const pose = view.get();
+            return {
+              x: (clientX - surfaceRect.left - pose.x) / pose.zoom,
+              y: (clientY - surfaceRect.top - pose.y) / pose.zoom,
+            };
+          },
+        });
+        adapterRef.current = next;
+        setAdapter(next);
+        setReady(true);
+      })
+      .catch((reason: unknown) => {
+        if (cancelled) return;
+        setError(reason instanceof Error ? reason.message : String(reason));
+      });
+    return () => {
+      cancelled = true;
+      mountedRef.current?.dispose();
+      mountedRef.current = null;
+      adapterRef.current?.dispose();
+      adapterRef.current = null;
+    };
+  }, [documentId, store, view, visited, path, exportName, isolationSetupSpec]);
+
+  if (error) {
+    return (
+      <div
+        role="alert"
+        data-testid="scene-document-error"
+        style={{ padding: 12, fontSize: 12, color: themeVars.semantic.danger, maxWidth: 640 }}
+      >
+        <div style={{ fontWeight: 600, marginBottom: 4 }}>
+          {path}
+          {exportName ? ` — ${exportName}` : ''}
+        </div>
+        <div style={{ color: themeVars.content.muted, whiteSpace: 'pre-wrap' }}>{error}</div>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      data-testid="scene-document-pixi-isolation"
+      data-document-id={documentId}
+      data-vgai-backdrop-color={active ? CANVAS_SCENE_BACKGROUND : undefined}
+      data-vgai-backdrop-policy={active ? 'dark-frost' : undefined}
+      onPointerDown={() => setActiveScope('viewport')}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        overflow: 'hidden',
+        pointerEvents: 'auto',
+        backgroundColor: CANVAS_SCENE_BACKGROUND,
+        touchAction: 'none',
+      }}
+    >
+      <CanvasSceneBackdrop view={view} />
+      {adapter ? <RootSelectionOverlay adapter={adapter} view={view} transformModeAware /> : null}
+      <CanvasSceneControls
+        active={active}
+        {...(adapter ? { adapter } : {})}
+        containerRef={containerRef}
+        view={view}
+      />
+      {!ready ? (
+        <div
+          data-testid="scene-document-loading"
+          style={{ padding: 12, fontSize: 12, color: themeVars.content.muted, fontStyle: 'italic' }}
+        >
+          mounting…
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+async function loadIsolatedSceneComponent(
+  path: string,
+  exportName: string | undefined,
+): Promise<IsolatedPixiScreenCtor> {
+  const project = getCurrentProject();
+  if (!project) throw new Error('No project is open, so its scene modules cannot be loaded.');
+  return takeNamedExport<IsolatedPixiScreenCtor>(
+    isolationImportUrl(project.rootPath, path),
+    path,
+    exportName,
+  );
+}
+
+/** Load the adapter-declared zero-argument prerequisite for one Edit piece. */
+async function loadIsolationSetup(
+  path: string,
+  exportName: string | undefined,
+): Promise<() => void | Promise<void>> {
+  const project = getCurrentProject();
+  if (!project) throw new Error('No project is open, so its isolation setup cannot be loaded.');
+  return takeNamedExport<() => void | Promise<void>>(
+    isolationImportUrl(project.rootPath, path),
+    path,
+    exportName,
+  );
+}
+
+/** Headless full-composition capture for a Canvas scene Content tile. */
+export async function capturePixiIsolationScenePreview(
+  props: Pick<PixiIsolationSceneContentProps, 'path' | 'exportName' | 'isolationSetup'>,
+  request: DocumentPreviewCaptureRequest,
+): Promise<string> {
+  const layer = document.createElement('div');
+  layer.style.cssText = `position:fixed;left:-20000px;top:0;width:${request.width}px;height:${request.height}px;overflow:hidden;`;
+  document.body.appendChild(layer);
+  const view = createRootViewController();
+  let mounted: MountedIsolatedPixiScreen | null = null;
+  try {
+    const Ctor = await loadIsolatedSceneComponent(props.path, props.exportName);
+    const assets = await loadSiblingAssetInitializer(props.path);
+    const isolationSetup = props.isolationSetup
+      ? await loadIsolationSetup(props.isolationSetup.path, props.isolationSetup.export)
+      : undefined;
+    mounted = await mountIsolatedPixiScreen(Ctor, {
+      ...assets,
+      ...(isolationSetup ? { isolationSetup } : {}),
+      view,
+      layer,
+    });
+    const image = await capturePixiDisplayObjectThumbnail(mounted.screen, {
+      width: request.width,
+      height: request.height,
+      budget: Number.POSITIVE_INFINITY,
+      pixi: mounted.pixi,
+    });
+    if (!image) throw new Error('The Canvas scene has no capturable composition.');
+    return image;
+  } finally {
+    mounted?.dispose();
+    layer.remove();
+  }
+}

package/src/host/components/ResolutionPicker.tsx

@@ -0,0 +1,89 @@
+import { faDesktop } from '@fortawesome/free-solid-svg-icons';
+import { AnchoredMenu, Button, EditorIcon, MenuItem, Text } from '@volter/editor-sdk/widgets';
+import { useRef, useState } from 'react';
+
+export interface Resolution {
+  label: string;
+  width: number | null;
+  height: number | null;
+}
+
+export const RESOLUTIONS: Resolution[] = [
+  { label: 'Fill', width: null, height: null },
+  { label: 'iPhone SE — 375×667', width: 375, height: 667 },
+  { label: 'iPhone 14 — 390×844', width: 390, height: 844 },
+  { label: 'iPhone 14 Pro Max — 430×932', width: 430, height: 932 },
+  { label: 'iPad Mini — 768×1024', width: 768, height: 1024 },
+  { label: 'iPad Pro 11″ — 834×1194', width: 834, height: 1194 },
+  { label: 'Laptop — 1366×768', width: 1366, height: 768 },
+  { label: 'Desktop — 1920×1080', width: 1920, height: 1080 },
+];
+
+/** Shared preview-resolution picker for Game and isolated story documents. */
+export function ResolutionPicker({
+  resolution,
+  onResolutionChange,
+  scale,
+  title = 'Change preview resolution',
+  options = RESOLUTIONS,
+}: {
+  resolution: Resolution;
+  onResolutionChange: (resolution: Resolution) => void;
+  scale: number;
+  title?: string;
+  /** Menu entries. Callers with a project-declared resolution swap the list
+   *  so the declared entry is offered and unreachable choices are not. */
+  options?: Resolution[];
+}) {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLButtonElement>(null);
+
+  const isFill = resolution.width === null;
+  const label = isFill ? 'Fill' : `${resolution.width}×${resolution.height}`;
+
+  return (
+    <div className="vgai-playbar-popover-anchor">
+      <Button
+        ref={ref}
+        variant="ghost"
+        size="comfortable"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? 'vgai-resolution-picker-menu' : undefined}
+        onClick={() => setOpen((value) => !value)}
+        title={title}
+      >
+        <EditorIcon icon={faDesktop} size="md" />
+        <Text variant="code">{label}</Text>
+        {!isFill && scale < 1 && (
+          <Text variant="caption" tone="dim">
+            {Math.round(scale * 100)}%
+          </Text>
+        )}
+      </Button>
+      {open && (
+        <AnchoredMenu
+          id="vgai-resolution-picker-menu"
+          anchorRef={ref}
+          className="vgai-resolution-menu"
+          gap={4}
+          onDismiss={() => setOpen(false)}
+        >
+          {options.map((candidate) => (
+            <MenuItem
+              key={candidate.label}
+              role="menuitemradio"
+              aria-checked={candidate.label === resolution.label}
+              onSelect={() => {
+                onResolutionChange(candidate);
+                setOpen(false);
+              }}
+            >
+              {candidate.label}
+            </MenuItem>
+          ))}
+        </AnchoredMenu>
+      )}
+    </div>
+  );
+}

package/src/host/components/ThreeIsolationSceneContent.tsx

@@ -0,0 +1,180 @@
+/**
+ * Three implementation of an adapter-declared isolation scene document.
+ *
+ * The exact counterpart of `PixiIsolationSceneContent.tsx`, and extracted for
+ * the reason that module's own header already gives: "Loaded only when a
+ * Canvas scene document is actually rendered; the generic scene table registry
+ * must not make a Three project evaluate Pixi authoring." The three half sat
+ * INLINE in `scene-documents.tsx` instead, so the generic scene-table registry
+ * — which every project's tab row subscribes to at boot — carried the portable
+ * CSF mount with it: `stories/story-three-preview.ts`,
+ * `stories/mounted-story-viewport-source.ts`, `stories/story-mount-turn.ts`,
+ * `story-three-preview-runtime.ts`, `authoring/design-time-settle.ts` and
+ * `crash-null-boundary.ts` (measured 2026-09-18, phase 1 unit 9 of the
+ * open-source launch: six files, in a `models` build that declares no story).
+ *
+ * ## The mount, and who owns it
+ *
+ * Identical to the per-story 3D document's, deliberately and by reuse: the
+ * composition is mounted off-screen through `stories/story-three-preview.ts`
+ * and wrapped by `stories/mounted-story-viewport-source.ts`, whose
+ * per-activation disposer is EMPTY because a remount of this document (source
+ * identity change, not a tab flip) still calls `build()` again. This
+ * component's own effect cleanup is the ONE teardown path. See that module's
+ * header for the measured black-panel defect a second owner produces.
+ */
+
+import { fsImportPath } from '@volter/editor-sdk/session/project-module-url';
+import { themeVars } from '@volter/editor-sdk/widgets';
+import { useEffect, useRef, useState } from 'react';
+import type { DocumentPreviewCaptureRequest } from '@volter/editor-core/document-preview-source';
+import { captureAuthoredThreeScenePreview } from '../document-preview-three';
+import { getCurrentProject } from '@volter/editor-core/project-manager';
+import {
+  type MountedStoryViewportSource,
+  mountedStoryViewportSource,
+} from '../stories/mounted-story-viewport-source';
+import {
+  disposeStoryObject3D,
+  mountStoryObject3D,
+  type StoryPreviewComponent,
+} from '@volter/editor-core/stories/story-three-preview';
+import { takeNamedExport } from '../take-named-export';
+import type { WorkspaceDocumentContentProps } from '@volter/editor-core/workspace-document-registry';
+import { Object3DDocumentViewport } from '@volter/editor-core/components/Object3DDocumentViewport';
+
+export interface ThreeIsolationSceneState {
+  /** Project-relative module the composition lives in. */
+  readonly path: string;
+  readonly exportName: string | undefined;
+  readonly label: string;
+}
+
+export function ThreeIsolationSceneContent({
+  active,
+  documentId,
+  state,
+}: WorkspaceDocumentContentProps & { state: ThreeIsolationSceneState | undefined }) {
+  const [source, setSource] = useState<MountedStoryViewportSource | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const sourceRef = useRef<MountedStoryViewportSource | null>(null);
+  // EVERY OPEN DOCUMENT IS MOUNTED, and this row is opened for EVERY
+  // scene a project declares — so mounting at open time would build every
+  // scene's fiber root at boot. Mount on first activation and retain it
+  // afterwards; a mount freed on deactivation is the black-panel defect
+  // `mountedStoryViewportSource` documents.
+  const [visited, setVisited] = useState(active);
+  useEffect(() => {
+    if (active) setVisited(true);
+  }, [active]);
+
+  const path = state?.path;
+  const exportName = state?.exportName;
+  useEffect(() => {
+    if (!visited || !path) return;
+    let cancelled = false;
+    setError(null);
+    setSource(null);
+    void loadSceneComponent(path, exportName)
+      .then((Component) => mountStoryObject3D(Component, {}))
+      .then((mounted) => {
+        if (cancelled) {
+          void disposeStoryObject3D(mounted);
+          return;
+        }
+        const next = mountedStoryViewportSource(mounted);
+        sourceRef.current = next;
+        setSource(next);
+      })
+      .catch((reason: unknown) => {
+        if (cancelled) return;
+        setError(reason instanceof Error ? reason.message : String(reason));
+      });
+    return () => {
+      cancelled = true;
+      // THIS is the mount's one owner — see the module header.
+      sourceRef.current?.dispose();
+      sourceRef.current = null;
+      setSource(null);
+    };
+  }, [visited, path, exportName]);
+
+  if (!state) {
+    return (
+      <div style={{ padding: 12, fontSize: 12, color: themeVars.content.muted }}>
+        This scene document is no longer declared by the project's adapter.
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div
+        role="alert"
+        data-testid="scene-document-error"
+        style={{ padding: 12, fontSize: 12, color: themeVars.semantic.danger, maxWidth: 640 }}
+      >
+        <div style={{ fontWeight: 600, marginBottom: 4 }}>
+          {state.path}
+          {state.exportName ? ` — ${state.exportName}` : ''}
+        </div>
+        <div style={{ color: themeVars.content.muted, whiteSpace: 'pre-wrap' }}>{error}</div>
+      </div>
+    );
+  }
+
+  if (!source) {
+    return (
+      <div
+        data-testid="scene-document-loading"
+        style={{ padding: 12, fontSize: 12, color: themeVars.content.muted, fontStyle: 'italic' }}
+      >
+        mounting…
+      </div>
+    );
+  }
+
+  return (
+    <Object3DDocumentViewport
+      documentId={documentId}
+      sourcePath={state.path}
+      build={source.build}
+      displayName={state.label}
+      active={active}
+    />
+  );
+}
+
+/**
+ * Import the scene's own module through the project-module door and take the
+ * export the table named.
+ *
+ * Cache-busted per mount, the same always-fresh discipline design-time CSF
+ * loads use (`stories/story-discovery.ts`): a scene edited in the editor must
+ * be re-openable without a reload. The url is built by `fsImportPath`, the ONE
+ * owner of `/@fs/` urls for project code (PD-3).
+ */
+async function loadSceneComponent(
+  path: string,
+  exportName: string | undefined,
+): Promise<StoryPreviewComponent> {
+  const project = getCurrentProject();
+  if (!project) throw new Error('No project is open, so its scene modules cannot be loaded.');
+  const url = `${fsImportPath(project.rootPath, path)}?t=${Date.now()}`;
+  return takeNamedExport<StoryPreviewComponent>(url, path, exportName);
+}
+
+/** Headless capture door for Content. It mounts the authored source without
+ * opening or activating its workspace document. */
+export async function captureThreeIsolationScenePreview(
+  state: ThreeIsolationSceneState,
+  request: DocumentPreviewCaptureRequest,
+): Promise<string> {
+  const Component = await loadSceneComponent(state.path, state.exportName);
+  const mounted = await mountStoryObject3D(Component, {});
+  try {
+    return captureAuthoredThreeScenePreview(mounted.root, mounted.scene, request);
+  } finally {
+    await disposeStoryObject3D(mounted);
+  }
+}