@volter/editor-threejs 0.5.210 → 0.5.212

package/src/kit/viewport-authoring-policy.ts

@@ -1,53 +1,12 @@
-/**
- * WHAT THE GIZMO VIEWPORT ASKS THE SHELL — the one collaborator
- * `editor-viewport.ts` declares and the shell installs at boot.
- *
- * ARCHITECTURE-CORE §Editor chrome, "The viewport stack is separable": a
- * surface below the shell never imports the shell's transport, a world
- * authoring adapter, or project discovery. The viewport was importing six
- * `authoring/` modules to ask four questions —
- *
- *   · which adapter am I driving, and which one do the shared panels drive?
- *   · what is under the pointer?
- *   · which native root owns the current selection, and is it painted here?
- *   · which three root is world-hidden, and how do I apply that?
- *
- * — and every one of those answers is a COMPOSITE fact. `layered-pick.ts`
- * walks `CompositeAuthoringAdapter.childAdapters()` in manifest z-order;
- * `panel-authoring.ts` reaches the workspace-document registry;
- * `world-hidden-viewport.ts` and `viewport-tool-context.ts` resolve the
- * composite's live three child. The viewport itself knows about none of that:
- * it raycasts a scene and drags a gizmo. Measured, those six edges were 96 of
- * its 193 files.
- *
- * ## The default is the NO-SHELL answer, and it is deliberate
- *
- * {@link DEFAULT_VIEWPORT_AUTHORING_POLICY} is what a viewport mounted with no
- * shell above it (a bounded host; a fixture) gets: no composite exists,
- * so there are no layers to walk, no other panel to agree with, no world-group
- * eye to honour. Each default states that outright rather than half-answering.
- * The ONE default that is real logic is {@link adapterOnlyToolOwner} — the
- * structural single-adapter fallback `resolveViewportToolContext` already used
- * for non-composite adapters, which lives here now and is imported BACK by
- * `authoring/viewport-tool-context.ts` so there is one copy of it.
- *
- * In the editor the shell policy is installed once by `EditorProvider`
- * (`EditorContext.tsx`), before any viewport mounts — including the Asset Lab
- * document's own, which is why that document keeps today's behaviour exactly.
- * The install site is the PROVIDER rather than `the world root's stage` because a
- * workspace can have an Asset Lab document open with no scene the world root's stage
- * mounted at all, and that document's viewport must not silently fall to the
- * defaults.
- */
+/** The shell installs the viewport’s authoring policy: adapter resolution, picking, selection ownership and world-hidden roots. Asset documents can use this seam without importing shell discovery or transport modules. */
 
 import type { AuthoringAdapter } from '@volter/project/adapter';
-import { adapterOnlyToolOwner, type ViewportToolOwner } from '@volter/sdk/kit/authoring/viewport-tool-owner';
+import { adapterOnlyToolOwner, type ViewportToolOwner } from '@volter/sdk/authoring/viewport-tool-owner';
 
 export { adapterOnlyToolOwner, type ViewportToolOwner };
 import type * as THREE from 'three';
