@volter/editor-threejs 0.5.212 → 0.5.214

package/src/kit/components/asset-viewers/Object3DPreview.tsx

@@ -1,5 +1,5 @@
 import type { ToolObject3DPreviewContext, ToolObject3DPreviewExtension } from '../../../object3d-contributions';
-import { themeVars } from '@volter/sdk/widgets';
+import { StateSurface, themeVars } from '@volter/sdk/widgets';
 import { useEffect, useRef, useState } from 'react';
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
@@ -294,24 +294,8 @@ export function Object3DPreview({
         background: themeVars.surface.inset,
       }}
     >
-      {loading && !error ? (
-        <span style={{ position: 'absolute', padding: 10, color: themeVars.content.muted }}>
-          Loading…
-        </span>
-      ) : null}
-      {!active ? (
-        <span style={{ position: 'absolute', padding: 10, color: themeVars.content.muted }}>
-          Preview suspended while inactive.
-        </span>
-      ) : null}
-      {error ? (
-        <div
-          role="alert"
-          style={{ position: 'absolute', padding: 10, color: themeVars.semantic.danger }}
-        >
-          {error}
-        </div>
-      ) : null}
+      {!active ? <StateSurface fill compact title="Preview suspended while inactive." /> : null}
+      {error ? <StateSurface fill compact tone="error" title={`${displayName} could not be previewed`} detail={error} /> : null}
     </div>
   );
 }

package/src/kit/components/asset-viewers/QuarksAssetDocument.tsx

@@ -1,5 +1,6 @@
 import type { ToolObject3DDocumentAuthoringFactory } from '../../../object3d-contributions';
