@volter/editor-threejs 0.5.66 → 0.5.68

package/src/kit/components/ViewportOverlay.tsx

@@ -0,0 +1,215 @@
+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, useId, useMemo, useReducer, useState, useSyncExternalStore } from 'react';
+import { activeAuthoringVersion, subscribeActiveAuthoring } from '@volter/editor-sdk/kit/authoring/active-adapter';
+import {
+  object3DDocumentSession,
+  object3DDocumentSessionsVersion,
+  subscribeObject3DDocumentSessions,
+} from '../authoring/object3d-document-session-registry';
+import { resolvePanelAuthoring } from '@volter/editor-sdk/kit/authoring/panel-authoring';
+import type { EditorShellStore } from '../editor-shell-store';
+import { activeLightCount } from '@volter/editor-sdk/kit/light-explorer-model';
+import { CORE_WORKSPACE_UTILITIES } from '@volter/editor-sdk/kit/workspace-core-utilities';
+import {
+  subscribeWorkspaceDocuments,
+  workspaceDocumentRegistryVersion,
+} from '@volter/editor-sdk/kit/workspace-document-registry';
+import { showWorkspaceUtility } from '@volter/editor-sdk/kit/workspace-host-commands';
+import { ViewportOverlaysMenu } from '@volter/editor-sdk/kit/components/ViewportOverlaysMenu';
+import {
+  setViewGridVisible,
+  subscribeViewportPresentation,
+  viewGridVisible,
+  viewportPresentationVersion,
+} from '@volter/editor-sdk/kit/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/editor-sdk/kit/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
+ * 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 is the stage's VIEW's switch (`overlays.grid.visible` in
+ * `kit/viewport-presentation`, keyed by `documentId`): the one flag this
+ * button, the document's header, the `toggle.grid` action, `set-grid` and
+ * `vgai status`'s `showGrid` all read and write.
+ */
+export function ViewportOverlay({
+  store,
+  documentId,
+}: {
+  readonly store: EditorShellStore;
+  readonly documentId: string;
+}) {
+  useSyncExternalStore(store.shell.subscribe, store.shell.getSnapshot);
+  useSyncExternalStore(subscribeWorkspaceDocuments, workspaceDocumentRegistryVersion);
+  useSyncExternalStore(subscribeActiveAuthoring, activeAuthoringVersion);
+  useSyncExternalStore(subscribeObject3DDocumentSessions, object3DDocumentSessionsVersion);
+  const { adapter } = resolvePanelAuthoring(store.shell);
+  const session = object3DDocumentSession(documentId);
+  useSyncExternalStore(session?.subscribe ?? NO_SESSION_SUBSCRIBE, session?.getSnapshot ?? ZERO);
+  useSyncExternalStore(subscribeViewportPresentation, viewportPresentationVersion);
+  const grid = viewGridVisible(documentId);
+  // THE VIEW'S NAME ON THE BAR (the look's `stage.chrome.viewName` `bar`, Unreal's
+  // "Perspective" pill) leads these controls and opens the view menu; wherever the name opens
+  // that menu itself (`bar`, `menu`) the camera icon is not drawn a second time.
+  const chrome = useViewportChrome();
+  const words = useViewportWords();
+  const namedView = chrome.viewName === 'bar' || chrome.viewName === 'menu';
+  // ON THE LOOK'S BAR these controls sit in the bar's display slot, which the document's surface
+  // draws beside the tools (`WorkspaceDocumentSurface`); they are portalled there so the row
+  // flows as one. Found from this stage's own place in the page.
+  const [anchor, setAnchor] = useState<HTMLSpanElement | null>(null);
+  const findSlot = (): HTMLElement | null =>
+    anchor
+      ?.closest('.vgai-dock-document-content')
+      ?.querySelector<HTMLElement>(':scope > .vgai-stage-bar [data-stage-bar-slot="display"]') ?? null;
+  // ONE OVERLAY PER SLOT: a document hosting two stages has one bar, so the first overlay to
+  // claim its slot draws there and any other keeps its own place.
+  const owner = useId();
+  const found = findSlot();
+  const slot = found && (found.dataset['owner'] === undefined || found.dataset['owner'] === owner) ? found : null;
+  // The surface's bar can commit after this render (a change of look reaches both at once), so
+  // the slot is looked for again once the page has settled.
+  const [, reslot] = useReducer((value: number) => value + 1, 0);
+  useEffect(() => {
+    const now = findSlot();
+    if (now && now.dataset['owner'] === undefined) now.dataset['owner'] = owner;
+    const claimable = now && now.dataset['owner'] === owner ? now : null;
+    if (claimable !== slot) reslot();
+  });
+  useEffect(
+    () => () => {
+      if (slot?.dataset['owner'] === owner) delete slot.dataset['owner'];
+    },
+    [slot, owner],
+  );
+  const toolbar = (
+    <FloatingToolbar
+      label="Viewport display"
+      className="vgai-viewport-toolbar vgai-viewport-toolbar-right vgai-stage-display"
+    >
+      {chrome.viewName === 'bar' && session ? (
+        <ViewportViewMenu
+          shell={store.shell}
+          documentId={documentId}
+          label={stageViewName(session.viewport, session.projection(), 'long')}
+        />
+      ) : null}
+      <Tooltip text={`Grid: ${grid ? 'On' : 'Off'}`}>
+        <IconButton
+          aria-label="Toggle grid"
+          aria-pressed={grid}
+          size="comfortable"
+          onClick={() => setViewGridVisible(documentId, !grid)}
+        >
+          <EditorIcon icon={faBorderAll} size="md" />
+        </IconButton>
+      </Tooltip>
+      <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).
+        onChange={(mode) => (session ? session.setMode(mode) : store.setShadingMode(mode))}
+        words={words.shading}
+      />
+      {namedView ? null : <ViewportViewMenu shell={store.shell} documentId={documentId} />}
+      <LightExplorerButton adapter={adapter} store={store} />
+    </FloatingToolbar>
+  );
+  return (
+    <>
+      <span ref={setAnchor} hidden />
+      {slot ? createPortal(toolbar, slot) : toolbar}
+    </>
+  );
+}
+
+/** The shading mode a document stage is painting (the menu names one it does not offer). */
+function sessionShading(
+  session: ReturnType<typeof object3DDocumentSession>,
+): ViewportShadingMode | 'uv' | 'vertex-colors' | null {
+  return session?.presentation().mode ?? null;
+}
+
+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.shell.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, word }: { store: EditorShellStore; word?: string | undefined }) {
+  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' },
+    { key: 'cursor' as const, label: '3D Cursor' },
+    { key: 'empties' as const, label: 'Empties' },
+  ];
+
+  return (
+    <ViewportOverlaysMenu
+      label="Helpers"
+      {...(word !== undefined ? { word } : {})}
+      master={{ enabled: store.shell.showHelpers, onToggle: () => store.shell.toggleHelpers() }}
+      choices={helperTypes.map((helper) => ({
+        id: helper.key,
+        label: helper.label,
+        enabled: store.shell.helperVisibility[helper.key],
+        onToggle: () => store.shell.toggleHelperType(helper.key),
+      }))}
+    />
+  );
+}

