@volter/editor-threejs 0.5.211 → 0.5.213

package/src/kit/components/ViewportViewMenu.tsx

@@ -10,12 +10,12 @@ import {
   Tooltip,
 } from '@volter/sdk/widgets';
 import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
-import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import type { ShellStore } from '@volter/sdk/shell-store';
 import {
   setThreeViewportProjection,
   subscribeThreeViewportPresentation,
   threeViewportPresentation,
-} from '@volter/sdk/kit/three-viewport-presentation';
+} from '../three-viewport-presentation';
 import {
   object3DDocumentSession,
   object3DDocumentSessionsVersion,
@@ -25,22 +25,11 @@ import {
 const NO_SESSION_SUBSCRIBE = () => () => {};
 const ZERO = () => 0;
 
-/** The standard Scene-view camera menu: projection and axis views in one
- * place. These are editor-camera choices only. */
-/** The stage's projection + axis-view presets. `shell` is the STAGE's own
- *  store's shell, so a preset drives the stage the control is mounted over
- *  (ARCHITECTURE-CORE §One stage unit 4).
- *
- *  A DOCUMENT STAGE IS PAINTED BY ITS SESSION (`Object3DDocumentSession.camera()`), and the
- *  editor-wide projection (`setThreeViewportProjection`) reaches only the world root's stage
- *  (`world-root-stage.ts` is its one subscriber): over a document the Perspective and
- *  Orthographic buttons changed nothing, the defect `ViewportFurniture`'s projection toggle
- *  records. With `documentId` naming a stage that has a session, the menu drives that session,
- *  as the document toolbar's view menu does; the world root keeps the editor-wide value.
- *
- *  `label` draws the trigger as the view's NAME (the look's `stage.chrome.viewName`: Godot's
- *  "⋮ Perspective", Unreal's "Perspective" pill) instead of the camera icon; `kebab` puts
- *  Godot's three dots before it. */
+/**
+ * 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
+ * name instead of a camera icon, and kebab prefixes the label with three dots.
+ */
 export function ViewportViewMenu({
   shell,
   documentId,

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';
@@ -8,7 +8,7 @@ import {
   createAssetPreviewSnapshot,
   disposeAssetPreviewSnapshot,
 } from '../../asset-preview';
-import { useEditorStore } from '@volter/sdk/kit/editor-runtime';
+import { useEditorStore } from '@volter/sdk/editor-runtime';
 import { Object3DDocumentViewport } from '../StageHost';
 
 function entityClips(source: THREE.Object3D): THREE.AnimationClip[] {
@@ -21,17 +21,8 @@ function entityClips(source: THREE.Object3D): THREE.AnimationClip[] {
   return [...discovered];
 }
 
-/**
- * Isolated native projection of a live `Object3D`; the source graph is never
- * reparented (`createAssetPreviewSnapshot` copies it).
- *
- * The object comes in already resolved, so this component has no way to fail
- * for a thing that is on screen — it is the honest shared body of both the
- * Asset Lab's entity document ({@link EntityModelDocument}, which resolves the
- * scene entity and owns the "no longer available" case) and the inspector's
- * preview section (`components/InspectorObjectPreview.tsx`), whose subject the
- * composer has already proved previewable.
- */
+/** Isolated projection of an already-resolved Object3D, shared by entity documents and Inspector
+ * previews. Snapshot the source so its graph stays parented to its owner. */
 export function Object3DSnapshotDocument({
   documentId,
   source,
@@ -76,7 +67,7 @@ export function Object3DSnapshotDocument({
       chromeless={chromeless}
       // The chromeless host is the inspector's preview, which remounts on
       // every selection — it draws through the shared renderer instead of
-      // building one per click (`inspector-preview-renderer.ts`). A full
+      // building one per click. A full
       // document lives as long as its panel and keeps its own.
       rendererLane={chromeless ? 'inspector-preview' : 'own'}
       assetType="entity"
@@ -103,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,14 +1,15 @@
+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';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
 import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
-import type { InspectionSection } from '@volter/sdk/kit/inspection-model';
-import { CONTRIBUTED_SECTION_ORDER, PROPERTIES_SECTION_ORDER } from '@volter/sdk/kit/inspection-model';
-import { AssetEditorShell } from '@volter/sdk/kit/components/AssetEditorShell';
-import { subscribeProjectAsset } from '@volter/sdk/kit/components/asset-editor-persistence';
+import type { InspectionSection } from '@volter/sdk/inspection-model';
+import { CONTRIBUTED_SECTION_ORDER, PROPERTIES_SECTION_ORDER } from '@volter/sdk/inspection-model';
+import { AssetEditorShell } from '@volter/sdk/components/AssetEditorShell';
 
 interface EnvironmentImage {
   readonly texture: THREE.DataTexture;
@@ -296,7 +297,7 @@ export function EnvironmentAssetDocument({
 
   useEffect(() => {
     if (!active) return;
-    return subscribeProjectAsset(assetPath, () => setRevision((value) => value + 1));
+    return editorHost().files.subscribeAsset(assetPath, () => setRevision((value) => value + 1));
   }, [active, assetPath]);
 
   useEffect(() => {
@@ -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

@@ -1,58 +1,17 @@
 /**
- * THE LIVE MODELING VIEW (docs/BLENDER-PARITY.md §Live modeling view, Gap 1):
- * a project TypeScript module that builds an `Object3D`, opened as an Asset
- * Lab document that RE-EXECUTES ON EVERY SAVE with the camera untouched —
- * "watch it model".
+ * Live Object3D document for authored project modules. Probe the export before mounting a viewport;
+ * modules with other shapes use the caller's source viewer.
  *
- * WHAT IS NEW HERE IS ONE THING: the re-execution. Everything else is the
- * surface every other Object3D document already opens on
- * (`StageHost.tsx`'s `Object3DDocumentViewport` — orbit, pick,
- * framing, the document toolbar, the ordinary Object3D inspector subject), and
- * the contract it resolves is the bake lane's, unchanged
- * (`live-module-source.ts`).
+ * A stable build callback returns one owned Group. Rebuilds replace its child, preserving the
+ * stage's camera, renderer and adapter. This component owns child disposal; the viewport's returned
+ * graph disposer is empty so the graph has one teardown path.
  *
- * ## Why the camera survives a rebuild: ONE ROOT, SWAPPED CHILDREN
- *
- * `Object3DDocumentViewport` re-runs its whole lifetime effect — renderer,
- * scene, camera, adapter — whenever the `build` callback's IDENTITY changes.
- * That is how the parametric Builder documents rebuild
- * (`catalog/project-source/editor/tools/builder-document.tsx`: a param edit makes
- * a new `build`, the viewport tears down and stands back up), and it is
- * exactly why those documents snap the camera back to `cameraDirection` on
- * every slider nudge. A modeling loop cannot do that: the whole point is to
- * keep looking at the model from where you put yourself while it changes
- * underneath you.
- *
- * So `build` here is STABLE FOR THE DOCUMENT'S LIFETIME. It returns a
- * container `THREE.Group` this component owns, and a rebuild swaps that
- * container's single CHILD. The viewport never learns a rebuild happened; the
- * camera, the renderer and the GPU state are never touched. This is the
- * "OWNED graph" shape `ToolObject3DAuthoringProps.build` documents (the same
- * one the 3D board and the story turntable take, for the same reason: the
- * graph is async to create), so the returned `dispose` is deliberately empty
- * and THIS component's effect is the one teardown path.
- *
- * ## The probe decides which document this is
- *
- * Detection is structural, never a filename convention — the quarks precedent
- * (`JsonAssetDocument.tsx`). The module is imported and its export resolved
- * ONCE before anything mounts; only an `Object3D` gets the live viewport, and
- * anything else falls through to the `fallback` the caller passed (the
- * ordinary source viewer). Mounting the viewport first and retreating would
- * flash a 3D panel at every `.ts` file in the project.
- *
- * ## A broken save is never a blank pane
- *
- * Once live, a failing rebuild KEEPS THE LAST GOOD MODEL on screen, dimmed,
- * under a banner carrying the message and stack. The document does not
- * unmount, the workspace does not crash, and the next good save clears the
- * banner in place. A failure at FIRST open has no last-good root to keep, so
- * it shows the source viewer with the same banner above it and recovers to the
- * live view when the module compiles.
+ * A failed rebuild keeps the last good model dimmed under a diagnostic banner. A failure before
+ * the first model uses the source viewer with that banner. A successful build clears the failure.
  */
 
-import { beginLiveModuleRevision } from '@volter/sdk/session/project-module-url';
-import { themeVars } from '@volter/sdk/widgets';
+import { beginLiveModuleRevision } from '@volter/sdk/project-module-url';
+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';
@@ -60,7 +19,7 @@ import {
   object3DDocumentSession,
   registerObject3DDocumentPreparation,
 } from '../../authoring/object3d-document-session-registry';
-import { editorConsole } from '@volter/sdk/kit/editor-console';
+import { editorConsole } from '@volter/sdk/editor-console';
 import {
   buildLiveModuleObject3D,
   LiveModuleError,
@@ -71,18 +30,12 @@ import {
   projectModuleChangeMatches,
   projectModuleTransformError,
   subscribeProjectModuleChange,
-} from '@volter/sdk/kit/project-module-changes';
-import { notifyWorkspaceDocumentSelectionChanged } from '@volter/sdk/kit/workspace-document-registry';
+} from '@volter/sdk/project-module-changes';
+import { notifyWorkspaceDocumentSelectionChanged } from '@volter/sdk/workspace-document-registry';
 import { Object3DDocumentViewport } from '../Object3DDocumentViewport';
 import { STANDARD_COMPONENT_CAMERA_DIRECTION } from '../standard-viewport-dressing';
 
-/**
- * The asset-document host (`components/asset-documents.tsx`) hands its content
- * a plain BLOCK container of the panel's full height, not a flex parent — so
- * `flex: 1` on this component's own root measures ZERO and the viewport
- * canvas comes up 1241×0 (measured, 2026-08-29). Height 100% is what fills it;
- * the flex column below it is this component's own layout.
- */
+/** Fill the asset host’s block container by height; this component owns the flex column inside it. */
 const FILL = {
   height: '100%',
   width: '100%',
@@ -91,33 +44,21 @@ const FILL = {
   position: 'relative',
 } as const;
 
-/** The one growing child inside {@link FILL}. Both axes, because a flex ROW
- *  child with no grow measures 1×388 (also measured) — the mirror of the
- *  block-parent trap above. */
+/** Grow this child along both axes within FILL. */
 const FILL_CHILD = { flex: 1, minWidth: 0, minHeight: 0, display: 'flex' } as const;
 
-/** A project module is a live-model document, a plain source file, or not
- *  decided yet. `fallback` covers the last two the same way — the caller's
- *  ordinary viewer — and `reason` is why. */
+/** Whether this module is being probed, showing a live model, or using its ordinary source viewer. */
 type ProbeState =
   | { readonly status: 'probing' }
-  | { readonly status: 'live'; readonly exportName: string }
-  | { readonly status: 'fallback'; readonly reason: string };
+  | { readonly status: 'live' }
+  | { readonly status: 'fallback' };
 
 interface BuildFailure {
   readonly message: string;
   readonly stack?: string | undefined;
 }
 
-/**
- * What the banner says. A transform failure PREFERS the server's own reason:
- * the browser's `import()` rejection for a module the dev server refused to
- * transform is the opaque `Failed to fetch dynamically imported module: <url>`
- * (measured), while Vite reported `Unexpected ";"` at line:col with a source
- * frame on the HMR channel — and the second one is the only one a person
- * mid-edit can act on. The rejection then becomes the detail line, because it
- * is still the truth about what this document tried to do.
- */
+/** Prefer the dev server’s transform diagnostic to the opaque import rejection; retain the rejection as detail. */
 function describeRefusal(refusal: LiveModuleRefusal, modulePath: string): BuildFailure {
   if (refusal.kind !== 'import-failed') return { message: refusal.message };
   const transform = projectModuleTransformError(modulePath);
@@ -140,8 +81,7 @@ export function LiveModuleDocument({
   readonly modulePath: string;
   readonly displayName: string;
   readonly active: boolean;
-  /** Shown when this module is not a model module (and while one that WAS is
-   *  failing to import at first open). */
+  /** Shown while probing, for non-model exports, or when the first import fails. */
   readonly fallback: React.ReactNode;
 }) {
   const [probe, setProbe] = useState<ProbeState>({ status: 'probing' });
@@ -185,19 +125,7 @@ export function LiveModuleDocument({
       mounted = root;
       mountedDispose = dispose;
       container.add(root);
-      // THE CLIPS RIDE THE CONTAINER TOO. `live-module-source.ts` writes a
-      // build result's `animations` onto the built root "so the clip list
-      // travels with the graph the document mounts and every reader downstream
-      // (the Object3D document session, its animation transport) finds it where
-      // it finds a GLTF's" — but the graph this document MOUNTS is the stable
-      // container, and every one of those readers reads `root.animations` on
-      // the document root exactly (`ToolObject3DAuthoring`'s
-      // `source.root.animations.length > 0` gate builds the mixer and the
-      // transport; `model-inspection.ts`'s `root.animations.map` builds the
-      // Animation section). Measured on a rigged module with two looping clips:
-      // no transport, no Animation section, `editor.inspect()` listing only
-      // Preview/Geometry/Rig/Materials/Source. Copying the reference
-      // here is what makes the container the same subject the child is.
+      // Copy animations to the stable container, which is the document root inspected by the transport and Animation section.
       container.animations = root.animations;
       // The hierarchy/inspector project the live graph on every render, so the
       // swap is visible the moment the panels re-render — but nothing else
@@ -209,7 +137,7 @@ export function LiveModuleDocument({
       // Not a model module, and never was: this is an ordinary source file.
       // Silent by design — the project is full of them.
       if (refusal.kind === 'not-a-model' && !hasLastGood) {
-        setProbe({ status: 'fallback', reason: refusal.message });
+        setProbe({ status: 'fallback' });
         return;
       }
       const described = describeRefusal(refusal, modulePath);
@@ -218,7 +146,7 @@ export function LiveModuleDocument({
       // surface, not document-local noise. It retires on the next page load
       // that does not reproduce it (`server/console-ledger.ts`).
       editorConsole.error(`${modulePath}: ${described.message}`, 'live-module');
-      if (!hasLastGood) setProbe({ status: 'fallback', reason: refusal.message });
+      if (!hasLastGood) setProbe({ status: 'fallback' });
     };
 
     /** A save that lands mid-import supersedes this one; its own swap wins. */
@@ -247,7 +175,7 @@ export function LiveModuleDocument({
       captureFailure = null;
       clearProjectModuleTransformError(modulePath);
       setFailure(null);
-      setProbe({ status: 'live', exportName: built.exportName });
+      setProbe({ status: 'live' });
     };
 
     const rebuild = (): Promise<void> => {
@@ -278,14 +206,8 @@ export function LiveModuleDocument({
     };
   }, [container, documentId, modulePath, projectRoot]);
 
-  /**
-   * FRAME ONCE, on the first model this document ever shows — a rebuild must
-   * never move the camera, which is the one thing this document exists to
-   * avoid. The viewport registers its session in its own mount effect, a
-   * render AFTER the state flip that mounts it, so this waits for the session
-   * rather than assuming it: bounded, because "no session after a second" is a
-   * mount failure, not something to poll forever.
-   */
+  /** Frame the first built model once the viewport session mounts, waiting at most 61 animation-frame turns.
+   * Rebuilds retain the person's camera. */
   useEffect(() => {
     if (probe.status !== 'live' || framedRef.current) return;
     let frame = 0;
@@ -359,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,14 +1,15 @@
+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';
 import { LUTCubeLoader } from 'three/addons/loaders/LUTCubeLoader.js';
-import { readProjectTextFile } from '@volter/sdk/kit/editor-api';
-import type { InspectionSection } from '@volter/sdk/kit/inspection-model';
-import { CONTRIBUTED_SECTION_ORDER, PROPERTIES_SECTION_ORDER } from '@volter/sdk/kit/inspection-model';
-import { AssetEditorShell } from '@volter/sdk/kit/components/AssetEditorShell';
-import { subscribeProjectAsset } from '@volter/sdk/kit/components/asset-editor-persistence';
+import { readProjectTextFile } from '@volter/sdk/api/project-source';
+import type { InspectionSection } from '@volter/sdk/inspection-model';
+import { CONTRIBUTED_SECTION_ORDER, PROPERTIES_SECTION_ORDER } from '@volter/sdk/inspection-model';
+import { AssetEditorShell } from '@volter/sdk/components/AssetEditorShell';
 
 interface CubeLut {
   readonly title: string | null;
@@ -282,7 +283,7 @@ export function LutAssetDocument({
 
   useEffect(() => {
     if (!active) return;
-    return subscribeProjectAsset(assetPath, () => setRevision((value) => value + 1));
+    return editorHost().files.subscribeAsset(assetPath, () => setRevision((value) => value + 1));
   }, [active, assetPath]);
 
   useEffect(() => {
@@ -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}

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

@@ -1,35 +1,26 @@
 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';
 import {
   createOwnedObjectPreviewSnapshot,
   createPerspectiveAssetPreviewCamera,
-  disposeProjectAssetModel,
-  loadProjectAssetModel,
   measureAssetPreview,
   type NativeObjectPreviewSource,
   type OwnedObjectPreviewSnapshot,
 } from '../../asset-preview';
-import { registerPreviewResource } from '@volter/sdk/kit/asset-workflow/preview-resource-lifetime';
-import { registerDesignTimeSurface } from '@volter/sdk/kit/coverage/design-time-surfaces';
+import { registerPreviewResource } from '../../asset-workflow/preview-resource-lifetime';
+import { registerDesignTimeSurface } from '@volter/sdk/coverage/design-time-surfaces';
 import {
   isEditorPresentationActive,
   subscribeEditorPresentationActivity,
-} from '@volter/sdk/kit/editor-presentation-activity';
-import {
-  createModelPreviewSource,
-  loadModelThumbnailObject,
-  modelThumbnailFormat,
-} from '../../model-thumbnail';
+} from '../../editor-presentation-activity';
 
 export interface Object3DPreviewProps {
-  readonly assetPath?: string | undefined;
-  readonly materialPath?: string | undefined;
   readonly displayName?: string | undefined;
   readonly active?: boolean | undefined;
-  readonly sourceFactory?: (() => NativeObjectPreviewSource) | undefined;
+  readonly sourceFactory: () => NativeObjectPreviewSource;
   readonly showSkeleton?: boolean | undefined;
   readonly background?: THREE.ColorRepresentation | undefined;
   readonly cameraDirection?: readonly [number, number, number] | undefined;
@@ -65,8 +56,6 @@ let previewCardSequence = 0;
 
 /** Compact, non-authoring Object3D preview for cards, catalogs, and thumbnails. */
 export function Object3DPreview({
-  assetPath,
-  materialPath,
   displayName = 'Object3D preview',
   active = true,
   sourceFactory,
@@ -103,9 +92,8 @@ export function Object3DPreview({
     const scene = new THREE.Scene();
     const camera = new THREE.PerspectiveCamera(35, 1, 0.01, 1000);
     const controls = new OrbitControls(camera, renderer.domElement);
-    const clock = new THREE.Clock();
+    const timer = new THREE.Timer();
     let mixer: THREE.AnimationMixer | null = null;
-    let ownedModel: THREE.Object3D | null = null;
     let ownedFactory: OwnedObjectPreviewSnapshot | null = null;
     let extension: ToolObject3DPreviewExtension | undefined;
     let sparkRenderer: SparkRenderer | null = null;
@@ -192,29 +180,8 @@ export function Object3DPreview({
 
     const load = async () => {
       try {
-        if (sourceFactory) {
-          ownedFactory = createOwnedObjectPreviewSnapshot(sourceFactory);
-          await install(ownedFactory.root);
-          return;
-        }
-        if (!assetPath) throw new Error('Compact Object3D preview has no source.');
-        const format = modelThumbnailFormat(assetPath);
-        if (!format) throw new Error(`No native Three.js loader supports ${assetPath}.`);
-        const loaded =
-          format === 'glb' || format === 'gltf' || format === 'spz'
-            ? await loadProjectAssetModel(assetPath, controller.signal)
-            : await loadModelThumbnailObject({
-                url: assetPath,
-                format,
-                ...(materialPath ? { materialUrl: materialPath } : {}),
-              });
-        ownedModel = createModelPreviewSource(loaded);
-        if (controller.signal.aborted || disposed) {
-          disposeProjectAssetModel(ownedModel);
-          ownedModel = null;
-          return;
-        }
-        await install(ownedModel);
+        ownedFactory = createOwnedObjectPreviewSnapshot(sourceFactory);
+        await install(ownedFactory.root);
       } catch (caught) {
         if (!controller.signal.aborted && !disposed) {
           setError(caught instanceof Error ? caught.message : String(caught));
@@ -245,7 +212,8 @@ export function Object3DPreview({
       // PRESENTATION ONLY. The mixer is never advanced here — see
       // `poseAtFirstFrame`; `delta` drives the project's own presentation
       // extension and the orbit damping, both editor-owned.
-      const delta = Math.min(clock.getDelta(), 0.1);
+      timer.update();
+      const delta = Math.min(timer.getDelta(), 0.1);
       controls.update();
       if (sparkRenderer) scene.add(sparkRenderer);
       try {
@@ -261,7 +229,7 @@ export function Object3DPreview({
         cancelAnimationFrame(frame);
         frame = 0;
       } else if (!disposed && frame === 0) {
-        clock.getDelta();
+        timer.update();
         render();
       }
     });
@@ -293,7 +261,6 @@ export function Object3DPreview({
         } else material?.dispose();
       }
       if (ownedFactory) ownedFactory.dispose();
-      if (ownedModel) disposeProjectAssetModel(ownedModel);
       if (container.contains(renderer.domElement)) container.removeChild(renderer.domElement);
       releaseResizeObserver();
       releaseAnimationFrame();
@@ -301,11 +268,9 @@ export function Object3DPreview({
     };
   }, [
     active,
-    assetPath,
     background,
     cameraDirection,
     exposure,
-    materialPath,
     setupPreview,
     showGrid,
     showSkeleton,
@@ -329,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>
   );
 }