@volter/editor-threejs 0.5.212 → 0.5.214

package/src/kit/components/StageHost.tsx

@@ -3,7 +3,7 @@ import { ShellStore } from '@volter/sdk/shell-store';
 import type { ToolObject3DAuthoringProps, ToolObject3DDocumentAuthoring, ToolObject3DPreviewSource } from '../../object3d-contributions';
 import { invalidateStages, stageGeneration } from '@volter/sdk/stage-invalidation';
 import type { StageTransportSnapshot } from '@volter/sdk/host';
-import { EditorIcon, editorIcons, IconButton, themeVars } from '@volter/sdk/widgets';
+import { EditorBanner, EditorIcon, editorIcons, IconButton, themeVars } from '@volter/sdk/widgets';
 import type { AuthoringAdapter } from '@volter/project/adapter';
 import { contentWorldBounds } from '@volter/editor-threejs/viewport/content-bounds';
 import { isInEditorOwnedSubtree } from '@volter/editor-threejs/viewport/editor-layers';
@@ -57,8 +57,7 @@ import {
   studioStageApplies,
 } from '@volter/sdk/stage-context';
 import { registerStageStore } from '@volter/sdk/stage-store-registry';
-import { announceDocumentStage, registerDocumentViewport } from '@volter/sdk/document-viewports';
-import { sceneDocumentViewport } from '../scene-document-viewport';
+import { announceDocumentStage } from '@volter/sdk/document-viewports';
 import { threeStageTransformChrome } from './stage-transform-chrome';
 import { RetainedDocumentStates } from '../retained-document-states';
 import { perspectiveDistanceToFitBox } from '../three-viewport/camera-fit';
@@ -87,7 +86,6 @@ import {
 } from '@volter/sdk/workspace-document-registry';
 import { AssetEditorShell } from '@volter/sdk/components/AssetEditorShell';
 import { StageOverlays } from './StageOverlays';
-import type { WorldRootStageBinding } from './world-root-binding';
 import { TransportStrip } from '../transport-strip';
 
 // The stage's own keyboard actions, behind the same lazy boundary as the
@@ -105,7 +103,7 @@ import {
   watchPaletteBackdrop,
 } from './standard-viewport-dressing';
 import { ViewportFurniture } from './ViewportFurniture';
