@volter/editor-threejs 0.5.211 → 0.5.213

package/src/kit/collaboration-presence.ts

@@ -0,0 +1,41 @@
+import { editorHost } from '@volter/sdk/host';
+import type { CollaborationPresence } from '@volter/sdk/collaboration-types';
+
+let presence: CollaborationPresence = {
+  document: null,
+  file: null,
+  oid: null,
+  selection: [],
+  camera: null,
+  gesture: null,
+};
+let sent = '';
+let scheduled = false;
+let inFlight = false;
+
+const PRESENCE_INTERVAL_MS = 100;
+
+function schedulePresence(): void {
+  if (scheduled || inFlight) return;
+  scheduled = true;
+  globalThis.setTimeout(() => {
+    scheduled = false;
+    const serialized = JSON.stringify(presence);
+    if (serialized === sent) return;
+    sent = serialized;
+    inFlight = true;
+    void editorHost().collaboration.updatePresence(presence)
+      .catch(() => {
+        sent = '';
+      })
+      .finally(() => {
+        inFlight = false;
+        if (JSON.stringify(presence) !== sent) schedulePresence();
+      });
+  }, PRESENCE_INTERVAL_MS);
+}
+
+export function reportCollaborationPresence(patch: Partial<CollaborationPresence>): void {
+  presence = { ...presence, ...patch };
+  schedulePresence();
+}

package/src/kit/components/CameraInfo.tsx

@@ -1,6 +1,6 @@
 import { EditorSurface, Inline, Text } from '@volter/sdk/widgets';
 import { useEffect, useRef, useState } from 'react';
