@volter/editor-threejs 0.5.211 → 0.5.212

package/src/viewport-door.ts

@@ -1,28 +1,16 @@
 /**
- * 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.
+ * Registry for document stages' viewport rigs, helper displays and frame callbacks. Each mounted
+ * 3D stage binds under its document id and runs its frame hook from its own RAF loop.
  *
- * 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/sdk/host`'s `viewport` member, which is this.
+ * `viewportRig` and `onViewportFrame` follow the primary stage: the focused document's bound
+ * stage, else the first bound. The camera-flight seam reads that rig and uses its frame clock.
+ * `viewportStages()` exposes every bound stage so helpers can be attached to each separately.
+ * Stage subscriptions and helpers survive canvas remounts under the same document id.
  */
 
-import type { ViewportDoor, ViewportPresentation, ViewportRig, ViewportRoot, ViewportStage } from './viewport-api';
-import { activeWorkspaceDocumentId } from '@volter/sdk/kit/workspace-document-registry';
+import type { ViewportDoor, ViewportRig, ViewportStage } from './viewport-api';
+import { activeWorkspaceDocumentId } from '@volter/sdk/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;
@@ -30,25 +18,16 @@ 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.
- */
+/** Retain frame subscribers and helper assignments by document across viewport remounts and before binding. */
 const stageStateByDocument = new Map<
   string,
   {
@@ -75,9 +54,8 @@ function stageStateFor(documentId: string): {
 const primaryFrameListeners = new Set<(dtSeconds: number) => void>();
 const stageListeners = new Set<(stages: readonly ViewportStage[]) => void>();
 
-/** THE PRIMARY STAGE: presenting live roots > focused > first bound. */
+/** THE PRIMARY STAGE: 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);
@@ -115,17 +93,13 @@ function stageDoor(documentId: string, rig: ViewportRig): ViewportStage {
   };
 }
 
-/** 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. */
+/**
+ * Bind a document stage’s rig and helper display under its id. Rebinding replaces the prior
+ * binding; a stale unbind cannot remove its successor. Restore helpers set for this stage before it
+ * bound. Per-document helper assignments remain queued across bindings.
+ */
 export function bindViewportRig(
   rig: ViewportRig,
-  present: Presenter,
   setHelper: HelperSink,
   options: { readonly documentId: string },
 ): () => void {
@@ -133,11 +107,9 @@ export function bindViewportRig(
   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);
@@ -149,42 +121,10 @@ export function bindViewportRig(
   };
 }
 
-/** 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. */
@@ -202,17 +142,7 @@ export function viewportStages(): readonly ViewportStage[] {
   return stagesCache;
 }
 
-/**
- * WHICH HELPER KINDS A STAGE IS HOLDING — the kinds something has actually
- * shown on it through `setHelper` (`@volter/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.
- */
+/** Helper kinds assigned through this package's ViewportStage.setHelper, with cleared entries excluded. */
 export function viewportStageHelperKinds(documentId: string): readonly string[] {
   const state = stageStateByDocument.get(documentId);
   if (!state) return [];

package/contributions/three-integration.service.ts

@@ -1,13 +0,0 @@
-/**
- * The Three integration, installed at boot (`workspace.service`): the Object3D surfaces
- * contributions mount, the viewport's relay verbs, Asset Lab viewers, inspection and hierarchy
- * media, captures, the authoring policy and the session's view-state persistence
- * (`src/kit/three-integration.ts`). Every viewport also ensures it before it mounts.
- */
-import { ensureThreeIntegration } from '../src/kit/three-integration';
-
-export const point = 'workspace.service';
-
-export function start(): () => void {
-  return ensureThreeIntegration();
-}

package/src/adapter/hierarchy-marks.ts

@@ -1,156 +0,0 @@
-/**
- * The hierarchy-presentation convention: how a game tells the editor which
- * parts of its LIVE scene graph are one component instance, and which parts are
- * implementation rather than content.
- *
- * ## Why marks and not a second tree
- *
- * The live tree IS the display surface. A hierarchy derived from source would
- * be a mirror layer — a second model of the world that drifts from the one on
- * screen — so the boundaries a reader needs have to live ON the nodes. That is
- * what these marks are, and it is the whole mechanism: a component WRAPS its
- * functionality and MARKS its root; the editor supports the convention
- * generically and never learns which library, importer or lane produced the
- * node.
- *
- * ## STRUCTURE IS THE TREE'S JOB. MARKS ONLY CLASSIFY.
- *
- * There is deliberately no mark that says "show this row somewhere else". A
- * group owns its children by CONTAINING them; a prefab owns its parts by
- * CONTAINING them. If an object reads as belonging under something it is not
- * parented to, the tree is wrong and the tree is what to fix — because the
- * panel is not the only reader. `getWorldPosition`, raycasting, disposal,
- * `traverse`, every physics or gameplay walk and every person reading the
- * source all follow real parenthood, and a presentation-only "logical parent"
- * would be true for exactly one of them.
- *
- * The usual reason a world gets this wrong is that three's parent chain is a
- * TRANSFORM chain: `matrixWorld` is unconditionally `parent × local`, so an
- * object that must not inherit its owner's pose — a physics-driven body writing
- * a world transform every step, a world-space trail or decal, a follow camera
- * that must escape its target's rotation — gets mounted at the scene root, and
- * ownership is lost as a side effect. **That trade is not necessary.** Set
- * `object.matrixWorldAutoUpdate = false` (three r144+) and the parent's
- * propagation skips it: the object stays parented where it belongs and its
- * `matrixWorld` becomes yours to write. Keep it parented, own the matrix, and
- * the hierarchy needs no help.
- *
- * These two marks then have exactly one job left, which is CLASSIFICATION:
- * which of the objects that really are here is the game, and which is the
- * machinery underneath it.
- *
- * ## What the hierarchy is FOR
- *
- * It shows YOUR GAME: the structure you authored, plus the objects your game
- * makes while it runs. Nothing else. Three consequences, and every rule below
- * follows from them:
- *
- *  - **A spawned object is content.** A bullet you fired, a wave of enemies, a
- *    prop pulled out of a pool and parented into the level — these are rows.
- *    They exist, you can select them, and they are usually the exact things you
- *    opened the panel to look at. An object your game frees stops being a row,
- *    because it stopped existing.
- *  - **An implementation artifact is not.** The bones behind a rig, the batched
- *    renderer behind a particle system, the instanced-mesh pools behind a tile
- *    field, the `target` object three needs in order to aim a directional
- *    light: machinery a library or a helper builds so one thing you DID author
- *    can work. It belongs UNDER that thing, folded, not beside it.
- *  - **"Not in the source file" is the wrong test for either.** Half of a
- *    running world is not in the source file — that is what running means.
- *    Folding spawned gameplay because a document does not name it is the same
- *    defect as listing bones, in the more damaging direction: the rows it loses
- *    are the ones you were looking for.
- *
- * ## The two marks
- *
- * - {@link markComponentRoot} — "this subtree is one instance of `<name>`."
- *   The editor renders it as ONE row, closed, expandable on demand. Put it on
- *   the EARLIEST point the node exists: the constructor that makes it, or the
- *   ref callback that receives it. A component whose root is a plain `<mesh>`
- *   marks that mesh.
- * - {@link markBuiltInternal} — "this is IMPLEMENTATION, not content." It is
- *   **subtree-scoped**: marking the root of a built subtree marks everything
- *   under it, so a 60-bone rig costs one call and folding is transitive. The
- *   editor hides these rows and offers them behind the same "Reveal Internals"
- *   action a source-backed instance's internals already use — revealed rows
- *   are read-only, because there is no authored source for a rename or a
- *   reparent to write to.
- *
- * An instance therefore reads as the parent of everything meaningful beneath
- * it: content nested inside an implementation node is listed under the instance
- * rather than lost with it (the editor's `hierarchy-component-marks.ts` calls
- * that promotion), so marking a rig does not hide the mesh skinned to it.
- *
- * ## Mark it where the subtree is ATTACHED, by whoever attaches it
- *
- * A mark belongs at the attach seam: the code that puts an implementation
- * subtree into the world marks it in the same breath, because that code is the
- * only thing that knows the subtree is implementation. Not a later sweep of the
- * tree — "everything present at time T that the source did not name" is the
- * wrong predicate twice over. It arrives too early for anything attached
- * asynchronously (a model clone landing after its bytes resolve, a node gated
- * on an audio decode) and too late in principle for anything attached
- * afterwards (every spawn) — and were it re-run to catch those, it would
- * classify each spawned object as implementation, which is the second bullet
- * above inverted. Attach-seam marking has neither failure: it fires once, at
- * the moment the answer is known, and an unmarked node is content by default.
- *
- * The subtree scope is what keeps this cheap — one call per attached root, not
- * one per node, so a rig or a pool costs one line at the one place that builds
- * it.
- *
- * ## What is NOT built-internal
- *
- * A node your game means as content — even one a class rather than JSX
- * constructs — is content. `volterBuiltInternal` is not "the editor cannot write
- * this"; that question is `TransformProvider.editability`'s, answered per
- * channel with a sentence. This mark answers "is this implementation", and
- * getting it wrong hides real content.
- *
- * Both keys live in the structural mark registry (`../ecs/object-marks.ts`),
- * which the full typed `userData` registry includes, so
- * their literal strings are spelled exactly once; this module is the only
- * reader/writer, which is why the helpers below exist at all rather than
- * `setUserData` calls scattered through emitters and prefabs.
- */
-
-import type * as THREE from 'three';
-import { getObjectMark, setObjectMark } from '../ecs/object-marks';
-
-/**
- * Declare `node` the root of one component instance, displayed under `name`.
- *
- * `name` is the COMPONENT's name (`'Coin'`, `'HeroBox'`), not the instance's —
- * the instance is already named by `node.name`, and the editor prints both.
- */
-export function markComponentRoot(node: THREE.Object3D, name: string): void {
-  setObjectMark(node, 'volterComponentRoot', name);
-}
-
-/** The component name `node` is the root of, or `undefined` for an ordinary node. */
-export function componentRootName(node: THREE.Object3D | null | undefined): string | undefined {
-  const name = getObjectMark(node, 'volterComponentRoot');
-  return typeof name === 'string' && name ? name : undefined;
-}
-
-/** Whether `node` is a marked component-instance root. */
-export function isComponentRoot(node: THREE.Object3D | null | undefined): boolean {
-  return componentRootName(node) !== undefined;
-}
-
-/**
- * Declare `node` (and everything under it) IMPLEMENTATION of whatever node it
- * sits under, rather than content of its own. Call it on the ROOT of the built
- * subtree only, at the seam that attaches it — see this module's header for why
- * the seam and not a sweep.
- */
-export function markBuiltInternal(node: THREE.Object3D): void {
-  setObjectMark(node, 'volterBuiltInternal', true);
-}
-
-/** Whether `node` itself carries the implementation mark. Ancestry is the
- *  CALLER's walk — see this module's header for why the mark is subtree-scoped
- *  but not restamped onto descendants. */
-export function isBuiltInternal(node: THREE.Object3D | null | undefined): boolean {
-  return getObjectMark(node, 'volterBuiltInternal') === true;
-}