@volter/editor-core 0.5.57

package/src/authoring/object3d-gesture-controller.ts

@@ -0,0 +1,113 @@
+import type { ToolObject3DGesture, ToolObject3DPointerEvent } from '@volter/editor-sdk/contributions';
+
+export interface Object3DGestureControllerOptions {
+  readonly begin: (event: ToolObject3DPointerEvent) => ToolObject3DGesture | null;
+  readonly persist: (label?: string) => Promise<void>;
+  readonly reportError: (error: unknown) => void;
+}
+
+/** Exactly one project gesture at a time; every terminal path is explicit. */
+export class Object3DGestureController {
+  private active: { pointerId: number; gesture: ToolObject3DGesture } | null = null;
+  private settling = false;
+  private readonly idleWaiters = new Set<() => void>();
+
+  constructor(private readonly options: Object3DGestureControllerOptions) {}
+
+  begin(event: ToolObject3DPointerEvent): boolean {
+    if (this.active || this.settling) return false;
+    try {
+      const gesture = this.options.begin(event);
+      if (!gesture) return false;
+      this.active = { pointerId: event.pointerId, gesture };
+      return true;
+    } catch (error) {
+      this.options.reportError(error);
+      return false;
+    }
+  }
+
+  update(event: ToolObject3DPointerEvent): void {
+    if (!this.active || this.active.pointerId !== event.pointerId) return;
+    try {
+      this.active.gesture.update(event);
+    } catch (error) {
+      void this.cancelWithError(error);
+    }
+  }
+
+  async commit(event: ToolObject3DPointerEvent): Promise<boolean> {
+    const active = this.take(event.pointerId);
+    if (!active) return false;
+    this.settling = true;
+    try {
+      await active.commit(event);
+      await this.options.persist(active.label);
+      return true;
+    } catch (error) {
+      try {
+        await active.cancel();
+      } catch (cancelError) {
+        this.options.reportError({ operationError: error, rollbackError: cancelError });
+        return false;
+      }
+      this.options.reportError(error);
+      return false;
+    } finally {
+      this.settling = false;
+      for (const resolve of this.idleWaiters) resolve();
+      this.idleWaiters.clear();
+    }
+  }
+
+  async cancel(pointerId?: number): Promise<boolean> {
+    const active = this.take(pointerId);
+    if (!active) return false;
+    this.settling = true;
+    try {
+      await active.cancel();
+      return true;
+    } catch (error) {
+      this.options.reportError(error);
+      return false;
+    } finally {
+      this.settling = false;
+      for (const resolve of this.idleWaiters) resolve();
+      this.idleWaiters.clear();
+    }
+  }
+
+  /** A source handoff waits for persistence/rollback, including pointer-up work. */
+  async settle(): Promise<void> {
+    if (this.active) await this.cancel();
+    if (this.settling) await new Promise<void>((resolve) => this.idleWaiters.add(resolve));
+  }
+
+  hasActiveGesture(): boolean {
+    return this.active !== null;
+  }
+
+  private take(pointerId?: number): ToolObject3DGesture | null {
+    if (!this.active || (pointerId !== undefined && this.active.pointerId !== pointerId))
+      return null;
+    const gesture = this.active.gesture;
+    this.active = null;
+    return gesture;
+  }
+
+  private async cancelWithError(error: unknown): Promise<void> {
+    const active = this.take();
+    if (!active) return;
+    this.settling = true;
+    try {
+      await active.cancel();
+      this.options.reportError(error);
+    } catch (rollbackError) {
+      this.options.reportError({ operationError: error, rollbackError });
+    } finally {
+      this.settling = false;
+      for (const resolve of this.idleWaiters) resolve();
+      this.idleWaiters.clear();
+    }
+  }
+}

package/src/authoring/panel-authoring.ts

