@volter/editor-core 0.5.57

package/src/components/ViewportOverlay.tsx

@@ -0,0 +1,145 @@
+import { faBorderAll, faLightbulb } from '@fortawesome/free-solid-svg-icons';
+import { EditorIcon, FloatingToolbar, IconButton, Tooltip } from '@volter/editor-sdk/widgets';
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import { memo, useEffect, useMemo, useReducer, useSyncExternalStore } from 'react';
+import { activeAuthoringVersion, subscribeActiveAuthoring } from '../authoring/active-adapter';
+import {
+  object3DDocumentSession,
+  object3DDocumentSessionsVersion,
+  subscribeObject3DDocumentSessions,
+} from '../authoring/object3d-document-session-registry';
+import { resolvePanelAuthoring } from '../authoring/panel-authoring';
+import type { EditorShellStore } from '../editor-shell-store';
+import { activeLightCount } from '../light-explorer-model';
+import { CORE_WORKSPACE_UTILITIES } from '../workspace-core-utilities';
+import {
+  subscribeWorkspaceDocuments,
+  workspaceDocumentRegistryVersion,
+} from '../workspace-document-registry';
+import { showWorkspaceUtility } from '../workspace-host-commands';
+import { ViewportOverlaysMenu } from './ViewportOverlaysMenu';
+import { ViewportShadingMenu } from './ViewportShadingMenu';
+import { ViewportViewMenu } from './ViewportViewMenu';
+
+/**
+ * Three-specific viewport display controls, mounted over ONE STAGE and driving
+ * THAT stage (ARCHITECTURE-CORE §One stage unit 4): `store` is the stage's own
+ * store, so a prefab's grid button toggles the prefab's grid rather than the
+ * world's. Performance moved to the global header telemetry so Scene and Play
+ * expose one source-following instrument.
+ *
+ * GRID routes through the stage's `Object3DDocumentSession` when it has one.
+ * That is not a second source of truth: the session writes the SAME
+ * `viewport.grid.visible` the store's toggle reaches through
+ * `EditorViewport.syncFromStore`, and it is what the document's own header
+ * button and `vgai status`'s `showGrid` already read
+ * (`command-listener.ts`'s `documentPresentation?.grid ?? store.showGrid`).
+ * Two writers of one flag is how a toggle comes back on by itself.
+ */
+export function ViewportOverlay({
+  store,
+  documentId,
+}: {
+  readonly store: EditorShellStore;
+  readonly documentId: string;
+}) {
+  useSyncExternalStore(store.subscribe, store.getSnapshot);
+  useSyncExternalStore(subscribeWorkspaceDocuments, workspaceDocumentRegistryVersion);
+  useSyncExternalStore(subscribeActiveAuthoring, activeAuthoringVersion);
+  useSyncExternalStore(subscribeObject3DDocumentSessions, object3DDocumentSessionsVersion);
+  const { adapter } = resolvePanelAuthoring(store);
+  const session = object3DDocumentSession(documentId);
+  useSyncExternalStore(session?.subscribe ?? NO_SESSION_SUBSCRIBE, session?.getSnapshot ?? ZERO);
+  const grid = session ? session.presentation().grid : store.showGrid;
+  return (
+    <FloatingToolbar
+      label="Viewport display"
+      className="vgai-viewport-toolbar vgai-viewport-toolbar-right"
+    >
+      <Tooltip text={`Grid: ${grid ? 'On' : 'Off'}`}>
+        <IconButton
+          aria-label="Toggle grid"
+          aria-pressed={grid}
+          size="comfortable"
+          onClick={() => (session ? session.setGrid(!grid) : store.toggleGrid())}
+        >
+          <EditorIcon icon={faBorderAll} size="md" />
+        </IconButton>
+      </Tooltip>
+      <HelpersButton store={store} />
+      <ViewportShadingMenu
+        mode={store.shadingMode}
+        onChange={(mode) => store.setShadingMode(mode)}
+      />
+      <ViewportViewMenu store={store} />
+      <LightExplorerButton adapter={adapter} store={store} />
+    </FloatingToolbar>
+  );
+}
+
+const NO_SESSION_SUBSCRIBE = () => () => {};
+const ZERO = () => 0;
+
+/** Keep the hierarchy walk off ordinary viewport-store renders. The adapter
+ * notifies when its projected tree changes; a stable adapter prop lets React
+ * skip this child for unrelated grid/shading/selection updates. */
+const LightExplorerButton = memo(function LightExplorerButton({
+  adapter,
+  store,
+}: {
+  readonly adapter: AuthoringAdapter;
+  readonly store: EditorShellStore;
+}) {
+  const [, refresh] = useReducer((value: number) => value + 1, 0);
+  useEffect(() => adapter.subscribe?.(refresh), [adapter]);
+  // `adapter.subscribe` is `store.subscribe` on every shipping adapter, so the
+  // `memo` above cannot stop this button re-rendering on a bare selection
+  // click — and `activeLightCount` walks the WHOLE tree. Key the walk on
+  // `contentVersion`, which a selection-only notify leaves alone.
+  const lightCount = useMemo(() => activeLightCount(adapter), [adapter, store.contentVersion]);
+  if (lightCount === 0) return null;
+  return (
+    <Tooltip text={`Open Light Explorer · ${lightCount} ${lightCount === 1 ? 'light' : 'lights'}`}>
+      <IconButton
+        aria-label="Open Light Explorer"
+        size="comfortable"
+        onClick={() => showWorkspaceUtility(CORE_WORKSPACE_UTILITIES.lightExplorer.id)}
+      >
+        <EditorIcon icon={faLightbulb} size="md" />
+      </IconButton>
+    </Tooltip>
+  );
+});
+
+function HelpersButton({ store }: { store: EditorShellStore }) {
+  const helperTypes = [
+    { key: 'bounds' as const, label: 'Bounds' },
+    { key: 'lights' as const, label: 'Lights' },
+    { key: 'cameras' as const, label: 'Cameras' },
+    { key: 'colliders' as const, label: 'Colliders' },
+    { key: 'joints' as const, label: 'Joints' },
+    { key: 'particles' as const, label: 'Particle Emitters' },
+    { key: 'lod' as const, label: 'LOD' },
+    { key: 'audio' as const, label: 'Audio' },
+    { key: 'splines' as const, label: 'Splines' },
+    { key: 'navmesh' as const, label: 'NavMesh' },
+    { key: 'constraints' as const, label: 'Constraints' },
+    { key: 'reflectionProbes' as const, label: 'Reflection Probes' },
+    { key: 'triggerVolumes' as const, label: 'Trigger Volumes' },
+    { key: 'skeletons' as const, label: 'Skeletons' },
+    { key: 'weights' as const, label: 'Weights' },
+  ];
+
+  return (
+    <ViewportOverlaysMenu
+      label="Helpers"
+      master={{ enabled: store.showHelpers, onToggle: () => store.toggleHelpers() }}
+      choices={helperTypes.map((helper) => ({
+        id: helper.key,
+        label: helper.label,
+        enabled: store.helperVisibility[helper.key],
+        onToggle: () => store.toggleHelperType(helper.key),
+      }))}
+    />
+  );
+}

