@volter/editor-threejs 0.5.65 → 0.5.67

package/src/viewport-api.ts

@@ -0,0 +1,92 @@
+/**
+ * THE AUTHORED THREE VIEWPORT'S PUBLIC SHAPE — what a lane that mounts something reaches through
+ * `viewport-door.ts`: the rig a camera flight drives, the frame loop it rides, the helpers it
+ * shows, every mounted stage, and the one verb that swaps the viewport's subject for a live
+ * instance's roots (Play's adoption of the running scene).
+ */
+import type { MountedRoot } from '@volter/editor-project/adapter/root-adapter';
+import type * as THREE from 'three';
+
+/** A live instance's roots, presented as the authored viewport's subject. */
+export interface ViewportPresentation {
+  /** The root whose native subject the viewport shows. */
+  readonly worldId: string;
+  /** Restores the viewport's prior subject; idempotent. */
+  dispose(): void;
+}
+
+/** The authored viewport's camera rig, while a viewport is mounted. */
+export interface ViewportRig {
+  readonly camera: THREE.PerspectiveCamera;
+  /** The camera the stage draws with NOW: {@link camera}, or the orthographic one in an
+   *  orthographic view. What a document lighting or picking in step with the picture needs. */
+  drawCamera(): THREE.Camera;
+  readonly orbit: { readonly target: THREE.Vector3; enabled: boolean; update(): void };
+  /** The editor's own scene (helpers live on its editor layer). */
+  readonly scene: THREE.Scene;
+}
+
+/**
+ * ONE MOUNTED 3D STAGE, named by the document it draws. Every 3D document
+ * mounts a stage of its own (ARCHITECTURE-CORE §One stage); this is the door
+ * to a particular one, where the viewport door's singular members
+ * are the door to whichever is primary.
+ */
+export interface ViewportStage {
+  /** The workspace document this stage draws. */
+  readonly documentId: string;
+  rig(): ViewportRig;
+  /** As the viewport door's `setHelper`, on this stage alone. */
+  setHelper(kind: string, object: THREE.Object3D | null): void;
+  /** Runs after THIS stage's own per-frame update; the return unsubscribes. */
+  onFrame(fn: (dtSeconds: number) => void): () => void;
+}
+
+/**
+ * THE AUTHORED VIEWPORT, as a lane that mounts something reaches it: the rig
+ * a camera flight drives, the frame loop it rides, and the one verb that
+ * swaps the viewport's subject for a live instance's roots (Play's adoption
+ * of the running scene). Which native surface the viewport renders is the
+ * host's; a lane that finds no rig (a headless tab, a project with no Three
+ * root) mounts without one.
+ *
+ * THE SINGULAR MEMBERS ARE THE PRIMARY STAGE — the stage presenting live
+ * roots if one is, else the FOCUSED stage, else the first bound. A camera
+ * flight and Play's adoption want exactly that one, which is why they read
+ * here and never enumerate.
+ *
+ * {@link stages} is EVERY mounted 3D stage. A helper is an `Object3D` and an
+ * `Object3D` has one parent, so there is no "set it once for all stages": a
+ * helper wanted on every stage is set on each stage through `stages()`, and
+ * `onStages` is how a lane keeps up with stages that mount and unmount after
+ * it made that pass.
+ */
+/** A mounted adapter surface offered to the viewport. Execution, input and
+ * ticking stay with the caller; presentation requires only identity and mount.
+ * A game's richer root instance can satisfy this interface directly.
+ */
+export interface ViewportRoot {
+  readonly id: string;
+  readonly mounted: MountedRoot;
+}
+
+export interface ViewportDoor {
+  rig(): ViewportRig | null;
+  /** Null when the viewport has no subject among `roots` (no Three root). */
+  presentRoots(roots: readonly ViewportRoot[]): ViewportPresentation | null;
+  /** Runs after the viewport's own per-frame update; the return unsubscribes. */
+  onFrame(fn: (dtSeconds: number) => void): () => void;
+  /**
+   * Show an editor-only helper object of `kind` in the authored viewport (a
+   * baked navmesh's debug mesh), replacing the previous one of that kind;
+   * null clears it. Visibility follows the host's Helpers menu: a kind the
+   * menu lists (`navmesh`) toggles on its own, any other follows the master
+   * toggle. Kept across viewport remounts.
+   */
+  setHelper(kind: string, object: THREE.Object3D | null): void;
+  /** Every mounted 3D stage, in bind order. */
+  stages(): readonly ViewportStage[];
+  /** Fires whenever a stage mounts or unmounts; the return unsubscribes. */
+  onStages(fn: (stages: readonly ViewportStage[]) => void): () => void;
+}
+

package/src/viewport-door.ts

