@volter/editor-threejs 0.5.93 → 0.5.95

package/package.json

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

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/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;