@volter/editor-threejs 0.5.92 → 0.5.94

package/package.json

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

package/src/kit/components/Object3DDocumentToolbar.tsx

@@ -13,6 +13,7 @@ import {
   Button,
   EditorBanner,
   EditorIcon,
+  editorIcons,
   EditorPopover,
   EditorToolbar,
   IconButton,
@@ -430,6 +431,20 @@ export function Object3DDocumentToolbar({
             </Text>
           </label>
         </ViewportDisplayModeMenu>
+        {/* BLENDER'S SHOW GIZMO (`View3D.show_gizmo`), beside Show Overlays as Blender's header
+            has them: this stage's transform and navigation gizmos, apart from its overlays. */}
+        {stage === null ? null : (
+          <Tooltip text={`Gizmos: ${stage.showGizmos ? 'On' : 'Off'}`}>
+            <IconButton
+              aria-label="Toggle gizmos"
+              aria-pressed={stage.showGizmos}
+              size="comfortable"
+              onClick={() => stage.toggleGizmos()}
+            >
+              <EditorIcon icon={editorIcons.viewport.gizmos} size="md" />
+            </IconButton>
+          </Tooltip>
+        )}
         {/* THE EYE WAS THE OVERLAYS CONTROL ALL ALONG — measured by what it
             toggles, which is Grid and Bounds, exactly Blender's Show Overlays
             subject. It takes Blender's mark, and Blender's split toggle+chevron:

package/src/kit/components/StageHost.tsx

@@ -80,6 +80,7 @@ import {
   recordViewportFirstFrame,
 } from '@volter/editor-sdk/kit/viewport-activation-timings';
 import { bindViewportRig, runViewportFrame } from '../../viewport-door';
+import type { StageFrameCost } from '../../viewport-api';
 import {
   notifyWorkspaceDocumentSelectionChanged,
   openWorkspaceDocuments,
@@ -2089,6 +2090,54 @@ export function Object3DDocumentViewport({
         };
 
         host.frame = animate;
+        /**
+         * THE FRAME WITHOUT THE DISPLAY'S CAP (`ViewportRig.frameCost`): this stage's own `animate`,
+         * 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 => {
+          if (!renderer) throw new Error('This stage has no renderer yet.');
+          const activeRenderer = renderer;
+          const gl = activeRenderer.getContext();
+          const pixel = new Uint8Array(4);
+          const times: number[] = [];
+          for (let index = 0; index <= frames; index++) {
+            const start = performance.now();
+            animate(start, true);
+            gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
+            if (index > 0) times.push(performance.now() - start);
+          }
+          const drawn = { calls: activeRenderer.info.render.calls, triangles: activeRenderer.info.render.triangles };
+          let meshes = 0;
+          let sceneTriangles = 0;
+          host.scene.traverseVisible((object) => {
+            const mesh = object as THREE.Mesh;
+            if (!mesh.isMesh || !mesh.geometry) return;
+            meshes++;
+            const index = mesh.geometry.getIndex();
+            const count = index ? index.count : (mesh.geometry.getAttribute('position')?.count ?? 0);
+            sceneTriangles += Math.floor(count / 3) * ((mesh as THREE.InstancedMesh).count ?? 1);
+          });
+          const sorted = [...times].sort((a, b) => a - b);
+          const at = (q: number) => sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))] ?? 0;
+          const size = activeRenderer.getDrawingBufferSize(new THREE.Vector2());
+          const ratio = activeRenderer.getPixelRatio();
+          const round = (value: number) => Math.round(value * 100) / 100;
+          return {
+            frames,
+            medianMs: round(at(0.5)),
+            p95Ms: round(at(0.95)),
+            minMs: round(sorted[0] ?? 0),
+            width: size.x,
+            height: size.y,
+            cssWidth: round(size.x / ratio),
+            cssHeight: round(size.y / ratio),
+            devicePixelRatio: ratio,
+            drawn,
+            scene: { meshes, triangles: sceneTriangles },
+            drawMode: viewPresentation(documentId).drawMode,
+          };
+        };
         rendererSessionRef.current = host.rendererSession;
         if (!host.initialized) {
           if (!chromeless) {
@@ -2110,6 +2159,7 @@ export function Object3DDocumentViewport({
                   drawCamera: () => host.session?.camera() ?? viewport.camera,
                   orbit: viewport.orbitControls,
                   scene: host.scene,
+                  frameCost: (frames) => measureFrameCost(frames),
                 },
                 () => null,
                 (kind, object) => viewport.setHelper(kind, object),

package/src/kit/components/ViewportFurniture.tsx

@@ -472,7 +472,7 @@ export function ViewportFurniture({
           header's view control and the Home and numpad-period keys, as Blender's is its View
           menu. The Camera button is not drawn yet: looking through a scene camera is not a
           view this stage has. */}
-      {navigationControls ? (
+      {navigationControls && store.showGizmos ? (
       <div
         data-testid="viewport-navigation"
         role="toolbar"

package/src/kit/editor-viewport.ts

@@ -3165,7 +3165,7 @@ export class EditorViewport {
     // same rationale as the per-notify `applyRootHiddenVisibility` above.
     if (hidden) policy.suppressRootEnvironment(this._scene);
     const gizmoEpoch = this._store.gizmoEpoch;
-    const gizmoSig = `${this._store.shell.showHelpers}|${JSON.stringify(vis)}|${hiddenRootId ?? ''}|${hidden}|${this._threejsToolContextActive}`;
+    const gizmoSig = `${this._store.shell.showHelpers}|${this._store.shell.showGizmos}|${JSON.stringify(vis)}|${hiddenRootId ?? ''}|${hidden}|${this._threejsToolContextActive}`;
     const mapChanged = this._objectMap !== this._lastGizmoObjectMap;
     const settingsChanged = gizmoSig !== this._lastGizmoSig;
     const membershipChanges = mapChanged
@@ -3261,7 +3261,8 @@ export class EditorViewport {
         ? anyChannelWritable(selectedId)
         : (authoring.transforms?.editability?.(selectedId, activeTransformChannel).writable ?? true)
       : false;
-    if (selectedId && selectedTransformWritable) {
+    // Blender's Show Gizmo off draws no transform gizmo, and the selection stays as it is.
+    if (selectedId && selectedTransformWritable && this._store.shell.showGizmos) {
       if (!this._anyGizmoDragging()) {
         if (this._store.shell.pivotMode === 'median-point' && this._store.shell.selectedEntityIds.size > 1) {
           const median = new THREE.Vector3();
@@ -3982,6 +3983,7 @@ export class EditorViewport {
   renderViewCube(renderer: THREE.WebGLRenderer): void {
     if (!this._threeSurfaceShowing) return; // no three stage, no compass (Blender's is persistent on one)
     if (this._navigation === 'hidden') return;
+    if (!this._store.shell.showGizmos) return; // the stage's Show Gizmo is off
     if (this._cameraView) return; // exact camera view owns the viewport
     const w = renderer.domElement.clientWidth;
     const h = renderer.domElement.clientHeight;
@@ -4859,6 +4861,7 @@ export class EditorViewport {
   private _isOverViewCube(clientX: number, clientY: number): boolean {
     // An indicator is only drawn, and a triad has nothing to click: clicks pass to the stage.
     if (this._navigation !== 'interactive' || this._gizmoLook.navigationForm === 'triad') return false;
+    if (!this._store.shell.showGizmos) return false;
     const rect = this._canvas.getBoundingClientRect();
     const x = clientX - rect.left;
     const y = clientY - rect.top;

package/src/kit/viewport-commands.ts

@@ -31,6 +31,7 @@ import {
   viewPresentationBinding,
 } from '@volter/editor-sdk/kit/viewport-presentation';
 import { threeStoreForHost } from './three-state';
+import { viewportStages } from '../viewport-door';
 import { threeStateOf } from './three-state';
 
 function activeObject3DDocumentSession() {
@@ -179,6 +180,34 @@ export const viewportCommands: CommandContribution['commands'] = {
     }
     return { ok: true, data: { ...documentSession.cameraPose() } };
   }),
+  /**
+   * WHAT A FRAME OF A 3D DOCUMENT'S STAGE COSTS WHEN NOTHING CAPS IT (`ViewportRig.frameCost`):
+   * the active document's stage, or the one `stage` names by its id (a split's second area is
+   * `<documentId>#area-2`). The frame is the stage's own, so a draw mode, a split or a scene
+   * changes it the way it changes what a person sees; the reading says which it measured.
+   */
+  'document-frame-cost': verb((_store, cmd) => {
+    const frames = cmd['frames'] ?? 60;
+    if (typeof frames !== 'number' || !Number.isInteger(frames) || frames < 1 || frames > 600)
+      return { ok: false, error: 'document-frame-cost: "frames" must be a whole number in 1..600.' };
+    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 documentId = named ?? activeWorkspaceDocumentId();
+    const stages = viewportStages();
+    const stage = stages.find((one) => one.documentId === documentId);
+    if (!stage)
+      return {
+        ok: false,
+        error:
+          `document-frame-cost: no 3D stage draws ${documentId === null ? 'the active document' : JSON.stringify(documentId)}. ` +
+          `The mounted stages are: ${stages.map((one) => one.documentId).join(', ') || 'none'}.`,
+      };
+    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) } };
+  }, 120_000),
   'capture-viewport': verb(async (store, cmd) => {
     // Fresh, unthrottled on-demand capture (see EditorShellStore.captureViewportImage).
     const requested = captureSizeFromCommand(cmd);

package/src/viewport-api.ts

@@ -6,6 +6,7 @@
  */
 import type { MountedRoot } from '@volter/editor-project/adapter/root-adapter';
 import type * as THREE from 'three';
+import type { StageFrameCostReading } from '@volter/editor-sdk';
 
 /** A live instance's roots, presented as the authored viewport's subject. */
 export interface ViewportPresentation {
@@ -15,12 +16,23 @@ export interface ViewportPresentation {
   dispose(): void;
 }
 
+/** What a frame of a stage costs, uncapped ({@link ViewportRig.frameCost}): the wire's reading
+ *  without the stage's id, which the door adds. */
+export type StageFrameCost = Omit<StageFrameCostReading, 'stage'>;
+
 /** 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;
+  /**
+   * WHAT A FRAME OF THIS STAGE COSTS WHEN NOTHING CAPS IT: the stage's own frame (its update,
+   * its hooks, its render and view cube) run `frames` times back to back outside
+   * `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;
   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;