-import { OBJECT3D_SURFACE_BUILDING, ViewportSurfaceStatus } from '../viewport-surface-status';
+import { Progress } from '@volter/sdk/progress';
 import { workspaceHistoryService } from '@volter/sdk/components/workspace-history';
 import {
   bindViewPresentation,
@@ -113,10 +111,12 @@ import {
   mergeLayers,
   type PresentationLayer,
   reportViewDraw,
+  setViewFraming,
   setViewPresentation,
   stageLightsPerMode,
   startingPresentation,
   subscribeViewportPresentation,
+  viewFraming,
   viewPresentation,
   viewPresentationSnapshot,
   type ViewportDrawMode,
@@ -166,23 +166,6 @@ export type SourceDocumentAuthoringFactory = (
   context: SourceDocumentAuthoringContext,
 ) => ToolObject3DDocumentAuthoring;
 
-/** WHAT THE STAGE IS SHOWING. `build` is one Object3D the caller's `build()`
- * constructs, in isolation; its kind supplies authoring behavior and chrome,
- * and this host owns renderer lifetime, capture and disposal. `world-root` is
- * the project's world: the contributing package's binding mounts the
- * manifest's roots and presents the live roots Play adopts, and this host
- * gives it the same surface place, frame session, per-stage door and
- * overlays. A modeling host never loads a world binding. */
-export type Object3DDocumentContent =
-  | { readonly kind: 'build' }
-  | { readonly kind: 'world-root'; load(): Promise<WorldRootStageBinding> };
-
-/** Throttle for the world-root stage's clip rescan. A traverse per store
- *  notification would run on every selection change; 500 ms is fast enough
- *  that a streamed-in character becomes scrubbable while a person is still
- *  looking at it. */
-const CLIP_RESCAN_INTERVAL_MS = 500;
-
 /** Module-level so its identity is stable across renders, which
  *  `useSyncExternalStore` requires; the theme root is global, so no stage's
  *  own element narrows it. */
@@ -190,15 +173,7 @@ function subscribeThemeViewportGroup(onChange: () => void): () => void {
   return subscribeNativeSelectionTheme(null, onChange);
 }
 
-export interface Object3DDocumentViewportProps
-  extends Omit<ToolObject3DAuthoringProps, 'build' | 'sourcePath'> {
-  /** Required by `build` content (and by the SDK door, where both stay
-   *  mandatory); a `world-root` stage constructs nothing of its own and has no
-   *  single source file — its content is the manifest's roots. */
-  readonly build?: ToolObject3DAuthoringProps['build'];
-  readonly sourcePath?: string;
-  /** See {@link Object3DDocumentContent}. Default `{ kind: 'build' }`. */
-  readonly content?: Object3DDocumentContent;
+export interface Object3DDocumentViewportProps extends ToolObject3DAuthoringProps {
   /** See `@volter/sdk`'s `ToolObject3DAuthoringProps.audit`. */
   readonly audit?: boolean;
   /** Reuse the canonical Asset Lab viewport with NONE of the document chrome —
@@ -425,7 +400,7 @@ class Object3DDocumentHost {
 
   constructor(
     readonly lane: 'own' | 'inspector-preview',
-    readonly surface: ReturnType<typeof mountViewportSurface> | ReturnType<WorldRootStageBinding['mountWorldRootSurface']>,
+    readonly surface: ReturnType<typeof mountViewportSurface>,
     store: EditorShellStore,
   ) {
     this.store = store;
@@ -511,7 +486,6 @@ export function Object3DDocumentViewport({
   statistics,
   subject,
   gridScale,
-  content,
 }: Object3DDocumentViewportProps) {
   const viewStageKind = stageKind ?? stageKindOf(documentId);
   // ANNOUNCE THE STAGE (`authoring/object3d-document-session-registry.ts`).
@@ -588,16 +562,10 @@ export function Object3DDocumentViewport({
     return () => retainedObject3DStages.release(retained, generation);
   }, [documentId]);
   const retainedState = retainedRef.current;
-  // WHAT THIS STAGE SHOWS. A world root stays attached while hidden: Play
-  // adopts into it, and the play-entry flight rides its frame clock.
-  const worldRoot = content?.kind === 'world-root';
   // Only a visible pane owns an interactive attachment. Hidden documents
   // retain their state and return their renderer to the bounded pool.
-  const wantsSurface = active || worldRoot;
-  const worldRootLoadRef = useRef(content?.kind === 'world-root' ? content.load : null);
-  worldRootLoadRef.current = content?.kind === 'world-root' ? content.load : null;
-  const [surfaceAttached, setSurfaceAttached] = useState(wantsSurface);
-  useEffect(() => setSurfaceAttached(wantsSurface), [wantsSurface]);
+  const [surfaceAttached, setSurfaceAttached] = useState(active);
+  useEffect(() => setSurfaceAttached(active), [active]);
   // The selection silhouette is a LIVE prop: a modeling document turns it off
   // the moment it enters its own sub-object mode and back on when it leaves,
   // and the session applies that to the composer it has already built. The ref
@@ -620,7 +588,7 @@ export function Object3DDocumentViewport({
     setSurfaceStatus('building');
     return () => {
       const host = documentHostRef.current;
-      if (host && !worldRoot) {
+      if (host) {
         // Inactive tabs stay open in the workspace. Their source remains
         // mounted in retained CPU state while the expensive attachment goes
         // back to the pool. A source revision or final close still disposes it.
@@ -640,7 +608,7 @@ export function Object3DDocumentViewport({
       host?.close();
       documentHostRef.current = null;
     };
-  }, [documentId, rendererLane, retainedState, surfaceAttached, worldRoot]);
+  }, [documentId, rendererLane, retainedState, surfaceAttached]);
   const openingViewRef = useRef(openingView);
   openingViewRef.current = openingView;
   const documentPresentationRef = useRef(documentPresentation);
@@ -677,10 +645,6 @@ export function Object3DDocumentViewport({
   const persistenceSessionRef = useRef<Promise<AssetDocumentPersistenceSession> | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [surfaceStatus, setSurfaceStatus] = useState<'building' | 'ready'>('building');
-  // A world root's own mount state and the binding that draws its overlays.
-  const [worldRootBinding, setWorldRootBinding] = useState<WorldRootStageBinding | null>(null);
-  const [designMountStatus, setDesignMountStatus] = useState<'mounting' | 'ready'>('mounting');
-  const [designRootIds, setDesignRootIds] = useState<readonly string[]>([]);
   const [projection, setProjection] = useState<ThreeViewportProjection>('perspective');
   // The live authoring adapter this document's inspection composes from. It
   // only exists once the graph is built, so it is state rather than a ref:
@@ -707,122 +671,14 @@ export function Object3DDocumentViewport({
   useEffect(() => {
     let cancelled = false;
     if (!surfaceAttached) return;
-    /**
-     * THE WORLD ROOT'S CONTENT BINDING. It shows the project's world rather
-     * than one constructed Object3D, so it brings its own surface, scene,
-     * composer and the presenter Play adopts through; everything else about
-     * the stage is the host's, exactly as it is for a prefab or a model.
-     */
-    const installWorldRoot = async (
-      load: () => Promise<WorldRootStageBinding>,
-    ): Promise<void> => {
-      const container = containerRef.current;
-      const canvasHost = canvasHostRef.current;
-      if (!container || !canvasHost || documentHostRef.current) return;
-      const stats = shellStatsRef.current;
-      const store = threeStoreForHost();
-      if (!stats || !store) {
-        // The world root IS the shell's own subject — its readout, its
-        // adoption stack, its transport. A bounded host has none of that.
-        setError('The world root needs the editor shell above it; this host has none.');
-        return;
-      }
-      const binding = await load();
-      if (cancelled || documentHostRef.current) return;
-      setWorldRootBinding(() => binding);
-      markViewportConstructStarted();
-      const host = new Object3DDocumentHost(
-        'own',
-        binding.mountWorldRootSurface(canvasHost, container, displayName),
-        // The world is the session's own subject: Play adoption, ingest, the
-        // project history and the host door's hierarchy facet all address the
-        // SESSION store, so this stage runs on it rather than a private one.
-        store,
-      );
-      documentHostRef.current = host;
-      host.cleanups.push(registerStageStore(documentId, host.store.shell));
-      host.cleanups.push(registerStageTransport(documentId, host.transport));
-      host.cleanups.push(
-        registerDocumentViewport(documentId, {
-          ...sceneDocumentViewport(host.store, documentId),
-          ...threeStageTransformChrome(documentId),
-        }),
-      );
-      const stage = binding.installWorldRootStage({
-        store: host.store,
-        documentId,
-        container,
-        canvas: host.surface.canvas,
-        renderer: host.surface.renderer,
-        stats,
-        onMountStatus: setDesignMountStatus,
-        onRootIds: setDesignRootIds,
-        runFrame: (delta) => runViewportFrame(documentId, delta),
-      });
-      host.viewport = stage.viewport;
-      host.frame = stage.frame;
-      host.content = {
-        scene: stage.scene,
-        settle: () => Promise.resolve(),
-        dispose: async () => stage.dispose(),
-      };
-      // Rescan clip subjects on throttled store changes as the world tree mounts and updates.
-      // Inspect the scene the stage draws, including a session store’s scene.
-      const clipScan = scanClipSubjects(() => host.store.scene ?? stage.scene, host.transport, {
-        // A game makes its mixers as its world runs, not when the store changes.
-        rescanOnLiveMixers: true,
-      });
-      let lastClipScan = 0;
-      host.cleanups.push(() => clipScan.dispose());
-      host.cleanups.push(
-        host.store.shell.subscribe(() => {
-          const now = performance.now();
-          if (now - lastClipScan < CLIP_RESCAN_INTERVAL_MS) return;
-          lastClipScan = now;
-          clipScan.refresh();
-        }),
-      );
-      // This stage's presenter is the real one: Play adoption is a condition
-      // on the world-root binding, and a `build` stage declines every root.
-      host.cleanups.push(
-        bindViewportRig(
-          {
-            camera: stage.viewport.camera,
-            drawCamera: () => stage.viewport.renderCamera,
-            orbit: stage.viewport.orbitControls,
-            projection: stage.viewport.projectionOwner,
-            scene: stage.scene,
-            renderer: host.surface.renderer,
-          },
-          stage.setHelper,
-          { documentId },
-        ),
-      );
-      rendererSessionRef.current = host.rendererSession;
-      host.initialized = true;
-      markViewportConstructReady();
-      // The binding's own overlay reports mount progress.
-      setSurfaceStatus('ready');
-      // Always active: the play-entry flight rides this clock while the Game
-      // document holds focus; the stage skips frames by its own visibility.
-      host.rendererSession.setActive(true);
-    };
     const install = async () => {
       await documentHostRef.current?.content?.settle();
       while (liveGestureActive()) await whenLiveGestureIdle();
       if (cancelled) return;
-      const loadWorldRoot = worldRootLoadRef.current;
-      if (loadWorldRoot) return installWorldRoot(loadWorldRoot);
       const container = containerRef.current;
       const canvasHost = canvasHostRef.current;
       if (!container || !canvasHost) return;
-      if (!build || sourcePath === undefined) {
-        // `build` content is one Object3D the caller constructs from one file.
-        // Both are required by the SDK; validate callers at the runtime boundary.
-        setError('This stage shows `build` content and was given no `build()`/`sourcePath`.');
-        return;
-      }
-      let source: ReturnType<NonNullable<typeof build>>;
+      let source: ReturnType<typeof build>;
       const retainedGeneration = retainedObject3DStages.generation(retainedState);
       try {
         source = retainedState.source ?? build();
@@ -877,6 +733,8 @@ export function Object3DDocumentViewport({
       const history = workspaceHistoryService();
       if (history) store.shell.attachHistory(history);
       const shared = rendererLane === 'inspector-preview';
+      // Only the document's own view keeps its framing: a preview of it stands where it frames.
+      const recordsFraming = !shared && !chromeless;
       const studioStage = studioStageRef.current;
       const hasShell = hasShellRef.current;
       const assetSubject = assetSubjectRef.current;
@@ -1440,6 +1298,7 @@ export function Object3DDocumentViewport({
             presentationAdapter?.hierarchy.idForNativeObject?.(object) ?? adapter.hierarchy.idForNativeObject?.(object);
           if (id) store.objectMap.set(id, object);
         });
+        const opening = !host.session;
         if (!host.session) {
           // The view's camera (`ViewportCamera`): its field of view, and the direction it opens
           // from when the document states none.
@@ -1528,6 +1387,18 @@ export function Object3DDocumentViewport({
           // After the pose, which draws in perspective: an orthographic view comes back as one.
           viewport.setProjection(projection);
           retainedState.camera = null;
+        } else if (opening && recordsFraming) {
+          // THE VIEW'S STATE OVER THE FILE'S: a document that was seen before opens where it was
+          // last seen (`viewFraming`, restored from workspace storage, as Code-OSS restores an
+          // editor's view state), in place of the opening view its file states.
+          const framing = viewFraming(documentId);
+          if (framing) {
+            const [x, y, z] = framing.position;
+            const [tx, ty, tz] = framing.target;
+            const [ux, uy, uz] = framing.up;
+            viewport.setPose({ x, y, z }, { x: tx, y: ty, z: tz }, undefined, { x: ux, y: uy, z: uz });
+            host.session.setProjection(framing.projection);
+          }
         }
         const documentSession = host.session;
         documentStateRef.current = documentState;
@@ -1578,8 +1449,11 @@ export function Object3DDocumentViewport({
           if (viewPresentation(documentId).drawMode !== mode)
             setViewPresentation(documentId, { drawMode: mode as ViewportDrawMode });
         };
-        // Initialize draw mode from the document’s file, then the restored view, then the session default. Synchronize the view to the resulting session mode.
-        const restoredMode = ownLayer?.drawMode ?? viewPresentationSnapshot(documentId).drawMode;
+        // The draw mode the view opens in: the view state (the person's last view of this document,
+        // `document-view-states.ts`), else what the document's file states, else the session's default,
+        // as Code-OSS restores an editor's view state over its input's defaults. The view then follows
+        // the session.
+        const restoredMode = viewPresentationSnapshot(documentId).drawMode ?? ownLayer?.drawMode;
         if (restoredMode !== undefined && viewModes.has(restoredMode) && host.session)
           host.session.setMode(restoredMode);
         sessionToView();
@@ -1718,8 +1592,39 @@ export function Object3DDocumentViewport({
           }
         };
         host.syncHostScene = syncHostScene;
+        // WHERE THE VIEW STANDS, recorded as it moves (`setViewFraming`): when the orbit controls
+        // report a move (`OrbitControls.update` dispatches `change` for any move, `setPose`'s
+        // included), when the session changes (its projection), and before every draw. A door can
+        // move the camera with no ordinary draw after it: measured, a pose set through
+        // `editor.present` was not recorded by draws alone; that the page's tab was not on screen
+        // is the likely cause, not measured. A photograph's draw (`captureImage`) leaves the view's
+        // camera where it stands. During a photograph the projection recorded last stands, as a
+        // guard: no caller switches the projection for a photograph today.
+        let recordedFraming = '';
+        let recordedProjection: 'perspective' | 'orthographic' | null = null;
+        const recordFraming = (): void => {
+          if (!recordsFraming) return;
+          const position = viewport.camera.position.toArray();
+          const target = viewport.orbitControls.target.toArray();
+          const up = viewport.camera.up.toArray();
+          const projection =
+            documentSession.photographing() && recordedProjection !== null ? recordedProjection : documentSession.projection();
+          const key = `${position}|${target}|${up}|${projection}`;
+          if (key === recordedFraming) return;
+          recordedFraming = key;
+          recordedProjection = projection;
+          setViewFraming(documentId, { position, target, up, projection });
+        };
+        const controls = viewport.orbitControls;
+        controls.addEventListener('change', recordFraming);
+        const stopSessionFraming = documentSession.subscribe(recordFraming);
+        host.cleanups.push(() => {
+          controls.removeEventListener('change', recordFraming);
+          stopSessionFraming();
+        });
         documentSession.setBeforeRender((interactive) => {
           host.syncHostScene?.();
+          recordFraming();
           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, multiDraw: renderer.extensions.has('WEBGL_multi_draw'), renderer, drawMode: mode, pixelScale: documentSession.drawPixelScale(), photograph: documentSession.photographing()});
@@ -1736,7 +1641,7 @@ export function Object3DDocumentViewport({
           host.transportAdvances++;
           source.update?.(deltaSeconds);
         };
-        // Scan this source's animation subjects once. World-root stages rescan as their trees update.
+        // Scan this source's animation subjects once.
         const clipScan = scanClipSubjects(source.root, host.transport);
         host.cleanups.push(() => clipScan.dispose());
         const retainedTransport = retainedState.transport;
@@ -1867,8 +1772,8 @@ export function Object3DDocumentViewport({
           host.presence?.syncMarkers(delta);
           viewport.update(delta);
           // This stage's frame hook. After viewport.update, the same order the
-          // scene panel uses, so anything riding the loop (a camera flight)
-          // has final say over the pose and orbit damping never fights it.
+          // scene panel uses, so anything riding the loop has final say over
+          // the pose and orbit damping never fights it.
           if (!chromeless) runViewportFrame(documentId, delta);
           if (navigationMeasurement) {
             const camera = documentSession.camera();
@@ -2102,7 +2007,6 @@ export function Object3DDocumentViewport({
             store.shell.onViewportAction((action) => {
               switch (action.type) {
                 case 'focus-selection':
-                case 'focus-scene':
                   // The session frames the selection, else the whole subject,
                   // and says so on the console when there is nothing to frame.
                   if (!host.session?.frame() && host.session?.root)
@@ -2251,7 +2155,6 @@ export function Object3DDocumentViewport({
     surfaceAttached,
     sourceAuthoring,
     sourcePath,
-    worldRoot,
   ]);
 
   useEffect(() => {
@@ -2263,11 +2166,10 @@ export function Object3DDocumentViewport({
       firstFrameGateRef.current = false;
       markViewportRafResume(documentId);
     }
-    // A world root keeps its clock while another document holds focus.
-    session.setActive(active || worldRoot);
+    session.setActive(active);
     // A hidden stage keeps no live accumulation (its targets are the drawing buffer's size).
     if (!active) documentHostRef.current?.session?.releaseLive();
-  }, [active, documentId, worldRoot]);
+  }, [active, documentId]);
 
   // The stage's own handle for the capabilities that drive it directly (the
   // viewport hotkeys). `surfaceStatus` is what re-renders once the stage has
@@ -2336,44 +2238,12 @@ export function Object3DDocumentViewport({
             chrome="document"
           />
         ) : null}
-        {shellStore && worldRootBinding ? (
-          <worldRootBinding.Overlays
-            store={shellStore}
-            documentId={documentId}
-            mountStatus={designMountStatus}
-            rootIds={designRootIds}
-          />
-        ) : null}
         {/* Show a dismissible error notice over any stage that remains available. */}
         {error && (
-          <div
-            role="alert"
-            style={{
-              position: 'absolute',
-              insetInline: 0,
-              top: 0,
-              display: 'flex',
-              justifyContent: 'center',
-              padding: 'var(--volter-space-3)',
-              pointerEvents: 'none',
-            }}
-          >
-            <div
-              className="volter-chrome-island"
-              style={{
-                display: 'flex',
-                alignItems: 'center',
-                gap: 'var(--volter-space-3)',
-                maxWidth: '80%',
-                padding: 'var(--volter-space-2) var(--volter-space-3)',
-                borderRadius: 'var(--volter-radius-md)',
-                border: `var(--volter-stroke-resting) solid ${themeVars.semantic.danger}`,
-                background: themeVars.surface.raised,
-                color: themeVars.semantic.danger,
-                pointerEvents: 'auto',
-              }}
-            >
-              <span>{error}</span>
+          <EditorBanner
+            tone="error"
+            style={{ position: 'absolute', insetInline: 0, top: 0 }}
+            actions={
               <IconButton
                 size="compact"
                 aria-label="Dismiss"
@@ -2382,13 +2252,13 @@ export function Object3DDocumentViewport({
               >
                 <EditorIcon icon={editorIcons.action.close} />
               </IconButton>
-            </div>
-          </div>
+            }
+          >
+            {error}
+          </EditorBanner>
         )}
-        {!error && surfaceStatus === 'building' && (
-          <ViewportSurfaceStatus testId="object3d-document-status">
-            {OBJECT3D_SURFACE_BUILDING}
-          </ViewportSurfaceStatus>
+        {!error && !chromeless && surfaceStatus === 'building' && (
+          <Progress documentId={documentId} title="Preparing the viewport" />
         )}
         {/* Inset furniture by the canvas bleed so chrome stays inside the visible panel. */}
         <div

package/src/kit/components/ViewportViewMenu.tsx

@@ -27,7 +27,7 @@ const ZERO = () => 0;
 
 /**
  * Editor-camera projection and axis presets for the stage’s own shell. A documentId targets its
- * Object3DDocumentSession; the world root uses the editor-wide projection. label shows the view
+ * Object3DDocumentSession; without one, the editor-wide projection. label shows the view
  * name instead of a camera icon, and kebab prefixes the label with three dots.
  */
 export function ViewportViewMenu({

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

@@ -1,5 +1,5 @@
 import { threeStateOf } from '../../three-state';
-import { themeVars } from '@volter/sdk/widgets';
+import { StateSurface } from '@volter/sdk/widgets';
 import { liveMixerFor } from '@volter/editor-threejs/animation/live-mixers';
 import { useCallback, useSyncExternalStore } from 'react';
 import type * as THREE from 'three';
@@ -94,9 +94,7 @@ export function EntityModelDocument({
 
   if (!source)
     return (
-      <div role="alert" style={{ padding: 20, color: themeVars.semantic.danger }}>
-        Scene entity {entityId} is no longer available.
-      </div>
+      <StateSurface tone="error" title={`Scene entity ${entityId} is no longer available`} />
     );
   return (
     <Object3DSnapshotDocument

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

@@ -1,6 +1,7 @@
 import { editorHost } from '@volter/sdk/host';
 import { faCloudSun, faSliders } from '@fortawesome/free-solid-svg-icons';
-import { NumberInput, themeVars } from '@volter/sdk/widgets';
+import { NumberInput, StateSurface, themeVars } from '@volter/sdk/widgets';
+import { Progress } from '@volter/sdk/progress';
 import { useEffect, useMemo, useRef, useState } from 'react';
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
@@ -386,9 +387,7 @@ export function EnvironmentAssetDocument({
         title={title}
         status="HDR image unavailable"
       >
-        <div role="alert" style={{ padding: 20, color: themeVars.semantic.danger }}>
-          {loadError}
-        </div>
+        <StateSurface tone="error" title={`Could not load ${title}`} detail={loadError} />
       </AssetEditorShell>
     );
   }
@@ -400,9 +399,8 @@ export function EnvironmentAssetDocument({
         active={active}
         type="environment image"
         title={title}
-        status="Loading HDR image"
       >
-        <div style={{ padding: 20, color: themeVars.content.muted }}>Loading environment…</div>
+        <Progress documentId={documentId} title={`Loading ${title}`} />
       </AssetEditorShell>
     );
   }

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

@@ -11,7 +11,7 @@
  */
 
 import { beginLiveModuleRevision } from '@volter/sdk/project-module-url';
-import { themeVars } from '@volter/sdk/widgets';
+import { EditorBanner, themeVars } from '@volter/sdk/widgets';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import * as THREE from 'three';
 import { disposeProjectAssetModel } from '../../asset-preview';
@@ -281,37 +281,13 @@ export function LiveModuleDocument({
  *  and never a toast — the document itself has to say why it is stale. */
 function BuildFailureBanner({ failure }: { readonly failure: BuildFailure }) {
   return (
-    <div
-      role="alert"
+    <EditorBanner
+      tone="error"
       data-testid="live-module-error"
-      style={{
-        position: 'absolute',
-        top: 8,
-        left: 8,
-        right: 8,
-        zIndex: 2,
-        maxHeight: '60%',
-        overflow: 'auto',
-        padding: '8px 10px',
-        borderRadius: themeVars.shape.small,
-        background: themeVars.surface.raised,
-        border: `1px solid ${themeVars.semantic.danger}`,
-        color: themeVars.semantic.danger,
-        fontFamily: themeVars.typography.mono,
-        fontSize: 11,
-        lineHeight: 1.5,
-        whiteSpace: 'pre-wrap',
-        wordBreak: 'break-word',
-        pointerEvents: 'auto',
-      }}
+      style={{ position: 'absolute', top: 0, left: 0, right: 0, zIndex: 2 }}
+      detail={failure.stack ? `${failure.message}\n${failure.stack}` : failure.message}
     >
-      <div style={{ fontWeight: 600 }}>
-        This module did not build — showing the last good model.
-      </div>
-      <div style={{ marginTop: 4 }}>{failure.message}</div>
-      {failure.stack ? (
-        <div style={{ marginTop: 6, color: themeVars.content.muted }}>{failure.stack}</div>
-      ) : null}
-    </div>
+      This module did not build — showing the last good model.
+    </EditorBanner>
   );
 }

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

@@ -1,6 +1,7 @@
 import { editorHost } from '@volter/sdk/host';
 import { faCircleHalfStroke, faSliders } from '@fortawesome/free-solid-svg-icons';
-import { Checkbox, NumberInput, themeVars } from '@volter/sdk/widgets';
+import { Checkbox, NumberInput, StateSurface, themeVars } from '@volter/sdk/widgets';
+import { Progress } from '@volter/sdk/progress';
 import { EffectComposer, EffectPass, LUT3DEffect, RenderPass } from 'postprocessing';
 import { useEffect, useMemo, useRef, useState } from 'react';
 import * as THREE from 'three';
@@ -367,9 +368,7 @@ export function LutAssetDocument({
         title={basename(assetPath)}
         status="CUBE LUT 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>
     );
   }
@@ -381,9 +380,8 @@ export function LutAssetDocument({
         active={active}
         type="color grade"
         title={basename(assetPath)}
-        status="Loading CUBE LUT"
       >
-        <div style={{ padding: 20, color: themeVars.content.muted }}>Loading color grade…</div>
+        <Progress documentId={documentId} title={`Loading ${basename(assetPath)}`} />
       </AssetEditorShell>
     );
   }

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

@@ -1,4 +1,5 @@
-import { themeVars } from '@volter/sdk/widgets';
+import { StateSurface } from '@volter/sdk/widgets';
+import { Progress } from '@volter/sdk/progress';
 import { useCallback, useEffect, useState } from 'react';
 import type * as THREE from 'three';
 import {
@@ -83,14 +84,9 @@ export function ModelAssetDocument({
   }, [assetPath, model]);
   if (error)
     return (
-      <div role="alert" style={{ padding: 20, color: themeVars.semantic.danger }}>
-        {error}
-      </div>
-    );
-  if (!model)
-    return (
-      <div style={{ padding: 20, color: themeVars.content.muted }}>Loading {displayName}…</div>
+      <StateSurface tone="error" title={`Could not load ${displayName}`} detail={error} />
     );
+  if (!model) return <Progress documentId={documentId} title={`Loading ${displayName}`} />;
   return (
     <Object3DDocumentViewport
       documentId={documentId}