-import { useEditorStats } from '@volter/sdk/kit/editor-runtime';
+import { useEditorStats } from '@volter/sdk/editor-runtime';
 
 function fmt(n: number): string {
   return n.toFixed(2);
@@ -33,14 +33,12 @@ export function CameraInfo() {
   }, [stats]);
 
   return (
-    // P6-U6 (owner taste decision 3: HUD overlays → real islands): under
-    // islands chrome the pill wears the shared glass-island material
-    // (compact tier; pointer-events stays none — it is a readout, not a
-    // control). Bars chrome keeps the pre-U6 overlay surface + blur.
+    // HUD overlays use the compact island material under islands chrome and the overlay surface
+    // under bars chrome. The readout keeps pointer events disabled.
     <EditorSurface
       variant="overlay"
       border
-      className="volter-camera-info volter-chrome-island volter-glass-island"
+      className="volter-camera-info volter-chrome-island"
       data-island-scale="compact"
     >
       <Inline gap={8} align="center" style={{ whiteSpace: 'nowrap' }}>

package/src/kit/components/InspectorObjectPreview.tsx

@@ -1,49 +1,22 @@
 import type * as THREE from 'three';
 import { Object3DSnapshotDocument } from './asset-viewers/EntityModelDocument';
 
-/**
- * Inspector-sized projection of the canonical Asset Lab viewport, over a live
- * `Object3D` the caller already has in hand.
- *
- * It takes the OBJECT, not an id to look one up by: a subject's preview is
- * composed only when the thing is genuinely previewable
- * (`inspection/compose.ts`), and the object the composer proved exists is the
- * one rendered here. A scene node and a part inside an asset document are
- * therefore the same case — the part is not in the shell's object map, and
- * with an id this component could only have shown a "no longer available"
- * alert for a thing that is right there on screen.
- *
- * Every host passes `fill`: the section body's square box, the compact card's
- * round disc, and the minimized card's round thumb all own their own geometry
- * and this component just fills it.
- */
+/** Fill the Inspector media slot with a preview of its already-resolved Object3D. The caller
+ * supplies the document identity, source object and display name. */
 export function InspectorObjectPreview({
   previewKey,
   object,
   displayName,
-  fill = false,
 }: {
   /** Stable identity for the isolated preview document. */
   previewKey: string;
   object: THREE.Object3D;
   displayName: string;
-  fill?: boolean;
 }) {
   return (
     <div
       data-testid="inspector-object-preview"
-      style={
-        fill
-          ? { position: 'absolute', inset: 0, overflow: 'hidden' }
-          : {
-              width: '100%',
-              height: 220,
-              minHeight: 220,
-              borderBottom: '1px solid var(--volter-structural-divider)',
-              overflow: 'hidden',
-              position: 'relative',
-            }
-      }
+      style={{ position: 'absolute', inset: 0, overflow: 'hidden' }}
     >
       <Object3DSnapshotDocument
         documentId={`inspector-preview:${previewKey}`}

package/src/kit/components/Object3DDocumentToolbar.css

@@ -0,0 +1,75 @@
+/* Imported by `Object3DDocumentToolbar.tsx`, so this sheet loads with the toolbar's module, after the
+ * host's theme.css, and a declaration here wins over one theme.css makes at the same specificity. The
+ * toolbar's border and its labelled control's gap are therefore left to `.volter-toolbar` and
+ * `.volter-btn`. `padding: 0` and `min-height: auto` below differ from `.volter-toolbar`'s, and compute
+ * the recipe's values only because `.volter-toolbar[data-compact="true"]` (theme.css) outranks them:
+ * both toolbars are `EditorToolbar compact`, which emits that attribute. */
+/* THE 3D DOCUMENT'S CONTROLS LIVE IN THE HOST'S HEADER STRIP now
+   (`WorkspaceDocumentSurface`), not floating over the stage: one row, the
+   view group first and the preview group pushed to the trailing edge. The
+   strip supplies the divider and height; these groups are plain in-flow
+   toolbars inside it. */
+.volter-model-document-header {
+  display: flex;
+  align-items: center;
+  gap: var(--volter-space-2);
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.volter-model-viewport-toolbar {
+  position: static;
+  min-height: auto;
+  padding: 0;
+  background: transparent;
+  box-shadow: none;
+}
+
+.volter-model-viewport-toolbar--preview {
+  margin-left: auto;
+}
+
+.volter-model-viewport-toolbar > * {
+  flex: 0 0 auto;
+}
+
+.volter-model-toolbar-labelled-control {
+  display: inline-flex;
+  align-items: center;
+  white-space: nowrap;
+}
+
+.volter-model-capture-preview {
+  position: absolute;
+  z-index: var(--volter-z-sticky);
+  top: calc(var(--volter-space-3) + var(--volter-control-default-height) + var(--volter-space-2));
+  right: var(--volter-space-3);
+  width: min(420px, calc(100% - 2 * var(--volter-space-3)));
+  padding: var(--volter-space-3);
+}
+
+.volter-model-capture-preview > div {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: var(--volter-space-3);
+}
+
+.volter-model-capture-preview img {
+  display: block;
+  width: 100%;
+}
+
+.volter-model-toolbar-error {
+  position: absolute;
+  z-index: var(--volter-z-sticky);
+  right: var(--volter-space-3);
+  bottom: var(--volter-space-3);
+  max-width: 420px;
+}
+
+@media (width <= 720px) {
+  .volter-model-toolbar-labelled-control > span {
+    display: none;
+  }
+}

package/src/kit/components/Object3DDocumentToolbar.tsx

@@ -36,18 +36,12 @@ import {
   object3DDocumentSessionsVersion,
   subscribeObject3DDocumentSessions,
 } from '../authoring/object3d-document-session-registry';
-import {
-  contributedChromeVersion,
-  contributedHeaderItems,
-  subscribeContributedChrome,
-} from '@volter/sdk/kit/chrome-registry';
-import type { HelperVisibility } from '@volter/sdk/kit/shell-store';
-import { object3DDocumentWritePolicy } from '@volter/sdk/kit/object3d-document-write-policy';
-import { stageStore, stageStoresVersion, subscribeStageStores } from '@volter/sdk/kit/stage-store-registry';
+import type { HelperVisibility } from '@volter/sdk/shell-store';
+import { assetDocumentWritePolicy } from '@volter/sdk/asset-document-write-policy';
+import { stageStore, stageStoresVersion, subscribeStageStores } from '@volter/sdk/stage-store-registry';
 import { viewportStageHelperKinds } from '../../viewport-door';
 import {
   type PresentationLayer,
-  applyViewPreset,
   DOCUMENT_STUDIO_PRESET,
   setViewGridVisible,
   viewGridVisible,
@@ -55,13 +49,12 @@ import {
   stageLightsPerMode,
   startingPresentation,
   studioPresets,
-  viewPresets,
   viewPresentationBinding,
   subscribeViewportPresentation,
   viewPresentation,
   viewportPresentationVersion,
-} from '@volter/sdk/kit/viewport-presentation';
-import { ViewportOverlaysGlyph, ViewportOverlaysMenu } from '@volter/sdk/kit/components/ViewportOverlaysMenu';
+} from '@volter/sdk/viewport-presentation';
+import { ViewportOverlaysGlyph, ViewportOverlaysMenu } from './ViewportOverlaysMenu';
 import {
   type ViewportDisplayModeChoice,
   ViewportDisplayModeMenu,
@@ -69,6 +62,7 @@ import {
   viewportShadingModes,
   viewportShadingSegments,
 } from './ViewportShadingMenu';
+import './Object3DDocumentToolbar.css';
 
 const subscribeToNothing = () => () => undefined;
 const noSessionVersion = () => 0;
@@ -80,11 +74,9 @@ const noSessionVersion = () => 0;
  * (`View3DOverlay.show_bones`, `makesrna/intern/rna_space.cc:5125-5129`, drawn
  * by `scripts/startup/bl_ui/space_view3d.py:7161` with `text="Bones"`), and it
  * is Blender's noun that is used here rather than the Helpers vocabulary's
- * `Skeletons`, because this menu IS that popover — the comment on the eye below
- * says so. `Weights` has no Blender checkbox at all: Blender reaches weight
+ * `Skeletons`, because this menu uses Blender's overlay vocabulary. `Weights` has no Blender checkbox at all: Blender reaches weight
  * colours through Weight Paint MODE, and an inspection surface has no brushes
- * to enter one, so it is a display toggle here (WORK.md §Blender in the tab is
- * Blender, "Inspection parity", I4).
+ * to enter one, so it is a display toggle here.
  *
  * A ROW STANDS ONLY WHERE THE DOCUMENT PUT A HELPER OF THAT KIND on this stage
  * (`viewportStageHelperKinds`) — the same rule the Outliner's restriction
@@ -114,19 +106,13 @@ export function Object3DDocumentToolbar({
     object3DDocumentSessionsVersion,
   );
   const session = object3DDocumentSession(documentId);
-  useSyncExternalStore(
-    subscribeContributedChrome,
-    contributedChromeVersion,
-    contributedChromeVersion,
-  );
   useSyncExternalStore(
     session?.subscribe ?? subscribeToNothing,
     session?.getSnapshot ?? noSessionVersion,
     session?.getSnapshot ?? noSessionVersion,
   );
   // THIS STAGE's own store and its own helpers: the shared panels read
-  // whichever store the FOCUSED document's stage runs on (ARCHITECTURE-CORE
-  // §One stage), and a toolbar is a control over ITS document, never over the
+  // whichever store the FOCUSED document's stage runs on , and a toolbar is a control over ITS document, never over the
   // world root's.
   useSyncExternalStore(subscribeStageStores, stageStoresVersion, stageStoresVersion);
   const stage = stageStore(documentId);
@@ -206,8 +192,8 @@ export function Object3DDocumentToolbar({
     try {
       // The shell owns where a framing is RECORDED (`.volter/thumbnails.json`,
       // written through the project-file route); this surface only knows the
-      // asset and the pose. See `object3d-document-write-policy.ts`.
-      await object3DDocumentWritePolicy().saveThumbnailFraming(
+      // asset and the pose. See `asset-document-write-policy.ts`.
+      await assetDocumentWritePolicy().saveThumbnailFraming(
         assetPath,
         reset ? undefined : session.cameraPose(),
       );
@@ -237,13 +223,7 @@ export function Object3DDocumentToolbar({
         label="Viewport view controls"
         className="volter-model-viewport-toolbar volter-model-viewport-toolbar--view"
       >
-        {/* THE BUTTON SAYS WHAT IT DOES. `session.frame()` frames the
-            selection when there is one and the whole subject when there is
-            not, but it was labelled "Frame selection" unconditionally — so a
-            tester hunting a fit-the-board control on the 3D board reported
-            finding none, then discovered this button does exactly that
-            (runhuman passes 87 and 89). One control, named for the job it is
-            about to do. */}
+        {/* Name the framing control for the selection, or the whole subject when selection is empty. */}
         <Tooltip text={frameLabel}>
           <IconButton aria-label={frameLabel} onClick={() => session.frame()}>
             <EditorIcon icon={faExpand} size="md" />
@@ -255,11 +235,7 @@ export function Object3DDocumentToolbar({
               ref={viewRef}
               type="button"
               size="compact"
-              // A dropdown TRIGGER is a widget, not a label: Blender's
-              // `Object Mode v` in the same row of chrome is a 20px well
-              // (#272727 in a 1px #3c3c3c border) while its plain menu words
-              // — View/Select/Add — carry no chrome at all. `ghost` said this
-              // was the second kind; it is the first.
+              // Use the select-like trigger variant for the mode dropdown.
               variant="secondary"
               aria-label={`Camera view: ${presentation.projection}`}
               aria-haspopup="menu"
@@ -329,12 +305,6 @@ export function Object3DDocumentToolbar({
             </IconButton>
           </Tooltip>
         ) : null}
-        {/* A package's own controls on this document (`@volter/sdk/chrome`,
-            `placement: 'object3d-document'`): handed the document's id; the
-            contribution resolves its subject through its own integration. */}
-        {contributedHeaderItems('object3d-document').map(({ id, Component }) => (
-          <Component key={id} documentId={documentId} />
-        ))}
       </EditorToolbar>
       <EditorToolbar
         compact
@@ -344,46 +314,15 @@ export function Object3DDocumentToolbar({
         {/* THE DISPLAY CONTROLS SIT AT THE TRAILING EDGE, which is where
             Blender's are: its 3D View header packs Visibility, Gizmo,
             Overlays, X-Ray and Shading hard against the region's right border
-            and leaves the middle empty. Ours used to clump them after the
-            view controls with three hundred pixels of bare header to their
-            right and this group's `...` alone at the edge. */}
-        {/* BLENDER'S SHADING CONTROL, one widget: the segments it has, and the
-            chevron's popover carrying every other mode AND the lighting rows
-            that used to be a second `Studio v` dropdown further along the row.
-            Blender's own shading popover is where Lighting lives (Studio /
-            MatCap / Flat), so the two controls were always one control drawn
-            twice — measured in `modeling-edit-none.png`, its header's trailing
-            cluster is five icon groups and no words at all. */}
+            and leaves the middle empty, and so does ours. */}
+        {/* The shading segments and popover form one widget; the popover contains the remaining modes and lighting settings. */}
         <ViewportDisplayModeMenu
           mode={presentation.mode}
           onChange={(mode) => session.setMode(mode)}
           choices={modes}
           segments={perMode ? perModeShadingSegments(declaredModes) : viewportShadingSegments}
         >
-          {/* A NAMED VIEW, first: a whole presentation (a target engine's default viewport —
-              its light, backdrop, overlays and tool) that the packages here contribute
-              (`*.view.ts`). Choosing one replaces the view's own choices; the rows below then
-              adjust it. Shown only where a package contributes one. */}
-          {viewPresets().length > 0 ? (
-            <label>
-              <span>View</span>
-              <Select
-                aria-label="View preset"
-                value=""
-                onChange={(event) => {
-                  if (event.target.value) applyViewPreset(documentId, event.target.value);
-                }}
-              >
-                <option value="">Choose…</option>
-                {viewPresets().map((preset) => (
-                  <option key={preset.id} value={preset.id}>
-                    {preset.title}
-                  </option>
-                ))}
-              </Select>
-            </label>
-          ) : null}
-          {/* LIGHTING AND EXPOSURE ARE THE VIEW'S PRESENTATION (`kit/viewport-presentation`):
+          {/* LIGHTING AND EXPOSURE ARE THE VIEW'S PRESENTATION (`@volter/sdk/viewport-presentation`):
               a studio preset, or the scene's own lights, and the tone's exposure. */}
           <label>
             <span>Lighting</span>
@@ -445,12 +384,7 @@ export function Object3DDocumentToolbar({
             </IconButton>
           </Tooltip>
         )}
-        {/* THE EYE WAS THE OVERLAYS CONTROL ALL ALONG — measured by what it
-            toggles, which is Grid and Bounds, exactly Blender's Show Overlays
-            subject. It takes Blender's mark, and Blender's split toggle+chevron:
-            the toggle is the MASTER flag, this stage's own helpers switch
-            (`StageHost` takes the grid, axis lines and selection marks down
-            with it), and each overlay below keeps its own choice under it. */}
+        {/* The master helpers toggle controls overlays; individual overlay choices remain stored underneath it. */}
         <ViewportOverlaysMenu
           glyph={<ViewportOverlaysGlyph />}
           {...(stage === null
@@ -460,7 +394,7 @@ export function Object3DDocumentToolbar({
             {
               id: 'grid',
               label: 'Grid',
-              // The VIEW's grid switch (`kit/viewport-presentation`), one per view.
+              // The VIEW's grid switch (`@volter/sdk/viewport-presentation`), one per view.
               enabled: viewGridVisible(documentId),
               onToggle: () => setViewGridVisible(documentId, !viewGridVisible(documentId)),
             },

package/src/kit/components/Object3DDocumentViewport.tsx

@@ -1,18 +1,15 @@
 /**
  * Lazy document boundary for the shared Object3D authoring surface.
  *
- * Registries and open-document planners need to be able to name this surface
- * during editor boot, but the implementation carries Asset Lab's animation,
- * capture, model-inspection, and source-authoring graph. Importing that graph
- * merely to register unopened document kinds put it on Scene's cold path.
- * Keep the public component shape here and evaluate the implementation only
- * when React actually renders an Object3D document.
+ * Registries and open-document planners can name this surface without importing its animation,
+ * capture, model-inspection and source-authoring implementation. React loads that implementation
+ * when it renders an Object3D document.
  */
 
 import { lazy, Suspense, useEffect } from 'react';
-import { announceDocumentStage } from '@volter/sdk/kit/document-viewports';
+import { announceDocumentStage } from '@volter/sdk/document-viewports';
 import type { Object3DDocumentViewportProps } from './StageHost';
-import { OBJECT3D_SURFACE_BUILDING, ViewportSurfaceStatus } from '@volter/sdk/kit/viewport-surface-status';
+import { Progress } from '@volter/sdk/progress';
 
 const LazyObject3DDocumentViewport = lazy(async () => {
   const module = await import('./StageHost');
@@ -29,9 +26,7 @@ export function Object3DDocumentViewport(props: Object3DDocumentViewportProps) {
   return (
     <Suspense
       fallback={
-        <ViewportSurfaceStatus testId="object3d-document-loading">
-          {OBJECT3D_SURFACE_BUILDING}
-        </ViewportSurfaceStatus>
+        props.chromeless ? null : <Progress documentId={props.documentId} title="Preparing the viewport" />
       }
     >
       <LazyObject3DDocumentViewport {...props} />

package/src/kit/components/StageHost.css

@@ -0,0 +1,40 @@
+/* The stage's studio floor and the asset workspace's box, applied by `StageHost.tsx`. They read only the
+   design system's shared tokens (`--volter-*`). */
+.volter-object3d-studio-stage {
+  /* Canonical Asset Lab presentation floor: a cool key-light bloom behind
+     the subject, a faint counter-light low in frame, and a restrained edge
+     vignette. The Three canvas is alpha-backed, so the same stage appears in
+     the full Asset Editor document and the inspector's preview section. */
+  background-color: var(--volter-object3d-stage-base, #1d232b);
+  background-image:
+    radial-gradient(
+      90% 72% at 50% 36%,
+      color-mix(in srgb, var(--volter-accent) 16%, rgb(122 148 177 / 22%)),
+      transparent 62%
+    ),
+    radial-gradient(70% 42% at 50% 92%, rgb(124 151 181 / 10%), transparent 72%),
+    radial-gradient(140% 112% at 50% 44%, transparent 42%, rgb(0 0 0 / 58%) 100%),
+    linear-gradient(
+      180deg,
+      var(--volter-object3d-stage-top, color-mix(in srgb, var(--volter-surface-raised) 82%, #394451)) 0%,
+      var(--volter-object3d-stage-bottom, color-mix(in srgb, var(--volter-surface-shell) 76%, #11151b))
+        100%
+    );
+}
+
+/* Inspector previews sit over the authored world, so retain some of that
+   context beneath the studio lighting. The full Asset Lab remains opaque. */
+.volter-object3d-studio-stage[data-volter-chromeless="true"] {
+  --volter-object3d-stage-base: rgb(29 35 43 / 34%);
+  --volter-object3d-stage-top: rgb(57 68 81 / 40%);
+  --volter-object3d-stage-bottom: rgb(17 21 27 / 52%);
+}
+
+.volter-object3d-asset-workspace {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  flex-direction: column;
+}