@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/components/ApplicationMenus.tsx

@@ -0,0 +1,372 @@
+import {
+  AnchoredMenu,
+  EditorIcon,
+  editorIcons,
+  MenuItem,
+  MenuTrigger,
+  MenuSeparator as Separator,
+} from '@volter/sdk/widgets';
+import { type RefObject, useRef, useState, useSyncExternalStore } from 'react';
+import { getActiveAuthoring } from '@volter/sdk/kit/authoring/active-adapter';
+import { selectAllAuthoringNodes } from '@volter/sdk/kit/authoring/shell-document-ops';
+import { useAvailabilitySelector } from '@volter/sdk/kit/availability-tick';
+import {
+  contributedChromeVersion,
+  contributedDisabledFingerprint,
+  contributedMenuItems,
+  subscribeContributedChrome,
+} from '@volter/sdk/kit/chrome-registry';
+import { openCommandPalette } from '@volter/sdk/kit/editor-commands';
+import { editorConsole } from '@volter/sdk/kit/editor-console';
+import { currentEditorViewUrl } from '../editor-current-view';
+import {
+  copySelection,
+  cutSelection,
+  deleteSelection,
+  duplicateSelection,
+  pasteSelection,
+} from '@volter/sdk/kit/editor-hotkeys';
+import { useEditorStore, useHistoryCommandSnapshot, useHistoryCommands } from '@volter/sdk/kit/editor-runtime';
+import { editorKeymapsVersion, subscribeEditorKeymap } from '@volter/sdk/kit/keymap-presets';
+import { getProjectTools, subscribeProjectTools } from '@volter/sdk/kit/project-tools';
+import { getSurfaceToolContributions, subscribeToolContributions } from '@volter/sdk/kit/tool-loader';
+import { openUndoHistory } from '@volter/sdk/kit/workspace-aux-commands';
+import { CORE_WORKSPACE_UTILITIES } from '@volter/sdk/kit/workspace-core-utilities';
+import {
+  showWorkspaceStaticPanel,
+  showWorkspaceUtility,
+  toggleWorkspaceFocus,
+} from '@volter/sdk/kit/workspace-host-commands';
+import {
+  activeEditorWorkspace,
+  editorWorkspaces,
+  editorWorkspacesVersion,
+  setEditorWorkspace,
+  subscribeEditorWorkspace,
+  subscribeEditorWorkspaces,
+  workspaceApplies,
+} from '@volter/sdk/kit/workspace-presets';
+import { subscribeWorkspaceStyles, workspaceStylesVersion } from '@volter/sdk/kit/workspace-style';
+import { toggleConsoleUtility } from '@volter/sdk/kit/workspace-utility-commands';
+import { openProjectToolsDocument } from '@volter/sdk/kit/components/project-tool-documents';
+import { openToolDocument } from '@volter/sdk/kit/components/tool-documents';
+
+type MenuId = 'edit' | 'view' | 'window' | 'debug' | 'tools' | 'help';
+
+export function ApplicationMenus() {
+  const store = useEditorStore();
+  const activeAuthoring = getActiveAuthoring(store);
+  const structure = activeAuthoring.structure;
+  const clipboardIds = [...store.selectedEntityIds];
+  const selectedId = clipboardIds[0];
+  const pasteParentId = selectedId
+    ? (activeAuthoring.hierarchy.node(selectedId)?.parentId ?? null)
+    : null;
+  const history = useHistoryCommands();
+  const historySnapshot = useHistoryCommandSnapshot();
+  // DOCUMENTS AND UTILITIES BOTH: this menu is the only door onto a project's
+  // `workspace.utility` drawer tab, which registers hidden by default.
+  const tools = useSyncExternalStore(
+    subscribeToolContributions,
+    getSurfaceToolContributions,
+    getSurfaceToolContributions,
+  );
+  // The three look registries: a package's workspace, keymap or style that
+  // registers after this menu mounted still lists (WORKBENCH.md §Contribution points).
+  useSyncExternalStore(subscribeEditorWorkspaces, editorWorkspacesVersion, editorWorkspacesVersion);
+  useSyncExternalStore(subscribeEditorKeymap, editorKeymapsVersion, editorKeymapsVersion);
+  useSyncExternalStore(subscribeWorkspaceStyles, workspaceStylesVersion, workspaceStylesVersion);
+  useSyncExternalStore(
+    subscribeContributedChrome,
+    contributedChromeVersion,
+    contributedChromeVersion,
+  );
+  /** A package's items at the end of a menu (`@volter/sdk/chrome`). */
+  const contributed = (menu: 'view' | 'window' | 'debug' | 'tools' | 'help') => {
+    const items = contributedMenuItems(menu);
+    if (items.length === 0) return null;
+    return (
+      <>
+        <Separator />
+        {items.map((item) => (
+          <MenuItem
+            key={item.id}
+            {...(item.testId ? { 'data-testid': item.testId } : {})}
+            disabled={item.disabled?.({}) ?? false}
+            onSelect={choose(() => item.execute({}))}
+          >
+            {typeof item.label === 'function' ? item.label() : item.label}
+          </MenuItem>
+        ))}
+      </>
+    );
+  };
+  const commands = useSyncExternalStore(subscribeProjectTools, getProjectTools, getProjectTools);
+  const workspace = useSyncExternalStore(
+    subscribeEditorWorkspace,
+    activeEditorWorkspace,
+    activeEditorWorkspace,
+  );
+  const [open, setOpen] = useState<MenuId | null>(null);
+  // A contributed item's `disabled` (and dynamic label) is asked at render,
+  // and the point promises it may follow session state — which needs
+  // SOMETHING to re-render the bar when that state moves. Sample the answers
+  // on the shared availability tick, but only while a menu is open: closed,
+  // this costs nothing; open, an item can go live or dead under the cursor.
+  useAvailabilitySelector(() => (open ? contributedDisabledFingerprint() : ''));
+  const rootRef = useRef<HTMLDivElement>(null);
+  // ONE STABLE REF PER MENU WORD, minted on first ask. `AnchoredMenu` measures
+  // this element every layout pass, so a fresh object per render would rebuild
+  // its placement callback on every one.
+  const anchorRefs = useRef<Record<string, RefObject<HTMLDivElement | null>>>({});
+  const anchorRef = (id: MenuId): RefObject<HTMLDivElement | null> =>
+    (anchorRefs.current[id] ??= { current: null });
+
+  // NO OUTSIDE-POINTER LISTENER OF ITS OWN. `AnchoredMenu` dismisses on a press outside the open
+  // menu and its trigger (`onDismiss` below), and the menu is PORTALED out of this bar: a listener
+  // asking whether the press was inside the bar answered no for the menu's own rows and closed it
+  // on `pointerdown`, before the row's `click`. Every Edit, View and Window item then did nothing
+  // for a person (measured 2026-09-28 with a real click on the browser-substrate page).
+
+  // A command that FAILS says so in the console, as the same verb over the wire does: a click
+  // that changed nothing and said nothing reads as a dead menu.
+  const choose = (action: () => unknown | Promise<unknown>) => () => {
+    setOpen(null);
+    Promise.resolve()
+      .then(action)
+      .catch((error: unknown) =>
+        editorConsole.error(
+          `The menu command failed: ${error instanceof Error ? error.message : String(error)}`,
+          'editor',
+        ),
+      );
+  };
+  const panels: Record<MenuId, React.ReactNode> = {
+    edit: (
+      <>
+        <MenuItem
+          disabled={historySnapshot.busy || !historySnapshot.canUndo}
+          onSelect={choose(() => history.undo())}
+        >
+          {historySnapshot.undoLabel ? `Undo ${historySnapshot.undoLabel}` : 'Undo'}
+        </MenuItem>
+        <MenuItem
+          disabled={historySnapshot.busy || !historySnapshot.canRedo}
+          onSelect={choose(() => history.redo())}
+        >
+          {historySnapshot.redoLabel ? `Redo ${historySnapshot.redoLabel}` : 'Redo'}
+        </MenuItem>
+        <Separator />
+        <MenuItem onSelect={choose(openUndoHistory)}>Undo History…</MenuItem>
+        <Separator />
+        <MenuItem
+          disabled={
+            clipboardIds.length === 0 ||
+            !structure?.cut ||
+            !(structure.canCopy?.(clipboardIds) ?? true)
+          }
+          onSelect={choose(() => cutSelection(store))}
+        >
+          Cut
+        </MenuItem>
+        <MenuItem
+          disabled={
+            clipboardIds.length === 0 ||
+            !structure?.copy ||
+            !(structure.canCopy?.(clipboardIds) ?? true)
+          }
+          onSelect={choose(() => copySelection(store))}
+        >
+          Copy
+        </MenuItem>
+        <MenuItem
+          disabled={!structure?.paste || !(structure.canPaste?.(pasteParentId) ?? true)}
+          onSelect={choose(() => pasteSelection(store))}
+        >
+          Paste
+        </MenuItem>
+        <Separator />
+        <MenuItem
+          disabled={store.selectedEntityIds.size === 0}
+          onSelect={choose(() => void duplicateSelection(store))}
+        >
+          Duplicate
+        </MenuItem>
+        <MenuItem
+          disabled={store.selectedEntityIds.size === 0}
+          onSelect={choose(() => void deleteSelection(store))}
+        >
+          Delete
+        </MenuItem>
+        <Separator />
+        <MenuItem onSelect={choose(() => selectAllAuthoringNodes(store))}>Select All</MenuItem>
+        <MenuItem
+          disabled={store.selectedEntityIds.size === 0}
+          onSelect={choose(() => store.select(null))}
+        >
+          Deselect All
+        </MenuItem>
+      </>
+    ),
+    view: (
+      <>
+        <MenuItem onSelect={choose(() => openCommandPalette())}>Command Palette…</MenuItem>
+        <MenuItem
+          onSelect={choose(async () => {
+            const url = currentEditorViewUrl(store);
+            try {
+              await navigator.clipboard.writeText(url);
+              editorConsole.log('Copied a link to the current editor view.', 'editor');
+            } catch (error) {
+              editorConsole.error(
+                `Could not copy the editor view link: ${error instanceof Error ? error.message : String(error)}`,
+                'editor',
+              );
+            }
+          })}
+        >
+          Copy View Link
+        </MenuItem>
+        <Separator />
+        <MenuItem onSelect={choose(toggleWorkspaceFocus)}>Toggle Focus Mode</MenuItem>
+        {contributed('view')}
+      </>
+    ),
+    window: (
+      <>
+        {/* NAMED WORKSPACES (ARCHITECTURE-CORE §Editor chrome). This run IS
+            `Window → Workspace` — the ruling's switching door, with the active
+            one checked. There is deliberately no persistent picker strip, and
+            nothing else in the editor calls `setEditorWorkspace`: switching
+            happens here, through the registered actions, or through
+            `editor.workspace(id)`. */}
+        {editorWorkspaces()
+          .filter((choice) => workspaceApplies(choice.id))
+          .map((choice) => (
+            <MenuItem
+              key={choice.id}
+              role="menuitemradio"
+              aria-checked={workspace === choice.id}
+              data-testid={`workspace-${choice.id}`}
+              title={choice.description}
+              onSelect={choose(() => setEditorWorkspace(choice.id))}
+            >
+              <EditorIcon
+                icon={editorIcons.status.success}
+                style={{ opacity: workspace === choice.id ? 1 : 0 }}
+              />
+              Workspace: {choice.title}
+            </MenuItem>
+          ))}
+        <Separator />
+        <MenuItem onSelect={choose(toggleConsoleUtility)}>Console</MenuItem>
+        <MenuItem
+          onSelect={choose(() => showWorkspaceUtility(CORE_WORKSPACE_UTILITIES.lightExplorer.id))}
+        >
+          Light Explorer
+        </MenuItem>
+        <MenuItem onSelect={choose(() => showWorkspaceStaticPanel('asset-library'))}>
+          Asset Library
+        </MenuItem>
+        <MenuItem onSelect={choose(() => showWorkspaceUtility('generations'))}>
+          Generations
+        </MenuItem>
+        {contributed('window')}
+      </>
+    ),
+    debug: <>{contributed('debug')}</>,
+    tools: (
+      <>
+        <MenuItem onSelect={choose(() => openProjectToolsDocument())}>
+          Project Tools…
+          {commands.tools.length > 0 ? ` (${commands.tools.length})` : ''}
+        </MenuItem>
+        <Separator />
+        {tools.length ? (
+          tools.map((tool) => {
+            return (
+              <MenuItem
+                key={tool.id}
+                onSelect={choose(() => {
+                  if (tool.point === 'workspace.document') openToolDocument(tool.id);
+                  else showWorkspaceUtility(`tool:${tool.id}`);
+                })}
+              >
+                {tool.title}
+              </MenuItem>
+            );
+          })
+        ) : (
+          <MenuItem disabled>No custom project tools</MenuItem>
+        )}
+        {contributed('tools')}
+      </>
+    ),
+    // Help holds what packages contribute to it; with nothing contributed the
+    // bar shows no Help menu rather than an empty one.
+    help: contributedMenuItems('help').length > 0 ? contributed('help') : null,
+  };
+
+  return (
+    <div
+      ref={rootRef}
+      data-testid="app-menubar"
+      style={{ display: 'flex', alignItems: 'stretch', marginLeft: 'var(--volter-space-2)' }}
+    >
+      {(['edit', 'view', 'window', 'debug', 'tools', 'help'] as const)
+        .filter((id) => panels[id] !== null)
+        .map((id) => (
+        <div key={id} ref={anchorRef(id)} style={{ position: 'relative' }}>
+          <MenuTrigger
+            data-testid={`app-menu-${id}`}
+            aria-haspopup="menu"
+            aria-expanded={open === id}
+            onClick={() => setOpen((current) => (current === id ? null : id))}
+            onKeyDown={(event) => {
+              if (event.key !== 'ArrowDown') return;
+              event.preventDefault();
+              setOpen(id);
+            }}
+            onPointerEnter={() => {
+              if (open) setOpen(id);
+            }}
+            style={{ textTransform: 'capitalize' }}
+          >
+            {id}
+          </MenuTrigger>
+          {open === id && (
+            /* PORTALED, NOT `position: absolute`. These words live in the app's
+                 title bar, and under the Code-OSS frame that bar is the workbench's
+                 own `.part.titlebar` — 26 px tall with `overflow: hidden`, as are
+                 `.titlebar-container` and our host slot inside it. An absolutely
+                 positioned popup was laid out correctly (190x279, every item with a
+                 box) and PAINTED one row: measured 2026-09-20 on U8's walk 3, where
+                 the Window menu showed `Workspace: Model` and hid eleven items.
+                 `AnchoredMenu` is the same primitive the toolbar, the telemetry
+                 cluster and the Object3D toolbar already use for exactly this — it
+                 measures the trigger, places the menu in viewport coordinates and
+                 portals it to the theme root, which is outside every clip. */
+            <AnchoredMenu
+              anchorRef={anchorRef(id)}
+              dismissBoundaryRef={anchorRef(id)}
+              align="start"
+              gap={0}
+              clamp
+              autoFocusFirst
+              onDismiss={() => {
+                const trigger = rootRef.current?.querySelector<HTMLButtonElement>(
+                  `[data-testid="app-menu-${id}"]`,
+                );
+                setOpen(null);
+                requestAnimationFrame(() => trigger?.focus());
+              }}
+              style={{ minWidth: 190 }}
+            >
+              {panels[id]}
+            </AnchoredMenu>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/kit/components/AssetEditorShell.tsx

@@ -0,0 +1,216 @@
+/**
+ * The asset document shell — the frame an open asset lives in, and NOTHING
+ * about how it is inspected.
+ *
+ * "What is an asset in three.js but a hierarchical group of other three.js
+ * assets" (owner, 2026-08-07). An asset document is the three paradigm scoped
+ * to a SUBTREE — Unity's prefab-isolation mode: same viewport, same hierarchy,
+ * same inspector box, only the root changed. So the ordinary inspector rides
+ * over an asset document exactly as it rides over the scene: the same box in
+ * the same corner, draggable, minimizable, expandable to the same column, with
+ * the same per-surface preference (`inspection/display.ts` resolves it for the
+ * `asset-lab` surface like any other). This shell renders none of it.
+ *
+ * What it owns is the two things that make the document a SUBJECT PRODUCER:
+ *
+ *  - it activates the asset-editor context, which is what makes the active
+ *    inspection surface `asset-lab` (`inspection/active-surface.ts`);
+ *  - it registers the document's SELECTION CONTEXT and publishes the
+ *    document's own subject description (`inspection/document-subject.ts`).
+ *
+ * The selection context is the load-bearing half, and every asset document
+ * registers one even with nothing to select. Registering it is how a document
+ * says "I am the subject": without it the Inspector falls back to the shared
+ * entity selection, and an image viewer would show whatever was picked in the
+ * scene before it was opened. A document with live authoring of its own (the
+ * Object3D editor) passes `selection` and its picked part flows through; a
+ * document without passes nothing and gets `{adapter: null, nodeId: null}`,
+ * which resolves to its own identity floor.
+ *
+ * The identity row is where that floor lives: even a document with no sections
+ * at all says what it is, what kind it is, and where it came from — and no
+ * section of its own stands in for that row, because identity is a property of
+ * the SUBJECT (`inspection/model.ts`).
+ */
+
+import { type ReactNode, useEffect, useRef } from 'react';
+import { activateAssetEditorContext } from '../asset-editor-context';
+import { publishDocumentInspectionSubject } from '../inspection/document-subject';
+import type { InspectionSection } from '@volter/sdk/kit/inspection-model';
+import type { NullInspectionSubject } from '../inspection/null-subject';
+import {
+  registerWorkspaceDocumentSelection,
+  type WorkspaceDocumentSelection,
+} from '@volter/sdk/kit/workspace-document-registry';
+
+/** What a document with no authoring of its own selects: itself. */
+const DOCUMENT_IS_THE_SUBJECT: WorkspaceDocumentSelection = { adapter: null, nodeId: null };
+
+/**
+ * The part of a document subject whose change can alter the Inspector's
+ * structure. Function identities deliberately stay out of this key: render
+ * functions and field IO are read through `descriptionRef` below, so a parent
+ * render updates them without feeding the Inspector's own notification back
+ * into another publication.
+ */
+function subjectPublicationKey(subject: NullInspectionSubject): string {
+  return JSON.stringify({
+    id: subject.id,
+    title: subject.title,
+    hint: subject.hint,
+    kindLabel: subject.kindLabel,
+    note: subject.note,
+    sections: subject.sections.map((section) => ({
+      id: section.id,
+      title: section.title,
+      order: section.order,
+      description: section.description,
+      defaultOpen: section.defaultOpen,
+      testId: section.testId,
+      keepMounted: section.keepMounted,
+      railGroup: section.railGroup,
+      bodyKind: section.body.kind,
+    })),
+    quickActions: subject.quickActions?.map((action) => ({
+      id: action.id,
+      title: action.title,
+      label: action.label,
+      placement: action.placement,
+      pressed: action.pressed,
+      disabled: action.disabled,
+    })),
+  });
+}
+
+/**
+ * The three optional props below are spelled `?: T | undefined` rather than
+ * `?: T`, because `AssetEditorShell` PASSES ITS OWN THROUGH: under
+ * `exactOptionalPropertyTypes` an explicit `undefined` is not the same as an
+ * absent key, so `sections={sections}` on a shell whose own `sections` is
+ * optional is a type error against `?: T`. Undefined is a value this component
+ * genuinely handles (`sections ?? []`, `status &&`, `selection?.()`) — the
+ * widened type says that, where a conditional spread at the one call site would
+ * only hide it.
+ */
+interface AssetEditorSubjectProps {
+  documentId: string;
+  active?: boolean;
+  type: string;
+  title: string;
+  /** This document's own inspection sections, for the subject it publishes
+   *  when nothing inside it is picked. Identity (name/kind/provenance) is
+   *  composed from `title`/`type`/`status` — a document always has one, even
+   *  with no sections at all. */
+  sections?: readonly InspectionSection[] | undefined;
+  status?: string | undefined;
+  /** What is picked INSIDE this document, for a document with authoring of
+   *  its own. Read on demand (the registry calls it), so it may close over
+   *  live state that changes without re-registering. */
+  selection?: (() => WorkspaceDocumentSelection | null) | undefined;
+}
+
+/**
+ * The non-visual half of an Asset Lab document. Kept separate from the frame
+ * so project-owned contribution UIs can publish the standard subject without
+ * sending React elements across the project/editor runtime boundary.
+ */
+export function AssetEditorSubject({
+  documentId,
+  active = true,
+  type,
+  title,
+  sections,
+  status,
+  selection,
+}: AssetEditorSubjectProps) {
+  useEffect(() => {
+    if (!active) return;
+    return activateAssetEditorContext({
+      documentId,
+      title,
+      type,
+      ...(status ? { status } : {}),
+    });
+  }, [active, documentId, status, title, type]);
+
+  // ONE owner for this document's selection context (the registry keys by
+  // document id, so a second registrant would silently displace the first and
+  // take the entry with it on unmount). The ref keeps the registration stable
+  // while the provider it delegates to is free to change every render.
+  const selectionRef = useRef(selection);
+  selectionRef.current = selection;
+  useEffect(() => {
+    if (!active) return;
+    return registerWorkspaceDocumentSelection(
+      documentId,
+      () => selectionRef.current?.() ?? DOCUMENT_IS_THE_SUBJECT,
+    );
+  }, [active, documentId]);
+
+  // The document's subject DESCRIPTION — identity plus its own sections, in
+  // the same shape every surface's `describeSubject(null)` answer takes.
+  // The latest description is read on demand, so section IO closures remain
+  // live without publishing on every render. Publishing itself notifies the
+  // Inspector; doing it after every Inspector-driven parent render creates a
+  // notification -> render -> publication loop and React eventually throws
+  // "Maximum update depth exceeded" when an Object3D prefab opens.
+  const description: NullInspectionSubject = {
+    id: documentId,
+    title,
+    // `kindLabel` is what earns the composed identity ROW, and a document
+    // always names its kind: an Asset Lab document IS a thing with a name, a
+    // type and a provenance.
+    kindLabel: type,
+    ...(status ? { note: { text: status, testId: 'asset-editor-status' } } : {}),
+    sections: sections ?? [],
+  };
+  const descriptionRef = useRef(description);
+  descriptionRef.current = description;
+  const publicationKey = subjectPublicationKey(description);
+  useEffect(() => {
+    if (!active) return;
+    return publishDocumentInspectionSubject(documentId, () => descriptionRef.current);
+  }, [active, documentId, publicationKey]);
+
+  return null;
+}
+
+export function AssetEditorShell({
+  documentId,
+  active = true,
+  type,
+  title,
+  sections,
+  status,
+  fill = false,
+  selection,
+  children,
+}: AssetEditorSubjectProps & {
+  /** The child owns the whole viewport box and clips itself (a 3D canvas),
+   *  rather than flowing and scrolling inside it. */
+  fill?: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <section
+      className="volter-asset-editor"
+      data-testid={`asset-editor:${type}`}
+      aria-label={`${title} Asset Editor`}
+    >
+      <AssetEditorSubject
+        documentId={documentId}
+        active={active}
+        type={type}
+        title={title}
+        sections={sections}
+        status={status}
+        selection={selection}
+      />
+      <main
+        className={`volter-asset-editor__viewport${fill ? ' volter-asset-editor__viewport--fill' : ''}`}
+      >
+        {children}
+      </main>
+    </section>
+  );
+}