@volter/editor-game 0.5.65

package/src/host/design-system-stories/fixtures/authoring.ts

@@ -0,0 +1,247 @@
+import type {
+  AuthoringAdapter,
+  EditorNode,
+  PropertyDescriptor,
+  Transform,
+} from '@volter/editor-project/adapter';
+
+const hierarchyNodes: Readonly<Record<string, Omit<EditorNode, 'label'>>> = {
+  scene: {
+    id: 'scene',
+    role: 'document',
+    secondaryLabel: 'src/scenes/AuroraScene.tsx',
+    kind: 'scene',
+    parentId: null,
+    childIds: ['environment', 'camera', 'player', 'enemy-bravo', 'turret'],
+  },
+  environment: {
+    id: 'environment',
+    role: 'folder',
+    kind: 'group',
+    parentId: 'scene',
+    childIds: ['key-light', 'fill-light', 'ground'],
+  },
+  'key-light': {
+    id: 'key-light',
+    role: 'entity',
+    kind: 'light',
+    parentId: 'environment',
+    childIds: [],
+  },
+  'fill-light': {
+    id: 'fill-light',
+    role: 'entity',
+    kind: 'light',
+    parentId: 'environment',
+    childIds: [],
+  },
+  ground: {
+    id: 'ground',
+    role: 'entity',
+    kind: 'mesh',
+    parentId: 'environment',
+    childIds: [],
+  },
+  camera: {
+    id: 'camera',
+    role: 'entity',
+    kind: 'camera',
+    parentId: 'scene',
+    childIds: [],
+  },
+  player: {
+    id: 'player',
+    role: 'entity',
+    kind: 'mesh',
+    parentId: 'scene',
+    childIds: ['weapon'],
+  },
+  weapon: {
+    id: 'weapon',
+    role: 'entity',
+    kind: 'mesh',
+    parentId: 'player',
+    childIds: [],
+  },
+  // The two instance states the hierarchy row now has to say out loud: a
+  // component instance carrying its type, and one whose three transform
+  // channels are all refused. Every other node above stays a plain entity,
+  // which is the third state.
+  'enemy-bravo': {
+    id: 'enemy-bravo',
+    role: 'component',
+    kind: 'group',
+    typeLabel: 'Enemy',
+    parentId: 'scene',
+    childIds: [],
+  },
+  turret: {
+    id: 'turret',
+    role: 'component',
+    kind: 'group',
+    typeLabel: 'Turret',
+    parentId: 'scene',
+    childIds: [],
+  },
+};
+
+const initialLabels: Readonly<Record<string, string>> = {
+  scene: 'Aurora',
+  environment: 'Environment',
+  'key-light': 'Key Light',
+  'fill-light': 'Fill Light',
+  ground: 'Ground',
+  camera: 'Main Camera',
+  player: 'Player',
+  weapon: 'Pulse Blade',
+  'enemy-bravo': 'EnemyBravo',
+  turret: 'WatchTurret',
+};
+
+const commonProperties: readonly PropertyDescriptor[] = [
+  { path: 'name', label: 'Name', type: 'string' },
+  { path: 'visible', label: 'Visible', type: 'boolean' },
+  { path: 'locked', label: 'Locked', type: 'boolean' },
+];
+
+const propertiesByKind: Readonly<Record<string, readonly PropertyDescriptor[]>> = {
+  mesh: [
+    ...commonProperties,
+    { path: 'material.color', label: 'Tint', type: 'color', group: 'Material' },
+    {
+      path: 'material.finish',
+      label: 'Finish',
+      type: 'enum',
+      options: ['Matte', 'Metal', 'Glass'],
+      group: 'Material',
+    },
+    { path: 'gameplay.health', label: 'Health', type: 'number', group: 'Gameplay' },
+    { path: 'gameplay.respawn', label: 'Respawn', type: 'boolean', group: 'Gameplay' },
+  ],
+  light: [
+    ...commonProperties,
+    { path: 'light.color', label: 'Color', type: 'color', group: 'Light' },
+    { path: 'light.intensity', label: 'Intensity', type: 'number', group: 'Light' },
+    { path: 'light.shadows', label: 'Shadows', type: 'boolean', group: 'Light' },
+  ],
+  camera: [
+    ...commonProperties,
+    {
+      path: 'camera.projection',
+      label: 'Projection',
+      type: 'enum',
+      options: ['Perspective', 'Orthographic'],
+      group: 'Camera',
+    },
+    { path: 'camera.fov', label: 'Field of view', type: 'number', group: 'Camera' },
+  ],
+  group: commonProperties,
+  scene: commonProperties,
+};
+
+/** Mutable adapter fixture shared by every authoring-system story. */
+export function createAuthoringFixture(): AuthoringAdapter {
+  const listeners = new Set<() => void>();
+  const labels = new Map(Object.entries(initialLabels));
+  const values = new Map<string, unknown>();
+  const transforms = new Map<string, Transform>();
+  let selection = ['player'];
+
+  for (const id of Object.keys(hierarchyNodes)) {
+    values.set(`${id}:visible`, true);
+    values.set(`${id}:locked`, id === 'ground');
+    transforms.set(id, {
+      position: id === 'player' ? [1.5, 0, -2] : [0, 0, 0],
+      rotation: [0, 0, 0, 1],
+      scale: [1, 1, 1],
+    });
+  }
+  values.set('player:material.color', '#6ea8ff');
+  values.set('player:material.finish', 'Metal');
+  values.set('player:gameplay.health', 100);
+  values.set('player:gameplay.respawn', true);
+  values.set('weapon:material.color', '#a9e8ff');
+  values.set('weapon:material.finish', 'Glass');
+  values.set('weapon:gameplay.health', 24);
+  values.set('weapon:gameplay.respawn', false);
+  values.set('key-light:light.color', '#ffe3b0');
+  values.set('key-light:light.intensity', 3.2);
+  values.set('key-light:light.shadows', true);
+  values.set('fill-light:light.color', '#8cbcff');
+  values.set('fill-light:light.intensity', 1.4);
+  values.set('fill-light:light.shadows', false);
+  values.set('camera:camera.projection', 'Perspective');
+  values.set('camera:camera.fov', 52);
+
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+  const node = (id: string): EditorNode | null => {
+    const fixture = hierarchyNodes[id];
+    return fixture ? { ...fixture, label: labels.get(id) ?? id } : null;
+  };
+
+  return {
+    capabilities: {
+      transform: true,
+      inspectorFields: true,
+      persist: false,
+    },
+    provenance: {
+      source: 'document',
+      label: 'scene',
+      detail: 'Fixture data exercises the same adapter contract as an authored scene document.',
+    },
+    hierarchy: {
+      roots: () => [node('scene')!],
+      node,
+      object3D: () => null,
+      idForObject3D: () => null,
+    },
+    selection: {
+      get: () => selection,
+      set: (ids) => {
+        selection = ids;
+        notify();
+      },
+    },
+    transforms: {
+      dimensions: () => '3d',
+      get: (id) => transforms.get(id) ?? transforms.get('scene')!,
+      // H2 — one fixture row is fully refused, with the kind of sentence a
+      // real adapter produces. The row shows THIS string and nothing else.
+      editability: (id, channel) =>
+        id === 'turret'
+          ? {
+              writable: false,
+              reason: `Turret does not forward ${channel} to its group root.`,
+            }
+          : { writable: true },
+      beginEdit: () => undefined,
+      apply: (id, transform) => {
+        transforms.set(id, transform);
+        notify();
+      },
+      endEdit: () => undefined,
+    },
+    inspector: {
+      properties: (id) => {
+        const kind = node(id)?.kind ?? 'object';
+        return [...(propertiesByKind[kind] ?? commonProperties)];
+      },
+      get: (id, path) => {
+        if (path === 'name') return labels.get(id);
+        return values.get(`${id}:${path}`);
+      },
+      set: (id, path, value) => {
+        if (path === 'name') labels.set(id, String(value));
+        else values.set(`${id}:${path}`, value);
+        notify();
+      },
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}

package/src/host/design-system-stories/fixtures/editor-runtime.tsx

@@ -0,0 +1,115 @@
+import { type ReactNode, useEffect, useLayoutEffect, useState } from 'react';
+import { resetProjectThumbnailManifestCache } from '@volter/editor-core/asset-workflow/thumbnail-system';
+import { type EditorRuntime, EditorRuntimeProvider, type EditorStats } from '@volter/editor-core/editor-runtime';
+import { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import { EditorSession } from '@volter/editor-core/history/editor-session';
+import { getStorageBackend, MemStorage, setStorageBackend } from '@volter/editor-core/storage/index';
+import {
+  activeWorkspaceUtility,
+  installWorkspaceHostCommands,
+  setActiveWorkspaceUtility,
+  setWorkspaceUtilityTabs,
+  workspaceUtilityTabs,
+} from '@volter/editor-core/workspace-host-commands';
+import { availableWorkspaceUtilities } from '@volter/editor-core/workspace-utility-registry';
+
+const ZERO_STATS: EditorStats = {
+  fps: 60,
+  frameTime: 16.7,
+  drawCalls: 42,
+  triangles: 12_480,
+  cameraPosition: { x: 4, y: 3, z: 8 },
+  cameraTarget: { x: 0, y: 1, z: 0 },
+};
+
+/** A real, bounded editor runtime for production component stories. */
+export function createStoryEditorRuntime(): EditorRuntime {
+  const store = new EditorShellStore();
+  const session = new EditorSession('storybook-fixture');
+  store.attachHistory(session.history);
+  return {
+    store,
+    session,
+    stats: ZERO_STATS,
+    initPromise: Promise.resolve(),
+  };
+}
+
+/**
+ * Installs the smallest honest workspace controller needed by shell stories.
+ * The production toolbar still talks through its normal semantic command
+ * boundary; the fixture only supplies the host state that Storybook does not
+ * mount. This keeps toolbar behavior testable without cloning its UI.
+ */
+export function installStoryWorkspaceUtilityController(): () => void {
+  const previousTabs = workspaceUtilityTabs();
+  const previousActive = activeWorkspaceUtility();
+  let tabs = availableWorkspaceUtilities()
+    .filter((utility) => utility.visibleByDefault !== false)
+    .map((utility) => utility.id);
+
+  const publishTabs = () => setWorkspaceUtilityTabs(tabs);
+  const showUtility = (id: string) => {
+    if (!tabs.includes(id)) {
+      tabs = [...tabs, id];
+      publishTabs();
+    }
+    setActiveWorkspaceUtility(id);
+  };
+  const uninstall = installWorkspaceHostCommands({
+    showStaticPanel: () => undefined,
+    showUtility,
+    toggleUtility: (id) => {
+      if (activeWorkspaceUtility() === id) setActiveWorkspaceUtility(null);
+      else showUtility(id);
+    },
+    closeUtility: (id) => {
+      tabs = tabs.filter((tabId) => tabId !== id);
+      publishTabs();
+      if (activeWorkspaceUtility() === id) setActiveWorkspaceUtility(null);
+    },
+    showAuxiliary: () => undefined,
+    toggleFocus: () => undefined,
+  });
+
+  publishTabs();
+  setActiveWorkspaceUtility(null);
+  return () => {
+    uninstall();
+    setWorkspaceUtilityTabs(previousTabs);
+    setActiveWorkspaceUtility(previousActive);
+  };
+}
+
+/**
+ * Shared Storybook host for components that normally consume EditorContext.
+ * It deliberately provides runtime state only: project discovery, network
+ * listeners, and filesystem initialization remain application lifecycles.
+ */
+export function StoryEditorRuntime({
+  children,
+  onRuntime,
+}: {
+  readonly children: ReactNode | ((runtime: EditorRuntime) => ReactNode);
+  readonly onRuntime?: (runtime: EditorRuntime) => void;
+}) {
+  const [runtime] = useState(createStoryEditorRuntime);
+  useLayoutEffect(() => {
+    const previousStorage = getStorageBackend();
+    setStorageBackend(new MemStorage());
+    resetProjectThumbnailManifestCache();
+    return () => {
+      setStorageBackend(previousStorage);
+      resetProjectThumbnailManifestCache();
+    };
+  }, []);
+  useEffect(() => {
+    onRuntime?.(runtime);
+    return () => runtime.session.dispose();
+  }, [onRuntime, runtime]);
+  return (
+    <EditorRuntimeProvider runtime={runtime}>
+      {typeof children === 'function' ? children(runtime) : children}
+    </EditorRuntimeProvider>
+  );
+}

package/src/host/document-preview-three.ts

@@ -0,0 +1,110 @@
+import { collectContentNodeRecords } from '@volter/editor-threejs/viewport/content-bounds';
+import { isEditorOwnedObject } from '@volter/editor-threejs/viewport/editor-layers';
+import { markHostRenderer } from '@volter/editor-threejs/viewport/renderer-ownership';
+import * as THREE from 'three';
+import type { DocumentPreviewCaptureRequest } from '@volter/editor-core/document-preview-source';
+import { frameableContentBounds } from '@volter/editor-core/scene-framing';
+
+function authoredCameras(root: THREE.Object3D): THREE.Camera[] {
+  const cameras: THREE.Camera[] = [];
+  root.traverse((object) => {
+    if (!isEditorOwnedObject(object) && (object as THREE.Camera).isCamera)
+      cameras.push(object as THREE.Camera);
+  });
+  return cameras;
+}
+
+function fallbackCamera(root: THREE.Object3D, aspect: number): THREE.PerspectiveCamera {
+  // The shared collector includes furniture for other callers. Capture fits
+  // only authored content, so remove isolated helper subtrees for this pass.
+  const helpers: { object: THREE.Object3D; parent: THREE.Object3D }[] = [];
+  root.traverse((object) => {
+    if (object.parent && isEditorOwnedObject(object))
+      helpers.push({ object, parent: object.parent });
+  });
+  for (const { object } of helpers) object.removeFromParent();
+  let records: ReturnType<typeof collectContentNodeRecords>;
+  try {
+    records = collectContentNodeRecords(root);
+  } finally {
+    for (const { object, parent } of helpers) parent.add(object);
+  }
+  const meaningful = records.filter((record) => !record.overlay && !record.enclosure);
+  const candidates = meaningful;
+  const bounds = frameableContentBounds(candidates.map((record) => record.box));
+  const camera = new THREE.PerspectiveCamera(42, aspect, 0.01, 100_000);
+  const center = bounds.isEmpty() ? new THREE.Vector3() : bounds.getCenter(new THREE.Vector3());
+  const radius = bounds.isEmpty()
+    ? 1
+    : Math.max(0.01, bounds.getBoundingSphere(new THREE.Sphere()).radius);
+  const distance = radius / Math.sin(THREE.MathUtils.degToRad(camera.fov / 2));
+  camera.position
+    .copy(center)
+    .addScaledVector(new THREE.Vector3(1, 0.75, 1).normalize(), distance * 1.15);
+  camera.lookAt(center);
+  camera.near = Math.max(0.001, distance - radius * 2.5);
+  camera.far = distance + radius * 3;
+  camera.updateProjectionMatrix();
+  camera.updateMatrixWorld(true);
+  return camera;
+}
+
+function captureCamera(root: THREE.Object3D, request: DocumentPreviewCaptureRequest): THREE.Camera {
+  if (request.camera) {
+    const camera = new THREE.PerspectiveCamera(
+      request.camera.fov ?? 42,
+      request.width / request.height,
+      0.01,
+      100_000,
+    );
+    camera.position.set(
+      request.camera.position.x,
+      request.camera.position.y,
+      request.camera.position.z,
+    );
+    camera.lookAt(request.camera.target.x, request.camera.target.y, request.camera.target.z);
+    camera.updateMatrixWorld(true);
+    return camera;
+  }
+  const declared = authoredCameras(root);
+  if (declared.length === 1) {
+    const camera = declared[0]!.clone();
+    camera.matrixWorld.copy(declared[0]!.matrixWorld);
+    camera.matrixWorld.decompose(camera.position, camera.quaternion, camera.scale);
+    if (camera instanceof THREE.PerspectiveCamera) {
+      camera.aspect = request.width / request.height;
+      camera.updateProjectionMatrix();
+    }
+    return camera;
+  }
+  return fallbackCamera(root, request.width / request.height);
+}
+
+/** One chrome-free frame of the authored scene. No studio dressing is added. */
+export function captureAuthoredThreeScenePreview(
+  root: THREE.Object3D,
+  scene: THREE.Scene,
+  request: DocumentPreviewCaptureRequest,
+  prepare?: (renderer: THREE.WebGLRenderer) => () => void,
+): string {
+  scene.updateMatrixWorld(true);
+  const camera = captureCamera(root, request);
+  const renderer = markHostRenderer(
+    new THREE.WebGLRenderer({ antialias: true, alpha: true, preserveDrawingBuffer: true }),
+  );
+  let cleanup: (() => void) | undefined;
+  try {
+    cleanup = prepare?.(renderer);
+    renderer.setPixelRatio(1);
+    renderer.setSize(request.width, request.height, false);
+    renderer.outputColorSpace = THREE.SRGBColorSpace;
+    renderer.toneMapping = THREE.ACESFilmicToneMapping;
+    renderer.setClearColor(0x20242b, scene.background === null ? 0 : 1);
+    renderer.render(scene, camera);
+    return renderer.domElement.toDataURL('image/png');
+  } finally {
+    cleanup?.();
+    renderer.dispose();
+    renderer.forceContextLoss();
+  }
+}

package/src/host/entry-adjudication.ts

@@ -0,0 +1,89 @@
+/**
+ * WHAT DOES THIS ENTRY MODULE MEAN? — the ONE editor-side answer.
+ *
+ * The engine owns the answer itself (`resolveR3FEntryAdapter`, and the
+ * packaged-aware `resolveR3FEntryAdapterForEditor` delegate that routes it
+ * through the project's own module graph). The editor's job is to ASK, once.
+ * Before this module there were three askers, and they had already drifted:
+ *
+ *  - the dev-server lane called the packaged-aware `…ForEditor`;
+ *  - the browser/hosted lane called the BARE `resolveR3FEntryAdapter`, so a
+ *    packaged run built a project component's adapter with the shell bundle's
+ *    Fiber and crashed hooks on a null React dispatcher — a divergence
+ *    invisible in dev and reachable only on the packaged lane;
+ *  - the design session had two more inline resolutions of its own, one of
+ *    which additionally understood a NAMED world export that neither other
+ *    lane did.
+ *
+ * All three shapes are here, and the messages stay with their callers: a
+ * project author reading "this entry has no mountable surface" needs to be
+ * told which lane and which file, and that is the caller's knowledge, not
+ * this function's.
+ *
+ * `entry-adjudication-single-owner.test.ts` is the tripwire; the canvas lane
+ * has its own single owner in the engine (`resolveCanvasEntryAdapter`, reached
+ * through `canvas-entry-runtime.ts`) and is not adjudicated here.
+ */
+
+import type { RootAdapter } from '@volter/editor-project/adapter';
+import { resolveR3FEntryAdapterForEditor } from './r3f-entry-runtime';
+
+/**
+ * Runtime shape a `RootAdapter` export must satisfy — the same check
+ * `guardModuleShape` makes for `{ module }` adapters: a non-null object with a
+ * non-empty string `id` and a function `mount`.
+ */
+export function isRootAdapterShaped(candidate: unknown): candidate is RootAdapter {
+  if (candidate === null || typeof candidate !== 'object') return false;
+  const obj = candidate as Record<string, unknown>;
+  return (
+    typeof obj['id'] === 'string' && obj['id'].length > 0 && typeof obj['mount'] === 'function'
+  );
+}
+
+/** What a caller may ask for beyond "read this module the usual way". */
+export interface EntryAdjudicationOptions {
+  /**
+   * The manifest's `world.export` — ONE component in a module that exports
+   * several (a game's `App.tsx` exporting `Scene` beside `Hud` and `App`).
+   *
+   * It takes precedence over an `adapter` export, and it is handed to the same
+   * resolver a default export is rather than being adapted here, so an entry
+   * module and a named world component reach fiber down one path. A name the
+   * module does not export is a NAMED failure, never a silent fall-back to
+   * `default` — which, for such a module, would mount the whole game into the
+   * Scene view.
+   */
+  readonly namedExport?: string | undefined;
+  /** The entry path, for the named-export failure message only. */
+  readonly entryPath?: string | undefined;
+}
+
+/**
+ * Resolve the `RootAdapter` a three-surface entry module means, or `null` when
+ * it means none — the caller raises its own error for that case.
+ *
+ * The precedence, in one place: an explicit `namedExport` first (when the
+ * caller asked for one), then a pre-built `adapter` export, then the engine's
+ * own answer for a module that default-exports its React world component.
+ */
+export async function adjudicateThreeEntry(
+  mod: Record<string, unknown>,
+  rootId: string,
+  opts?: EntryAdjudicationOptions,
+): Promise<RootAdapter | null> {
+  const named = opts?.namedExport;
+  if (named !== undefined) {
+    const picked = mod[named];
+    if (typeof picked !== 'function') {
+      throw new Error(
+        `three root "${rootId}": ${opts?.entryPath ?? 'the entry module'} has no exported ` +
+          `component "${named}" (manifest \`world.export\`) — it exports ` +
+          `${Object.keys(mod).join(', ') || '(nothing)'}.`,
+      );
+    }
+    return resolveR3FEntryAdapterForEditor({ default: picked }, rootId);
+  }
+  if (isRootAdapterShaped(mod['adapter'])) return mod['adapter'];
+  return resolveR3FEntryAdapterForEditor(mod, rootId);
+}