@@ -0,0 +1,121 @@
+/**
+ * ONE resolver for "which authoring adapter do the shared panels drive?" —
+ * the Hierarchy and the Inspector must never disagree, and before this module
+ * they each open-coded the same expression.
+ *
+ * ## The defect this exists for (audit A1/A3, 2026-08-01) — and its MEASURED cause
+ *
+ * Symptom: every pixi ingest (the in-tree canvas fixtures, and
+ * the synthetic `ingest-pixi` manifest fixtures) mounted, captured and drew,
+ * `getAuthoringOverride()` held a healthy `PixiAuthoringAdapter` with
+ * `{transform, inspectorFields, persist}` all true — and the Hierarchy still
+ * rendered "No authoring adapter" while the Inspector took its
+ * nothing-to-show branch. The three route (the `games-fps` fixture) bound fine in the same session
+ * shape.
+ *
+ * The audit's hypothesis was adapter RESOLUTION: that the active workspace
+ * document's adapter shadowed the ingest override at `Inspector.tsx`'s
+ * `documentSelection?.adapter ?? getActiveAuthoring(store)`. Reproduced live on
+ * a single-`ingest-pixi`-root project and measured: `activeWorkspaceDocument
+ * Selection()` is `null`, the only open document is `workspace:game`, and the
+ * override is already correct at the moment the panels are showing the wrong
+ * thing. Resolution was never wrong. **It was a stale render**: the override
+ * slot is module state with no change notification, and the panels only
+ * re-rendered because ingest entry ALSO calls `setActiveViewportTab`, which in
+ * a Three-rooted project activates a different center document and the
+ * workspace registry's `notifyChanged()` re-rendered them incidentally. With no
+ * Three root there is one center document, that activation is a no-op, and the
+ * incidental notification never happens.
+ *
+ * The fix is therefore in `active-adapter.ts` (the slot notifies) plus the
+ * subscription the panels take out beside this resolver. This module exists so
+ * the two panels share ONE expression and one subscription set instead of two
+ * copies that can drift apart again.
+ *
+ * ## Why the resolution ORDER is unchanged
+ *
+ * An earlier revision of this fix also made an ingest override outrank a
+ * document-published adapter — the audit's hypothesis, kept "just in case". It
+ * is deliberately NOT here: it was never observed (measured null document
+ * selection in the reproduction above), and reaching `isIngestActive` from a
+ * module both shared panels import drags `ingest/mount-ingest-root.ts`'s whole transitive
+ * graph — the pixi stack and the engine renderer setup — into the
+ * Hierarchy's module graph, which broke six unit suites outright on a
+ * `URL.createObjectURL` that does not exist in the node test environment. A
+ * behavior change nobody could demonstrate is not worth a dependency edge that
+ * heavy. If document shadowing is ever actually observed, it should be fixed
+ * where the document's provider is registered (`world-documents.tsx`), which
+ * is the layer that knows a foreign session is live.
+ */
+
+import type { AdapterSurface, AuthoringAdapter } from '@volter/editor-project/adapter';
+import type { EditorShellStore } from '../editor-shell-store';
+import {
+  activeWorkspaceDocument,
+  activeWorkspaceDocumentSelection,
+  type WorkspaceDocumentSelection,
+} from '../workspace-document-registry';
+import { getActiveAuthoring } from './active-adapter';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+
+export interface PanelAuthoringBinding {
+  /** The adapter the Hierarchy/Inspector must drive. */
+  readonly adapter: AuthoringAdapter;
+  /** Render substrate owned by the active authored document. `null` for
+   * composition/reference documents that do not focus one root surface. */
+  readonly surface: AdapterSurface | null;
+  /** The active document's selection context, when it publishes one. */
+  readonly documentSelection: WorkspaceDocumentSelection | null;
+}
+
+/**
+ * An authored root document projects only the root it is showing. The Game
+ * document intentionally falls through to the full composite: composition is
+ * its subject, while a Scene/world document's subject is one root.
+ *
+ * `world` documents carry their manifest root id as provenance. The pinned
+ * Three Scene document predates per-root document ids, so its focused child is
+ * the one live Three adapter that honestly reports transform authoring.
+ */
+function adapterSurface(kind: string): AdapterSurface | null {
+  return kind === 'three' || kind === 'canvas' || kind === 'dom' ? kind : null;
+}
+
+function rootDocumentBinding(
+  active: AuthoringAdapter,
+): { adapter: AuthoringAdapter; surface: AdapterSurface } | null {
+  if (!(active instanceof CompositeAuthoringAdapter)) return null;
+  const document = activeWorkspaceDocument()?.descriptor;
+  if (!document) return null;
+
+  const children = active.childAdapters();
+  if (document.kind === 'world') {
+    const rootId = document.provenance?.rootId;
+    const child = rootId ? children.find((candidate) => candidate.worldId === rootId) : undefined;
+    const surface = child ? adapterSurface(child.kind) : null;
+    return child && surface ? { adapter: child.adapter, surface } : null;
+  }
+  if (document.kind === 'scene') {
+    const child = children.find(
+      (candidate) => candidate.kind === 'three' && candidate.adapter.capabilities.transform,
+    );
+    if (!child) return null;
+    return {
+      adapter: active.projectedDocumentAdapter(child.worldId) ?? child.adapter,
+      surface: 'three',
+    };
+  }
+  return null;
+}
+
+export function resolvePanelAuthoring(store: EditorShellStore): PanelAuthoringBinding {
+  const documentSelection = activeWorkspaceDocumentSelection();
+  const active = getActiveAuthoring(store);
+  const rootBinding = rootDocumentBinding(active);
+  const documentKind = activeWorkspaceDocument()?.descriptor.kind;
+  return {
+    adapter: documentSelection?.adapter ?? rootBinding?.adapter ?? active,
+    surface: documentKind === 'story' ? 'dom' : (rootBinding?.surface ?? null),
+    documentSelection,
+  };
+}