package/src/components/ViewportOverlaysMenu.tsx

@@ -0,0 +1,153 @@
+import { faCaretDown, faCheck, faEye, faEyeSlash } from '@fortawesome/free-solid-svg-icons';
+import {
+  EditorIcon,
+  IconButton,
+  Menu,
+  MenuItem,
+  MenuSeparator,
+  SplitButtonGroup,
+  Tooltip,
+} from '@volter/editor-sdk/widgets';
+import { type ReactNode, useEffect, useRef, useState } from 'react';
+
+export interface ViewportOverlayChoice {
+  readonly id: string;
+  readonly label: string;
+  readonly enabled: boolean;
+  readonly disabled?: boolean;
+  readonly onToggle: () => void;
+}
+
+/**
+ * BLENDER'S OVERLAY MARK, transcribed from `modeling-edit-none.png` at its
+ * native 2x (the 3D View header's Show Overlays toggle, ink x 2424..2455,
+ * y 64..91): a filled disc up and to the right, a stroked ring down and to
+ * the left, and a GAP between them where the ring passes in front — the gap
+ * is what keeps the ring readable against the disc, and without it the two
+ * merge into one blob at 14 px. The disc-minus-gap is traced as one boundary
+ * (the disc's far arc, then the gap circle's arc back) rather than knocked
+ * out, because a knockout drawn over a single fill leaks wherever it reaches
+ * past that fill's edge.
+ *
+ * Drawn here rather than through `EditorIcon`: the icon-set seam is keyed by
+ * Font Awesome name, and no name in the set carries two overlapping circles —
+ * hanging this mark on `clone` or `layer-group` would move those marks too.
+ */
+export function ViewportOverlaysGlyph() {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      className="vgai-viewport-overlays-glyph"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <path
+        d="M5.24 4.51 A5.3 5.3 0 1 1 11.89 11.16 A5.85 5.85 0 0 0 5.24 4.51 Z"
+        fill="currentColor"
+      />
+      <circle cx="6.1" cy="10.3" r="4.4" fill="none" stroke="currentColor" strokeWidth="1.1" />
+    </svg>
+  );
+}
+
+export function ViewportOverlaysMenu({
+  label = 'Overlays',
+  choices,
+  master,
+  glyph,
+}: {
+  readonly label?: string;
+  readonly choices: readonly ViewportOverlayChoice[];
+  readonly master?: { readonly enabled: boolean; readonly onToggle: () => void };
+  /** Replaces the eye — a caller whose overlays have Blender's own mark. */
+  readonly glyph?: ReactNode;
+}) {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+  const anyEnabled = choices.some((choice) => choice.enabled);
+  const active = master?.enabled ?? anyEnabled;
+  const mark = glyph ?? <EditorIcon icon={active ? faEye : faEyeSlash} size="md" />;
+
+  useEffect(() => {
+    if (!open) return;
+    const handler = (event: MouseEvent) => {
+      if (ref.current && !ref.current.contains(event.target as Node)) setOpen(false);
+    };
+    document.addEventListener('mousedown', handler);
+    return () => document.removeEventListener('mousedown', handler);
+  }, [open]);
+
+  const menu = open ? (
+    <Menu className="vgai-helpers-menu" onDismiss={() => setOpen(false)}>
+      {master ? (
+        <>
+          <MenuItem
+            role="menuitemcheckbox"
+            aria-checked={master.enabled}
+            onSelect={master.onToggle}
+          >
+            <span className="vgai-menu-check">
+              {master.enabled && <EditorIcon icon={faCheck} size="xs" />}
+            </span>
+            Show {label}
+          </MenuItem>
+          <MenuSeparator />
+        </>
+      ) : null}
+      {choices.map((choice) => (
+        <MenuItem
+          key={choice.id}
+          role="menuitemcheckbox"
+          aria-checked={choice.enabled}
+          disabled={choice.disabled}
+          onSelect={choice.onToggle}
+        >
+          <span className="vgai-menu-check">
+            {choice.enabled && <EditorIcon icon={faCheck} size="xs" />}
+          </span>
+          {choice.label}
+        </MenuItem>
+      ))}
+    </Menu>
+  ) : null;
+
+  return (
+    <div ref={ref} className="vgai-viewport-popover-anchor">
+      {master ? (
+        <SplitButtonGroup>
+          <Tooltip text={`${label}: ${active ? 'On' : 'Off'}`}>
+            <IconButton
+              aria-label={`Toggle ${label.toLowerCase()}`}
+              aria-pressed={active}
+              size="comfortable"
+              onClick={master.onToggle}
+            >
+              {mark}
+            </IconButton>
+          </Tooltip>
+          <IconButton
+            aria-label={`Choose ${label.toLowerCase()}`}
+            aria-expanded={open}
+            size="comfortable"
+            onClick={() => setOpen(!open)}
+          >
+            <EditorIcon icon={faCaretDown} size="xs" />
+          </IconButton>
+        </SplitButtonGroup>
+      ) : (
+        <Tooltip text={`${label}: ${active ? 'On' : 'Off'}`}>
+          <IconButton
+            aria-label={`Choose ${label.toLowerCase()}`}
+            aria-expanded={open}
+            aria-pressed={active}
+            size="comfortable"
+            onClick={() => setOpen(!open)}
+          >
+            {mark}
+          </IconButton>
+        </Tooltip>
+      )}
+      {menu}
+    </div>
+  );
+}

