@volter/editor-threejs 0.5.210 → 0.5.212

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,4 @@
-import { announceDocumentStage } from '@volter/sdk/kit/document-viewports';
+import { announceDocumentStage } from '@volter/sdk/document-viewports';
 import { lazy, Suspense, useEffect } from 'react';
 import type { ToolObject3DAuthoringProps, ToolObject3DPreviewProps } from '../../object3d-contributions';
 

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;

package/src/kit/components/stage-transform-chrome.ts

@@ -1,11 +1,11 @@
 /**
  * What a three stage adds to its document's viewport
- * (`@volter/sdk/kit/document-viewports`): the transform-tool driver, read
+ * (`@volter/sdk/document-viewports`): the transform-tool driver, read
  * synchronously, and the shelf strip and header wells behind `lazy()`, so a
  * bounded host that mounts a stage never loads the editor's toolbar.
  */
 import { lazy } from 'react';
-import { documentStageContext, type StageTransformDriver, stageTransformDriver } from '@volter/sdk/kit/stage-context';
+import { documentStageContext, type StageTransformDriver, stageTransformDriver } from '@volter/sdk/stage-context';
 import { threeStoreForHost } from '../three-state';
 
 /** What the host's transform tools drive on this document's stage. */
@@ -17,7 +17,7 @@ export function threeStageTransformDriver(documentId: string): StageTransformDri
 const TransformTools = lazy(() =>
   import('./stage-transform-tools').then((m) => ({ default: m.ThreeStageTransformTools })),
 );
-const TransformControls = lazy(() =>
+const TransformSettings = lazy(() =>
   import('./stage-transform-tools').then((m) => ({ default: m.ThreeStageTransformControls })),
 );
 
@@ -25,6 +25,6 @@ export function threeStageTransformChrome(documentId: string) {
   return {
     transformTools: () => threeStageTransformDriver(documentId),
     TransformTools,
-    TransformControls,
+    TransformSettings,
   } as const;
 }

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

@@ -1,27 +1,21 @@
 /**
  * A THREE STAGE'S TRANSFORM TOOLS, as the stage contributes them to its
- * document's chrome (`@volter/sdk/kit/document-viewports`): what the
+ * document's chrome (`@volter/sdk/document-viewports`): what the
  * host's transform tools drive on it (`stage-context.ts`'s one answer), the tool
  * strip on its shelf and the gizmo's header wells. Every tool writes THIS
  * stage's own store (`stage-store-registry.ts`); the world root's stage runs on
  * the session store, so the Scene document is unchanged either way.
  */
-import { stageTransformDoor } from '@volter/sdk/contributions';
-import { type ViewportInteraction, viewPresentation } from '@volter/sdk/kit/viewport-presentation';
+import { type ViewportInteraction, viewPresentation } from '@volter/sdk/viewport-presentation';
 import { useEffect, useSyncExternalStore } from 'react';
-import { useEditorStore } from '@volter/sdk/kit/editor-runtime';
+import { useEditorStore } from '@volter/sdk/editor-runtime';
 import type { EditorShellStore } from '../editor-shell-store';
 import { threeStageTransformDriver } from './stage-transform-chrome';
-import { stageStore, stageStoresVersion, subscribeStageStores } from '@volter/sdk/kit/stage-store-registry';
+import { stageStore, stageStoresVersion, subscribeStageStores } from '@volter/sdk/stage-store-registry';
 import { threeStateOf } from '../three-state';
-import { ToolStrip, TransformHeaderControls } from '@volter/sdk/kit/components/Toolbar';
+import { ToolStrip, TransformHeaderControls } from '@volter/sdk/components/Toolbar';
 
-/**
- * THE VIEWS WHOSE SHELF HAS ALREADY OPENED, per store — keyed by the VIEW as well, because
- * several views can share one store (measured: a restored `main` armed the shared store, and
- * HeroBox opened after it never got its own boot tool). A `WeakMap` because a store outlives
- * nothing here.
- */
+/** Track boot-tool activation per store and view, since multiple views can share one store. */
 const shelfOpened = new WeakMap<EditorShellStore, Set<string>>();
 
 /**
@@ -62,8 +56,7 @@ export function ThreeStageTransformTools({ documentId }: { readonly documentId:
     if (driver === 'gizmo') armShelfBootTool(own && threeStateOf(own), documentId);
   }, [driver, own, documentId]);
   if (driver === 'none') return null;
-  const door = driver === 'modal' ? stageTransformDoor(documentId) : null;
-  return <ToolStrip store={own ?? shell} {...(door ? { door } : {})} />;
+  return <ToolStrip store={own ?? shell} />;
 }
 
 export function ThreeStageTransformControls({ documentId }: { readonly documentId: string }) {