-import { themeVars } from '@volter/sdk/widgets';
+import { StateSurface } from '@volter/sdk/widgets';
+import { Progress } from '@volter/sdk/progress';
 import type {
   AuthoringAdapter,
   InspectorProvider,
@@ -503,14 +504,9 @@ export function QuarksAssetDocument({
 
   if (error)
     return (
-      <div role="alert" style={{ padding: 20, color: themeVars.semantic.danger }}>
-        {error}
-      </div>
-    );
-  if (!artifact)
-    return (
-      <div style={{ padding: 20, color: themeVars.content.muted }}>Loading {displayName}…</div>
+      <StateSurface tone="error" title={`Could not load ${displayName}`} detail={error} />
     );
+  if (!artifact) return <Progress documentId={documentId} title={`Loading ${displayName}`} />;
   return (
     <Object3DDocumentViewport
       documentId={documentId}

package/src/kit/components/asset-viewers/ShaderAssetDocument.tsx

@@ -1,6 +1,7 @@
 import { editorHost } from '@volter/sdk/host';
 import { faCode, faSliders, faTriangleExclamation } from '@fortawesome/free-solid-svg-icons';
-import { Checkbox, ColorInput, NumberInput, Select, themeVars } from '@volter/sdk/widgets';
+import { Checkbox, ColorInput, EditorBanner, NumberInput, Select, spaceVar, StateSurface, Text, themeVars } from '@volter/sdk/widgets';
+import { Progress } from '@volter/sdk/progress';
 import { useEffect, useMemo, useRef, useState } from 'react';
 import * as THREE from 'three';
 import { readProjectTextFile } from '@volter/sdk/api/project-source';
@@ -449,6 +450,14 @@ function UniformControlRow({
   );
 }
 
+/** One diagnostic as a line: where (the file, its line and column) and what. */
+function diagnosticLine(diagnostic: ShaderDiagnostic, files: ShaderFiles): string {
+  const file = diagnostic.stage === 'program' ? null : files[diagnostic.stage];
+  const where = file?.available ? basename(file.path) : diagnostic.stage;
+  const at = diagnostic.line ? `:${diagnostic.line}${diagnostic.column ? `:${diagnostic.column}` : ''}` : '';
+  return `${where}${at} · ${diagnostic.message}`;
+}
+
 function DiagnosticList({
   diagnostics,
   files,
@@ -457,37 +466,21 @@ function DiagnosticList({
   files: ShaderFiles;
 }) {
   if (diagnostics.length === 0) {
-    return (
-      <div style={{ color: themeVars.semantic.success, fontSize: 11, padding: 4 }}>
-        Shader program compiled successfully.
-      </div>
-    );
+    return <StateSurface inline tone="success" title="Shader program compiled successfully." />;
   }
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 6, padding: 4 }}>
-      {diagnostics.map((diagnostic, index) => {
-        const file = diagnostic.stage === 'program' ? null : files[diagnostic.stage];
-        return (
-          <div
-            key={`${diagnostic.stage}:${diagnostic.line ?? 0}:${diagnostic.message}:${index}`}
-            style={{
-              color:
-                diagnostic.severity === 'warning'
-                  ? themeVars.semantic.warning
-                  : themeVars.semantic.danger,
-              fontSize: 10,
-              lineHeight: 1.45,
-            }}
-          >
-            {file?.available ? basename(file.path) : diagnostic.stage}
-            {diagnostic.line
-              ? `:${diagnostic.line}${diagnostic.column ? `:${diagnostic.column}` : ''}`
-              : ''}
-            {' · '}
-            {diagnostic.message}
-          </div>
-        );
-      })}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: spaceVar[2] }}>
+      {diagnostics.map((diagnostic, index) => (
+        <Text
+          key={`${diagnostic.stage}:${diagnostic.line ?? 0}:${diagnostic.message}:${index}`}
+          as="div"
+          variant="code"
+          selectable
+          tone={diagnostic.severity === 'warning' ? 'warning' : 'danger'}
+        >
+          {diagnosticLine(diagnostic, files)}
+        </Text>
+      ))}
     </div>
   );
 }
@@ -589,17 +582,18 @@ export function ShaderAssetDocument({
         order: PROPERTIES_SECTION_ORDER,
         body: {
           kind: 'custom',
-          render: () => (
+          // (shown once the files are read: the document passes its sections only then)
+          render: () => files && (
             <div
               style={{ display: 'flex', flexDirection: 'column', gap: 5, padding: 4, fontSize: 10 }}
             >
               <span>
-                Vertex · {files ? basename(files.vertex.path) : 'Loading…'}
-                {files && !files.vertex.available ? ' (preview fallback)' : ''}
+                Vertex · {basename(files.vertex.path)}
+                {!files.vertex.available ? ' (preview fallback)' : ''}
               </span>
               <span>
-                Fragment · {files ? basename(files.fragment.path) : 'Loading…'}
-                {files && !files.fragment.available ? ' (preview fallback)' : ''}
+                Fragment · {basename(files.fragment.path)}
+                {!files.fragment.available ? ' (preview fallback)' : ''}
               </span>
               <span style={{ color: themeVars.content.muted }}>
                 Ordinary sibling GLSL files; runtime composition stays in TS/TSX.
@@ -658,9 +652,7 @@ export function ShaderAssetDocument({
         title={basename(assetPath)}
         status="Shader unavailable"
       >
-        <div role="alert" style={{ padding: 20, color: themeVars.semantic.danger }}>
-          {loadError}
-        </div>
+        <StateSurface tone="error" title={`Could not load ${basename(assetPath)}`} detail={loadError} />
       </AssetEditorShell>
     );
   }
@@ -671,9 +663,8 @@ export function ShaderAssetDocument({
         active={active}
         type="shader"
         title={basename(assetPath)}
-        status="Loading GLSL"
       >
-        <div style={{ padding: 20, color: themeVars.content.muted }}>Loading shader files…</div>
+        <Progress documentId={documentId} title={`Loading ${basename(assetPath)}`} />
       </AssetEditorShell>
     );
   }
@@ -721,22 +712,13 @@ export function ShaderAssetDocument({
           </Select>
         </div>
         {diagnostics.length > 0 && (
-          <div
-            style={{
-              position: 'absolute',
-              left: 12,
-              right: 12,
-              bottom: 12,
-              maxHeight: 120,
-              overflow: 'auto',
-              padding: 8,
-              border: `1px solid ${themeVars.semantic.danger}`,
-              borderRadius: 6,
-              background: themeVars.surface.overlay,
-            }}
+          <EditorBanner
+            tone={diagnostics.some((diagnostic) => diagnostic.severity !== 'warning') ? 'error' : 'warning'}
+            style={{ position: 'absolute', left: 0, right: 0, bottom: 0 }}
+            detail={diagnostics.map((diagnostic) => diagnosticLine(diagnostic, files)).join('\n')}
           >
-            <DiagnosticList diagnostics={diagnostics} files={files} />
-          </div>
+            {`${diagnostics.length} issue${diagnostics.length === 1 ? '' : 's'}`}
+          </EditorBanner>
         )}
       </div>
     </AssetEditorShell>

package/src/kit/components/object3d-contribution-surfaces.tsx

@@ -1,4 +1,5 @@
 import { announceDocumentStage } from '@volter/sdk/document-viewports';
+import { Progress } from '@volter/sdk/progress';
 import { lazy, Suspense, useEffect } from 'react';
 import type { ToolObject3DAuthoringProps, ToolObject3DPreviewProps } from '../../object3d-contributions';
 
@@ -12,7 +13,8 @@ const Authoring = lazy(async () => ({ default: (await import('./StageHost')).Too
 
 export function Object3DPreviewSurface(props: ToolObject3DPreviewProps) {
   return (
-    <Suspense fallback={<div style={{ minHeight: 240 }}>Loading 3D preview…</div>}>
+    // (a preview card reports no wait: it is a card in a panel or a catalog, neither a document nor a view)
+    <Suspense fallback={null}>
       <Preview {...props} />
     </Suspense>
   );
@@ -26,7 +28,7 @@ export function Object3DAuthoringSurface(props: ToolObject3DAuthoringProps) {
   // `workspace.document` contributions do not, and which is which belongs to the PROJECT.
   useEffect(() => announceDocumentStage(props.documentId), [props.documentId]);
   return (
-    <Suspense fallback={<div style={{ minHeight: 240 }}>Loading 3D authoring surface…</div>}>
+    <Suspense fallback={<Progress documentId={props.documentId} title="Loading 3D authoring surface" />}>
       <Authoring {...props} />
     </Suspense>
   );

package/src/kit/components/stage-transform-tools.tsx

@@ -3,8 +3,7 @@
  * document's chrome (`@volter/sdk/document-viewports`): what the
  * host's transform tools drive on it (`stage-context.ts`'s one answer), the tool
  * strip on its shelf and the gizmo's header wells. Every tool writes THIS
- * stage's own store (`stage-store-registry.ts`); the world root's stage runs on
- * the session store, so the Scene document is unchanged either way.
+ * stage's own store (`stage-store-registry.ts`).
  */
 import { type ViewportInteraction, viewPresentation } from '@volter/sdk/viewport-presentation';
 import { useEffect, useSyncExternalStore } from 'react';

package/src/kit/editor-shell-store.ts

@@ -99,35 +99,11 @@ export class EditorShellStore {
     this._statePersistence = persistence;
   }
 
-  /** The game camera lookup the last `focusOnScene` carried, read by the world stage while its
-   *  auto-frame window is open. */
-  get sceneCameraLookup(): (() => THREE.Camera | null) | null {
-    return this._sceneCameraLookup;
-  }
-  protected _sceneCameraLookup: (() => THREE.Camera | null) | null = null;
-
-  /**
-   * Frame the whole active scene — the first thing a reader should see when a
-   * world they did not author opens. The viewport keeps
-   * asking until the world HAS content, because a game builds itself
-   * asynchronously; any camera input from the reader cancels it (see
-   * `the world root's stage`). A no-op for a scene the reader already has a camera on.
-   *
-   * `gameCamera` is a LIVE LOOKUP, not a camera: a game's own camera
-   * may not exist yet on the frame it is captured on, so the viewport asks
-   * again while its window is open. When one turns up, its view is adopted
-   * instead of any measurement — see `scene-framing.ts`.
-   */
-  focusOnScene(gameCamera?: () => THREE.Camera | null): void {
-    this._sceneCameraLookup = gameCamera ?? null;
-    this.shell.focusOnScene();
-  }
-
   /**
    * Live viewport camera pose, read straight from the bound Three.js camera +
    * orbit target (`bindScene`/`setOrbitTarget`).
    * Null only when nothing has bound a camera yet (e.g. a headless store in a
-   * unit test that never mounted `the world root's stage`).
+   * unit test that never mounted a stage).
    */
   get cameraPose(): { position: THREE.Vector3; target: THREE.Vector3; fov: number } | null {
     if (!this._camera) return null;
@@ -326,7 +302,7 @@ export class EditorShellStore {
    * Fresh, on-demand viewport capture (unthrottled, unlike the periodic
    * autosave thumbnail above) — backs the `capture-viewport` relay command.
    * Returns null when no renderer/scene/camera is bound yet (e.g. before
-   * `the world root's stage` has mounted).
+   * a stage has mounted).
    */
   captureViewportImage(
     size: number | { width: number; height: number } = EditorShellStore.THUMBNAIL_SIZE,

package/src/kit/editor-viewport.ts

@@ -477,6 +477,14 @@ const _gridQuat = new THREE.Quaternion();
 const _gridEye = new THREE.Vector3();
 const _gridUp = new THREE.Vector3(0, 1, 0);
 
+/**
+ * What the floor's overlays (its grid and its axes) are drawn with: a surface in their own plane, a level's ground at
+ * 0, shows them on it, as Blender's grid passes its depth test on a tie (`DRW_STATE_DEPTH_LESS_EQUAL`,
+ * overlay_grid.hh). three's depth test passes a tie too; the offset keeps it where the two surfaces' depths round
+ * apart, which would split it pixel by pixel.
+ */
+const ON_THE_FLOOR = { polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 } as const;
+
 /**
  * The floor grid as a shader over one plane (`extent` metres square, y = 0).
  * Lines are `fwidth`-antialiased so they keep one on-screen width at every
@@ -604,6 +612,7 @@ function createFloorGrid(extent: number): THREE.Mesh<THREE.PlaneGeometry, THREE.
     transparent: true,
     depthWrite: false,
     side: THREE.DoubleSide,
+    ...ON_THE_FLOOR,
   });
   const mesh = new THREE.Mesh(geometry, material);
   mesh.name = 'editor-floor-grid';
@@ -1000,6 +1009,7 @@ export class EditorViewport {
         opacity: 1,
         depthWrite: false,
         toneMapped: false,
+        ...ON_THE_FLOOR,
       }),
     );
     // Share the floor's grazing fade. LineMaterial interpolates the segment endpoints with
@@ -1422,7 +1432,7 @@ export class EditorViewport {
     return this._scene;
   }
 
-  /** Camera that paints the Scene document: the free editor camera. */
+  /** Camera that paints the stage: the free editor camera. */
   get renderCamera(): THREE.Camera {
     return this.freeCamera;
   }

package/src/kit/three-integration.ts

@@ -22,7 +22,6 @@ import { editorHost } from '@volter/sdk/host';
 import { onShellStore } from '@volter/sdk/shell-store-door';
 import { registerThreeCanvasRender } from './three-canvas-render';
 import { registerThreeHierarchyRowMedia } from './three-hierarchy-row-media';
-import { registerThreePlayCameraFlight } from './play-camera-flight';
 import { registerThreeInspectionMedia } from './three-inspection-media';
 import { threeStateOf } from './three-state';
 import { installViewportAuthoringPolicy } from './viewport-authoring-policy';
@@ -68,7 +67,6 @@ export function ensureThreeIntegration(): () => void {
     reportViewportStatus(),
     registerThreeCanvasRender(),
     registerThreeHierarchyRowMedia(),
-    registerThreePlayCameraFlight(),
     registerRendererResourceCounts('hostLive', liveHostRendererCount),
     registerRendererResourceCounts('interactive', interactiveViewportRendererCounts),
     registerRendererResourceCounts('inspectorPreview', inspectorPreviewRendererCounts),

package/src/viewport-api.ts

@@ -1,7 +1,6 @@
 /**
  * THE AUTHORED THREE VIEWPORT'S PUBLIC SHAPE — what a lane that mounts something reaches through
- * `viewport-door.ts`: the rig a camera flight drives, the frame loop it rides, the helpers it
- * shows and every mounted stage.
+ * `viewport-door.ts`: every mounted stage, its rig, its frame loop and the helpers it shows.
  */
 import type * as THREE from 'three';
 import type { StageFrameCostReading } from '@volter/sdk';
@@ -35,9 +34,7 @@ export interface ViewportRig {
 
 /**
  * ONE MOUNTED 3D STAGE, named by the document it draws. Every 3D document
- * mounts a stage of its own ; this is the door
- * to a particular one, where the viewport door's singular members
- * are the door to whichever is primary.
+ * mounts a stage of its own; this is the door to a particular one.
  */
 export interface ViewportStage {
   /** The workspace document this stage draws. */
@@ -50,14 +47,8 @@ export interface ViewportStage {
 }
 
 /**
- * THE AUTHORED VIEWPORT, as a lane that mounts something reaches it: the rig
- * a camera flight drives and the frame loop it rides. Which native surface the
- * viewport renders is the host's; a lane that finds no rig (a headless tab, a
- * project with no Three root) mounts without one.
- *
- * THE SINGULAR MEMBERS ARE THE PRIMARY STAGE — the FOCUSED stage, else the
- * first bound. A camera flight wants exactly that one, which is why it reads
- * here and never enumerates.
+ * THE AUTHORED VIEWPORT, as a lane that mounts something reaches it. Which
+ * native surface the viewport renders is the host's.
  *
  * {@link stages} is EVERY mounted 3D stage. A helper is an `Object3D` and an
  * `Object3D` has one parent, so there is no "set it once for all stages": a
@@ -66,9 +57,6 @@ export interface ViewportStage {
  * it made that pass.
  */
 export interface ViewportDoor {
-  rig(): ViewportRig | null;
-  /** Runs after the viewport's own per-frame update; the return unsubscribes. */
-  onFrame(fn: (dtSeconds: number) => void): () => void;
   /**
    * Show an editor-only helper object of `kind` in the authored viewport (a
    * baked navmesh's debug mesh), replacing the previous one of that kind;

package/src/viewport-door.ts

@@ -2,14 +2,11 @@
  * 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.
  *
- * `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, ViewportRig, ViewportStage } from './viewport-api';
-import { activeWorkspaceDocumentId } from '@volter/sdk/workspace-document-registry';
 
 /** An editor-only helper object, typed by the host door it is shown through. */
 type HelperObject = Parameters<ViewportDoor['setHelper']>[1];
@@ -24,8 +21,7 @@ interface Binding {
   readonly helpers: Map<string, HelperObject>;
 }
 
-/** Every bound stage, keyed by the document it draws; insertion-ordered, so
- *  "the first bound" is a real answer. */
+/** Every bound stage, keyed by the document it draws, in bind order. */
 const bound = new Map<string, Binding>();
 /** Retain frame subscribers and helper assignments by document across viewport remounts and before binding. */
 const stageStateByDocument = new Map<
@@ -47,23 +43,8 @@ function stageStateFor(documentId: string): {
   }
   return state;
 }
-/** Listeners on the singular `onViewportFrame`: they follow the PRIMARY
- *  stage, so they are held here and fanned in rather than added to a
- *  binding's own set, which would strand them on a stage that stops being
- *  primary (or unmounts). */
-const primaryFrameListeners = new Set<(dtSeconds: number) => void>();
 const stageListeners = new Set<(stages: readonly ViewportStage[]) => void>();
 
-/** THE PRIMARY STAGE: focused > first bound. */
-function primary(): Binding | null {
-  const focused = activeWorkspaceDocumentId();
-  if (focused !== null) {
-    const match = bound.get(focused);
-    if (match) return match;
-  }
-  return bound.values().next().value ?? null;
-}
-
 let stagesCache: readonly ViewportStage[] | null = null;
 
 function notifyStages(): void {
@@ -121,20 +102,6 @@ export function bindViewportRig(
   };
 }
 
-export function viewportRig(): ViewportRig | null {
-  return primary()?.rig ?? null;
-}
-
-/** 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. */
-export function onViewportFrame(fn: (dtSeconds: number) => void): () => void {
-  primaryFrameListeners.add(fn);
-  return () => {
-    primaryFrameListeners.delete(fn);
-  };
-}
-
 /** Every bound stage, in bind order. */
 export function viewportStages(): readonly ViewportStage[] {
   if (!stagesCache)
@@ -156,12 +123,9 @@ export function onViewportStages(fn: (stages: readonly ViewportStage[]) => void)
   };
 }
 
-/** A stage's RAF loop calls this after its own update each frame. The stage's
- *  own listeners always run; the primary-stage listeners run here only when
- *  this stage IS the primary. */
+/** A stage's RAF loop calls this after its own update each frame, running the stage's own listeners. */
 export function runViewportFrame(documentId: string, dtSeconds: number): void {
   const binding = bound.get(documentId);
   if (!binding) return;
   for (const fn of binding.frameListeners) fn(dtSeconds);
-  if (primary() === binding) for (const fn of primaryFrameListeners) fn(dtSeconds);
 }

package/src/kit/components/world-root-binding.ts

@@ -1,59 +0,0 @@
-/**
- * THE WORLD ROOT'S CONTENT BINDING, as the stage host sees it.
- *
- * A stage shows either one Object3D a caller builds (`build` content) or the
- * project's world (`world-root` content): the manifest's roots mounted by a
- * design session, drawn by the world's own image pipeline, with the presenter
- * Play adopts live roots through. The host owns the surface's place, the frame
- * session, the per-stage door, the furniture and the overlays for both. What
- * mounts a world is the contributing package's — it runs the game runtime,
- * which a modeling host never carries — so the package hands the host this
- * binding and the host loads it only for a stage that shows a world.
- */
-import type { ComponentType } from 'react';
-import type * as THREE from 'three';
-import type { EditorShellStore } from '../editor-shell-store';
-import type { EditorStats } from '@volter/sdk/editor-runtime';
-import type { EditorViewport } from '../editor-viewport';
-
-export interface WorldRootStageOptions {
-  /** The session's store: the world is the session's own subject. */
-  readonly store: EditorShellStore;
-  readonly documentId: string;
-  readonly container: HTMLDivElement;
-  readonly canvas: HTMLCanvasElement;
-  readonly renderer: THREE.WebGLRenderer;
-  readonly stats: EditorStats;
-  readonly onMountStatus: (status: 'mounting' | 'ready') => void;
-  readonly onRootIds: (rootIds: readonly string[]) => void;
-  /** This stage's frame hook on the per-stage viewport door. */
-  readonly runFrame: (deltaSeconds: number) => void;
-}
-
-export interface WorldRootStage {
-  readonly scene: THREE.Scene;
-  readonly viewport: EditorViewport;
-  frame(timeMs: number, resumed: boolean): void;
-  setHelper(kind: string, object: THREE.Object3D | null): void;
-  dispose(): void;
-}
-
-export interface WorldRootOverlayProps {
-  readonly store: EditorShellStore;
-  /** The stage's own document — its stage context is read by this id. */
-  readonly documentId: string;
-  readonly mountStatus: 'mounting' | 'ready';
-  readonly rootIds: readonly string[];
-}
-
-export interface WorldRootStageBinding {
-  /** The world's own drawing surface, built to the world's render settings. */
-  mountWorldRootSurface(
-    canvasHost: HTMLDivElement,
-    container: HTMLDivElement,
-    displayName: string,
-  ): { canvas: HTMLCanvasElement; renderer: THREE.WebGLRenderer; lease: null };
-  installWorldRootStage(options: WorldRootStageOptions): WorldRootStage;
-  /** What the stage shows over a world: its mount state and camera authoring. */
-  readonly Overlays: ComponentType<WorldRootOverlayProps>;
-}