@volter/editor-threejs 0.5.211 → 0.5.212

package/src/kit/asset-workflow/model-inspection.ts

@@ -98,41 +98,6 @@ export function classifyModelStructure(
   return 'static';
 }
 
-export interface Object3DNodeInspection {
-  readonly type: string;
-  readonly visible: boolean;
-  readonly children: number;
-  readonly descendants: number;
-  readonly renderOrder: number;
-  readonly layers: number;
-  readonly geometry: null | {
-    readonly vertices: number;
-    readonly triangles: number;
-    readonly indexed: boolean;
-    readonly attributes: readonly string[];
-    readonly uvChannels: readonly string[];
-    readonly morphTargets: number;
-    readonly nonFiniteAttributeValues: number;
-    readonly bounds: { x: number; y: number; z: number } | null;
-  };
-  readonly materials: Array<{
-    readonly id: string;
-    readonly name: string;
-    readonly type: string;
-    readonly color: string | null;
-    readonly textureSlots: readonly string[];
-  }>;
-  readonly skin: null | {
-    readonly bones: number;
-    readonly rootBones: readonly string[];
-    readonly bindMode: string;
-  };
-  readonly bone: null | {
-    readonly parent: string | null;
-    readonly children: readonly string[];
-  };
-}
-
 interface SkinWeightInspection {
   readonly weightedVertices: number;
   readonly nonNormalizedVertices: number;
@@ -155,16 +120,14 @@ const textureKeys = [
   'specularMap',
 ] as const;
 
-/**
- * A material's base colour as hex, or `null` when it has none.
- *
- * `.isColor` rather than `instanceof THREE.Color`: these roots arrive from
- * `../authoring/source-object3d-authoring-adapter.ts` and the selection
- * inspector, so under the packaged runtime the material was constructed by the
- * PROJECT's own `three` module and its `Color` is not the shell's constructor.
- * `instanceof` there reports every authored colour as absent. Same rule and
- * same reason as `../authoring/three-scene-identity.ts`.
- */
+/** The URL a texture's image was loaded from, when it has one (an HTMLImageElement's `src`); r186
+ *  types a texture's source data by its image parameter, unknown here. */
+function sourceUrl(texture: THREE.Texture): string | undefined {
+  const data = texture.source.data as { src?: unknown } | null | undefined;
+  return typeof data?.src === 'string' ? data.src : undefined;
+}
+
+/** Read a material’s base color as hex, or null when absent. The isColor brand supports other realms. */
 function materialColorHex(material: THREE.Material): string | null {
   if (!('color' in material)) return null;
   const color = (material as THREE.Material & { color?: THREE.Color }).color;
@@ -354,10 +317,7 @@ export function inspectModel(root: THREE.Object3D): ModelInspection {
       materialUsers.set(material, users);
       const slots = materialSlots.get(material) ?? [];
       for (const key of textureKeys) {
-        // Structural brand, not `instanceof`: these roots arrive from
-        // `source-object3d-authoring-adapter.ts` and the selection inspector,
-        // so under the packaged runtime the material was built by the
-        // PROJECT's `three`. See `../authoring/three-scene-identity.ts`.
+        // Use the structural material brand for objects supplied by project modules.
         const texture = (material as THREE.Material & Record<string, unknown>)[key] as
           | THREE.Texture
           | undefined;
@@ -374,7 +334,7 @@ export function inspectModel(root: THREE.Object3D): ModelInspection {
             materialId: material.uuid,
             materialName: material.name || material.type,
             slot: key,
-            textureName: texture.name || texture.source.data?.src || 'Texture',
+            textureName: texture.name || sourceUrl(texture) || 'Texture',
             width: image?.width ?? null,
             height: image?.height ?? null,
             format: texture.format,
@@ -438,7 +398,7 @@ export function inspectModel(root: THREE.Object3D): ModelInspection {
     hierarchy,
     materialNames: [...materials].map((material) => material.name || material.type),
     textureNames: [...textures].map(
-      (texture) => texture.name || texture.source.data?.src || 'Texture',
+      (texture) => texture.name || sourceUrl(texture) || 'Texture',
     ),
     materialSlots: [...materials].map((material) => ({
       id: material.uuid,
@@ -600,87 +560,6 @@ export function inspectModelRig(root: THREE.Object3D): ModelRigInspection {
   };
 }
 
-function inspectNodeGeometry(geometry: THREE.BufferGeometry | undefined) {
-  if (!geometry) return null;
-  const size = geometryBounds(geometry)?.getSize(new THREE.Vector3());
-  const position = geometry.getAttribute('position');
-  return {
-    vertices: position?.count ?? 0,
-    triangles: Math.floor((geometry.index?.count ?? position?.count ?? 0) / 3),
-    indexed: geometry.index !== null,
-    attributes: Object.keys(geometry.attributes).sort(),
-    uvChannels: Object.keys(geometry.attributes)
-      .filter((name) => /^uv\d*$/.test(name))
-      .sort(),
-    morphTargets: geometry.morphAttributes['position']?.length ?? 0,
-    nonFiniteAttributeValues: countNonFiniteAttributeValues(geometry),
-    bounds: size ? { x: size.x, y: size.y, z: size.z } : null,
-  } satisfies NonNullable<Object3DNodeInspection['geometry']>;
-}
-
-function inspectNodeMaterials(mesh: THREE.Mesh): Object3DNodeInspection['materials'] {
-  const objectMaterials = Array.isArray(mesh.material)
-    ? mesh.material
-    : mesh.material
-      ? [mesh.material]
-      : [];
-  return objectMaterials.map((material) => ({
-    id: material.uuid,
-    name: material.name || material.type,
-    type: material.type,
-    color: materialColorHex(material),
-    textureSlots: textureKeys.filter(
-      (key) =>
-        ((material as THREE.Material & Record<string, unknown>)[key] as THREE.Texture | undefined)
-          ?.isTexture === true,
-    ),
-  }));
-}
-
-function inspectNodeSkin(object: THREE.Object3D): Object3DNodeInspection['skin'] {
-  const mesh = object as THREE.SkinnedMesh;
-  if (!mesh.isSkinnedMesh) return null;
-  return {
-    bones: mesh.skeleton.bones.length,
-    rootBones: mesh.skeleton.bones
-      .filter((bone) => !(bone.parent as THREE.Bone | null)?.isBone)
-      .map((bone) => bone.name || bone.uuid),
-    bindMode: mesh.bindMode,
-  };
-}
-
-function inspectNodeBone(object: THREE.Object3D): Object3DNodeInspection['bone'] {
-  const bone = object as THREE.Bone;
-  if (!bone.isBone) return null;
-  return {
-    parent: (bone.parent as THREE.Bone | null)?.isBone
-      ? bone.parent?.name || bone.parent?.uuid || null
-      : null,
-    children: bone.children
-      .filter((child): child is THREE.Bone => (child as THREE.Bone).isBone)
-      .map((child) => child.name || child.uuid),
-  };
-}
-
-/** Inspect one selected native node without manufacturing an authored descriptor. */
-export function inspectObject3DNode(object: THREE.Object3D): Object3DNodeInspection {
-  let descendants = -1;
-  object.traverse(() => descendants++);
-  const mesh = object as THREE.Mesh;
-  return {
-    type: object.type,
-    visible: object.visible,
-    children: object.children.length,
-    descendants,
-    renderOrder: object.renderOrder,
-    layers: object.layers.mask,
-    geometry: inspectNodeGeometry(mesh.geometry),
-    materials: inspectNodeMaterials(mesh),
-    skin: inspectNodeSkin(object),
-    bone: inspectNodeBone(object),
-  };
-}
-
 export type ModelDiagnosticMode =
   | 'lit'
   | 'unlit'
@@ -806,25 +685,3 @@ export function rootMotionTrailPoints(clip: THREE.AnimationClip): THREE.Vector3[
   }
   return points;
 }
-
-/** Resolve a hierarchy/material row to the preview objects it represents. */
-export function modelSelectionObjects(
-  root: THREE.Object3D,
-  selection: { kind: 'node' | 'material'; id: string },
-): THREE.Object3D[] {
-  if (selection.kind === 'node') {
-    const object = root.getObjectByProperty('uuid', selection.id);
-    return object ? [object] : [];
-  }
-  const selected: THREE.Object3D[] = [];
-  root.traverse((object) => {
-    const mesh = object as THREE.Mesh;
-    const materials = Array.isArray(mesh.material)
-      ? mesh.material
-      : mesh.material
-        ? [mesh.material]
-        : [];
-    if (materials.some((material) => material.uuid === selection.id)) selected.push(mesh);
-  });
-  return selected;
-}

package/src/kit/asset-workflow/preview-resource-lifetime.ts

@@ -0,0 +1,25 @@
+export type PreviewResourceKind =
+  | 'webglContext'
+  | 'animationFrame'
+  | 'resizeObserver'
+  | 'objectUrl';
+
+const current: Record<PreviewResourceKind, number> = {
+  webglContext: 0,
+  animationFrame: 0,
+  resizeObserver: 0,
+  objectUrl: 0,
+};
+const peaks = { ...current };
+
+/** Local diagnostic counter used by stress tests and the Debugger; never uploads identifiers. */
+export function registerPreviewResource(kind: PreviewResourceKind): () => void {
+  current[kind]++;
+  peaks[kind] = Math.max(peaks[kind], current[kind]);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    current[kind] = Math.max(0, current[kind] - 1);
+  };
+}

package/src/kit/authoring/component-instance-root.ts

@@ -105,50 +105,14 @@ function forwardedCallsiteOid(object: THREE.Object3D | null | undefined): string
  * same oid twice, and both mint the same shape of id: the first one seen in
  * depth-first order keeps the bare address, later ones get `#1`, `#2`, ….
  *
- * The suffix is spelled HERE and nowhere else. It was previously written out at
- * four sites — two minting walks (`projection/three.ts`,
- * `R3fSourceAuthoringAdapter.indexGraph`), one authority check, and one
- * presence report that stripped it back off with `split('#')[0]` — which is how
- * a convention becomes four conventions.
+ * The suffix is spelled HERE and nowhere else: the minting walks
+ * (`projection/three.ts`, `R3fSourceAuthoringAdapter.indexGraph`), the authority
+ * check and the presence report all use this one.
  */
 export function occurrenceId(baseId: string, occurrence: number): string {
   return occurrence === 0 ? baseId : `${baseId}#${occurrence}`;
 }
 
-/** True for `…#1`, `…#2` — an id that is NOT its address's first occurrence. */
-export function isOccurrenceId(id: string): boolean {
-  return id.includes('#');
-}
-
-/** `id` with any occurrence suffix removed — the address all its occurrences share. */
-export function withoutOccurrence(id: string): string {
-  const hash = id.indexOf('#');
-  return hash < 0 ? id : id.slice(0, hash);
-}
-
-/**
- * Whether two live objects are renders of THE SAME JSX element.
- *
- * This is the CAPABILITY question behind an occurrence id, and it is the whole
- * reason the two causes above must not be treated alike. N objects that share
- * one callsite AND render one definition element are N renders of one element;
- * the element is the unit of edit, so a literal prop on it is honestly
- * writable and moving one moves all — which is exactly what the source says. A
- * reparented interior element renders a DIFFERENT definition element, merely
- * addressed by the callsite it escaped from, so writing that callsite's props
- * would edit the instance instead of the object under the pointer.
- *
- * Both objects having no own oid counts as the same element: an unstamped pair
- * is a component with several spatial roots (R3F003), which the callsite's own
- * authoring contract already refuses on better grounds than a guess here.
- */
-export function rendersSameSourceElement(
-  a: THREE.Object3D | null | undefined,
-  b: THREE.Object3D | null | undefined,
-): boolean {
-  return ownOidOf(a) === ownOidOf(b);
-}
-
 /**
  * The oid that ADDRESSES `object` in source — the key every id, source
  * location and prop write resolves through.

package/src/kit/authoring/live-object-transform.ts

@@ -1,33 +1,4 @@
-/**
- * Reading the transform of a LIVE `Object3D` the editor did not write.
- *
- * THE TRAP, measured on the racing-game ingest (2026-08-15). A physics library
- * that drives a node writes the node's MATRIX and turns matrix composition off:
- * `@react-three/cannon`'s frame handler is literally
- * `object.matrixAutoUpdate = false; object.matrix.copy(m)`. Three never
- * decomposes that back, so `object.position`/`.quaternion`/`.scale` keep
- * whatever they held when the body was created — forever. Everything derived
- * from `matrixWorld` (selection brackets, bounds, three's own
- * `TransformControls`) tracks the truth, while everything derived from
- * `.position` shows the spawn point. Measured side by side: the driven chassis
- * reported `[-110, 0.75, 220]` in the Inspector while the game's own state
- * provider put it at `(-24.5, 0.85, 186.2)`.
- *
- * That mismatch is worse than a wrong number: origin markers and gizmo anchors
- * derived from `.position` sit somewhere the object is not, while the bounding
- * box around them is correct, so the editor contradicts itself on screen.
- *
- * THE RULE: **when a node owns its own matrix (`matrixAutoUpdate === false`),
- * the MATRIX is the transform.** Decompose it — through three's own
- * `Matrix4.decompose`, never a re-derivation. Otherwise the vector fields are
- * authoritative and are read directly: deliberately not "always decompose",
- * because for an ordinary node `matrix` is one frame BEHIND a write the editor
- * just made, and reading it back would make a gizmo drag stutter.
- *
- * Nothing here is library-specific: the predicate is three's own flag, so any
- * driver following the same convention (cannon, a custom integrator, an
- * animation system baking matrices) is covered without naming it.
- */
+/** Read matrix-driven Object3D transforms by decomposing matrix when matrixAutoUpdate is false; otherwise use position, quaternion and scale. Do not rewrite the object. */
 
 import * as THREE from 'three';
 

package/src/kit/authoring/object3d-document-session-registry.ts

@@ -1,20 +1,18 @@
 /**
  * Lightweight registry for live Object3D document sessions.
  *
- * State/control readers only need to find a session that some document has
- * already constructed. Keeping this map beside the implementation made every
- * reader load the implementation's postprocessing, skeleton, outline and
- * diagnostic-rendering graph during a plain Scene boot. The class remains the
- * native session type; this module owns only its live identities.
+ * State/control readers find sessions constructed by their documents. The implementation
+ * dependency is type-only; this module owns live identities and lazily loads the document
+ * toolbar without importing the session's rendering implementation.
  */
-import { startingPresentation, viewGridVisible, viewPresentationBinding } from '@volter/sdk/kit/viewport-presentation';
+import { startingPresentation, viewGridVisible, viewPresentationBinding } from '@volter/sdk/viewport-presentation';
 import {
   type DocumentViewport,
   registerDocumentViewport,
-} from '@volter/sdk/kit/document-viewports';
+} from '@volter/sdk/document-viewports';
 import { lazy } from 'react';
 import type { Object3DDocumentSession } from './object3d-document-session';
-import { registerDocumentStageSession } from '@volter/sdk/kit/document-stage-sessions';
+import { registerDocumentStageSession } from '@volter/sdk/document-stage-sessions';
 
 // The document header's shading, helpers and capture menus. Behind `lazy()`, so
 // this registry stays the light read it is for every other caller.
@@ -66,7 +64,7 @@ export function registerObject3DDocumentSession(
 const xyz = ([x, y, z]: readonly [number, number, number]) => ({ x, y, z });
 
 /** An Object3D document's own viewport: its session's camera, view mode, grid,
- *  framing, selection and photograph (`@volter/sdk/kit/document-viewports`). */
+ *  framing, selection and photograph (`@volter/sdk/document-viewports`). */
 function object3DDocumentViewport(session: Object3DDocumentSession): DocumentViewport {
   type Preset = Parameters<Object3DDocumentSession['setViewPreset']>[0];
   type Mode = Parameters<Object3DDocumentSession['setMode']>[0];
@@ -155,9 +153,3 @@ export function subscribeObject3DDocumentSessions(listener: () => void): () => v
 export function object3DDocumentSessionsVersion(): number {
   return registryVersion;
 }
-
-export function __resetObject3DDocumentSessionsForTest(): void {
-  sessions.clear();
-  preparations.clear();
-  notifyRegistry();
-}