@volter/editor-threejs 0.5.211 → 0.5.213

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

@@ -1,5 +1,6 @@
 import type { ToolObject3DDocumentAuthoringFactory } from '../../../object3d-contributions';
-import { themeVars } from '@volter/sdk/widgets';
+import { StateSurface } from '@volter/sdk/widgets';
+import { Progress } from '@volter/sdk/progress';
 import type {
   AuthoringAdapter,
   InspectorProvider,
@@ -16,7 +17,7 @@ import { useCallback, useEffect, useMemo, useState } from 'react';
 import type * as THREE from 'three';
 import { type ParticleSystem, QuarksLoader } from 'three.quarks';
 import { quarksParticleSystems } from '../../authoring/quarks-particle-systems';
-import { projectOutputPath } from '@volter/sdk/kit/project-provenance';
+import { projectPathOfServedAsset } from '@volter/sdk/project/output-roots';
 import { Object3DDocumentViewport } from '../StageHost';
 import { threeObject } from '../../../adapter/three-contract';
 
@@ -445,7 +446,7 @@ export async function loadNativeQuarksJsonSource(
     return null;
   }
   return isNativeQuarksJson(json)
-    ? { text, json, projectPath: projectOutputPath(assetPath) }
+    ? { text, json, projectPath: projectPathOfServedAsset(assetPath) }
     : null;
 }
 