package/src/kit/components/ViewportShadingMenu.tsx

@@ -0,0 +1,340 @@
+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, useMemo, 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' },
+];
+
+/** The names of the modes a stage may paint that this menu does not offer. */
+const OWN_MODE_NAMES: Readonly<Record<string, string>> = {
+  preview: 'Material Preview',
+  rendered: 'Rendered',
+  uv: 'UV',
+  'vertex-colors': 'Vertex Colors',
+};
+
+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' | 'rendered';
+  readonly label: string;
+}
+
+/**
+ * THREE OF BLENDER'S FOUR, and the fourth stands only where it has a mode.
+ * 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"). A stage that keeps its lighting per draw mode draws Blender's
+ * own four instead ({@link perModeShadingSegments}); elsewhere a Rendered cell
+ * would be a shim promising a render the stage does not 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' },
+];
+
+/**
+ * BLENDER'S OWN FOUR CELLS, for a stage that keeps lighting per draw mode as Blender's shading
+ * types do: Wireframe, Solid (`solid` — materials' colours under its studio lights), Material
+ * Preview (`preview`) and Rendered (`rendered`). A cell stands only where the stage says how its
+ * mode is lit, so none is a shim; Solid and Wireframe are lit by the stage's own default.
+ */
+export function perModeShadingSegments(
+  declared: ReadonlySet<string>,
+): ReadonlyArray<ViewportShadingSegment<ViewportShadingMode>> {
+  return [
+    { mode: 'wireframe', glyph: 'wireframe', label: 'Wireframe' },
+    { mode: 'solid', glyph: 'sphere', label: 'Solid' },
+    ...(declared.has('preview') ? [{ mode: 'preview' as const, glyph: 'preview' as const, label: 'Material Preview' }] : []),
+    ...(declared.has('rendered') ? [{ mode: 'rendered' as const, glyph: 'rendered' as const, label: 'Rendered' }] : []),
+  ];
+}
+
+/**
+ * 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' || glyph === 'rendered' ? (
+        <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 === 'rendered' ? (
+        // Blender's Rendered mark is a lit ball: the filled disc with a highlight up and left.
+        <circle cx="5.6" cy="5.6" r="2.3" fill="var(--vgai-surface-overlay, #ffffff)" fillOpacity="0.7" />
+      ) : 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,
+  words,
+}: {
+  /** The mode the stage paints. One this menu does not offer (a stage's Material Preview or
+   *  Rendered, a Model document's UV or vertex colours) is still shown by its own name. */
+  mode: ViewportShadingMode | 'uv' | 'vertex-colors';
+  onChange: (mode: ViewportShadingMode) => void;
+  disabled?: boolean;
+  /** Each mode's name in the target's own words (the look's `stage.words.shading`). */
+  words?: Readonly<Partial<Record<string, string>>>;
+}) {
+  const choices = useMemo(() => {
+    const offered = viewportShadingModes.map((choice) => ({ ...choice, label: words?.[choice.mode] ?? choice.label }));
+    if (offered.some((choice) => choice.mode === mode)) return offered;
+    const label = words?.[mode] ?? OWN_MODE_NAMES[mode] ?? mode;
+    return [...offered, { mode: mode as ViewportShadingMode, label, description: 'The mode this view is drawn in' }];
+  }, [words, mode]);
+  return (
+    <ViewportDisplayModeMenu
+      mode={mode as ViewportShadingMode}
+      onChange={onChange}
+      choices={choices}
+      disabled={disabled}
+    />
+  );
+}