package/src/components/ViewportShadingMenu.tsx

@@ -0,0 +1,300 @@
+import { faCaretDown, faCheck } from '@fortawesome/free-solid-svg-icons';
+import {
+  AnchoredMenu,
+  Button,
+  EditorIcon,
+  IconButton,
+  MenuItem,
+  MenuSeparator,
+  Tooltip,
+  themeVars,
+} from '@volter/editor-sdk/widgets';
+import type { ViewportShadingMode } from '@volter/editor-threejs/render/viewport-shading';
+import { type ReactNode, useRef, useState } from 'react';
+
+export const viewportShadingModes: ReadonlyArray<{
+  mode: ViewportShadingMode;
+  label: string;
+  description: string;
+}> = [
+  { mode: 'solid', label: 'Material', description: 'Authored materials and lighting' },
+  { mode: 'clay', label: 'Solid', description: 'Neutral flat-shaded geometry' },
+  { mode: 'unlit', label: 'Unlit', description: 'Base color without scene lighting' },
+  { mode: 'wireframe', label: 'Wireframe', description: 'Renderable triangle edges' },
+  { mode: 'matcap', label: 'Matcap', description: 'Neutral clay sphere — form without color' },
+  { mode: 'normals', label: 'Normals', description: 'Surface-normal direction colors' },
+  { mode: 'overdraw', label: 'Overdraw', description: 'Additive overlap visualization' },
+];
+
+export interface ViewportDisplayModeChoice<T extends string> {
+  readonly mode: T;
+  readonly label: string;
+  readonly description: string;
+}
+
+/**
+ * A SHADING SEGMENT — one cell of Blender's four-button shading group, which
+ * is what its 3D View header spends on shading instead of a word dropdown.
+ * `glyph` names the MARK, never the mode: the same sphere means "solid" in
+ * any vocabulary, and a caller's mode ids are its own.
+ */
+export interface ViewportShadingSegment<T extends string> {
+  readonly mode: T;
+  readonly glyph: 'wireframe' | 'sphere' | 'preview';
+  readonly label: string;
+}
+
+/**
+ * THREE OF BLENDER'S FOUR, and the missing one is missing on purpose.
+ * Blender's group is Wireframe / Solid / Material Preview / Rendered; this
+ * viewport implements the first three (`viewportShadingModes` above:
+ * `wireframe`, `clay` — its own label is "Solid" — and `solid`, labelled
+ * "Material"). There is no path-traced or offline-rendered mode behind a
+ * fourth cell, so no fourth cell is drawn: a segment whose mode does not
+ * exist is a shim that promises a render this viewport cannot produce.
+ * Every other mode this viewport HAS (Unlit, Matcap, Normals, Overdraw, and
+ * the document's UV / Vertex-colors when the asset carries them) stays in the
+ * popover behind the chevron, which is also where Blender keeps the rest of
+ * its shading controls.
+ */
+export const viewportShadingSegments: ReadonlyArray<ViewportShadingSegment<ViewportShadingMode>> = [
+  { mode: 'wireframe', glyph: 'wireframe', label: 'Wireframe' },
+  { mode: 'clay', glyph: 'sphere', label: 'Solid' },
+  { mode: 'solid', glyph: 'preview', label: 'Material' },
+];
+
+/**
+ * The three marks, transcribed from `modeling-edit-none.png` at its native 2x
+ * — the 3D View header's shading group, cells at x 2628 / 2666 / 2704, y
+ * 60..95, each a 36x36 device cell carrying 28..32 device px of ink. On the
+ * 16-unit box here (the icon set's own grid, so these sit at the same optical
+ * size as every `EditorIcon` beside them):
+ *
+ *  - WIREFRAME is a wire globe: a ring, two latitude chords and ONE meridian,
+ *    and the frame settles the spacing — measured off the circle's own centre
+ *    (device rows 64..91, so centre row 77.5, radius 14) the chords sit at
+ *    ±5 device px and the meridian 5 device px LEFT of centre, i.e. all three
+ *    at 0.357 of the radius. The off-centre meridian is what makes it read as
+ *    a globe seen from three-quarters rather than a crosshair.
+ *  - SPHERE is a plain filled disc. Blender's carries a near-white body
+ *    inside a lighter rim; at 14 CSS px the rim is below this instrument's
+ *    floor and a flat disc is the honest reduction.
+ *  - PREVIEW is the ring with its upper-left lobe filled: the fill's right
+ *    edge is a near-vertical chord just left of centre (device offset 13 of
+ *    28, held from row 68 down) and its lower edge a cut from the ring at
+ *    row 78.5 down-right to row 82 — measured, because the first cut put
+ *    that edge two device rows high and the mark read as a pie chart rather
+ *    than a lit sphere. Blender hatches the remaining lower-right quadrant;
+ *    three hatch strokes cannot survive 14 px and are deliberately not
+ *    drawn, so this mark is Blender's silhouette without its texture.
+ *
+ * These are drawn HERE rather than fetched through `EditorIcon` because the
+ * icon-set seam is keyed by Font Awesome NAME, and the three names that would
+ * carry these marks are already spent on other jobs (`globe` is the
+ * transform-space toggle, `circle` is the Outliner's generic object, and
+ * `circle-half-stroke` is the LUT document's before/after). Re-drawing a
+ * shared name would move those marks too. The precedent is the sibling
+ * segmented group in this same header — `@volter/editor-blender`'s select-mode cells draw
+ * their own glyphs inline for the same reason.
+ */
+function ViewportShadingGlyph({
+  glyph,
+}: {
+  readonly glyph: ViewportShadingSegment<string>['glyph'];
+}) {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      className="vgai-viewport-shading-glyph"
+      aria-hidden="true"
+      focusable="false"
+    >
+      {glyph === 'sphere' ? (
+        <circle cx="8" cy="8" r="7.3" fill="currentColor" />
+      ) : (
+        <circle cx="8" cy="8" r="7.3" fill="none" stroke="currentColor" strokeWidth="1.05" />
+      )}
+      {glyph === 'wireframe' ? (
+        <g stroke="currentColor" strokeWidth="1.05">
+          <line x1="1.7" y1="5.4" x2="14.3" y2="5.4" />
+          <line x1="1.7" y1="10.6" x2="14.3" y2="10.6" />
+          <line x1="5.4" y1="1.7" x2="5.4" y2="14.3" />
+        </g>
+      ) : null}
+      {glyph === 'preview' ? (
+        <path
+          d="M7.73 1.23 L7.73 10.43 L1.22 8.04 A6.78 6.78 0 0 1 7.73 1.23 Z"
+          fill="currentColor"
+        />
+      ) : null}
+    </svg>
+  );
+}
+
+export function ViewportDisplayModeMenu<T extends string>({
+  mode,
+  onChange,
+  choices,
+  disabled = false,
+  segments,
+  children,
+}: {
+  mode: T;
+  onChange: (mode: T) => void;
+  choices: ReadonlyArray<ViewportDisplayModeChoice<T>>;
+  disabled?: boolean;
+  /** Draw Blender's segmented group instead of a labelled trigger. */
+  segments?: ReadonlyArray<ViewportShadingSegment<T>>;
+  /** Extra rows for the popover — Blender keeps its lighting controls here. */
+  children?: ReactNode;
+}) {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLButtonElement>(null);
+  const active = choices.find((entry) => entry.mode === mode) ?? choices[0];
+  if (!active) return null;
+
+  const menu =
+    open && !disabled ? (
+      <AnchoredMenu
+        id="vgai-viewport-shading-menu"
+        anchorRef={ref}
+        aria-label="Viewport shading modes"
+        onDismiss={() => setOpen(false)}
+        style={{
+          minWidth: 230,
+        }}
+      >
+        {choices.map((entry) => (
+          <MenuItem
+            key={entry.mode}
+            role="menuitemradio"
+            aria-checked={entry.mode === mode}
+            onSelect={() => {
+              onChange(entry.mode);
+              setOpen(false);
+            }}
+            style={{ display: 'grid', gridTemplateColumns: '14px 1fr', gap: 7 }}
+          >
+            <span style={{ opacity: entry.mode === mode ? 1 : 0 }}>
+              <EditorIcon icon={faCheck} size="xs" />
+            </span>
+            <span>
+              <span style={{ display: 'block' }}>{entry.label}</span>
+              <span
+                style={{
+                  display: 'block',
+                  color: themeVars.content.dim,
+                  fontSize: 10,
+                }}
+              >
+                {entry.description}
+              </span>
+            </span>
+          </MenuItem>
+        ))}
+        {children ? (
+          <>
+            <MenuSeparator />
+            <div className="vgai-viewport-shading-options">{children}</div>
+          </>
+        ) : null}
+      </AnchoredMenu>
+    ) : null;
+
+  if (segments) {
+    // BLENDER'S SHADING CONTROL: the modes it HAS as joined cells, then the
+    // chevron whose popover holds everything else. The cells join the way the
+    // sibling select-mode group in this same header joins — square inner
+    // corners and a shared border — so the five read as one widget with one
+    // cell lit, and `aria-pressed` is the only thing that paints the lit one.
+    return (
+      <div className="vgai-viewport-popover-anchor">
+        <span className="vgai-viewport-shading-segments" role="group" aria-label="Viewport shading">
+          {segments.map((segment) => (
+            <Tooltip key={segment.mode} text={`Viewport shading: ${segment.label}`}>
+              <IconButton
+                size="compact"
+                shape="segment"
+                variant="secondary"
+                aria-pressed={segment.mode === mode}
+                aria-label={`Viewport shading: ${segment.label}`}
+                disabled={disabled}
+                onClick={() => onChange(segment.mode)}
+              >
+                <ViewportShadingGlyph glyph={segment.glyph} />
+              </IconButton>
+            </Tooltip>
+          ))}
+          <Tooltip text="Shading options">
+            <IconButton
+              ref={ref}
+              size="compact"
+              shape="segment"
+              variant="secondary"
+              aria-label="Shading options"
+              aria-haspopup="menu"
+              aria-expanded={open}
+              aria-controls={open ? 'vgai-viewport-shading-menu' : undefined}
+              disabled={disabled}
+              onClick={() => setOpen((value) => !value)}
+            >
+              <EditorIcon icon={faCaretDown} size="xs" />
+            </IconButton>
+          </Tooltip>
+        </span>
+        {menu}
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ position: 'relative' }}>
+      <Tooltip text={`Viewport shading: ${active.label}`}>
+        {/* A control's CHROME never encodes its VALUE. The variant used to be
+            `mode === 'solid' ? 'ghost' : 'secondary'`, so the trigger's well
+            appeared and disappeared as you used it — and at rest (`solid`,
+            labelled "Material") it was a transparent slab where Blender paints
+            a bordered well: measured in `modeling-object-none.png`, `Object
+            Mode v` is #272727 inside a 1px #3c3c3c border, 20px tall, on a
+            #343434 header. `secondary` is this estate's select-like trigger
+            already (FontPicker's `.vgai-field-trigger`), so no new variant. */}
+        <Button
+          ref={ref}
+          type="button"
+          size="compact"
+          variant="secondary"
+          aria-label={`Viewport shading: ${active.label}`}
+          aria-haspopup="menu"
+          aria-expanded={open}
+          aria-controls={open ? 'vgai-viewport-shading-menu' : undefined}
+          disabled={disabled}
+          onClick={() => setOpen((value) => !value)}
+          style={{ display: 'inline-flex', alignItems: 'center', gap: 5, minWidth: 66 }}
+        >
+          <span>{active.label}</span>
+          <EditorIcon icon={faCaretDown} size="xs" />
+        </Button>
+      </Tooltip>
+      {menu}
+    </div>
+  );
+}
+
+export function ViewportShadingMenu({
+  mode,
+  onChange,
+  disabled = false,
+}: {
+  mode: ViewportShadingMode;
+  onChange: (mode: ViewportShadingMode) => void;
+  disabled?: boolean;
+}) {
+  return (
+    <ViewportDisplayModeMenu
+      mode={mode}
+      onChange={onChange}
+      choices={viewportShadingModes}
+      disabled={disabled}
+    />
+  );
+}