@@ -503,14 +504,9 @@ export function QuarksAssetDocument({
 
   if (error)
     return (
-      <div role="alert" style={{ padding: 20, color: themeVars.semantic.danger }}>
-        {error}
-      </div>
-    );
-  if (!artifact)
-    return (
-      <div style={{ padding: 20, color: themeVars.content.muted }}>Loading {displayName}…</div>
+      <StateSurface tone="error" title={`Could not load ${displayName}`} detail={error} />
     );
+  if (!artifact) return <Progress documentId={documentId} title={`Loading ${displayName}`} />;
   return (
     <Object3DDocumentViewport
       documentId={documentId}

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

@@ -1,12 +1,13 @@
+import { editorHost } from '@volter/sdk/host';
 import { faCode, faSliders, faTriangleExclamation } from '@fortawesome/free-solid-svg-icons';
-import { Checkbox, ColorInput, NumberInput, Select, themeVars } from '@volter/sdk/widgets';
+import { Checkbox, ColorInput, EditorBanner, NumberInput, Select, spaceVar, StateSurface, Text, themeVars } from '@volter/sdk/widgets';
+import { Progress } from '@volter/sdk/progress';
 import { useEffect, useMemo, useRef, useState } from 'react';
 import * as THREE from 'three';
-import { readProjectTextFile } from '@volter/sdk/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';
 import {
   FALLBACK_FRAGMENT_SHADER,
   FALLBACK_VERTEX_SHADER,
@@ -18,7 +19,7 @@ import {
   type ShaderUniformDescriptor,
   shaderCompanionPath,
   shaderStageFromPath,
-} from '@volter/sdk/kit/components/asset-viewers/shader-source';
+} from './shader-source';
 
 type PreviewGeometry = 'sphere' | 'box' | 'plane';
 type UniformPreviewValue = number | boolean | string | number[];
@@ -267,7 +268,7 @@ function ShaderPreview({
     const observer = new ResizeObserver(resize);
     observer.observe(host);
 
-    const clock = new THREE.Clock();
+    const timer = new THREE.Timer();
     try {
       renderer.compile(scene, camera);
       renderer.render(scene, camera);
@@ -294,7 +295,8 @@ function ShaderPreview({
 
     const render = () => {
       if (disposed) return;
-      const elapsed = clock.getElapsedTime();
+      timer.update();
+      const elapsed = timer.getElapsed();
       for (const descriptor of descriptors) {
         const uniform = uniforms[descriptor.name];
         if (!uniform) continue;
@@ -448,6 +450,14 @@ function UniformControlRow({
   );
 }
 
+/** One diagnostic as a line: where (the file, its line and column) and what. */
+function diagnosticLine(diagnostic: ShaderDiagnostic, files: ShaderFiles): string {
+  const file = diagnostic.stage === 'program' ? null : files[diagnostic.stage];
+  const where = file?.available ? basename(file.path) : diagnostic.stage;
+  const at = diagnostic.line ? `:${diagnostic.line}${diagnostic.column ? `:${diagnostic.column}` : ''}` : '';
+  return `${where}${at} · ${diagnostic.message}`;
+}
+
 function DiagnosticList({
   diagnostics,
   files,
@@ -456,37 +466,21 @@ function DiagnosticList({
   files: ShaderFiles;
 }) {
   if (diagnostics.length === 0) {
-    return (
-      <div style={{ color: themeVars.semantic.success, fontSize: 11, padding: 4 }}>
-        Shader program compiled successfully.
-      </div>
-    );
+    return <StateSurface inline tone="success" title="Shader program compiled successfully." />;
   }
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 6, padding: 4 }}>
-      {diagnostics.map((diagnostic, index) => {
-        const file = diagnostic.stage === 'program' ? null : files[diagnostic.stage];
-        return (
-          <div
-            key={`${diagnostic.stage}:${diagnostic.line ?? 0}:${diagnostic.message}:${index}`}
-            style={{
-              color:
-                diagnostic.severity === 'warning'
-                  ? themeVars.semantic.warning
-                  : themeVars.semantic.danger,
-              fontSize: 10,
-              lineHeight: 1.45,
-            }}
-          >
-            {file?.available ? basename(file.path) : diagnostic.stage}
-            {diagnostic.line
-              ? `:${diagnostic.line}${diagnostic.column ? `:${diagnostic.column}` : ''}`
-              : ''}
-            {' · '}
-            {diagnostic.message}
-          </div>
-        );
-      })}
+    <div style={{ display: 'flex', flexDirection: 'column', gap: spaceVar[2] }}>
+      {diagnostics.map((diagnostic, index) => (
+        <Text
+          key={`${diagnostic.stage}:${diagnostic.line ?? 0}:${diagnostic.message}:${index}`}
+          as="div"
+          variant="code"
+          selectable
+          tone={diagnostic.severity === 'warning' ? 'warning' : 'danger'}
+        >
+          {diagnosticLine(diagnostic, files)}
+        </Text>
+      ))}
     </div>
   );
 }
@@ -535,8 +529,8 @@ export function ShaderAssetDocument({
     const reload = () => setFileRevision((revision) => revision + 1);
     const companionPath = shaderCompanionPath(assetPath);
     const unsubscribers = [
-      subscribeProjectAsset(assetPath, reload),
-      ...(companionPath ? [subscribeProjectAsset(companionPath, reload)] : []),
+      editorHost().files.subscribeAsset(assetPath, reload),
+      ...(companionPath ? [editorHost().files.subscribeAsset(companionPath, reload)] : []),
     ];
     return () => {
       for (const unsubscribe of unsubscribers) unsubscribe();
@@ -588,17 +582,18 @@ export function ShaderAssetDocument({
         order: PROPERTIES_SECTION_ORDER,
         body: {
           kind: 'custom',
-          render: () => (
+          // (shown once the files are read: the document passes its sections only then)
+          render: () => files && (
             <div
               style={{ display: 'flex', flexDirection: 'column', gap: 5, padding: 4, fontSize: 10 }}
             >
               <span>
-                Vertex · {files ? basename(files.vertex.path) : 'Loading…'}
-                {files && !files.vertex.available ? ' (preview fallback)' : ''}
+                Vertex · {basename(files.vertex.path)}
+                {!files.vertex.available ? ' (preview fallback)' : ''}
               </span>
               <span>
-                Fragment · {files ? basename(files.fragment.path) : 'Loading…'}
-                {files && !files.fragment.available ? ' (preview fallback)' : ''}
+                Fragment · {basename(files.fragment.path)}
+                {!files.fragment.available ? ' (preview fallback)' : ''}
               </span>
               <span style={{ color: themeVars.content.muted }}>
                 Ordinary sibling GLSL files; runtime composition stays in TS/TSX.
@@ -657,9 +652,7 @@ export function ShaderAssetDocument({
         title={basename(assetPath)}
         status="Shader unavailable"
       >
-        <div role="alert" style={{ padding: 20, color: themeVars.semantic.danger }}>
-          {loadError}
-        </div>
+        <StateSurface tone="error" title={`Could not load ${basename(assetPath)}`} detail={loadError} />
       </AssetEditorShell>
     );
   }
@@ -670,9 +663,8 @@ export function ShaderAssetDocument({
         active={active}
         type="shader"
         title={basename(assetPath)}
-        status="Loading GLSL"
       >
-        <div style={{ padding: 20, color: themeVars.content.muted }}>Loading shader files…</div>
+        <Progress documentId={documentId} title={`Loading ${basename(assetPath)}`} />
       </AssetEditorShell>
     );
   }
@@ -720,22 +712,13 @@ export function ShaderAssetDocument({
           </Select>
         </div>
         {diagnostics.length > 0 && (
-          <div
-            style={{
-              position: 'absolute',
-              left: 12,
-              right: 12,
-              bottom: 12,
-              maxHeight: 120,
-              overflow: 'auto',
-              padding: 8,
-              border: `1px solid ${themeVars.semantic.danger}`,
-              borderRadius: 6,
-              background: themeVars.surface.overlay,
-            }}
+          <EditorBanner
+            tone={diagnostics.some((diagnostic) => diagnostic.severity !== 'warning') ? 'error' : 'warning'}
+            style={{ position: 'absolute', left: 0, right: 0, bottom: 0 }}
+            detail={diagnostics.map((diagnostic) => diagnosticLine(diagnostic, files)).join('\n')}
           >
-            <DiagnosticList diagnostics={diagnostics} files={files} />
-          </div>
+            {`${diagnostics.length} issue${diagnostics.length === 1 ? '' : 's'}`}
+          </EditorBanner>
         )}
       </div>
     </AssetEditorShell>

package/src/kit/components/asset-viewers/shader-source.ts

@@ -0,0 +1,144 @@
+/** Native GLSL document helpers. GLSL remains the artifact; these functions
+ * only describe it for Asset Lab and never serialize a Volter shader shape. */
+
+export type ShaderStage = 'vertex' | 'fragment';
+
+export interface ShaderUniformDescriptor {
+  readonly name: string;
+  readonly type: string;
+  readonly arraySize?: number | undefined;
+  readonly stages: readonly ShaderStage[];
+}
+
+export interface ShaderDiagnostic {
+  readonly stage: ShaderStage | 'program';
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly line?: number | undefined;
+  readonly column?: number | undefined;
+}
+
+const VERTEX_SUFFIXES = ['.vert', '.vert.glsl'] as const;
+const FRAGMENT_SUFFIXES = ['.frag', '.frag.glsl'] as const;
+
+function cleanPath(path: string): string {
+  return path.split(/[?#]/, 1)[0]!.toLowerCase();
+}
+
+export function shaderStageFromPath(path: string, source = ''): ShaderStage {
+  const clean = cleanPath(path);
+  if (VERTEX_SUFFIXES.some((suffix) => clean.endsWith(suffix))) return 'vertex';
+  if (FRAGMENT_SUFFIXES.some((suffix) => clean.endsWith(suffix))) return 'fragment';
+  return /\bgl_Position\b/.test(source) ? 'vertex' : 'fragment';
+}
+
+/** Conventional sibling only. A standalone `.glsl` file stays standalone. */
+export function shaderCompanionPath(path: string): string | null {
+  const clean = path.split(/[?#]/, 1)[0]!;
+  if (/\.vert\.glsl$/i.test(clean)) return clean.replace(/\.vert\.glsl$/i, '.frag.glsl');
+  if (/\.frag\.glsl$/i.test(clean)) return clean.replace(/\.frag\.glsl$/i, '.vert.glsl');
+  if (/\.vert$/i.test(clean)) return clean.replace(/\.vert$/i, '.frag');
+  if (/\.frag$/i.test(clean)) return clean.replace(/\.frag$/i, '.vert');
+  return null;
+}
+
+function withoutComments(source: string): string {
+  // Preserve newlines so reflection never perturbs source-line diagnostics.
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, ' '))
+    .replace(/\/\/[^\n]*/g, '');
+}
+
+function declarations(source: string, stage: ShaderStage): ShaderUniformDescriptor[] {
+  const result: ShaderUniformDescriptor[] = [];
+  const pattern =
+    /\buniform\s+(?:(?:lowp|mediump|highp)\s+)?([A-Za-z_]\w*)\s+([A-Za-z_]\w*)\s*(?:\[\s*(\d+)\s*\])?\s*;/g;
+  for (const match of withoutComments(source).matchAll(pattern)) {
+    const type = match[1];
+    const name = match[2];
+    if (!type || !name) continue;
+    const arraySize = match[3] ? Number.parseInt(match[3], 10) : undefined;
+    result.push({ name, type, ...(arraySize ? { arraySize } : {}), stages: [stage] });
+  }
+  return result;
+}
+
+export function reflectShaderUniforms(
+  vertexSource: string,
+  fragmentSource: string,
+): ShaderUniformDescriptor[] {
+  const reflected = new Map<string, ShaderUniformDescriptor>();
+  for (const uniform of [
+    ...declarations(vertexSource, 'vertex'),
+    ...declarations(fragmentSource, 'fragment'),
+  ]) {
+    const current = reflected.get(uniform.name);
+    if (!current) {
+      reflected.set(uniform.name, uniform);
+      continue;
+    }
+    reflected.set(uniform.name, {
+      ...current,
+      stages: [...new Set([...current.stages, ...uniform.stages])],
+    });
+  }
+  return [...reflected.values()];
+}
+
+export function parseShaderDiagnostics(
+  log: string,
+  stage: ShaderDiagnostic['stage'],
+): ShaderDiagnostic[] {
+  const diagnostics = log
+    .split('\n')
+    .map((line) => parseDiagnosticLine(line.trim(), stage))
+    .filter((diagnostic): diagnostic is ShaderDiagnostic => diagnostic !== null);
+  if (diagnostics.length === 0 && log.trim()) {
+    diagnostics.push({ stage, severity: 'error', message: log.trim() });
+  }
+  return diagnostics;
+}
+
+function parseDiagnosticLine(
+  text: string,
+  stage: ShaderDiagnostic['stage'],
+): ShaderDiagnostic | null {
+  if (!text) return null;
+  const colon = text.match(/^(ERROR|WARNING):\s*\d+:(\d+)(?::|\((\d+)\):)\s*(.*)$/i);
+  if (colon) {
+    return {
+      stage,
+      severity: colon[1]!.toLowerCase() === 'warning' ? 'warning' : 'error',
+      line: Number.parseInt(colon[2]!, 10),
+      ...(colon[3] ? { column: Number.parseInt(colon[3], 10) } : {}),
+      message: colon[4] || text,
+    };
+  }
+  const paren = text.match(/^\d+:(\d+)\((\d+)\):\s*(?:(error|warning)\s*:?)?\s*(.*)$/i);
+  if (!paren) return null;
+  return {
+    stage,
+    severity: paren[3]?.toLowerCase() === 'warning' ? 'warning' : 'error',
+    line: Number.parseInt(paren[1]!, 10),
+    column: Number.parseInt(paren[2]!, 10),
+    message: paren[4] || text,
+  };
+}
+
+/** Reset driver-reported lines after Three's injected ShaderMaterial prefix. */
+export function previewShaderSource(source: string): string {
+  return `#line 1\n${source}`;
+}
+
+export const FALLBACK_VERTEX_SHADER = `varying vec2 vUv;
+
+void main() {
+  vUv = uv;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}`;
+
+export const FALLBACK_FRAGMENT_SHADER = `varying vec2 vUv;
+
+void main() {
+  gl_FragColor = vec4(vUv, 0.55, 1.0);
+}`;

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

@@ -1,6 +1,6 @@
 /**
  * THE THREE.JS ASSET LAB VIEWERS, registered by route
- * (`@volter/sdk/kit/asset-viewers`): a glTF model, an environment map, a
+ * (`@volter/sdk/asset-viewers`): a glTF model, an environment map, a
  * LUT, a shader, a live modeling module and a live entity's model. Each loads on
  * first use, so a document that never opens one never pays for three.js.
  */
@@ -10,7 +10,7 @@ import {
   type JsonContentViewer,
   registerAssetViewer,
   registerJsonContentViewer,
-} from '@volter/sdk/kit/asset-viewers';
+} from '@volter/sdk/asset-viewers';
 import { type ComponentType, lazy } from 'react';
 
 const viewers: Readonly<Record<AssetViewerRoute, ComponentType<AssetViewerProps>>> = {
@@ -64,18 +64,6 @@ const viewers: Readonly<Record<AssetViewerRoute, ComponentType<AssetViewerProps>
       ),
     };
   }),
-  'model-preview': lazy(async () => {
-    const { Object3DPreview } = await import('./Object3DPreview');
-    return {
-      default: (props: AssetViewerProps) => (
-        <Object3DPreview
-          assetPath={props.assetPath}
-          {...(props.materialPath ? { materialPath: props.materialPath } : {})}
-          displayName={props.displayName}
-        />
-      ),
-    };
-  }),
   // A project script that BUILDS an Object3D opens as the live modeling
   // document; anything else keeps the text preview it is handed as `fallback`.
   module: lazy(async () => {

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

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

package/src/kit/components/stage-keyboard.tsx

@@ -3,18 +3,12 @@
  * Frame, pivot, snap and the vertex-snap hold, bound for the stage whose
  * document is ACTIVE.
  *
- * They belong to the STAGE, and until 2026-09-19 they were mounted from
- * `stage-overlay-set.tsx`, which a stage only reaches when it has the shell
- * above it (`StageHost.tsx`'s `shellStore && !chromeless`). A document
- * contributed by a PACKAGE mounts outside `EditorProvider`, so the Model
- * document reached NONE of them: measured live in the Code-OSS frame on a
- * models project, the editor's action table held 29 entries — the shell set
- * alone — and the stage's nine (`transform.combined/translate/rotate/scale`,
- * `viewport.toggleSnap/frameSelection/cyclePivot/snapToFloor`, the four view
- * presets) were absent, so G/R/S on the Model stage answered nothing at all.
- * The overlay set is an OVERLAY condition (a bounded host must not pay for
- * the collaboration client it reaches); which keys a stage answers is not,
- * and the two were one line by accident.
+ * They belong to the STAGE, not to `stage-overlay-set.tsx`, which a stage
+ * only reaches when it has the shell above it (`StageHost.tsx`'s
+ * `shellStore && !chromeless`): a document contributed by a PACKAGE mounts
+ * outside `EditorProvider` and still answers G/R/S. The overlay set is an
+ * OVERLAY condition (a bounded host must not pay for the collaboration client
+ * it reaches); which keys a stage answers is not.
  *
  * The ONE registry still means ONE holder (`hotkeys.ts`'s scope table, and
  * `key-actions.ts`'s action table under the frame): the active

package/src/kit/components/stage-overlay-set.tsx

@@ -2,26 +2,26 @@
  * hints and statistics. Package documents supply their own chrome. */
 
 import { useSyncExternalStore } from 'react';
-import { activeAuthoringVersion, subscribeActiveAuthoring } from '@volter/sdk/kit/authoring/active-adapter';
+import { activeAuthoringVersion, subscribeActiveAuthoring } from '@volter/sdk/authoring/active-adapter';
 import {
   object3DDocumentSessionsVersion,
   subscribeObject3DDocumentSessions,
 } from '../authoring/object3d-document-session-registry';
 import type { EditorShellStore } from '../editor-shell-store';
 import type { EditorViewport } from '../editor-viewport';
-import { documentStageContext, type StageChrome, threeSelectionToolsApply } from '@volter/sdk/kit/stage-context';
+import { documentStageContext, type StageChrome, stageSelectionToolsApply } from '@volter/sdk/stage-context';
 import {
   subscribeWorkspaceDocuments,
   workspaceDocumentRegistryVersion,
-} from '@volter/sdk/kit/workspace-document-registry';
+} from '@volter/sdk/workspace-document-registry';
 import {
   subscribeViewportPresentation,
   viewPresentation,
   viewportPresentationVersion,
-} from '@volter/sdk/kit/viewport-presentation';
+} from '@volter/sdk/viewport-presentation';
 import { CameraInfo } from './CameraInfo';
 import { StatsOverlay } from './StatsOverlay';
-import { TransientHintOverlay } from '@volter/sdk/kit/components/TransientHint';
+import { TransientHintOverlay } from '@volter/sdk/components/TransientHint';
 import { ViewportOverlay } from './ViewportOverlay';
 
 /** What the HOST hands over about the stage itself — its own store, the
@@ -52,8 +52,7 @@ export function StageOverlaySet({
   active,
   chrome,
 }: StageOverlaySetProps) {
-  /** THIS stage's own store — the shell's until the stage has finished
-   *  building, which is the same store every overlay read before unit 4. */
+  /** Use the stage's store once built, and the shell store during bootstrap. */
   const stageStore = stage?.store ?? store;
   useSyncExternalStore(store.shell.subscribe, store.shell.getShellSnapshot ?? store.shell.getSnapshot);
   // The stage's own state (its grid, helpers, stats, tool mode) lives on ITS
@@ -64,42 +63,34 @@ export function StageOverlaySet({
   useSyncExternalStore(subscribeWorkspaceDocuments, workspaceDocumentRegistryVersion);
   // THIS stage's context — not the focused one. A capability is present where
   // its condition holds, and the condition is asked of the stage that would
-  // draw it (ARCHITECTURE-CORE §One stage).
+  // draw it.
   const ctx = documentStageContext(store.shell, documentId, chrome);
   /** Whether the selection tools draw here — and that is the WHOLE condition:
    *  they read THIS stage's own store (`stage.store`, the one the shared
    *  panels reach through `focusedStageStore()`), so a prefab's grid button
    *  toggles the prefab's grid and its readout reports the camera its reader
    *  is looking through. */
-  const showsSelectionTools = threeSelectionToolsApply(ctx);
+  const showsSelectionTools = stageSelectionToolsApply(ctx);
   // The camera readout is the editor's own; a view whose target draws none leaves it off
   // (`overlays.cameraReadout`).
   useSyncExternalStore(subscribeViewportPresentation, viewportPresentationVersion, viewportPresentationVersion);
   const cameraReadout = viewPresentation(documentId).overlays.cameraReadout;
   return (
     <>
-      {/* THE STAGE'S OWN KEYBOARD is no longer mounted here: this module is
-          reached only by a stage that has the shell above it, and a
-          package-contributed document (the Model document) has none — so it
-          answered no stage key at all. It is `StageHost.tsx`'s now, beside
-          the stage handle, under the same activation condition
-          (`stage-keyboard.tsx` carries the measurement). */}
+      {/* StageHost mounts the stage keyboard beside its handle under the stage's activation condition. */}
       {showsSelectionTools ? (
         <>
           <ViewportOverlay store={stageStore} documentId={documentId} />
           {cameraReadout ? <CameraInfo /> : null}
         </>
       ) : null}
-      {ctx.surface === 'three' && stageStore.showStats && <StatsOverlay />}
+      {ctx.surface === 'stage' && stageStore.showStats && <StatsOverlay />}
       {/* H2 — the ONE transient hint channel. Lives here because a refused
           transform is a viewport gesture; the overlay is absent from the DOM
           entirely until something has a reason to say. ONE channel means one
           mount — the ACTIVE stage's — so a hint never draws twice. */}
       {active ? <TransientHintOverlay /> : null}
-      {/* W4 (inventory row V9): the scene document mounts NO network overlay.
-          Compact connection state lives in the status bar
-          (`status-contributions.tsx`); the detailed surface is the `network`
-          workspace utility (`NetworkInspectorPanel`), revealed from there. */}
+      {/* Connection state belongs to the status bar; the network utility provides detail. */}
     </>
   );
 }

package/src/kit/components/stage-presence-markers.ts

@@ -1,36 +1,15 @@
-/**
- * THE OTHER PARTICIPANTS, ON A STAGE — the spatial half of collaboration
- * presence: what THIS stage publishes about the reader's own camera and
- * gestures, and the camera frusta, selection boxes and pointer rays it paints
- * for everyone else (WORK.md §Presence and the substrate, presence unit 4).
- *
- * It was the scene panel's, so only the world root had it. Under
- * ARCHITECTURE-CORE §One stage it is a CAPABILITY with a condition — a stage
- * painting a three surface — so every 3D document mounts it and a prefab
- * story shows the same markers the Scene does.
- *
- * WHICH STAGE A PARTICIPANT IS ON. Presence is ONE record per participant
- * (`collaboration-presence.ts`), and its `document` field is written by the
- * shell for the ACTIVE workspace document (`DefaultEditorLayout.tsx`). So a
- * stage publishes its camera only while its own document is the active one —
- * otherwise several stages would overwrite each other's pose in the single
- * record — and paints a participant only on the stage whose id matches that
- * participant's `presence.document`. Measured against the spec's "publish it
- * from the host with the stage's documentId": the presence record has ONE
- * `document` field and the shell already owns it, so the stage owns the
- * CONDITION on writing, not a second writer of that field.
- */
+/** Publish this stage’s camera only while its document is active, and draw each participant on the stage named by presence.document. The shell owns the document field. */
 
-import type { CollaborationParticipant } from '@volter/sdk/session/collaboration-types';
+import { editorHost } from '@volter/sdk/host';
+import type { CollaborationParticipant } from '@volter/sdk/collaboration-types';
 import { EDITOR_THEME_CLASS, graphiteDarkEditorTheme } from '@volter/sdk/widgets';
 import { contentWorldBounds } from '@volter/editor-threejs/viewport/content-bounds';
 import * as THREE from 'three';
-import { collaborationSnapshot } from '@volter/sdk/kit/collaboration-client';
-import { reportCollaborationPresence } from '@volter/sdk/kit/collaboration-presence';
-import { EDITOR_PARTICIPANT_ID } from '@volter/sdk/kit/editor-presence';
+import { reportCollaborationPresence } from '../collaboration-presence';
+import { COLLABORATION_PARTICIPANT_ID as EDITOR_PARTICIPANT_ID } from '@volter/sdk/editor-session-attribution';
 import type { EditorShellStore } from '../editor-shell-store';
 import type { EditorViewport } from '../editor-viewport';
-import { activeWorkspaceDocumentId } from '@volter/sdk/kit/workspace-document-registry';
+import { activeWorkspaceDocumentId } from '@volter/sdk/workspace-document-registry';
 
 interface RemoteCameraMarker {
   camera: THREE.PerspectiveCamera;
@@ -58,9 +37,7 @@ interface RemoteRayMarker {
 /**
  * Remote-camera labels paint into a DETACHED canvas, and a 2D context cannot
  * resolve `var(--volter-…)` — so the theme's value has to be read off the live
- * theme root before it reaches `fillStyle`. Before a theme is installed (unit
- * environments), fall back to the default theme's own value rather than a raw
- * literal, so the label never depends on a color the theme contract doesn't own.
+ * theme root before it reaches `fillStyle`. Use the default theme's value during bootstrap.
  */
 function contentOnAccentColor(): string {
   const root = document.querySelector(`.${EDITOR_THEME_CLASS}`);
@@ -324,7 +301,7 @@ export function bindStagePresenceMarkers(options: StagePresenceOptions): StagePr
   const remoteRayMarkers = new Map<string, RemoteRayMarker>();
   let remotePresenceSequence = -1;
   const syncRemoteSpatialMarkers = (): void => {
-    const snapshot = collaborationSnapshot();
+    const snapshot = editorHost().collaboration.snapshot();
     if (!snapshot || snapshot.sequence === remotePresenceSequence) return;
     remotePresenceSequence = snapshot.sequence;
     /** THE PAINT CONDITION: a participant is on the stage its own presence
@@ -409,7 +386,7 @@ export function bindStagePresenceMarkers(options: StagePresenceOptions): StagePr
     if (!publishes()) return;
     const participantId = (event as CustomEvent<{ participantId?: unknown }>).detail?.participantId;
     if (typeof participantId !== 'string') return;
-    const camera = collaborationSnapshot()?.participants.find(
+    const camera = editorHost().collaboration.snapshot()?.participants.find(
       (participant) => participant.participantId === participantId,
     )?.presence.camera;
     if (!camera) return;