@@ -0,0 +1,237 @@
+/**
+ * THE AUTHORED VIEWPORT'S DOOR — the host's side of `host.viewport` (WORK.md
+ * §Play leaves the host, P2). Every mounted 3D STAGE binds its rig and its
+ * presenter here under its own document id (ARCHITECTURE-CORE §One stage:
+ * there is one stage host, mounted once per 3D document, and the door is per
+ * stage) and drives its frame hook from its own RAF loop; the lanes that
+ * mount something (Play's adoption of the live scene, the play-entry camera
+ * flight) read here and never hold a panel.
+ *
+ * The SINGULAR members — `viewportRig`, `presentViewportRoots`,
+ * `setViewportHelper`, `onViewportFrame` — resolve THE PRIMARY STAGE at call
+ * time: the stage presenting live roots if one is, else the FOCUSED stage
+ * (`activeWorkspaceDocumentId()`'s), else the first bound. Focus and
+ * presentation are the two facts; nothing here is "the scene viewport" by
+ * name. `viewportStages()` is every stage, for the lane that must touch each
+ * one (a helper `Object3D` has one parent, so it is set per stage).
+ *
+ * Until the lanes move, the host's own lanes import this registry directly; a
+ * package reads `@volter/editor-sdk/host`'s `viewport` member, which is this.
+ */
+
+import type { ViewportDoor, ViewportPresentation, ViewportRig, ViewportRoot, ViewportStage } from './viewport-api';
+import { activeWorkspaceDocumentId } from '@volter/editor-sdk/kit/workspace-document-registry';
+
+type Presenter = (roots: readonly ViewportRoot[]) => ViewportPresentation | null;
+/** An editor-only helper object, typed by the host door it is shown through. */
+type HelperObject = Parameters<ViewportDoor['setHelper']>[1];
+type HelperSink = (kind: string, object: HelperObject) => void;
+
+interface Binding {
+  readonly documentId: string;
+  readonly rig: ViewportRig;
+  readonly present: Presenter;
+  readonly setHelper: HelperSink;
+  readonly frameListeners: Set<(dtSeconds: number) => void>;
+  /** Helpers set on THIS stage by kind, so a re-bind restores them. */
+  readonly helpers: Map<string, HelperObject>;
+  /** A presentation of live roots is alive on this stage right now. */
+  presenting: boolean;
+}
+
+/** Every bound stage, keyed by the document it draws; insertion-ordered, so
+ *  "the first bound" is a real answer. */
+const bound = new Map<string, Binding>();
+/**
+ * What belongs to the STAGE rather than to its current canvas, held by
+ * document id so it OUTLIVES a binding: its frame subscribers and its
+ * helpers. A stage's viewport remounts (a dock re-layout, HMR) without its
+ * baked navmesh having to be re-baked — the `setHelper` contract the SDK
+ * states — and without a lane's `onFrame` going quiet.
+ */
+const stageStateByDocument = new Map<
+  string,
+  {
+    readonly frameListeners: Set<(dtSeconds: number) => void>;
+    readonly helpers: Map<string, HelperObject>;
+  }
+>();
+
+function stageStateFor(documentId: string): {
+  readonly frameListeners: Set<(dtSeconds: number) => void>;
+  readonly helpers: Map<string, HelperObject>;
+} {
+  let state = stageStateByDocument.get(documentId);
+  if (!state) {
+    state = { frameListeners: new Set(), helpers: new Map() };
+    stageStateByDocument.set(documentId, state);
+  }
+  return state;
+}
+/** Listeners on the singular `onViewportFrame`: they follow the PRIMARY
+ *  stage, so they are held here and fanned in rather than added to a
+ *  binding's own set, which would strand them on a stage that stops being
+ *  primary (or unmounts). */
+const primaryFrameListeners = new Set<(dtSeconds: number) => void>();
+const stageListeners = new Set<(stages: readonly ViewportStage[]) => void>();
+
+/** THE PRIMARY STAGE: presenting live roots > focused > first bound. */
+function primary(): Binding | null {
+  for (const binding of bound.values()) if (binding.presenting) return binding;
+  const focused = activeWorkspaceDocumentId();
+  if (focused !== null) {
+    const match = bound.get(focused);
+    if (match) return match;
+  }
+  return bound.values().next().value ?? null;
+}
+
+let stagesCache: readonly ViewportStage[] | null = null;
+
+function notifyStages(): void {
+  stagesCache = null;
+  const snapshot = viewportStages();
+  for (const fn of stageListeners) fn(snapshot);
+}
+
+/** A stage door resolves its binding BY ID on every call, so a door held
+ *  across that stage's remount keeps driving the live canvas rather than the
+ *  disposed one. */
+function stageDoor(documentId: string, rig: ViewportRig): ViewportStage {
+  const state = stageStateFor(documentId);
+  return {
+    documentId,
+    rig: () => bound.get(documentId)?.rig ?? rig,
+    setHelper: (kind, object) => {
+      state.helpers.set(kind, object);
+      bound.get(documentId)?.setHelper(kind, object);
+    },
+    onFrame: (fn) => {
+      state.frameListeners.add(fn);
+      return () => {
+        state.frameListeners.delete(fn);
+      };
+    },
+  };
+}
+
+/** A mounted stage binds its rig, how it presents live roots and how it shows
+ *  a helper, under the id of the document it draws; the return unbinds (a
+ *  re-bind for the same id REPLACES, and a stale binding's unbind never
+ *  removes its successor). Helpers set through the singular door before the
+ *  bind are applied now, the way they always were — but "before the bind" is
+ *  now per stage: a helper shown on THIS document's stage returns to it, and
+ *  a helper set while nothing is bound anywhere is dropped rather than
+ *  appearing on whichever stage happens to mount next. */
+export function bindViewportRig(
+  rig: ViewportRig,
+  present: Presenter,
+  setHelper: HelperSink,
+  options: { readonly documentId: string },
+): () => void {
+  const state = stageStateFor(options.documentId);
+  const next: Binding = {
+    documentId: options.documentId,
+    rig,
+    present,
+    setHelper,
+    frameListeners: state.frameListeners,
+    helpers: state.helpers,
+    presenting: false,
+  };
+  bound.set(options.documentId, next);
+  for (const [kind, object] of next.helpers) setHelper(kind, object);
+  notifyStages();
+  return () => {
+    if (bound.get(options.documentId) !== next) return;
+    bound.delete(options.documentId);
+    notifyStages();
+  };
+}
+
+/** Show (or clear with null) the editor-only helper of `kind` on the PRIMARY
+ *  stage. A helper wanted on every stage is set per stage through
+ *  {@link viewportStages} — an `Object3D` has one parent. */
+export function setViewportHelper(kind: string, object: HelperObject): void {
+  const stage = primary();
+  if (!stage) return;
+  stage.helpers.set(kind, object);
+  stage.setHelper(kind, object);
+}
+
+export function viewportRig(): ViewportRig | null {
+  return primary()?.rig ?? null;
+}
+
+export function presentViewportRoots(roots: readonly ViewportRoot[]): ViewportPresentation | null {
+  const stage = primary();
+  if (!stage) return null;
+  const presentation = stage.present(roots);
+  if (!presentation) return null;
+  // The stage stays PRIMARY for as long as it is showing live roots — that is
+  // what makes Play's own camera flight and frame hook keep finding it while
+  // focus moves to the live document.
+  stage.presenting = true;
+  let released = false;
+  return {
+    worldId: presentation.worldId,
+    dispose: () => {
+      if (!released) {
+        released = true;
+        stage.presenting = false;
+      }
+      presentation.dispose();
+    },
+  };
+}
+
+/** Runs after the PRIMARY stage's own per-frame update, and RE-TARGETS: the
+ *  listener follows whichever stage is primary, not the one that was primary
+ *  when it subscribed. */
+export function onViewportFrame(fn: (dtSeconds: number) => void): () => void {
+  primaryFrameListeners.add(fn);
+  return () => {
+    primaryFrameListeners.delete(fn);
+  };
+}
+
+/** Every bound stage, in bind order. */
+export function viewportStages(): readonly ViewportStage[] {
+  if (!stagesCache)
+    stagesCache = [...bound.values()].map((binding) => stageDoor(binding.documentId, binding.rig));
+  return stagesCache;
+}
+
+/**
+ * WHICH HELPER KINDS A STAGE IS HOLDING — the kinds something has actually
+ * shown on it through `setHelper` (`@volter/editor-sdk/host`,
+ * `ViewportStage.setHelper`), cleared ones excluded.
+ *
+ * It exists because a 3D document's own OVERLAYS MENU must follow what the
+ * document put there and nothing else (`Object3DDocumentToolbar`): Blender's
+ * viewport overlay popover lists Bones, and ours may not list a Bones row over
+ * a document that has no bones to show. Same rule as the Outliner's restriction
+ * columns — a control follows what the thing behind it ANSWERS, never a knob.
+ */
+export function viewportStageHelperKinds(documentId: string): readonly string[] {
+  const state = stageStateByDocument.get(documentId);
+  if (!state) return [];
+  return [...state.helpers].filter(([, object]) => object !== null).map(([kind]) => kind);
+}
+
+export function onViewportStages(fn: (stages: readonly ViewportStage[]) => void): () => void {
+  stageListeners.add(fn);
+  return () => {
+    stageListeners.delete(fn);
+  };
+}
+
+/** A stage's RAF loop calls this after its own update each frame. The stage's
+ *  own listeners always run; the primary-stage listeners run here only when
+ *  this stage IS the primary. */
+export function runViewportFrame(documentId: string, dtSeconds: number): void {
+  const binding = bound.get(documentId);
+  if (!binding) return;
+  for (const fn of binding.frameListeners) fn(dtSeconds);
+  if (primary() === binding) for (const fn of primaryFrameListeners) fn(dtSeconds);
+}