@volter/editor-threejs 0.5.210 → 0.5.212

package/src/kit/components/StageOverlays.tsx

@@ -1,8 +1,7 @@
 /**
  * The lazy boundary for a stage's overlays. The host names them; only a stage
  * that actually has a shell above it (and therefore something for them to
- * read) evaluates the module. See `stage-overlay-set.tsx` for what they are
- * and `world-root-stage.ts`'s header for why the condition gates the LOAD.
+ * read) evaluates the module. See `stage-overlay-set.tsx` for what they are.
  */
 import { lazy, Suspense } from 'react';
 import type { StageOverlaySetProps } from './stage-overlay-set';

package/src/kit/components/StatsOverlay.tsx

@@ -1,7 +1,7 @@
 import { themeVars } from '@volter/sdk/widgets';
 import { useEffect, useState } from 'react';
-import { useEditorStats } from '@volter/sdk/kit/editor-runtime';
-import { latestTabCensus } from '@volter/sdk/kit/tab-census';
+import { useEditorStats } from '@volter/sdk/editor-runtime';
+import { latestTabCensus } from '@volter/sdk/tab-census';
 
 export function StatsOverlay() {
   const stats = useEditorStats();
@@ -19,26 +19,14 @@ export function StatsOverlay() {
   }, []);
 
   return (
-    // V-10 — this was an EIGHTH one-off "dark panel"
-    // value (`rgba(0,0,0,0.7)`, flat black, no border) directly stacked
-    // above-right of ViewportOverlay's cluster and CameraInfo's pill in the
-    // same corner. Given the same border/radius treatment as its siblings so
-    // the whole corner reads as one family.
-    // P6-U6 (owner taste decision 3: HUD overlays → real islands): the paint
-    // moved to `.volter-hud-overlay` so islands chrome can promote it to the
-    // shared glass-island material (compact tier); bars chrome paints the
-    // exact pre-U6 overlay-whisper recipe from the same class.
+    // Use the shared HUD overlay treatment for this statistics readout.
     <div
-      className="volter-hud-overlay volter-chrome-island volter-glass-island"
+      className="volter-hud-overlay volter-chrome-island"
       data-island-scale="compact"
       data-hud-border="strong"
       style={{
         position: 'absolute',
-        // U6.5 F1/P2-18 — second HUD tier: below the viewport toolbar row.
-        // The var carries the glass breathing band (54px islands / 102px the
-        // floating header-island clearance, scoped in theme.css); the bare
-        // fallback is the pre-glass 48px so treatment-less chrome ("bars":
-        // graphite/classic/lite/reduced) stays pixel-identical to main.
+        // Place the second HUD tier below the viewport toolbar using the look’s clearance variable.
         top: 'var(--volter-viewport-overlay-hud-top, 48px)',
         right: 8,
         padding: '6px 10px',

package/src/kit/components/ViewportFurniture.tsx

@@ -1,22 +1,7 @@
 /**
- * THE VIEWPORT'S FURNITURE — what every 3D area carries besides its content
- * (Blender's 3D Viewport: the view text at the top-left, "User Perspective"
- * over the collection and active object; the navigation cluster under the
- * axis gizmo at the top-right — zoom, pan, frame, projection). Drawn by the
- * 3D document host (`StageHost`) over its stage for every
- * document with chrome; nothing here holds state of its own. Hidden while the
- * host has no viewport yet.
- *
- * WHICH OBJECT A BUTTON DRIVES IS THE QUESTION TO ASK BEFORE ADDING ONE.
- * `StageHost` is this component's only caller and every stage it hosts is
- * painted by `Object3DDocumentSession.renderViewport` — through
- * `session.camera()`, not through `viewport.renderCamera`. So a verb whose
- * effect is the CAMERA'S POSE reaches the picture through the viewport (the
- * session's cameras are derived from that pose every frame), while a verb
- * that changes WHICH camera paints must go to the session. The projection
- * button got that wrong and was inert everywhere it was drawn; see its own
- * comment below for the measurement, and do not route a new control to
- * `viewport.*` without checking which side of that line it falls on.
+ * Shared viewport furniture for chromed 3D stages: view text, axis navigation, zoom, pan, framing
+ * and projection controls. StageHost owns the state. Camera-pose controls drive the viewport;
+ * projection controls drive the document session when present and the viewport otherwise.
  */
 import type { ToolCameraView, ToolViewportStatistic } from '../../object3d-contributions';
 import {
@@ -31,7 +16,7 @@ import { Fragment, type PointerEvent as ReactPointerEvent, useCallback, useEffec
 import * as THREE from 'three';
 import { axisViewName } from '../asset-workflow/model-inspection';
 import type { Object3DDocumentSession } from '../authoring/object3d-document-session';
-import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import type { ShellStore } from '@volter/sdk/shell-store';
 import {
   COMPASS_CENTER_RIGHT_PX,
   COMPASS_CLUSTER_TOP_PX,
@@ -44,19 +29,17 @@ import {
   subscribeViewportPresentation,
   viewPresentation,
   viewportPresentationVersion,
-} from '@volter/sdk/kit/viewport-presentation';
+} from '@volter/sdk/viewport-presentation';
 import { ViewportViewMenu } from './ViewportViewMenu';
 import {
   lookDeclaresViewportColors,
   lookPaintsLightViewport,
   subscribeNativeSelectionTheme,
   useViewportChrome,
-} from '@volter/sdk/kit/native-selection-style';
-import type { ThreeViewportProjection } from '@volter/sdk/kit/three-viewport-presentation';
+} from '@volter/sdk/native-selection-style';
+import type { ThreeViewportProjection } from '../three-viewport-presentation';
 
-/** The cluster sits 8px under the compass — one number, owned by the
- *  compass's own box (`editor-viewport.ts`, measured against Blender's
- *  navigation gizmo), never restated here. */
+/** Position the navigation cluster relative to the compass’s shared box. */
 const CLUSTER_TOP = COMPASS_CLUSTER_TOP_PX;
 
 /** Module-level for `useSyncExternalStore`'s stable identity; the theme root
@@ -71,27 +54,7 @@ function subscribeThemeViewportGroup(onChange: () => void): () => void {
 const NO_SESSION_SUBSCRIBE = (): (() => void) => () => {};
 const NO_SESSION_SNAPSHOT = (): number => 0;
 
-/**
- * THE STATISTICS BLOCK'S GEOMETRY, measured on `sculpting.png` — the ONE
- * reference frame that photographs the overlay's counts (every other frame
- * has the Statistics overlay off; `modeling-front-ortho.png`'s third line is
- * the ortho grid's unit, not a count). Device px at native 2x, CSS halved:
- *
- *   `User Perspective`   ink y 181..201, x 138..306   (baseline ~196.5)
- *   `(1) Cube | Cube`    ink y 211..237, x 139..300   (baseline ~231.5)
- *   `Vertices`  `8`      ink y 273..288, label x 136..216, value x 252..262
- *   `Faces`     `6`      ink y 308..323, label x 138..194, value x 252..261
- *
- * Three facts that become the two constants below. The line step INSIDE a
- * block is 35 device (17.5 CSS) — the same step the two identity lines use.
- * The step from the subject line to `Vertices` is 56.5 device, so the stats
- * block stands one extra 21.5 device (10.75 CSS) off the lines above it;
- * `space-5` is 10, the nearest rung, and the scale has nothing at 11.
- * And the VALUE is a COLUMN, not a space: both rows start their number at
- * exactly x 252 device while their labels end at 216 and 194, so the label
- * cell is a fixed 115 device / 57.5 CSS measured from the block's own left
- * edge (x 137) — 58 at the rounding the rest of this file uses.
- */
+/** Statistics use the identity text’s line step, a space-5 gap and a fixed 58 CSS-pixel value column. */
 const STATISTICS_BLOCK_OFFSET = 5 as const;
 /** See {@link STATISTICS_BLOCK_OFFSET}: Blender's value column, CSS px from
  *  the overlay block's left edge. */
@@ -154,7 +117,7 @@ export function ViewportFurniture({
   subject: documentSubject,
   gridScale,
 }: ViewportFurnitureProps) {
-  useSyncExternalStore(store.subscribe, store.getShellSnapshot ?? store.getSnapshot);
+  useSyncExternalStore(store.subscribe, store.getShellSnapshot);
   // THE LINES FOLLOW THE CAMERA: the view text names the axis the view looks down and the grid
   // line names the step at the current zoom, and neither is a store or session change.
   useSyncExternalStore(
@@ -168,37 +131,13 @@ export function ViewportFurniture({
     ),
     () => (viewport ? cameraSignature(viewport, session) : ''),
   );
-  // The VIEW TEXT must follow the projection the stage is actually drawing
-  // with. A document session carries its own (`session.camera()` returns its
-  // orthographic camera off it), and the viewport's flag says nothing about
-  // it — so the text read "User Perspective" over an orthographic stage the
-  // moment the document toolbar's own projection menu was used.
+  // Read projection from the document session’s drawing camera so the view text matches the stage.
   useSyncExternalStore(
     session?.subscribe ?? NO_SESSION_SUBSCRIBE,
     session?.getSnapshot ?? NO_SESSION_SNAPSHOT,
     session?.getSnapshot ?? NO_SESSION_SNAPSHOT,
   );
-  // THE VIEW TEXT IS THE BRIGHTEST THING IN BLENDER'S FRAME, and it is the one
-  // place Blender goes to pure white: measured on `modeling-edit-none.png` at
-  // native 2x, both overlay lines plateau at 255 (240 px at 255 against 296 at
-  // its AA neighbour 253) where its panel text inks 229. Ours drew
-  // `content.primary` — one step back, over the busiest backdrop in the
-  // window.
-  //
-  // `content.onAccent` IS THE MEMBER THAT HOLDS 255, and its NAME is
-  // misleading for this role: Blender spends that ink mostly NOT on an accent.
-  // DO NOT RENAME IT — it is a pre-v3 core key in all three palette lists and
-  // every shipped palette document names it, so a rename breaks every skin on
-  // disk to make a docblock read better. This comment is the correction.
-  //
-  // AND IT IS GATED, because the member's real role is "ink that must read
-  // over a fill the PALETTE chose". Measured: Classic's `content.onAccent` is
-  // #101820 — near-black, correct against its light accent chip and ruinous
-  // over a mid-grey viewport. The gate is the predicate that already decides
-  // every other viewport paint question (`lookDeclaresViewportColors`, the
-  // same one the grid's distance fade reads): a look that declares what the
-  // viewport is painted has answered for both values, and a look that leaves
-  // the backdrop to the editor keeps the ink it had. Classic is bit-identical.
+  // Use onAccent viewport ink only when the look declares viewport colours; otherwise retain the palette’s ordinary text colour.
   const lookPaintsViewport = useSyncExternalStore(
     subscribeThemeViewportGroup,
     lookDeclaresViewportColors,
@@ -215,10 +154,7 @@ export function ViewportFurniture({
   useSyncExternalStore(subscribeViewportPresentation, viewportPresentationVersion, viewportPresentationVersion);
   const navigationControls = viewPresentation(documentId).overlays.navigationControls;
   if (!viewport) return null;
-  // Blender's view text names the DIRECTION as well as the projection —
-  // "Front Orthographic" on numpad 1 (`modeling-front-ortho.png`), "User
-  // Perspective" the moment the view is orbited off that axis. Derived from
-  // the live camera, so it reverts on the first drag the way Blender's does.
+  // Derive the view's direction and projection labels from its live camera.
   const axis =
     axisViewName(
       viewport.camera.position.clone().sub(viewport.orbitControls.target),
@@ -231,39 +167,7 @@ export function ViewportFurniture({
   const viewText = through
     ? `Camera ${through.projection === 'perspective' ? 'Perspective' : 'Orthographic'}`
     : `${axis} ${drawn === 'perspective' ? 'Perspective' : 'Orthographic'}`;
-  // THE SUBJECT LINE. Blender's is `(frame) <active collection> | <active
-  // object>` — THREE parts, and which part is which was settled by CONTRAST
-  // across the frames, never from one of them. `modeling-object-none.png`,
-  // `modeling-object-selected.png` and `layout.png` all read
-  // `(1) Collection | Cube`; `sculpting.png` reads `(1) Cube | Cube` only
-  // because THAT file's collection is itself named Cube. So the leading part
-  // is a CONTAINER and the trailing part is the ACTIVE OBJECT — neither is
-  // the mesh datablock, which Blender never puts on this line at all.
-  //
-  // We have one of Blender's three. There is no frame (no timeline) and no
-  // collection; the DOCUMENT is the only container an object on this stage
-  // belongs to, so it takes the leading slot — a world-root stage names a
-  // scene there and the selection names an object inside it.
-  //
-  // AND THE CONTAINER SLOT IS DROPPED WHEN IT IS NOT A CONTAINER. A Model
-  // document names its own subject, so both slots resolve to ONE string from
-  // ONE
-  // source and the overlay rendered `cube | cube` — one entity printed
-  // twice, which is not Blender's pair. Measured live on a cold models build
-  // before this change. Blender would happily print two identical words
-  // there (sculpting.png does); ours would be printing one thing twice, so
-  // it says that one thing once.
-  //
-  // THE TRAILING PART IS THE ACTIVE OBJECT, not the oldest selected one.
-  // `store.selectedEntityId` is the store's own active id — `[...selection]
-  // .at(-1)`, what the transform gizmo binds to and what the Outliner marks
-  // as its active row. This read `[...selectedEntityIds][0]`, the OLDEST id,
-  // which is the same defect `inspector-selection.ts`'s docblock records
-  // fixing for the inspector on 2026-09-18 (click A, ctrl-click B, and the
-  // gizmo moved to B while the inspector kept showing A). Back-applied here,
-  // the third reader of that selection. A Model document holds one entity,
-  // so this half is not visible in its frame; it shows on any stage where
-  // two objects can be selected at once.
+  // Show the document container and active object, omitting a duplicate container when the document already names the subject. Use selectedEntityId for the active object.
   const activeId = store.selectedEntityId;
   const activeName = (activeId === null ? null : objectName(activeId)) || null;
   const subject =
@@ -298,8 +202,8 @@ export function ViewportFurniture({
     const move = (moveEvent: PointerEvent): void => {
       const lenNew = 5 + moveEvent.clientY - regionTop;
       const factor = Math.max(0.01, 2 * (lenNew / lenOld - 1) + 1);
-      if (frameZoom0 !== null && session?.cameraView()) {
-        session.setCameraViewZoom(frameZoom0 / factor);
+      if (frameZoom0 !== null && session!.cameraView()) {
+        session!.setCameraViewZoom(frameZoom0 / factor);
       } else if (ortho) {
         ortho.zoom = zoom0 / factor;
         ortho.updateProjectionMatrix();
@@ -431,8 +335,7 @@ export function ViewportFurniture({
         </div>
       ) : null}
       {chrome.viewName === 'gizmo' ? (
-        // UNITY'S LABEL UNDER THE SCENE GIZMO (`Editor-SceneGizmo.png`): the projection's mark and
-        // its name, and a click toggles the projection, as Unity's does.
+        // The projection label below the scene gizmo also toggles the projection.
         <button
           type="button"
           data-testid="viewport-view-name"
@@ -465,13 +368,8 @@ export function ViewportFurniture({
           {stageViewName(viewport, drawn, 'short')}
         </button>
       ) : null}
-      {/* BLENDER'S NAVIGATION CLUSTER (`view3d_gizmo_navigate.cc`): Zoom and Pan, each a drag;
-          Camera; and the projection toggle, whose mark is the projection the view has. Cell,
-          gap, pitch and capsule width are Blender's (`modeling-edit-none.png`: glyph boxes 16
-          CSS, pitch 30, a 28 CSS capsule). Framing is not here: its home is the document
-          header's view control and the Home and numpad-period keys, as Blender's is its View
-          menu. The Camera button is not drawn yet: looking through a scene camera is not a
-          view this stage has. */}
+      {/* Navigation offers zoom and pan drags, a supplied camera view, and a projection
+          toggle. Framing belongs to the document header and Home/numpad-period keys. */}
       {navigationControls && store.showGizmos ? (
       <div
         data-testid="viewport-navigation"
@@ -482,16 +380,7 @@ export function ViewportFurniture({
         style={{
           position: 'absolute',
           top: CLUSTER_TOP,
-          // 12, not 8: PAINTED EDGE to PAINTED EDGE is how the reference was
-          // read, and this panel's rect runs ~3 CSS past the last pixel the
-          // viewport paints (the dock's sash). At 8 the gap measured 5.0 CSS
-          // against Blender's 9.0 (`modeling-edit-none.png`: the capsule's
-          // last column is device 2817 and the area's dark boundary starts at
-          // 2836); at 12 it is 9.0.
-          // UNGATED, like every other number this cluster carries: its 28 and
-          // 16 are Blender's for every skin already (`theme.css`'s
-          // `.volter-viewport-navigation` block, no palette selector), and the
-          // estate's `css-style-identity-selector` gate forbids one anyway.
+          // Offset the cluster 12 CSS pixels from the panel boundary to retain the visible gap beyond the sash.
           right: 'var(--volter-space-6)',
           display: 'flex',
           flexDirection: 'column',
@@ -514,23 +403,7 @@ export function ViewportFurniture({
             <EditorIcon size="2xl" icon={editorIcons.viewport.pan} />
           </IconButton>
         </Tooltip>
-        {/* THE PROJECTION THIS BUTTON MEANS IS THE STAGE'S, NOT THE
-            VIEWPORT'S. It drove `viewport.setProjection` and was INERT
-            wherever this cluster is drawn — `StageHost` is its only caller,
-            every stage it hosts is painted by
-            `Object3DDocumentSession.renderViewport` through `session.camera()`,
-            and that camera reads the SESSION's own `projection` (the comment
-            on the view text above already said so). Measured 2026-09-19 in a
-            cold models scaffold: the click flipped `aria-pressed` and left the
-            frame hash byte-identical, while the document header's Camera view
-            menu — `session.setProjection`, the same intent one row up —
-            changed both the picture and the view text. It was worse than
-            inert: `dolly` below branches on `viewport.renderCamera`, so while
-            this button was "pressed" Zoom in and Zoom out went dead too, and
-            flipping back nudged the camera as `_syncPerspectiveFromOrthographic`
-            copied the phantom pose home. Transcribed from the sibling door
-            (`Object3DDocumentToolbar`), with the viewport kept as the answer
-            for a stage that has no session. */}
+        {/* Toggle the document session's camera view when a camera is available. */}
         {session?.hasCameraView() ? (
           <Tooltip text={through ? 'Leave the camera view' : 'Look through the camera'}>
             <IconButton size="comfortable" aria-label="Toggle the camera view" onClick={() => session.toggleCameraView()}>
@@ -541,12 +414,12 @@ export function ViewportFurniture({
         ) : null}
         {/* In a camera view, the lock that makes navigating it move the camera
             (`View3D.lock_camera`): `VIEW_LOCKED` while it holds, `VIEW_UNLOCKED` otherwise. */}
-        {through && session?.cameraViewLocked() !== null ? (
-          <Tooltip text={session?.cameraViewLocked() ? 'Unlock the camera from the view' : 'Lock the camera to the view'}>
-            <IconButton size="comfortable" aria-label="Lock the camera to the view" onClick={() => session?.toggleCameraViewLock()}>
+        {through && session!.cameraViewLocked() !== null ? (
+          <Tooltip text={session!.cameraViewLocked() ? 'Unlock the camera from the view' : 'Lock the camera to the view'}>
+            <IconButton size="comfortable" aria-label="Lock the camera to the view" onClick={() => session!.toggleCameraViewLock()}>
               <EditorIcon
                 size="2xl"
-                icon={session?.cameraViewLocked() ? editorIcons.viewport.cameraLocked : editorIcons.viewport.cameraUnlocked}
+                icon={session!.cameraViewLocked() ? editorIcons.viewport.cameraLocked : editorIcons.viewport.cameraUnlocked}
               />
             </IconButton>
           </Tooltip>
@@ -575,8 +448,8 @@ export function ViewportFurniture({
         )}
       </div>
       ) : null}
-      {through && session ? (
-        <CameraFrame view={through} canvas={session.renderer.domElement} locked={session.cameraViewLocked() === true} />
+      {through ? (
+        <CameraFrame view={through} canvas={session!.renderer.domElement} locked={session!.cameraViewLocked() === true} />
       ) : null}
     </>
   );

package/src/kit/components/ViewportOverlay.tsx

@@ -2,44 +2,43 @@ import { faBorderAll, faLightbulb } from '@fortawesome/free-solid-svg-icons';
 import { EditorIcon, FloatingToolbar, IconButton, Tooltip } from '@volter/sdk/widgets';
 import type { AuthoringAdapter } from '@volter/project/adapter';
 import { memo, useEffect, useId, useMemo, useReducer, useState, useSyncExternalStore } from 'react';
-import { activeAuthoringVersion, subscribeActiveAuthoring } from '@volter/sdk/kit/authoring/active-adapter';
+import { activeAuthoringVersion, subscribeActiveAuthoring } from '@volter/sdk/authoring/active-adapter';
 import {
   object3DDocumentSession,
   object3DDocumentSessionsVersion,
   subscribeObject3DDocumentSessions,
 } from '../authoring/object3d-document-session-registry';
-import { resolvePanelAuthoring } from '@volter/sdk/kit/authoring/panel-authoring';
+import { resolvePanelAuthoring } from '@volter/sdk/authoring/panel-authoring';
 import type { EditorShellStore } from '../editor-shell-store';
-import { activeLightCount } from '@volter/sdk/kit/light-explorer-model';
-import { CORE_WORKSPACE_UTILITIES } from '@volter/sdk/kit/workspace-core-utilities';
+import { activeLightCount } from '@volter/sdk/light-explorer-model';
+import { CORE_WORKSPACE_UTILITIES } from '@volter/sdk/workspace-core-utilities';
 import {
   subscribeWorkspaceDocuments,
   workspaceDocumentRegistryVersion,
-} from '@volter/sdk/kit/workspace-document-registry';
-import { showWorkspaceUtility } from '@volter/sdk/kit/workspace-host-commands';
-import { ViewportOverlaysMenu } from '@volter/sdk/kit/components/ViewportOverlaysMenu';
+} from '@volter/sdk/workspace-document-registry';
+import { showWorkspaceUtility } from '@volter/sdk/workspace-host-commands';
+import { ViewportOverlaysMenu } from './ViewportOverlaysMenu';
 import {
   setViewGridVisible,
   subscribeViewportPresentation,
   viewGridVisible,
   viewportPresentationVersion,
-} from '@volter/sdk/kit/viewport-presentation';
+} from '@volter/sdk/viewport-presentation';
 import { ViewportShadingMenu } from './ViewportShadingMenu';
 import type { ViewportShadingMode } from '@volter/editor-threejs/render/viewport-shading';
 import { ViewportViewMenu } from './ViewportViewMenu';
-import { useViewportChrome, useViewportWords } from '@volter/sdk/kit/native-selection-style';
+import { useViewportChrome, useViewportWords } from '@volter/sdk/native-selection-style';
 import { createPortal } from 'react-dom';
 import { stageViewName } from './stage-view-name';
 
 /**
  * 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
+ * THAT stage: `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.
+ * world's.
  *
  * GRID is the stage's VIEW's switch (`overlays.grid.visible` in
- * `kit/viewport-presentation`, keyed by `documentId`): the one flag this
+ * `@volter/sdk/viewport-presentation`, keyed by `documentId`): the one flag this
  * button, the document's header, the `toggle.grid` action, `set-grid` and
  * the editor's `status` command's `showGrid` all read and write.
  */
@@ -118,10 +117,7 @@ export function ViewportOverlay({
       <HelpersButton store={store} word={words.helpers} />
       <ViewportShadingMenu
         mode={sessionShading(session) ?? store.shadingMode}
-        // A document stage paints the mode its SESSION holds, and the store's is only what this
-        // menu shows: the session's `setMode` is what `set-shading-mode` drives, and writing the
-        // store alone relabelled the menu over an unchanged picture (measured under Unreal's look:
-        // "Wireframe" over the shaded box).
+        // Set the document session’s mode as well as the menu store so the rendered picture follows the choice.
         onChange={(mode) => (session ? session.setMode(mode) : store.setShadingMode(mode))}
         words={words.shading}
       />

package/src/kit/components/ViewportOverlaysMenu.tsx

@@ -0,0 +1,177 @@
+import { faCaretDown, faCheck, faEye, faEyeSlash } from '@fortawesome/free-solid-svg-icons';
+import {
+  Button,
+  EditorIcon,
+  IconButton,
+  Menu,
+  MenuItem,
+  MenuSeparator,
+  SplitButtonGroup,
+  Tooltip,
+} from '@volter/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="volter-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,
+  word,
+}: {
+  readonly label?: string;
+  /** The menu's name in the target's own words (Unreal's `Show`, Unity's `Gizmos`), drawn as
+   *  a word that opens the menu instead of the eye and its caret; its master switch stays the
+   *  menu's first item. */
+  readonly word?: 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="volter-helpers-menu" onDismiss={() => setOpen(false)}>
+      {master ? (
+        <>
+          <MenuItem
+            role="menuitemcheckbox"
+            aria-checked={master.enabled}
+            onSelect={master.onToggle}
+          >
+            <span className="volter-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="volter-menu-check">
+            {choice.enabled && <EditorIcon icon={faCheck} size="xs" />}
+          </span>
+          {choice.label}
+        </MenuItem>
+      ))}
+    </Menu>
+  ) : null;
+
+  if (word !== undefined) {
+    return (
+      <div ref={ref} className="volter-viewport-popover-anchor">
+        <Button
+          variant="ghost"
+          size="comfortable"
+          aria-label={`Choose ${label.toLowerCase()}`}
+          aria-expanded={open}
+          onClick={() => setOpen(!open)}
+        >
+          {word}
+          <EditorIcon icon={faCaretDown} size="xs" />
+        </Button>
+        {menu}
+      </div>
+    );
+  }
+
+  return (
+    <div ref={ref} className="volter-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/kit/components/ViewportShadingMenu.tsx

@@ -88,40 +88,7 @@ export function perModeShadingSegments(
   ];
 }
 
-/**
- * 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.
- */
+/** Local wireframe, Solid and Material Preview glyphs share the header’s 16-unit icon grid without replacing icon-set names used elsewhere. */
 function ViewportShadingGlyph({
   glyph,
 }: {
@@ -279,14 +246,7 @@ export function ViewportDisplayModeMenu<T extends string>({
   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 `.volter-field-trigger`), so no new variant. */}
+        {/* Keep one select-like trigger variant across modes. */}
         <Button
           ref={ref}
           type="button"