package/src/authoring/prefab-instance-inspector-section.tsx

@@ -0,0 +1,237 @@
+import { faCubesStacked } from '@fortawesome/free-solid-svg-icons';
+import {
+  Button,
+  Checkbox,
+  Dialog,
+  DialogBody,
+  DialogFooter,
+  DialogHeader,
+  FieldRow,
+  Text,
+  themeVars,
+} from '@volter/editor-sdk/widgets';
+import type {
+  AuthoringAdapter,
+  ComponentInstanceOverride,
+  EditorNode,
+} from '@volter/editor-project/adapter';
+import { useEffect, useState } from 'react';
+import { createHmrRegistrationGroup } from '../hmr-registration-group';
+import { GROUP_SECTION_ORDER, type InspectionSection } from '../inspection/model';
+import { registerInspectorSections } from '../inspector-section-registry';
+import { showTransientHint } from '../transient-hint';
+import {
+  applyAuthoringInstanceToComponent,
+  openAuthoringComponent,
+  revertAuthoringInstance,
+} from './consumer-actions';
+import { matchesPrefabInstance, prefabInstanceStoryAction } from './prefab-instance-section-model';
+
+function display(value: unknown): string {
+  return typeof value === 'string' ? value : JSON.stringify(value);
+}
+
+function PrefabInstanceSection({ adapter, nodeId }: { adapter: AuthoringAdapter; nodeId: string }) {
+  const description = adapter.instances?.describe(nodeId) ?? null;
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [applyTarget, setApplyTarget] = useState<ComponentInstanceOverride | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    setSelected(new Set());
+    setApplyTarget(null);
+  }, [nodeId]);
+
+  if (!description) return null;
+  const storyAction = prefabInstanceStoryAction(adapter, nodeId);
+
+  const toggle = (path: string, checked: boolean): void => {
+    setSelected((current) => {
+      const next = new Set(current);
+      if (checked) next.add(path);
+      else next.delete(path);
+      return next;
+    });
+  };
+
+  const revertSelected = async (): Promise<void> => {
+    if (selected.size === 0 || !adapter.instances) return;
+    setBusy(true);
+    try {
+      await revertAuthoringInstance(adapter, nodeId, [...selected]);
+      setSelected(new Set());
+      showTransientHint(
+        `Reverted ${selected.size} prefab override${selected.size === 1 ? '' : 's'}.`,
+      );
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const apply = async (): Promise<void> => {
+    if (!applyTarget || !adapter.instances) return;
+    setBusy(true);
+    try {
+      const result = await applyAuthoringInstanceToComponent(adapter, nodeId, applyTarget.path);
+      showTransientHint(result.message);
+      if (result.changed) setApplyTarget(null);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <div style={{ display: 'grid', gap: 10 }} data-testid="prefab-instance-overrides">
+      <FieldRow label="Prefab">
+        <Text>{description.componentName}</Text>
+      </FieldRow>
+      <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap' }}>
+        <Button
+          size="compact"
+          disabled={!adapter.instances?.openComponent}
+          onClick={() => openAuthoringComponent(adapter, nodeId)}
+        >
+          Open Component
+        </Button>
+        <Button
+          size="compact"
+          disabled={!storyAction}
+          title={
+            storyAction ? `Open ${storyAction.story.label}` : 'This prefab has no composed story.'
+          }
+          onClick={() => storyAction?.open()}
+        >
+          Open Story
+        </Button>
+      </div>
+
+      <div>
+        <Text tone="muted">Overrides ({description.overrides.length})</Text>
+        {description.overrides.length === 0 ? (
+          <div style={{ paddingTop: 6 }}>
+            <Text tone="muted">
+              Using component defaults. Change a property above and it will be listed here as an
+              override you can apply or revert.
+            </Text>
+          </div>
+        ) : (
+          <div style={{ display: 'grid', gap: 4, paddingTop: 6 }}>
+            {description.overrides.map((override) => (
+              <div
+                key={override.path}
+                style={{
+                  border: `1px solid ${themeVars.boundary.default}`,
+                  borderRadius: 5,
+                  display: 'grid',
+                  gap: 4,
+                  padding: 6,
+                }}
+              >
+                <label style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+                  <Checkbox
+                    checked={selected.has(override.path)}
+                    onChange={(event) => toggle(override.path, event.target.checked)}
+                  />
+                  <Text>{override.label}</Text>
+                  <Text tone="muted">{display(override.value)}</Text>
+                </label>
+                <div style={{ display: 'flex', alignItems: 'center', gap: 6, paddingLeft: 22 }}>
+                  <Text tone="muted">default: {override.defaultText ?? 'component fallback'}</Text>
+                  <Button
+                    size="compact"
+                    disabled={!override.canApplyToComponent || busy}
+                    title={override.applyUnavailableReason}
+                    onClick={() => setApplyTarget(override)}
+                  >
+                    Apply…
+                  </Button>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+      {description.overrides.length > 0 ? (
+        <Button
+          size="compact"
+          disabled={selected.size === 0 || busy}
+          title={selected.size === 0 ? 'Tick an override above to select it first.' : undefined}
+          onClick={() => void revertSelected()}
+        >
+          Revert Selected
+        </Button>
+      ) : null}
+
+      {applyTarget ? (
+        <Dialog
+          labelledBy="apply-prefab-default-title"
+          onDismiss={() => !busy && setApplyTarget(null)}
+        >
+          <DialogHeader
+            titleId="apply-prefab-default-title"
+            title={`Apply “${applyTarget.label} = ${display(applyTarget.value)}” to ${description.componentName}?`}
+          />
+          <DialogBody>
+            <div style={{ display: 'grid', gap: 8 }}>
+              <Text>
+                This changes the default used by {applyTarget.affectedInstanceCount} placed instance
+                {applyTarget.affectedInstanceCount === 1 ? '' : 's'}.
+              </Text>
+              <FieldRow label="Current default">
+                <Text tone="muted">{applyTarget.defaultText ?? 'component fallback'}</Text>
+              </FieldRow>
+              <FieldRow label="New default">
+                <Text>{display(applyTarget.value)}</Text>
+              </FieldRow>
+            </div>
+          </DialogBody>
+          <DialogFooter>
+            <Button disabled={busy} onClick={() => setApplyTarget(null)}>
+              Cancel
+            </Button>
+            <Button disabled={busy} onClick={() => void apply()}>
+              Apply
+            </Button>
+          </DialogFooter>
+        </Dialog>
+      ) : null}
+    </div>
+  );
+}
+
+function sections(
+  node: EditorNode | null,
+  adapter: AuthoringAdapter,
+): readonly InspectionSection[] {
+  if (!node || !matchesPrefabInstance(node, adapter)) return [];
+  const description = adapter.instances?.describe(node.id);
+  if (!description) return [];
+  return [
+    {
+      id: 'prefab-instance',
+      title: 'Prefab Instance',
+      icon: faCubesStacked,
+      order: GROUP_SECTION_ORDER + 125,
+      body: {
+        kind: 'custom',
+        render: () => <PrefabInstanceSection adapter={adapter} nodeId={node.id} />,
+        data: {
+          component: description.componentName,
+          sourcePath: description.sourcePath ?? null,
+          overrideCount: description.overrides.length,
+          overrides: description.overrides.map((override) => ({
+            path: override.path,
+            value: override.value,
+            default: override.defaultText ?? null,
+            canApplyToComponent: override.canApplyToComponent,
+          })),
+        },
+      },
+    },
+  ];
+}
+
+const registrationGroup = createHmrRegistrationGroup(import.meta.hot, 'prefab-instance-inspector');
+registrationGroup.ensure((track) => {
+  track(registerInspectorSections({ match: matchesPrefabInstance, sections }));
+});

package/src/authoring/prefab-instance-section-model.ts

@@ -0,0 +1,55 @@
+/**
+ * The two decisions the Prefab Instance inspector section makes before it
+ * renders anything: does this selection HAVE a prefab-instance description, and
+ * does it have a story of its own to open.
+ *
+ * They live here rather than inside the section because the section is a React
+ * component in a repo whose unit tests run headless (`environment: 'node'`) —
+ * the same reason `components/inspector-stories-gating.ts` exists. Both are
+ * pure functions of (adapter, node).
+ */
+
+import type { AuthoringAdapter, EditorNode, StoryRef } from '@volter/editor-project/adapter';
+import { resolveNodeScopedStories } from '../components/inspector-stories-gating';
+
+/**
+ * Whether `node` is a component instance this adapter can describe.
+ *
+ * Both halves are load-bearing. `adapter.instances` is OPTIONAL, so an adapter
+ * that has no instances provider at all must not match — the section would then
+ * register for every selection in that world and render nothing, an empty
+ * registered section. (`undefined !== null` is `true`: the absent provider
+ * cannot be tested by comparing its answer.)
+ */
+export function matchesPrefabInstance(node: EditorNode | null, adapter: AuthoringAdapter): boolean {
+  const instances = adapter.instances;
+  if (!node || !instances) return false;
+  return instances.describe(node.id) !== null;
+}
+
+/** The section's "Open Story" affordance, bound to the node's own first story. */
+export interface PrefabInstanceStoryAction {
+  readonly story: StoryRef;
+  /** Put the node's component into that story (opens its story document). */
+  readonly open: () => void;
+}
+
+/**
+ * The story this prefab instance can open, or `null` when it has none.
+ *
+ * Routed through {@link resolveNodeScopedStories} rather than `adapter.stories`
+ * because a world-level provider answers the same rows for EVERY node: on an
+ * ingest root those rows are the game's own scenes, and applying one navigates
+ * the whole game from inside a per-node section. When only a world-level
+ * provider exists this section offers no story action at all — the honest
+ * absence, since the node genuinely has no composed story.
+ */
+export function prefabInstanceStoryAction(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): PrefabInstanceStoryAction | null {
+  const provider = resolveNodeScopedStories(adapter, nodeId);
+  const story = provider?.storiesFor(nodeId)[0];
+  if (!provider || !story) return null;
+  return { story, open: () => provider.apply(nodeId, story.id) };
+}

package/src/authoring/project-authoring-session.ts

@@ -0,0 +1,105 @@
+/** The project owns its authoring session. Scene tabs attach renderers to it;
+ * closing a viewport must not remove the other scenes or component canvases. */
+import type { EditorShellStore } from '../editor-shell-store';
+import { runProjectReady } from '../project-ready';
+import {
+  availableWorkspaceDocuments,
+  requestAvailableWorkspaceDocument,
+} from '../workspace-available-documents';
+import { activeWorkspaceDocumentId, openWorkspaceDocuments } from '../workspace-document-registry';
+import type { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import {
+  bindEditModeRebuildOwner,
+  exitEditModeAuthoring,
+  installEditModeAuthoringForProject,
+} from './edit-mode-authoring';
+
+type Stage = (composite: CompositeAuthoringAdapter) => Promise<void>;
+class ProjectAuthoringSession {
+  private references = 0;
+  private disposed = false;
+  private composite: CompositeAuthoringAdapter | undefined;
+  private disposeDocuments: (() => void) | undefined;
+  private stages = new Set<Stage>();
+  private tail: Promise<void> = Promise.resolve();
+  private unbind: () => void;
+  readonly ready: Promise<void>;
+
+  constructor(private readonly store: EditorShellStore) {
+    this.unbind = bindEditModeRebuildOwner(() => this.rebuild());
+    this.ready = this.rebuild();
+  }
+  retain(): () => void {
+    this.references++;
+    return () => {
+      if (--this.references > 0) return;
+      this.disposed = true;
+      this.unbind();
+      this.disposeDocuments?.();
+      exitEditModeAuthoring(this.composite);
+      sessions.delete(this.store);
+    };
+  }
+  attach(stage: Stage): { ready: Promise<void>; dispose: () => void } {
+    const release = this.retain();
+    this.stages.add(stage);
+    // A stage attached during a rebuild is mounted by that rebuild. A later
+    // stage attaches to the already installed project without reinstalling it.
+    const ready = this.composite ? stage(this.composite) : this.tail;
+    return {
+      ready,
+      dispose: () => {
+        this.stages.delete(stage);
+        release();
+      },
+    };
+  }
+  private rebuild(): Promise<void> {
+    const run = this.tail.then(async () => {
+      if (this.disposed) return;
+      const active = activeWorkspaceDocumentId();
+      const available = new Set(availableWorkspaceDocuments().map((entry) => entry.descriptor.id));
+      const reopen = this.composite
+        ? openWorkspaceDocuments()
+            .map((document) => document.descriptor.id)
+            .filter((id) => available.has(id))
+        : [];
+      this.disposeDocuments?.();
+      this.disposeDocuments = undefined;
+      exitEditModeAuthoring(this.composite);
+      this.composite = undefined;
+      const composite = await installEditModeAuthoringForProject(this.store);
+      if (this.disposed) {
+        exitEditModeAuthoring(composite);
+        return;
+      }
+      const { installRootDocuments } = await import('../components/world-documents');
+      if (this.disposed) {
+        exitEditModeAuthoring(composite);
+        return;
+      }
+      this.composite = composite;
+      this.disposeDocuments = installRootDocuments(this.store, composite);
+      for (const id of reopen) requestAvailableWorkspaceDocument(id, id === active);
+      await Promise.all([...this.stages].map((stage) => stage(composite)));
+    });
+    this.tail = run.catch(() => undefined);
+    return run;
+  }
+}
+const sessions = new Map<EditorShellStore, ProjectAuthoringSession>();
+function sessionFor(store: EditorShellStore): ProjectAuthoringSession {
+  let session = sessions.get(store);
+  if (!session) {
+    session = new ProjectAuthoringSession(store);
+    sessions.set(store, session);
+  }
+  return session;
+}
+export function retainProjectAuthoringSession(store: EditorShellStore) {
+  const session = sessionFor(store);
+  return { ready: session.ready.then(() => runProjectReady()), dispose: session.retain() };
+}
+export function attachProjectAuthoringStage(store: EditorShellStore, stage: Stage) {
+  return sessionFor(store).attach(stage);
+}