@volter/editor-threejs 0.5.65 → 0.5.67

package/src/kit/components/Object3DDocumentToolbar.tsx

@@ -0,0 +1,549 @@
+import {
+  faBone,
+  faCamera,
+  faCaretDown,
+  faCheck,
+  faCube,
+  faEllipsis,
+  faExpand,
+  faRotateLeft,
+} from '@fortawesome/free-solid-svg-icons';
+import {
+  AnchoredMenu,
+  Button,
+  EditorBanner,
+  EditorIcon,
+  EditorPopover,
+  EditorToolbar,
+  IconButton,
+  MenuItem,
+  MenuSeparator,
+  Select,
+  Text,
+  TextInput,
+  Tooltip,
+} from '@volter/editor-sdk/widgets';
+import { useRef, useState, useSyncExternalStore } from 'react';
+import { captureModelAssetPreview, captureObjectAssetPreview } from '../asset-preview';
+import {
+  type ModelCameraPreset,
+  supportedModelDiagnosticModes,
+} from '../asset-workflow/model-inspection';
+import type { Object3DDocumentViewMode } from '../authoring/object3d-document-session';
+import {
+  object3DDocumentSession,
+  object3DDocumentSessionsVersion,
+  subscribeObject3DDocumentSessions,
+} from '../authoring/object3d-document-session-registry';
+import {
+  contributedChromeVersion,
+  contributedHeaderItems,
+  subscribeContributedChrome,
+} from '@volter/editor-sdk/kit/chrome-registry';
+import type { HelperVisibility } from '@volter/editor-sdk/kit/shell-store';
+import { object3DDocumentWritePolicy } from '@volter/editor-sdk/kit/object3d-document-write-policy';
+import { stageStore, stageStoresVersion, subscribeStageStores } from '@volter/editor-sdk/kit/stage-store-registry';
+import { viewportStageHelperKinds } from '../../viewport-door';
+import {
+  type PresentationLayer,
+  applyViewPreset,
+  DOCUMENT_STUDIO_PRESET,
+  setViewGridVisible,
+  viewGridVisible,
+  setViewPresentation,
+  stageLightsPerMode,
+  startingPresentation,
+  studioPresets,
+  viewPresets,
+  viewPresentationBinding,
+  subscribeViewportPresentation,
+  viewPresentation,
+  viewportPresentationVersion,
+} from '@volter/editor-sdk/kit/viewport-presentation';
+import { ViewportOverlaysGlyph, ViewportOverlaysMenu } from '@volter/editor-sdk/kit/components/ViewportOverlaysMenu';
+import {
+  type ViewportDisplayModeChoice,
+  ViewportDisplayModeMenu,
+  perModeShadingSegments,
+  viewportShadingModes,
+  viewportShadingSegments,
+} from './ViewportShadingMenu';
+
+const subscribeToNothing = () => () => undefined;
+const noSessionVersion = () => 0;
+
+/**
+ * THE DOCUMENT'S OWN OVERLAY ROWS, beside Grid and Bounds.
+ *
+ * Blender's viewport overlay popover carries a BONES checkbox
+ * (`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
+ * 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).
+ *
+ * A ROW STANDS ONLY WHERE THE DOCUMENT PUT A HELPER OF THAT KIND on this stage
+ * (`viewportStageHelperKinds`) — the same rule the Outliner's restriction
+ * columns follow: a control follows what the thing behind it answers, never a
+ * knob. So an imported GLB's Asset Lab document, which shows no bones, draws
+ * neither row.
+ */
+const DOCUMENT_HELPER_ROWS: readonly { key: keyof HelperVisibility; label: string }[] = [
+  { key: 'skeletons', label: 'Bones' },
+  { key: 'weights', label: 'Weights' },
+  { key: 'cursor', label: '3D Cursor' },
+  // Blender's overlay extras: the objects that have no surface.
+  { key: 'cameras', label: 'Cameras' },
+  { key: 'lights', label: 'Lights' },
+  { key: 'empties', label: 'Empties' },
+];
+export function Object3DDocumentToolbar({
+  documentId,
+  assetPath,
+}: {
+  readonly documentId: string;
+  readonly assetPath?: string;
+}) {
+  useSyncExternalStore(
+    subscribeObject3DDocumentSessions,
+    object3DDocumentSessionsVersion,
+    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
+  // world root's.
+  useSyncExternalStore(subscribeStageStores, stageStoresVersion, stageStoresVersion);
+  const stage = stageStore(documentId);
+  useSyncExternalStore(
+    stage?.subscribe ?? subscribeToNothing,
+    stage?.getSnapshot ?? noSessionVersion,
+    stage?.getSnapshot ?? noSessionVersion,
+  );
+  const helperKinds = viewportStageHelperKinds(documentId);
+  const [capture, setCapture] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [viewOpen, setViewOpen] = useState(false);
+  const [moreOpen, setMoreOpen] = useState(false);
+  const viewRef = useRef<HTMLButtonElement>(null);
+  const moreRef = useRef<HTMLButtonElement>(null);
+  useSyncExternalStore(subscribeViewportPresentation, viewportPresentationVersion, viewportPresentationVersion);
+  if (!session) return null;
+  const presentation = session.presentation();
+  const { lighting } = viewPresentation(documentId);
+  const binding = viewPresentationBinding(documentId);
+  const starting = binding ? startingPresentation(binding.stageKind) : null;
+  const documentStudioOffered =
+    binding?.documentLayer?.all?.lighting?.studioPreset === DOCUMENT_STUDIO_PRESET.id ||
+    starting?.all?.lighting?.studioPreset === DOCUMENT_STUDIO_PRESET.id;
+  // WHERE A LIGHTING CHOICE GOES: the current draw mode's, on a stage that keeps lighting per
+  // mode (Blender's Solid, Material Preview and Rendered each keep theirs), else every mode's.
+  const perMode = binding ? stageLightsPerMode(binding.stageKind) : false;
+  const lightingChoice = (choice: NonNullable<NonNullable<PresentationLayer['all']>['lighting']>): PresentationLayer =>
+    // Keyed by the mode the view resolves its lighting by (UV and vertex colours draw under it).
+    perMode ? { modes: { [viewPresentation(documentId).drawMode]: { lighting: choice } } } : { all: { lighting: choice } };
+  // THE MODES THE STAGE LIGHTS ITS OWN WAY, which are the cells it draws (`perModeShadingSegments`).
+  const declaredModes = new Set(
+    Object.entries(starting?.modes ?? {})
+      .filter(([, mode]) => mode?.lighting !== undefined)
+      .map(([mode]) => mode),
+  );
+  const availableModes = new Set(
+    supportedModelDiagnosticModes(session.root)
+      .filter((item) => item.available)
+      .map((item) => item.mode),
+  );
+  const modes: Array<ViewportDisplayModeChoice<Object3DDocumentViewMode>> = [
+    // On a per-mode stage `solid` IS Blender's Solid (materials' colours under its studio), so the
+    // neutral override is named for what it is.
+    ...(perMode
+      ? viewportShadingModes.map((choice) =>
+          choice.mode === 'solid'
+            ? { ...choice, label: 'Solid', description: "Materials' colours under the studio lights" }
+            : choice.mode === 'clay'
+              ? { ...choice, label: 'Clay' }
+              : choice,
+        )
+      : viewportShadingModes),
+    ...(declaredModes.has('preview')
+      ? [{ mode: 'preview' as const, label: 'Material Preview', description: 'Materials lit by a preview environment' }]
+      : []),
+    ...(declaredModes.has('rendered')
+      ? [{ mode: 'rendered' as const, label: 'Rendered', description: "Lit as a render is, by the scene's own lights" }]
+      : []),
+    ...(availableModes.has('uv')
+      ? [{ mode: 'uv' as const, label: 'UV', description: 'UV coordinates as surface color' }]
+      : []),
+    ...(availableModes.has('vertex-colors')
+      ? [
+          {
+            mode: 'vertex-colors' as const,
+            label: 'Vertex colors',
+            description: 'Authored color attributes without textures',
+          },
+        ]
+      : []),
+  ];
+
+  const saveThumbnailFraming = async (reset: boolean) => {
+    if (!assetPath) return;
+    setError(null);
+    try {
+      // The shell owns where a framing is RECORDED (`.vgai/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(
+        assetPath,
+        reset ? undefined : session.cameraPose(),
+      );
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+    }
+  };
+
+  const capturePreview = async () => {
+    setError(null);
+    try {
+      const options = { background: presentation.background } as const;
+      const result = assetPath?.toLowerCase().endsWith('.spz')
+        ? await captureModelAssetPreview(assetPath, options)
+        : captureObjectAssetPreview(session.root, options);
+      setCapture(`data:image/png;base64,${result.contactSheet.base64}`);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+    }
+  };
+
+  const frameLabel = session.selection().length > 0 ? 'Frame selection' : 'Frame all';
+  return (
+    <div className="vgai-model-document-header">
+      <EditorToolbar
+        compact
+        label="Viewport view controls"
+        className="vgai-model-viewport-toolbar vgai-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. */}
+        <Tooltip text={frameLabel}>
+          <IconButton aria-label={frameLabel} onClick={() => session.frame()}>
+            <EditorIcon icon={faExpand} size="md" />
+          </IconButton>
+        </Tooltip>
+        <div className="vgai-viewport-popover-anchor">
+          <Tooltip text="Camera orientation and projection">
+            <Button
+              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.
+              variant="secondary"
+              aria-label={`Camera view: ${presentation.projection}`}
+              aria-haspopup="menu"
+              aria-expanded={viewOpen}
+              onClick={() => setViewOpen((open) => !open)}
+              className="vgai-model-toolbar-labelled-control"
+            >
+              <EditorIcon icon={faCube} size="sm" />
+              <span>
+                {presentation.projection === 'perspective' ? 'Perspective' : 'Orthographic'}
+              </span>
+              <EditorIcon icon={faCaretDown} size="xs" />
+            </Button>
+          </Tooltip>
+          {viewOpen && (
+            <AnchoredMenu
+              anchorRef={viewRef}
+              align="start"
+              clamp
+              aria-label="Camera view"
+              onDismiss={() => setViewOpen(false)}
+              style={{ minWidth: 210 }}
+            >
+              {(['front', 'right', 'top', 'isometric'] as ModelCameraPreset[]).map((preset) => (
+                <MenuItem
+                  key={preset}
+                  onSelect={() => {
+                    session.setViewPreset(preset, 'view');
+                    setViewOpen(false);
+                  }}
+                >
+                  {preset === 'isometric'
+                    ? 'Perspective 3/4'
+                    : `${preset[0]?.toUpperCase()}${preset.slice(1)} view`}
+                </MenuItem>
+              ))}
+              <MenuSeparator />
+              {(['perspective', 'orthographic'] as const).map((projection) => (
+                <MenuItem
+                  key={projection}
+                  role="menuitemradio"
+                  aria-checked={presentation.projection === projection}
+                  onSelect={() => {
+                    session.setProjection(projection);
+                    setViewOpen(false);
+                  }}
+                >
+                  <span className="vgai-menu-check">
+                    {presentation.projection === projection && (
+                      <EditorIcon icon={faCheck} size="xs" />
+                    )}
+                  </span>
+                  {projection === 'perspective' ? 'Perspective' : 'Orthographic'}
+                </MenuItem>
+              ))}
+            </AnchoredMenu>
+          )}
+        </div>
+        {availableModes.has('skeleton') ? (
+          <Tooltip text={`Rig: ${presentation.skeleton ? 'Visible' : 'Hidden'}`}>
+            <IconButton
+              aria-label="Toggle rig overlay"
+              aria-pressed={presentation.skeleton}
+              onClick={() => session.setSkeleton(!presentation.skeleton)}
+            >
+              <EditorIcon icon={faBone} size="md" />
+            </IconButton>
+          </Tooltip>
+        ) : null}
+        {/* A package's own controls on this document (`@volter/editor-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
+        label="Viewport preview controls"
+        className="vgai-model-viewport-toolbar vgai-model-viewport-toolbar--preview"
+      >
+        {/* 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. */}
+        <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`):
+              a studio preset, or the scene's own lights, and the tone's exposure. */}
+          <label>
+            <span>Lighting</span>
+            <Select
+              aria-label="Lighting"
+              value={lighting.source === 'studio' ? `studio:${lighting.studioPreset}` : lighting.source}
+              onChange={(event) => {
+                const value = event.target.value;
+                setViewPresentation(
+                  documentId,
+                  lightingChoice(
+                    value.startsWith('studio:')
+                      ? { source: 'studio', studioPreset: value.slice('studio:'.length) }
+                      : { source: value as 'scene' },
+                  ),
+                );
+              }}
+            >
+              {studioPresets()
+                // The document's own studio is a choice only where the document brought one.
+                .filter((preset) => preset.id !== DOCUMENT_STUDIO_PRESET.id || documentStudioOffered)
+                .map((preset) => (
+                <option key={preset.id} value={`studio:${preset.id}`}>
+                  {preset.title}
+                </option>
+              ))}
+              <option value="scene">Scene lights</option>
+            </Select>
+          </label>
+          <label>
+            <span>Exposure</span>
+            <TextInput
+              aria-label="Preview exposure"
+              type="range"
+              min="0.2"
+              max="2"
+              step="0.1"
+              value={lighting.tone.exposure}
+              onChange={(event) =>
+                setViewPresentation(documentId, lightingChoice({ tone: { exposure: Number(event.target.value) } }))
+              }
+            />
+            <Text as="span" variant="caption">
+              {lighting.tone.exposure.toFixed(1)}
+            </Text>
+          </label>
+        </ViewportDisplayModeMenu>
+        {/* 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. It does NOT take Blender's split
+            toggle+chevron: that toggle binds to a MASTER overlays flag this
+            document's session does not have, and deriving one from "any
+            overlay is on" would silently drop the per-overlay state on the
+            first click. One button, one job, until the session has the flag. */}
+        <ViewportOverlaysMenu
+          glyph={<ViewportOverlaysGlyph />}
+          choices={[
+            {
+              id: 'grid',
+              label: 'Grid',
+              // The VIEW's grid switch (`kit/viewport-presentation`), one per view.
+              enabled: viewGridVisible(documentId),
+              onToggle: () => setViewGridVisible(documentId, !viewGridVisible(documentId)),
+            },
+            {
+              id: 'bounds',
+              label: 'Bounds',
+              enabled: presentation.bounds,
+              onToggle: () => session.setBounds(!presentation.bounds),
+            },
+            ...(stage === null
+              ? []
+              : DOCUMENT_HELPER_ROWS.filter((row) => helperKinds.includes(row.key)).map((row) => ({
+                  id: row.key,
+                  label: row.label,
+                  enabled: stage.helperVisibility[row.key],
+                  onToggle: () => stage.toggleHelperType(row.key),
+                }))),
+          ]}
+        />
+        <div className="vgai-viewport-popover-anchor">
+          <Tooltip text="Asset preview actions">
+            <IconButton
+              ref={moreRef}
+              aria-label="Asset preview actions"
+              aria-haspopup="menu"
+              aria-expanded={moreOpen}
+              onClick={() => setMoreOpen((open) => !open)}
+            >
+              <EditorIcon icon={faEllipsis} size="md" />
+            </IconButton>
+          </Tooltip>
+          {moreOpen && (
+            <AnchoredMenu
+              anchorRef={moreRef}
+              clamp
+              aria-label="Asset preview actions"
+              onDismiss={() => setMoreOpen(false)}
+              style={{ minWidth: 210 }}
+            >
+              <MenuItem
+                onSelect={() => {
+                  setMoreOpen(false);
+                  void capturePreview();
+                }}
+              >
+                <EditorIcon icon={faCamera} size="sm" />
+                Capture preview
+              </MenuItem>
+              {assetPath ? (
+                <>
+                  <MenuItem
+                    onSelect={() => {
+                      setMoreOpen(false);
+                      void saveThumbnailFraming(false);
+                    }}
+                  >
+                    Save thumbnail framing
+                  </MenuItem>
+                  <MenuItem
+                    onSelect={() => {
+                      setMoreOpen(false);
+                      void saveThumbnailFraming(true);
+                    }}
+                  >
+                    Reset thumbnail framing
+                  </MenuItem>
+                </>
+              ) : null}
+              <MenuSeparator />
+              <MenuItem
+                onSelect={() => {
+                  session.resetPresentation();
+                  setMoreOpen(false);
+                }}
+              >
+                <EditorIcon icon={faRotateLeft} size="sm" />
+                Reset viewport settings
+              </MenuItem>
+            </AnchoredMenu>
+          )}
+        </div>
+      </EditorToolbar>
+      {capture ? (
+        <EditorPopover className="vgai-model-capture-preview">
+          <div>
+            <Text as="strong" variant="label">
+              Deterministic views
+            </Text>
+            <Button type="button" variant="ghost" onClick={() => setCapture(null)}>
+              Close
+            </Button>
+          </div>
+          <img src={capture} alt="Front, right, top, and three-quarter model preview" />
+        </EditorPopover>
+      ) : null}
+      {error ? (
+        <EditorBanner className="vgai-model-toolbar-error" tone="error">
+          {error}
+        </EditorBanner>
+      ) : null}
+    </div>
+  );
+}

package/src/kit/components/Object3DDocumentViewport.tsx

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+
+import { lazy, Suspense, useEffect } from 'react';
+import { announceDocumentStage } from '@volter/editor-sdk/kit/document-viewports';
+import type { Object3DDocumentViewportProps } from './StageHost';
+import { OBJECT3D_SURFACE_BUILDING, ViewportSurfaceStatus } from '@volter/editor-sdk/kit/viewport-surface-status';
+
+const LazyObject3DDocumentViewport = lazy(async () => {
+  const module = await import('./StageHost');
+  return { default: module.Object3DDocumentViewport };
+});
+
+export function Object3DDocumentViewport(props: Object3DDocumentViewportProps) {
+  // ANNOUNCE BEFORE THE CHUNK RESOLVES. An opener's `ready` asks whether this
+  // document is mounting a stage at a moment when the implementation import is
+  // still in flight, and this boundary is the only thing rendered by then —
+  // announcing from inside `StageHost` would answer "no stage" for exactly the
+  // window the wait exists to cover.
+  useAnnouncedObject3DDocumentStage(props.documentId, props.chromeless);
+  return (
+    <Suspense
+      fallback={
+        <ViewportSurfaceStatus testId="object3d-document-loading">
+          {OBJECT3D_SURFACE_BUILDING}
+        </ViewportSurfaceStatus>
+      }
+    >
+      <LazyObject3DDocumentViewport {...props} />
+    </Suspense>
+  );
+}
+
+/**
+ * The announcement, spelled here and again at `StageHost.tsx`'s own
+ * `Object3DDocumentViewport` — deliberately NOT a shared hook, because
+ * importing one across these two files is the static edge that would put this
+ * boundary inside the implementation's own pinned closure and defeat the
+ * laziness the boundary exists for.
+ *
+ * A CHROMELESS mount announces nothing, for the same reason it registers no
+ * session (`StageHost.tsx:2235`): it is a thumbnail of a document, several can
+ * be alive for one id at once, and an opener waiting on one would wait forever.
+ */
+function useAnnouncedObject3DDocumentStage(documentId: string, chromeless = false): void {
+  useEffect(() => {
+    if (chromeless) return;
+    return announceDocumentStage(documentId);
+  }, [documentId, chromeless]);
+}