-import { makeNoAuthoringAdapter } from '@volter/sdk/kit/authoring/no-authoring-adapter';
-import type { ShellStore } from '@volter/sdk/kit/shell-store';
-
+import { makeNoAuthoringAdapter } from '@volter/sdk/authoring/no-authoring-adapter';
+import type { ShellStore } from '@volter/sdk/shell-store';
 
 export interface ViewportAuthoringPolicy {
   /** The adapter this viewport drives when its host injected none. */
@@ -84,7 +43,6 @@ export interface ViewportAuthoringPolicy {
   suppressRootEnvironment(scene: THREE.Scene): void;
 }
 
-
 /** Memoized per store, because the viewport calls `activeAuthoring` per gesture
  *  and adapter IDENTITY keys the selection scope and the handle cache. Mirrors
  *  `authoring/active-adapter.ts`'s own per-store memo. */
@@ -115,7 +73,7 @@ export const DEFAULT_VIEWPORT_AUTHORING_POLICY: ViewportAuthoringPolicy = {
     return true;
   },
   threeSurfaceShowing(_store, adapter) {
-    return !adapter.rects && typeof adapter.hierarchy.object3D === 'function';
+    return !adapter.rects && typeof adapter.hierarchy.nativeObject === 'function';
   },
   threeViewportRootId() {
     return null;
@@ -147,8 +105,3 @@ export function installViewportAuthoringPolicy(policy: ViewportAuthoringPolicy):
 export function viewportAuthoringPolicy(): ViewportAuthoringPolicy {
   return _policy;
 }
-
-/** Test seam: drop the installed policy. */
-export function __resetViewportAuthoringPolicyForTest(): void {
-  _policy = DEFAULT_VIEWPORT_AUTHORING_POLICY;
-}

package/src/kit/viewport-commands.ts

@@ -2,34 +2,26 @@
  * THE THREE VIEWPORT'S RELAY VERBS — framing, the camera, view presets, the
  * open Object3D document's orbit/turntable/frame, the viewport photograph and
  * the display and transform toggles. They are the Three viewport's, so they
- * reach the relay as a command contribution (`@volter/sdk/commands`,
- * `command-registry.ts`) rather than as rows of the kit's own table: a
- * composition with no Three viewport has none of them. Each budget travelled
- * with its verb from `command-table.ts`.
+ * are editor-threejs's Code-OSS commands `volter.<verb>` (`@volter/sdk/commands`),
+ * registered by its page half (`../../contributions/three.page.ts`), rather than
+ * rows of the kit's own table. Each command declares its budget in contributes.commands.
  */
-import type {
-  CommandContribution,
-  CommandDerivedRefresh,
-  CommandSpec,
-  EditorCommandMessage,
-  EditorCommandResult,
-} from '@volter/sdk/commands';
-import { commandLine } from '@volter/sdk/kit/product-command';
-import { activeWorkspaceDocumentId } from '@volter/sdk/kit/workspace-document-registry';
+import type { EditorCommandMessage, EditorCommandResult, VerbHandler } from '@volter/sdk/commands';
+import { commandLine } from '@volter/sdk/product-command';
+import { activeWorkspaceDocumentId } from '@volter/sdk/workspace-document-registry';
 import { object3DDocumentSession } from './authoring/object3d-document-session-registry';
-import { activeDocumentAuthoring } from '@volter/sdk/kit/authoring/shell-document-ops';
+import { activeDocumentAuthoring } from '@volter/sdk/authoring/shell-document-ops';
 import { handleAssetPreviewCommand } from './asset-preview-command';
-import { captureSizeFromCommand } from '@volter/sdk/kit/capture-size';
+import { captureSizeFromCommand } from '@volter/sdk/capture-size';
 import type { EditorShellStore, HelperVisibility } from './editor-shell-store';
-import { editorHost } from '@volter/sdk/host';
 import { entityObject3D } from './entity-object';
 import { VIEWPORT_SHADING_MODES } from '../render/viewport-shading';
-import { focusedStageStore } from '@volter/sdk/kit/stage-context';
+import { focusedStageStore } from '@volter/sdk/stage-context';
 import {
   setViewGridVisible,
   startingPresentation,
   viewPresentationBinding,
-} from '@volter/sdk/kit/viewport-presentation';
+} from '@volter/sdk/viewport-presentation';
 import { threeStoreForHost } from './three-state';
 import { viewportStages } from '../viewport-door';
 import { threeStateOf } from './three-state';
@@ -39,20 +31,14 @@ function activeObject3DDocumentSession() {
   return documentId ? object3DDocumentSession(documentId) : null;
 }
 
-/** One verb over the session's Three store. */
+/** One verb over the session's Three store. Its budget and derivation are its `contributes.commands` entry. */
 function verb(
   run: (store: EditorShellStore, cmd: EditorCommandMessage) => EditorCommandResult | Promise<EditorCommandResult>,
-  timeoutMs?: number,
-  derivedRefresh: CommandDerivedRefresh = 'none',
-): CommandSpec {
-  return {
-    ...(timeoutMs === undefined ? {} : { timeoutMs }),
-    derivedRefresh,
-    handle: (cmd) => {
-      const store = threeStoreForHost();
-      if (!store) return { ok: false, error: `${cmd.type} needs an editor session; none has opened yet.` };
-      return run(store, cmd);
-    },
+): VerbHandler {
+  return (cmd) => {
+    const store = threeStoreForHost();
+    if (!store) return { ok: false, error: `${cmd.type} needs an editor session; none has opened yet.` };
+    return run(store, cmd);
   };
 }
 
@@ -60,7 +46,7 @@ const OK: EditorCommandResult = { ok: true };
 
 type ShadingMode = Parameters<EditorShellStore['setShadingMode']>[0];
 
-export const viewportCommands: CommandContribution['commands'] = {
+export const viewportVerbs: Readonly<Record<string, VerbHandler>> = {
   'focus-entity': verb((store, cmd) => {
     if (!activeObject3DDocumentSession()?.frameIds([cmd['id'] as string])) {
       store.shell.focusOnEntity(cmd['id'] as string);
@@ -107,9 +93,7 @@ export const viewportCommands: CommandContribution['commands'] = {
     return OK;
   }),
   'view-preset': verb((store, cmd) => {
-    // An absent or unknown preset is refused BY NAME: unguarded it reached
-    // `cameraPresetDirection` and threw a TypeError that named neither the
-    // command nor the vocabulary (measured live, 2026-09-18).
+    // Refuse absent or unknown camera presets with the accepted vocabulary.
     const requested = cmd['preset'];
     const presets = ['top', 'front', 'right', 'perspective'] as const;
     if (typeof requested !== 'string' || !(presets as readonly string[]).includes(requested)) {
@@ -154,8 +138,8 @@ export const viewportCommands: CommandContribution['commands'] = {
   // the move's own wall clock. Both refuse a length past 60 s themselves. There
   // is no Scene fallback: the Scene viewport's camera answers to
   // `view-preset`/`set-camera` and has no framed subject to circle.
-  'document-orbit': verb((_store, cmd) => documentMove(cmd), 120_000),
-  'document-turntable': verb((_store, cmd) => documentMove(cmd), 120_000),
+  'document-orbit': verb((_store, cmd) => documentMove(cmd)),
+  'document-turntable': verb((_store, cmd) => documentMove(cmd)),
   'document-frame': verb((_store, cmd) => {
     const documentSession = activeObject3DDocumentSession();
     if (!documentSession) {
@@ -210,22 +194,11 @@ export const viewportCommands: CommandContribution['commands'] = {
     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, quality) } };
-  }, 120_000),
+  }),
   'capture-viewport': verb(async (store, cmd) => {
     // Fresh, unthrottled on-demand capture (see EditorShellStore.captureViewportImage).
     const requested = captureSizeFromCommand(cmd);
     if ('error' in requested) return { ok: false, error: requested.error };
-    // AN ADOPTED SCENE IS PRESENTED BY ITS ADOPTER. The store's renderer and
-    // camera are its own viewport's; re-rendering a scene another document
-    // adopted through them came back white.
-    if (store.hasAdoptedScene) {
-      try {
-        const capture = await editorHost().documents.captureActive(requested.size);
-        return { ok: true, data: { base64: capture.base64, mimeType: capture.mimeType } };
-      } catch (error) {
-        return { ok: false, error: error instanceof Error ? error.message : String(error) };
-      }
-    }
     const dataUrl = store.captureViewportImage(requested.size);
     if (!dataUrl) {
       // The refusal names the MECHANISM and the door that does answer: this door
@@ -235,21 +208,20 @@ export const viewportCommands: CommandContribution['commands'] = {
         ok: false,
         error:
           "This door photographs the editor's own three.js Scene viewport, and nothing has bound one " +
-          '(no renderer/scene/camera). A canvas-surface world (a first-party canvas root, or a ' +
-          'PixiJS/Phaser/Babylon ingest) never binds it — it draws on its own canvas in the Game ' +
-          'document. Capture that through `capture-active-document` (`editor.captureActiveDocument()`) ' +
-          `or the running game through \`bridge-screenshot\` (${commandLine('screenshot')}).`,
+          '(no renderer/scene/camera). Capture a document-owned canvas through ' +
+          '`capture-active-document` (`editor.captureActiveDocument()`) ' +
+          `or the running game through ${commandLine('capture --region play')}.`,
       };
     }
     const comma = dataUrl.indexOf(',');
     const base64 = comma >= 0 ? dataUrl.slice(comma + 1) : dataUrl;
     return { ok: true, data: { base64, mimeType: 'image/png' } };
-  }, undefined, 'if-content-changed'),
+  }),
   // The Asset Lab's photographs; the budget covers a multi-shot set's renders.
-  'capture-asset-preview': verb((store, cmd) => handleAssetPreviewCommand(store, cmd), 30_000, 'if-content-changed'),
+  'capture-asset-preview': verb((store, cmd) => handleAssetPreviewCommand(store, cmd)),
   // Display — set semantics (only toggle when the value differs).
   'set-grid': verb((_store, cmd) => {
-    // The ACTIVE view's grid switch (`kit/viewport-presentation`), one per view.
+    // The ACTIVE view's grid switch (`@volter/sdk/viewport-presentation`), one per view.
     const viewId = activeWorkspaceDocumentId();
     if (!viewId || !viewPresentationBinding(viewId)) {
       return { ok: false, error: 'set-grid: the active document draws no grid.' };
@@ -272,8 +244,7 @@ export const viewportCommands: CommandContribution['commands'] = {
   }),
   'set-shading-mode': verb((store, cmd) => {
     const documentSession = activeObject3DDocumentSession();
-    // A MODE THE VIEWPORT DOES NOT DRAW IS REFUSED BY NAME: an unknown one reached the renderer
-    // and every frame after it threw (`editor.shading('material')`).
+    // Refuse modes the active viewport does not support before changing renderer state.
     const mode = cmd['mode'];
     const known: readonly string[] = documentSession
       ? [...VIEWPORT_SHADING_MODES, 'uv', 'vertex-colors']

package/src/kit/viewport-hotkeys.ts

@@ -7,11 +7,11 @@
  * W/E/R under `volter`, G/R/S under `blender`.
  */
 import { editorHost } from '@volter/sdk/host';
-import { getActiveScope, installHotkeys, setActiveScope } from '@volter/sdk/kit/hotkeys';
-import { showTransientHint } from '@volter/sdk/kit/transient-hint';
+import { getActiveScope, installHotkeys, setActiveScope } from '@volter/sdk/hotkeys';
+import { showTransientHint } from '@volter/sdk/transient-hint';
 import type { EditorShellStore, TransformMode } from './editor-shell-store';
 import type { EditorViewport } from './editor-viewport';
-import { requestTransformMode } from '@volter/sdk/kit/transform-mode-request';
+import { requestTransformMode } from '@volter/sdk/transform-mode-request';
 
 export function registerViewportHotkeys(
   store: EditorShellStore,
@@ -23,18 +23,17 @@ export function registerViewportHotkeys(
     if (!viewport.isFlying) requestTransformMode(store.shell, mode);
   };
   const unbind = keyboard.bindActions([
-    { id: 'transform.select', scope: 'stage', run: transformMode('select') },
-    { id: 'transform.combined', scope: 'stage', run: transformMode('combined') },
-    { id: 'transform.translate', scope: 'stage', run: transformMode('translate') },
-    { id: 'transform.rotate', scope: 'stage', run: transformMode('rotate') },
-    { id: 'transform.scale', scope: 'stage', run: transformMode('scale') },
+    { id: 'transform.select', run: transformMode('select') },
+    { id: 'transform.combined', run: transformMode('combined') },
+    { id: 'transform.translate', run: transformMode('translate') },
+    { id: 'transform.rotate', run: transformMode('rotate') },
+    { id: 'transform.scale', run: transformMode('scale') },
     // Snap has a key and says what it did: a human build session asked "how
     // do you toggle the snap" with the magnet button on screen the whole time.
     // The hint names the ACTIVE keymap's key, never a remembered literal.
     // Holding Ctrl/⌘ during a drag snaps temporarily (editor-viewport.ts).
     {
       id: 'viewport.toggleSnap',
-      scope: 'stage',
       run: () => {
         store.shell.toggleSnap();
         const { translate, rotate, scale } = store.shell.snapValues;
@@ -46,36 +45,35 @@ export function registerViewportHotkeys(
         );
       },
     },
-    { id: 'viewport.frameSelection', scope: 'stage', run: () => store.shell.focusOnSelection() },
+    { id: 'viewport.frameSelection', run: () => store.shell.focusOnSelection() },
     {
       id: 'viewport.cyclePivot',
-      scope: 'stage',
       run: () => {
         const pivotModes = ['active-element', 'median-point', 'individual-origins'] as const;
         const idx = pivotModes.indexOf(store.shell.pivotMode);
         store.shell.setPivotMode(pivotModes[(idx + 1) % pivotModes.length]!);
       },
     },
-    { id: 'view.top', scope: 'stage', run: () => store.shell.setViewPreset('top') },
-    { id: 'view.front', scope: 'stage', run: () => store.shell.setViewPreset('front') },
-    { id: 'view.right', scope: 'stage', run: () => store.shell.setViewPreset('right') },
-    { id: 'view.bottom', scope: 'stage', run: () => store.shell.setViewPreset('bottom') },
-    { id: 'view.back', scope: 'stage', run: () => store.shell.setViewPreset('back') },
-    { id: 'view.left', scope: 'stage', run: () => store.shell.setViewPreset('left') },
-    { id: 'view.orbitLeft', scope: 'stage', run: () => store.shell.stepView('orbit-left') },
-    { id: 'view.orbitRight', scope: 'stage', run: () => store.shell.stepView('orbit-right') },
-    { id: 'view.orbitUp', scope: 'stage', run: () => store.shell.stepView('orbit-up') },
-    { id: 'view.orbitDown', scope: 'stage', run: () => store.shell.stepView('orbit-down') },
-    { id: 'view.opposite', scope: 'stage', run: () => store.shell.stepView('opposite') },
-    { id: 'view.rollLeft', scope: 'stage', run: () => store.shell.stepView('roll-left') },
-    { id: 'view.rollRight', scope: 'stage', run: () => store.shell.stepView('roll-right') },
-    { id: 'view.all', scope: 'stage', run: () => store.shell.frameAll() },
-    { id: 'view.zoomIn', scope: 'stage', run: () => store.shell.zoomView(1) },
-    { id: 'view.zoomOut', scope: 'stage', run: () => store.shell.zoomView(-1) },
-    { id: 'view.perspective', scope: 'stage', run: () => store.shell.setViewPreset('perspective') },
-    { id: 'view.projection', scope: 'stage', run: () => store.shell.toggleProjection() },
-    { id: 'view.camera', scope: 'stage', run: () => store.shell.toggleCameraView() },
-    { id: 'viewport.snapToFloor', scope: 'stage', run: () => viewport.snapSelectionToFloor() },
+    { id: 'view.top', run: () => store.shell.setViewPreset('top') },
+    { id: 'view.front', run: () => store.shell.setViewPreset('front') },
+    { id: 'view.right', run: () => store.shell.setViewPreset('right') },
+    { id: 'view.bottom', run: () => store.shell.setViewPreset('bottom') },
+    { id: 'view.back', run: () => store.shell.setViewPreset('back') },
+    { id: 'view.left', run: () => store.shell.setViewPreset('left') },
+    { id: 'view.orbitLeft', run: () => store.shell.stepView('orbit-left') },
+    { id: 'view.orbitRight', run: () => store.shell.stepView('orbit-right') },
+    { id: 'view.orbitUp', run: () => store.shell.stepView('orbit-up') },
+    { id: 'view.orbitDown', run: () => store.shell.stepView('orbit-down') },
+    { id: 'view.opposite', run: () => store.shell.stepView('opposite') },
+    { id: 'view.rollLeft', run: () => store.shell.stepView('roll-left') },
+    { id: 'view.rollRight', run: () => store.shell.stepView('roll-right') },
+    { id: 'view.all', run: () => store.shell.frameAll() },
+    { id: 'view.zoomIn', run: () => store.shell.zoomView(1) },
+    { id: 'view.zoomOut', run: () => store.shell.zoomView(-1) },
+    { id: 'view.perspective', run: () => store.shell.setViewPreset('perspective') },
+    { id: 'view.projection', run: () => store.shell.toggleProjection() },
+    { id: 'view.camera', run: () => store.shell.toggleCameraView() },
+    { id: 'viewport.snapToFloor', run: () => viewport.snapSelectionToFloor() },
   ]);
 
   const onPointerDown = () => setActiveScope('viewport');

package/src/kit/viewport-status-facet.ts

@@ -2,14 +2,13 @@
  * THE VIEWPORT'S STATUS KEYS, reported by the Three set as a status facet
  * (`host.session.reportFacet`): grid, helpers, stats, shading, helper visibility,
  * the armed transform tool, space and snap, and the camera — each for the stage
- * the person is looking at (`focusedStageStore`, ARCHITECTURE-CORE §One stage
- * unit 4), with an Object3D document's own presentation where it has one.
+ * the person is looking at , with an Object3D document's own presentation where it has one.
  */
 import { editorHost } from '@volter/sdk/host';
-import { activeWorkspaceDocumentId } from '@volter/sdk/kit/workspace-document-registry';
+import { activeWorkspaceDocumentId } from '@volter/sdk/workspace-document-registry';
 import { object3DDocumentSession } from './authoring/object3d-document-session-registry';
-import { focusedStageStore } from '@volter/sdk/kit/stage-context';
-import { viewGridVisible } from '@volter/sdk/kit/viewport-presentation';
+import { focusedStageStore } from '@volter/sdk/stage-context';
+import { viewGridVisible } from '@volter/sdk/viewport-presentation';
 import { threeStoreForHost } from './three-state';
 import { threeStateOf } from './three-state';
 

package/src/kit/viewport-surface-status.tsx

@@ -0,0 +1,44 @@
+/**
+ * The 3D board's empty-viewport vocabulary, reused by every other design
+ * surface that would otherwise sit blank while it builds. Scene's root-aware
+ * loading/failure/empty states live in `SurfaceStateOverlay`; this compact
+ * label remains for object/board construction whose subject is already known.
+ *
+ * Idle / building / ready is viewport STATE, not a new overlay channel —
+ * the board already owns this shape (`ThreeBoardDocument`: idle "Open this
+ * tab…", building "Settling N stories…"). Scene's first design
+ * mount and `Object3DDocumentViewport`'s first construct are the same wait
+ * with different subjects. Copy names the subject being prepared; it does not
+ * claim a narrower phase (such as physics settling) while indexing, mounting,
+ * bounds/layout, or renderer setup is actually in flight.
+ */
+
+import { themeVars } from '@volter/sdk/widgets';
+import type { ReactNode } from 'react';
+
+/** Fixed construct tail after the board scene exists — viewport-bind, not settle. */
+export const OBJECT3D_SURFACE_BUILDING = 'Preparing the viewport…';
+
+export function ViewportSurfaceStatus({
+  testId,
+  children,
+}: {
+  readonly testId: string;
+  readonly children: ReactNode;
+}) {
+  return (
+    <div
+      data-testid={testId}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        padding: 16,
+        fontSize: 12,
+        color: themeVars.content.muted,
+        pointerEvents: 'none',
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/loader.ts

@@ -3,7 +3,7 @@
  *
  * Provides a single LoadingManager (for Three.js loaders) and resolveUrl()
  * (for raw fetch calls) so that all engine asset requests go through one
- * configurable URL prefix. Call setAssetPrefix() once at runtime startup.
+ * configurable URL prefix.
  *
  * Three.js loaders constructed with `loadingManager` automatically rewrite
  * URLs via setURLModifier(). For raw fetch() calls, wrap the URL with
@@ -34,18 +34,12 @@ function rewriteUrl(url: string): string {
 export const loadingManager = new THREE.LoadingManager();
 loadingManager.setURLModifier(rewriteUrl);
 
-/** Pre-configured TextureLoader using the shared manager. */
-export const textureLoader = new THREE.TextureLoader(loadingManager);
-
 /**
  * Shared DRACOLoader for decoding DRACO-compressed GLTF/GLB meshes.
  *
- * The decoder wasm/js is vendored under
- * packages/game-editor/template/public/jsm/libs/draco/gltf/ and served at the
- * absolute runtime path '/jsm/libs/draco/gltf/' (DRACOLoader appends
- * draco_wasm_wrapper.js / draco_decoder.wasm to this path). This is an
- * absolute path, so it deliberately does NOT go through the asset prefix —
- * the decoder is engine infrastructure, not a scene asset.
+ * Decoder wasm/js is served at '/jsm/libs/draco/gltf/'. DRACOLoader
+ * appends draco_wasm_wrapper.js / draco_decoder.wasm to this absolute path,
+ * independently of the scene asset prefix.
  */
 export const dracoLoader = new DRACOLoader(loadingManager);
 dracoLoader.setDecoderPath('/jsm/libs/draco/gltf/');
@@ -53,77 +47,20 @@ dracoLoader.setDecoderPath('/jsm/libs/draco/gltf/');
 /**
  * Shared KTX2Loader for decoding KHR_texture_basisu (KTX2/Basis) textures.
  *
- * Vendored and served EXACTLY like the DRACO decoder above — the Basis
- * transcoder js/wasm live in repo-root `public/jsm/libs/basis/` (the editor)
- * and `packages/game-editor/template/public/jsm/libs/basis/` (a scaffolded game's
- * own build), pinned in `vendor/upstream-assets.lock.json`, and KTX2Loader
- * appends `basis_transcoder.js` / `.wasm` to this absolute path.
- *
- * Without this wiring, the Asset Budget's "Compress textures · KTX2" output
- * is a GLB nothing in the engine can load — which is why the op and this
- * loader landed together.
+ * The host serves basis_transcoder.js and basis_transcoder.wasm at
+ * '/jsm/libs/basis/'. KTX2Loader appends the filenames to this absolute path.
  */
 export const ktx2Loader = new KTX2Loader(loadingManager);
 ktx2Loader.setTranscoderPath('/jsm/libs/basis/');
 
-let ktx2SupportDetected = false;
-
-/**
- * Teach the shared KTX2Loader which compressed formats THIS GPU accepts.
- *
- * KTX2Loader refuses to transcode until it has seen a renderer, and the
- * answer is a property of the page's GPU rather than of any one renderer —
- * so the FIRST renderer to exist supplies it and every later one is a no-op.
- * Called by the engine's own renderer setup (`setup/setup-renderer.ts`) and
- * by the editor's viewport, which between them cover every surface that
- * parses a GLB.
- *
- * This sits on the MOUNT path, so it must never throw for a renderer it
- * cannot question. `detectSupport` reads `renderer.extensions.has/get` (or
- * `renderer.hasFeature` on a WebGPU renderer) — surface a headless stand-in
- * (the test harnesses' fake renderers, any non-WebGL host) does not have.
- * Such a renderer is skipped WITHOUT latching, so the first renderer that
- * can actually answer still configures the loader for the whole page.
- */
-export function detectKtx2Support(renderer: THREE.WebGLRenderer): void {
-  if (ktx2SupportDetected) return;
-  const probe = renderer as unknown as
-    | {
-        isWebGPURenderer?: boolean;
-        hasFeature?: unknown;
-        extensions?: { has?: unknown; get?: unknown };
-      }
-    | null
-    | undefined;
-  const canAnswer =
-    probe != null &&
-    (probe.isWebGPURenderer === true
-      ? typeof probe.hasFeature === 'function'
-      : typeof probe.extensions?.has === 'function' && typeof probe.extensions?.get === 'function');
-  if (!canAnswer) return;
-  ktx2Loader.detectSupport(renderer);
-  ktx2SupportDetected = true;
-}
-
 /** Pre-configured GLTFLoader using the shared manager, with DRACO decoding wired in. */
 export const gltfLoader = new GLTFLoader(loadingManager);
 gltfLoader.setDRACOLoader(dracoLoader);
 gltfLoader.setKTX2Loader(ktx2Loader);
-// EXT_meshopt_compression decoding (three's own bundled decoder — inline
-// wasm, no fetch). Without this, a meshopt-compressed GLB — including the
-// output of the editor's Asset Budget "Compress · meshopt" action (W4a M3) —
-// throws at load time in every runtime and the editor viewport. Symmetric
-// with the DRACO wiring above (CB2): the ONE shared loader owns codec setup.
+// Configure the shared loader’s bundled meshopt decoder for EXT_meshopt_compression, alongside its
+// DRACO decoder.
 gltfLoader.setMeshoptDecoder(MeshoptDecoder);
 
-/**
- * Set the URL prefix prepended to relative asset paths.
- * Called once by createGameRuntime(). Defaults to '/'.
- */
-export function setAssetPrefix(prefix: string): void {
-  _prefix = prefix.endsWith('/') ? prefix : prefix ? `${prefix}/` : '/';
-}
-
 /**
  * Resolve a relative asset URL using the current prefix.
  * Use this for raw fetch() calls — Three.js loaders using

package/src/object3d-contributions.ts

@@ -8,11 +8,11 @@
  */
 
 import type { AuthoringAdapter } from '@volter/project/adapter';
+import type { SourceObject3DAuthoringAdapter } from './kit/authoring/source-object3d-authoring-adapter';
 import type {
   DocumentPersistenceBinding,
-  DocumentPersistenceResource,
-} from '@volter/sdk/kit/authoring/object3d-document-persistence';
-import type { PresentationLayer } from '@volter/sdk/kit/viewport-presentation';
+} from '@volter/sdk/authoring/document-persistence-types';
+import type { PresentationLayer } from '@volter/sdk/viewport-presentation';
 import type { ComponentType } from 'react';
 import type {
   AnimationClip,
@@ -44,22 +44,23 @@ export interface ToolObject3DPreviewSource {
   readonly hierarchyRoots?: readonly Object3D[];
   readonly animations?: readonly AnimationClip[];
   /**
-   * The source's OWN tick, and the host drives it EXACTLY ONCE per mount — for
-   * the bounded design-time settle that gives a physics-owned body the pose it
-   * actually rests in (`authoring/design-time-settle.ts`). It is never a frame
-   * loop: content time does not advance on a design-time surface, so a source
-   * that animates from here shows its settled pose and then holds it. Play is
-   * where a world runs.
+   * The source's OWN tick: the stage's transport calls it as content time
+   * advances (`StageHost`'s `advanceContent`). Content time does not advance on
+   * its own on a design-time surface; Play is where a world runs.
    */
   update?(deltaSeconds: number): void;
   /** Prepare camera-dependent draw buffers immediately before rendering.
    * Does not advance content time or mutate the authored document. An optional
    * returned function restores temporary draw state, including after errors.
    * Interactive draws may use disposable navigation geometry; omitted/false
-   * always means full detail (captures and default frame-cost readings). */
-  prepareDraw?(camera: Camera, options?: {interactive: boolean; height: number; multiDraw?: boolean; renderer?: WebGLRenderer}): void | (() => void);
+   * always means full detail (captures and default frame-cost readings).
+   * `drawMode` is the stage's draw mode for this draw, `pixelScale` its target pixels per
+   * output pixel (the device pixel ratio on screen, the supersampling factor in a photograph),
+   * and `photograph` says the draw is a capture, which gets one chance: nothing in it may
+   * settle on a later frame. */
+  prepareDraw?(camera: Camera, options?: {interactive: boolean; height: number; multiDraw?: boolean; renderer?: WebGLRenderer; drawMode?: string; pixelScale?: number; photograph?: boolean}): void | (() => void);
   /**
-   * EVERY CHANGE TO WHAT THE SOURCE DRAWS, announced: the host calls
+   * EVERY CHANGE TO WHAT THE SOURCE DRAWS, announced: the source calls
    * `listener` whenever the source's graph, materials, textures or poses may
    * look different, and returns nothing from it. A source that offers this is
    * drawn only when something changed -- this, the camera, input on the
@@ -153,16 +154,8 @@ export interface ToolViewportDressing {
    */
   readonly viewLocked?: Object3D;
   /**
-   * THE STAGE'S VIEW TRANSFORM — three's `WebGLRenderer.toneMapping`. Omitted
-   * means the editor's own, ACES.
-   *
-   * A document whose source system states its own transform passes that one
-   * instead: Blender's factory scene is AgX (`view_settings.view_transform`),
-   * and this product's Blender RENDER path already photographs through
-   * `AgXToneMapping` — so before this existed the viewport was the one
-   * surface in the chain running a different curve from the thing it frames.
-   * It is not a look preference: the curve decides how a shading range lands
-   * on screen, and two curves over one radiance are two different pictures.
+   * The stage’s three.js tone-mapping transform; omitted uses ACES. Documents can supply their
+   * source system’s transform so viewport and render use the same curve, such as Blender’s AgX.
    */
   readonly toneMapping?: ToneMapping;
 }
@@ -213,7 +206,7 @@ export interface ToolObject3DAuthoringProps {
   /** Per-document overrides of the standard viewport dressing. */
   readonly dressing?: ToolViewportDressing;
   /** The kind of stage this view is, for its starting presentation
-   *  (`@volter/sdk/kit/viewport-presentation`): the document's own kind (`'model'`).
+   *  (`@volter/sdk/viewport-presentation`): the document's own kind (`'model'`).
    *  Without it the kind is read off the document id's prefix. */
   readonly stageKind?: string;
   /** How far the OPENING view stands back from a fit of the content: `1` fills the view (the
@@ -236,16 +229,10 @@ export interface ToolObject3DAuthoringProps {
   } | null;
   /**
    * THE DOCUMENT'S OWN PRESENTATION LAYER, over the stage's starting values and under a person's
-   * choices (`kit/viewport-presentation`): what the file itself says about how it is seen — a
+   * choices (`@volter/sdk/viewport-presentation`): what the file itself says about how it is seen — a
    * `.blend`'s saved lens as `camera.fov`. Read when the document binds.
    */
   readonly presentation?: PresentationLayer | null;
-  /**
-   * Optional binding from live native clips back to ordinary project source.
-   * Project code only serializes its own TypeScript shape; the editor owns the
-   * checksum-guarded write and records it in the canonical project history.
-   * Without this binding the animation workspace remains honestly read-only.
-   */
   /**
    * Project-owned serialization for this authored document. Each serializer
    * returns the exact bytes of one ordinary project file; the host writes all
@@ -387,16 +374,13 @@ export interface ToolObject3DDocumentState {
   readonly animations: readonly AnimationClip[];
 }
 
-/** One project-owned artifact participating in an Asset Lab commit. */
-export type ToolObject3DDocumentResource = DocumentPersistenceResource<ToolObject3DDocumentState>;
-
 export type ToolObject3DDocumentPersistence = DocumentPersistenceBinding<ToolObject3DDocumentState>;
 
 export interface ToolObject3DDocumentAuthoringContext extends ToolObject3DDocumentState {
   readonly documentId: string;
   readonly sourcePath: string;
   readonly scene: Scene;
-  readonly defaultAdapter: AuthoringAdapter;
+  readonly defaultAdapter: SourceObject3DAuthoringAdapter;
   /**
    * Serialize this project-owned document through its declared persistence
    * resources and record the change in canonical history. Rejects when the