@volter/editor-threejs 0.5.134 → 0.5.136

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/editor-threejs",
   "author": "Volter AI, Inc.",
-  "version": "0.5.134",
+  "version": "0.5.136",
   "publishConfig": {
     "access": "public"
   },
@@ -135,12 +135,12 @@
     "serving": "./dist-node/serving.mjs"
   },
   "dependencies": {
-    "@volter/editor-project": "0.5.134",
+    "@volter/editor-project": "0.5.136",
     "@sparkjsdev/spark": "^2.1.0",
     "three.quarks": "^0.16.0",
     "zod": "^4.3.6",
     "typescript": "5.9.3",
-    "@volter/editor-sdk": "0.5.134",
+    "@volter/editor-sdk": "0.5.136",
     "postprocessing": "6.38.3",
     "quarks.core": "0.16.0",
     "@fortawesome/free-solid-svg-icons": "^7.2.0"

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

@@ -174,7 +174,7 @@ export class Object3DDocumentSession {
   private readonly throughOrthographic = new THREE.OrthographicCamera();
   /** The host's mirror of the document scene onto the rendered scene — see
    *  {@link Object3DDocumentSession.setBeforeRender}. */
-  private beforeRender: (() => void | (() => void)) | null = null;
+  private beforeRender: ((interactive: boolean) => void | (() => void)) | null = null;
   private state = INITIAL_PRESENTATION;
   private version = 0;
   private readonly listeners = new Set<() => void>();
@@ -1253,7 +1253,7 @@ export class Object3DDocumentSession {
    * The host owns the step and clears it in its own teardown; the session only
    * holds the reference.
    */
-  setBeforeRender(step: (() => void | (() => void)) | null): void {
+  setBeforeRender(step: ((interactive: boolean) => void | (() => void)) | null): void {
     this.beforeRender = step;
   }
 
@@ -1338,8 +1338,8 @@ export class Object3DDocumentSession {
     for (const resolve of waiters) resolve(frame);
   }
 
-  render(renderSolid: (camera: THREE.Camera) => void): void {
-    const finishDraw = this.beforeRender?.();
+  render(renderSolid: (camera: THREE.Camera) => void, interactive = false): void {
+    const finishDraw = this.beforeRender?.(interactive);
     try {
       this.boneSelectionHighlight?.update();
       const camera = this.camera();
@@ -1391,7 +1391,7 @@ export class Object3DDocumentSession {
   }
 
   /** Visible authoring draw with the editor-only native selection silhouette. */
-  renderViewport(deltaSeconds = 0): void {
+  renderViewport(deltaSeconds = 0, interactive = false): void {
     this.advanceLook(deltaSeconds);
     this.ensureComposer();
     this.render((camera) => {
@@ -1407,7 +1407,7 @@ export class Object3DDocumentSession {
       composer.setMainScene(this.scene);
       composer.setMainCamera(camera);
       composer.render(deltaSeconds);
-    });
+    }, interactive);
   }
 
   resize(width: number, height: number): void {

package/src/kit/components/StageHost.tsx

@@ -1904,9 +1904,11 @@ export function Object3DDocumentViewport({
           }
         };
         host.syncHostScene = syncHostScene;
-        documentSession.setBeforeRender(() => {
+        documentSession.setBeforeRender((interactive) => {
           host.syncHostScene?.();
-          return source.prepareDraw?.(documentSession.camera());
+          const mode = documentSession.presentation().mode;
+          const navigation = interactive && ['solid', 'preview', 'clay', 'unlit', 'matcap'].includes(mode);
+          return source.prepareDraw?.(documentSession.camera(), {interactive: navigation, height: renderer.domElement.height});
         });
         // This loop draws the compass and every other overlay pass over the
         // document's own render, so it — and only it — can serve the chrome
@@ -2007,6 +2009,7 @@ export function Object3DDocumentViewport({
           drawnToneMapping = renderer.toneMapping;
           drawnExposure = renderer.toneMappingExposure;
         };
+        let navigationMeasurement: THREE.Quaternion | null = null;
         const animate = (time: number, resumed: boolean) => {
           if (disposed || !renderer || !viewport) return;
           const activeRenderer = renderer;
@@ -2032,6 +2035,11 @@ export function Object3DDocumentViewport({
           // scene panel uses, so anything riding the loop (a camera flight)
           // has final say over the pose and orbit damping never fights it.
           if (!chromeless) runViewportFrame(documentId, delta);
+          if (navigationMeasurement) {
+            const camera = documentSession.camera();
+            camera.quaternion.copy(navigationMeasurement);
+            camera.updateMatrixWorld(true);
+          }
           viewport.batchedRenderer.update(delta);
           profiler?.endPhase('editor');
           if (!resumed && !mustDraw(advanced)) {
@@ -2050,7 +2058,10 @@ export function Object3DDocumentViewport({
             host.scene.overrideMaterial = scene.overrideMaterial;
           try {
             activeViewport.renderWithInfrastructure(() => {
-              documentSession.renderViewport(delta);
+              // Photographs and the default frame-cost reading draw the
+              // full resident scene. Only navigation may use source-owned
+              // temporary geometry; the source restores it after the draw.
+              documentSession.renderViewport(delta, navigationMeasurement !== null || (!resumed && !documentSession.needsFrame()));
               activeViewport.renderViewCube(activeRenderer);
             });
           } finally {
@@ -2102,7 +2113,7 @@ export function Object3DDocumentViewport({
          * resumed so it draws, run back to back and each waited out on the GPU with a one-pixel
          * read, which a real frame never does; the first frame warms and is not counted.
          */
-        const measureFrameCost = (frames: number): StageFrameCost => {
+        const measureFrameCost = (frames: number, quality: 'full' | 'navigation' = 'full'): StageFrameCost => {
           if (!renderer) throw new Error('This stage has no renderer yet.');
           const activeRenderer = renderer;
           const gl = activeRenderer.getContext();
@@ -2110,17 +2121,31 @@ export function Object3DDocumentViewport({
           const times: number[] = [];
           const submitTimes: number[] = [];
           const completionTimes: number[] = [];
-          for (let index = 0; index <= frames; index++) {
-            const start = performance.now();
-            animate(start, true);
-            const submitted = performance.now();
-            gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
-            const completed = performance.now();
-            if (index > 0) {
-              times.push(completed - start);
-              submitTimes.push(submitted - start);
-              completionTimes.push(completed - submitted);
+          const camera = documentSession.camera();
+          const originalTurn = camera.quaternion.clone();
+          const axis = new THREE.Vector3(0, 1, 0);
+          try {
+            for (let index = 0; index <= frames; index++) {
+              // A real changed camera exercises culling, sorting and the
+              // source's navigation path. Never persist this diagnostic pose.
+              if (quality === 'navigation') navigationMeasurement = originalTurn.clone().multiply(
+                new THREE.Quaternion().setFromAxisAngle(axis, (index + 1) * 0.0005));
+              const start = performance.now();
+              animate(start, true);
+              const submitted = performance.now();
+              gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
+              const completed = performance.now();
+              if (index > 0) {
+                times.push(completed - start);
+                submitTimes.push(submitted - start);
+                completionTimes.push(completed - submitted);
+              }
             }
+          } finally {
+            navigationMeasurement = null;
+            camera.quaternion.copy(originalTurn);
+            camera.updateMatrixWorld(true);
+            dirty = true;
           }
           const drawn = { calls: activeRenderer.info.render.calls, triangles: activeRenderer.info.render.triangles };
           let meshes = 0;
@@ -2141,6 +2166,7 @@ export function Object3DDocumentViewport({
           const median = (values: number[]) => round(values.sort((a, b) => a - b)[Math.floor(values.length / 2)] ?? 0);
           return {
             frames,
+            quality,
             medianMs: round(at(0.5)),
             p95Ms: round(at(0.95)),
             minMs: round(sorted[0] ?? 0),
@@ -2177,7 +2203,7 @@ export function Object3DDocumentViewport({
                   drawCamera: () => host.session?.camera() ?? viewport.camera,
                   orbit: viewport.orbitControls,
                   scene: host.scene,
-                  frameCost: (frames) => measureFrameCost(frames),
+                  frameCost: (frames, quality) => measureFrameCost(frames, quality),
                 },
                 () => null,
                 (kind, object) => viewport.setHelper(kind, object),

package/src/kit/viewport-commands.ts

@@ -193,6 +193,9 @@ export const viewportCommands: CommandContribution['commands'] = {
     const named = cmd['stage'];
     if (named !== undefined && typeof named !== 'string')
       return { ok: false, error: 'document-frame-cost: "stage" names a stage by its document id.' };
+    const quality = cmd['quality'] ?? 'full';
+    if (quality !== 'full' && quality !== 'navigation')
+      return {ok: false, error: 'document-frame-cost: "quality" must be "full" or "navigation".'};
     const documentId = named ?? activeWorkspaceDocumentId();
     const stages = viewportStages();
     const stage = stages.find((one) => one.documentId === documentId);
@@ -206,7 +209,7 @@ export const viewportCommands: CommandContribution['commands'] = {
     const measure = stage.rig().frameCost;
     if (!measure)
       return { ok: false, error: `document-frame-cost: the stage for ${JSON.stringify(stage.documentId)} has no frame of its own to measure.` };
-    return { ok: true, data: { stage: stage.documentId, ...measure(frames) } };
+    return { ok: true, data: { stage: stage.documentId, ...measure(frames, quality) } };
   }, 120_000),
   'capture-viewport': verb(async (store, cmd) => {
     // Fresh, unthrottled on-demand capture (see EditorShellStore.captureViewportImage).

package/src/object3d-contributions.ts

@@ -54,8 +54,10 @@ export interface ToolObject3DPreviewSource {
   update?(deltaSeconds: number): void;
   /** Prepare camera-dependent draw buffers immediately before rendering.
    * Does not advance content time or mutate the authored document. An optional
-   * returned function restores temporary draw state, including after errors. */
-  prepareDraw?(camera: Camera): void | (() => void);
+   * returned function restores temporary draw state, including after errors.
+   * Interactive draws may use disposable navigation geometry; omitted/false
+   * always means full detail (captures and default frame-cost readings). */
+  prepareDraw?(camera: Camera, options?: {interactive: boolean; height: number}): void | (() => void);
   /**
    * EVERY CHANGE TO WHAT THE SOURCE DRAWS, announced: the host calls
    * `listener` whenever the source's graph, materials, textures or poses may

package/src/viewport-api.ts

@@ -32,7 +32,7 @@ export interface ViewportRig {
    * `requestAnimationFrame`, each waited out on the GPU, so the number is the frame's cost and
    * not the display's refresh. Absent on a stage with no frame of its own.
    */
-  frameCost?(frames: number): StageFrameCost;
+  frameCost?(frames: number, quality?: 'full' | 'navigation'): StageFrameCost;
   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;
@@ -101,4 +101,3 @@ export interface ViewportDoor {
   /** Fires whenever a stage mounts or unmounts; the return unsubscribes. */
   onStages(fn: (stages: readonly ViewportStage[]) => void): () => void;
 }
-