@volter/editor-core 0.5.57

package/src/components/ViewportViewMenu.tsx

@@ -0,0 +1,101 @@
+import { faCamera, faCaretDown } from '@fortawesome/free-solid-svg-icons';
+import {
+  Button,
+  EditorIcon,
+  EditorPopover,
+  IconButton,
+  Inline,
+  Stack,
+  Text,
+  Tooltip,
+} from '@volter/editor-sdk/widgets';
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import type { EditorShellStore } from '../editor-shell-store';
+import {
+  setThreeViewportProjection,
+  subscribeThreeViewportPresentation,
+  threeViewportPresentation,
+} from '../three-viewport-presentation';
+
+/** The standard Scene-view camera menu: projection and axis views in one
+ * place. These are editor-camera choices only. */
+/** The stage's projection + axis-view presets. `store` is the STAGE's own
+ *  store, so a preset drives the stage the control is mounted over
+ *  (ARCHITECTURE-CORE §One stage unit 4) — its `setViewPreset` reaches that
+ *  stage's viewport through its own action bus. */
+export function ViewportViewMenu({ store }: { readonly store: EditorShellStore }) {
+  const state = useSyncExternalStore(
+    subscribeThreeViewportPresentation,
+    threeViewportPresentation,
+    threeViewportPresentation,
+  );
+  const [open, setOpen] = useState(false);
+  const anchor = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!open) return;
+    const close = (event: MouseEvent) => {
+      if (!anchor.current?.contains(event.target as Node)) setOpen(false);
+    };
+    document.addEventListener('mousedown', close);
+    return () => document.removeEventListener('mousedown', close);
+  }, [open]);
+
+  const preset = (view: 'top' | 'front' | 'right'): void => {
+    setThreeViewportProjection('orthographic');
+    store.setViewPreset(view);
+  };
+
+  return (
+    <div ref={anchor} className="vgai-viewport-popover-anchor">
+      <Tooltip text={state.projection === 'perspective' ? 'Perspective' : 'Orthographic'}>
+        <IconButton
+          aria-label="Viewport views"
+          aria-expanded={open}
+          size="comfortable"
+          onClick={() => setOpen((value) => !value)}
+        >
+          <EditorIcon icon={open ? faCaretDown : faCamera} size="md" />
+        </IconButton>
+      </Tooltip>
+      {open ? (
+        <EditorPopover style={{ minWidth: 230 }}>
+          <Stack gap={3}>
+            <Text variant="caption" tone="muted">
+              Projection
+            </Text>
+            <Inline gap={1}>
+              <Button
+                size="compact"
+                variant={state.projection === 'perspective' ? 'primary' : 'ghost'}
+                onClick={() => setThreeViewportProjection('perspective')}
+              >
+                Perspective
+              </Button>
+              <Button
+                size="compact"
+                variant={state.projection === 'orthographic' ? 'primary' : 'ghost'}
+                onClick={() => setThreeViewportProjection('orthographic')}
+              >
+                Orthographic
+              </Button>
+            </Inline>
+            <Text variant="caption" tone="muted">
+              Axis View
+            </Text>
+            <Inline gap={1}>
+              <Button size="compact" variant="ghost" onClick={() => preset('top')}>
+                Top
+              </Button>
+              <Button size="compact" variant="ghost" onClick={() => preset('front')}>
+                Front
+              </Button>
+              <Button size="compact" variant="ghost" onClick={() => preset('right')}>
+                Right
+              </Button>
+            </Inline>
+          </Stack>
+        </EditorPopover>
+      ) : null}
+    </div>
+  );
+}

package/src/components/WorkspaceDocumentSurface.tsx

@@ -0,0 +1,204 @@
+import {
+  stageTransformDoor,
+  stageTransformsVersion,
+  subscribeStageTransforms,
+} from '@volter/editor-sdk/contributions';
+import type { EditorMaterialId } from '@volter/editor-sdk/widgets';
+import { useEffect, useSyncExternalStore } from 'react';
+import { activeAuthoringVersion, subscribeActiveAuthoring } from '../authoring/active-adapter';
+import {
+  object3DDocumentSessionsVersion,
+  subscribeObject3DDocumentSessions,
+} from '../authoring/object3d-document-session-registry';
+import { useEditorStore } from '../editor-runtime';
+import type { EditorShellStore } from '../editor-shell-store';
+import { nativeViewportShelfTool } from '../native-selection-style';
+import { documentStageContext, stageTransformDriver } from '../stage-context';
+import { stageStore, stageStoresVersion, subscribeStageStores } from '../stage-store-registry';
+import type {
+  WorkspaceDocumentDescriptor,
+  WorkspaceDocumentKind,
+} from '../workspace-document-registry';
+import { assetDocumentSpec } from './asset-documents';
+import { DocumentHeaderStrip } from './DocumentHeaderStrip';
+import { DocumentShelfRail } from './DocumentShelfRail';
+import { ToolStrip, TransformHeaderControls } from './Toolbar';
+
+/**
+ * THE STAGES WHOSE SHELF HAS ALREADY OPENED — the one piece of bookkeeping
+ * behind {@link armShelfBootTool}, and a `WeakSet` because a store outlives
+ * nothing here: it is the stage's, and when the stage goes so does the entry.
+ */
+const shelfOpened = new WeakSet<EditorShellStore>();
+
+/**
+ * THE SHELF'S BOOT TOOL IS THE LOOK'S, applied the first time this stage's
+ * shelf draws.
+ *
+ * Blender's tool shelf opens on Select Box, so a selected object carries no
+ * transform gizmo until one is armed (`DensityContribution.viewport.shelfTool`
+ * in `@volter/editor-sdk/looks`, which cites the frames); this editor's opens on
+ * the combined gizmo, which is what every look that names nothing keeps. It is a BOOT default and never a
+ * standing switch — the tool is one click away in the rail below, and once a
+ * person arms one the `WeakSet` above keeps this from ever second-guessing
+ * them, through a document tab switch, a workspace change or a look change.
+ *
+ * WHY HERE AND NOT WHERE THE STORE IS MINTED: `StageHost` is the gizmo
+ * viewport's own module and its value-import closure is PINNED
+ * (`scripts/validate-editor-closure.mjs`). This is the panel that DRAWS the
+ * shelf, so it is where the shelf's opening tool belongs; the reader it uses
+ * is the same leaf the viewport reads its gizmo size through, which costs that
+ * closure nothing either way.
+ */
+function armShelfBootTool(store: EditorShellStore | null): void {
+  if (store === null || shelfOpened.has(store)) return;
+  shelfOpened.add(store);
+  if (nativeViewportShelfTool() === 'select') store.setTransformMode('select');
+}
+
+export type WorkspaceDocumentFamily = 'world' | 'resource';
+export type WorkspaceDocumentPlacement =
+  | 'center-document'
+  | 'center-overlay'
+  /** A workspace's own EDITOR AREA — a second editor group beside or below
+   *  the centre document, holding the document its workspace declared
+   *  (`WorkspaceDocumentDescriptor.area`). */
+  | 'workspace-area';
+
+/** Semantic document family used by layout, hotkeys, and glass chrome. */
+export function workspaceDocumentFamily(kind: WorkspaceDocumentKind): WorkspaceDocumentFamily {
+  return kind === 'game' || kind === 'scene' || kind === 'world' ? 'world' : 'resource';
+}
+
+/** Resolve semantic document role against the material and the LAYOUT'S OWN
+ *  SHAPE: `backdrop` is true when the document is the workspace's background
+ *  — the grid is this one group and every other panel floats over it. A
+ *  workspace task then reads as an overlay card rather than a center tab. */
+export function workspaceDocumentPlacement(
+  descriptor: WorkspaceDocumentDescriptor,
+  material: EditorMaterialId,
+  backdrop: boolean,
+): WorkspaceDocumentPlacement {
+  // AN AREA WINS OVER EVERY OTHER PLACEMENT. A workspace that declared this
+  // document an area is stating where Blender's own screen puts it, and no
+  // material or backdrop reading may move it into the centre strip — that
+  // would put two editors on one tab rail and lose the split the ratio is a
+  // measurement of.
+  if (descriptor.area) return 'workspace-area';
+  return descriptor.workspaceRole === 'workspace-task' && material === 'glass' && backdrop
+    ? 'center-overlay'
+    : 'center-document';
+}
+
+/**
+ * Canonical host for a production document descriptor.
+ *
+ * The descriptor continues to own its content and optional toolbar. This
+ * host owns only the application-wide shell rules that every consumer must
+ * agree on: family, hotkey scope, toolbar placement, and content lifecycle.
+ */
+export function WorkspaceDocumentSurface({
+  viewId,
+  descriptor,
+  active,
+  backdrop = false,
+  chrome = true,
+}: {
+  readonly descriptor: WorkspaceDocumentDescriptor;
+  viewId?: string;
+  readonly active: boolean;
+  /** The document is the workspace's background (see
+   *  {@link workspaceDocumentPlacement}), so its header floats as an island
+   *  over the world rather than sitting in a strip above it. */
+  readonly backdrop?: boolean;
+  readonly chrome?: boolean;
+}) {
+  const Content = descriptor.Content;
+  const Toolbar = descriptor.Toolbar;
+  const Shelf = descriptor.Shelf;
+  const family = workspaceDocumentFamily(descriptor.kind);
+  // The shelf is built the way Blender's is: the host's transform TOOLS on
+  // top for any document whose active surface is a three stage (selection or
+  // not), the document's own operators beneath (`Shelf`). The transform
+  // CONTROLS that used to trail those tools (orientation, pivot, snap,
+  // options) ride the header instead — Blender's own placement.
+  // WHAT THOSE TOOLS DRIVE, and whether the header's wells are drawn at all,
+  // is `stageTransformDriver`'s one answer below: the wells configure the
+  // editor viewport's gizmo, so they follow the GIZMO arm and never appear
+  // over a stage that transforms through its own modal door.
+  const store = useEditorStore();
+  useSyncExternalStore(store.subscribe, store.getShellSnapshot ?? store.getSnapshot);
+  useSyncExternalStore(subscribeActiveAuthoring, activeAuthoringVersion, activeAuthoringVersion);
+  useSyncExternalStore(
+    subscribeObject3DDocumentSessions,
+    object3DDocumentSessionsVersion,
+    object3DDocumentSessionsVersion,
+  );
+  useSyncExternalStore(subscribeStageTransforms, stageTransformsVersion, stageTransformsVersion);
+  useSyncExternalStore(subscribeStageStores, stageStoresVersion, stageStoresVersion);
+  // A document with its OWN three stage (a model, an asset) carries the rail
+  // whatever the shell's roots say — a models project declares none. That is
+  // not a second rule: `stage-context.ts` answers what THIS document's stage is
+  // showing, and a document stage is a three stage.
+  const driver =
+    active && descriptor.kind !== 'game'
+      ? stageTransformDriver(documentStageContext(store, descriptor.id))
+      : 'none';
+  const door = driver === 'modal' ? stageTransformDoor(descriptor.id) : null;
+  // THE STORE THE GIZMO ARM WRITES — this stage's own, which for the world
+  // root IS the shell store (`StageHost.tsx`'s world-root install) and for
+  // every other stage is not. The shell is the fallback for a stage that has
+  // registered none yet, which is the state these controls used to write into
+  // permanently.
+  const gizmoStore = stageStore(descriptor.id) ?? store;
+  // THIS STAGE'S OWN store only — the shell's is the session's and arrives
+  // with whatever the world root was left at ({@link armShelfBootTool}). In an
+  // effect rather than in the body because arming notifies the store, and a
+  // store notification during another component's render is React's own
+  // "cannot update while rendering" case.
+  const ownStageStore = stageStore(descriptor.id);
+  useEffect(() => {
+    if (driver === 'gizmo') armShelfBootTool(ownStageStore);
+  }, [driver, ownStageStore]);
+  return (
+    <div
+      className="vgai-dock-document"
+      data-testid={`workspace-doc:${descriptor.id}`}
+      data-editor-hotkey-scope={family === 'world' ? 'viewport' : 'workspace'}
+      data-vgai-document-family={family}
+    >
+      {chrome && (
+        <DocumentHeaderStrip
+          documentId={descriptor.id}
+          runtime={descriptor.kind === 'game'}
+          island={backdrop && family === 'world'}
+          assetPath={assetDocumentSpec(descriptor.id)?.assetPath}
+          transformControls={
+            driver === 'gizmo' ? <TransformHeaderControls store={gizmoStore} /> : null
+          }
+        >
+          {Toolbar ? <Toolbar documentId={descriptor.id} active={active} /> : null}
+        </DocumentHeaderStrip>
+      )}
+      <div
+        className="vgai-dock-document-content"
+        data-workspace-document-id={descriptor.id}
+        data-workspace-view-id={viewId}
+      >
+        <Content documentId={descriptor.id} {...(viewId ? { viewId } : {})} active={active} />
+        {chrome && (
+          <DocumentShelfRail documentId={descriptor.id}>
+            {driver !== 'none' || Shelf ? (
+              <>
+                {driver === 'none' ? null : (
+                  <ToolStrip store={gizmoStore} {...(door ? { door } : {})} />
+                )}
+                {Shelf ? <Shelf documentId={descriptor.id} active={active} /> : null}
+              </>
+            ) : null}
+          </DocumentShelfRail>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/WorkspaceUtilitySurface.tsx

@@ -0,0 +1,22 @@
+import type { WorkspaceUtilityRegistration } from '../workspace-utility-registry';
+
+/** Canonical host for one registered workspace utility. */
+export function WorkspaceUtilitySurface({
+  utility,
+  testId,
+}: {
+  readonly utility: WorkspaceUtilityRegistration;
+  readonly testId?: string | undefined;
+}) {
+  const Content = utility.Content;
+  return (
+    <div
+      className="vgai-dock-panel vgai-regular-panel-portal"
+      data-testid={testId ?? `bottom-panel-utility-${utility.id}`}
+      data-editor-hotkey-scope="workspace"
+      data-vgai-noselect="true"
+    >
+      <Content />
+    </div>
+  );
+}

package/src/components/WorktreeSwitcher.css

@@ -0,0 +1,239 @@
+.vgai-worktree-switcher {
+  display: flex;
+  min-width: 0;
+  /* A GLYPH DOES NOT SHRINK, and it needs air: at 2px the two leading inks
+     merged into one blob at 1x (read at full scale, not reasoned about). One
+     grid step separates them and they read as the two controls they are. */
+  flex: 0 0 auto;
+  margin-left: var(--vgai-space-2);
+  align-items: center;
+}
+
+/* A GLYPH IN THE APP-MARK BAND (see WorktreeSwitcher.tsx for why the label
+   went): the same 14px box as the project glyph beside it, with no padding,
+   no chevron, and the ink centred.
+   TWO CLASSES because theme.css's `.vgai-menu-trigger` padding is equal
+   specificity and lands later (see ProjectHeader.css's leading-glyph rule for
+   the measurement). */
+.vgai-menu-trigger.vgai-worktree-trigger {
+  position: relative;
+  display: inline-flex;
+  width: 14px;
+  min-width: 0;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  gap: var(--vgai-space-2);
+}
+
+.vgai-worktree-dirty-dot {
+  width: 6px;
+  height: 6px;
+  flex: 0 0 auto;
+  border-radius: var(--vgai-radius-full);
+  background: var(--vgai-warn);
+}
+
+/* ON THE TRIGGER it is a BADGE, not a row item: with the label gone the dirty
+   mark would have widened the glyph by its own width plus a gap. It rides the
+   glyph's top-right corner and costs nothing. The menu ROWS keep the inline
+   dot above — there it sits after a branch name that is actually drawn. */
+.vgai-worktree-trigger .vgai-worktree-dirty-dot {
+  position: absolute;
+  top: 2px;
+  right: 1px;
+  width: 5px;
+  height: 5px;
+}
+
+.vgai-worktree-menu {
+  width: min(520px, calc(100vw - 24px));
+  padding: var(--vgai-space-2);
+}
+
+.vgai-worktree-version-control {
+  max-height: min(460px, 48vh);
+  overflow: auto;
+  padding: 0 var(--vgai-space-3) var(--vgai-space-2);
+}
+
+.vgai-worktree-version-control details > summary {
+  padding-block: var(--vgai-space-2);
+}
+
+.vgai-worktree-search {
+  display: flex;
+  align-items: center;
+  gap: var(--vgai-space-2);
+  padding: var(--vgai-space-1) var(--vgai-space-1) var(--vgai-space-2);
+}
+
+.vgai-worktree-search .vgai-input {
+  min-width: 0;
+  flex: 1;
+}
+
+.vgai-worktree-results {
+  max-height: min(420px, 60vh);
+  overflow: auto;
+}
+
+.vgai-worktree-section-label {
+  padding: var(--vgai-space-2) var(--vgai-space-4) var(--vgai-space-1);
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}
+
+.vgai-worktree-menu-item[data-current]:disabled {
+  color: var(--vgai-content-primary);
+}
+
+.vgai-worktree-menu-item[data-current]:disabled:hover {
+  background: var(--vgai-selection-bg);
+}
+
+.vgai-worktree-menu-item,
+.vgai-worktree-create-command {
+  min-width: 0;
+  min-height: 46px;
+  align-items: center;
+  gap: var(--vgai-space-2);
+  padding-block: var(--vgai-space-2);
+  padding-inline: var(--vgai-space-3);
+  white-space: normal;
+}
+
+.vgai-worktree-row-shell {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+}
+
+.vgai-worktree-row-shell > .vgai-worktree-menu-item {
+  min-width: 0;
+  flex: 1;
+}
+
+.vgai-worktree-row-icon {
+  display: inline-flex;
+  width: 18px;
+  flex: 0 0 18px;
+  align-items: center;
+  justify-content: center;
+  color: var(--vgai-content-muted);
+}
+
+.vgai-worktree-row-copy {
+  display: grid;
+  min-width: 0;
+  flex: 1;
+  gap: 1px;
+}
+
+.vgai-worktree-row-title,
+.vgai-worktree-row-detail {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.vgai-worktree-presence {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  padding-left: 5px;
+}
+
+.vgai-worktree-avatar {
+  --vgai-participant-color: var(--vgai-content-muted);
+  display: inline-flex;
+  width: 22px;
+  height: 22px;
+  margin-left: -5px;
+  align-items: center;
+  justify-content: center;
+  border: 2px solid var(--vgai-surface-overlay);
+  border-radius: var(--vgai-radius-full);
+  background: var(--vgai-participant-color);
+  color: white;
+  font-size: 8px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+}
+
+.vgai-worktree-avatar[data-kind="agent"] {
+  border-radius: 7px;
+}
+
+.vgai-worktree-avatar[data-status="needs-input"] {
+  box-shadow: 0 0 0 2px var(--vgai-warn);
+}
+
+.vgai-worktree-avatar[data-status="idle"],
+.vgai-worktree-avatar[data-status="done"] {
+  opacity: 0.62;
+}
+
+.vgai-worktree-avatar-more {
+  --vgai-participant-color: var(--vgai-surface-raised);
+  color: var(--vgai-content-muted);
+}
+
+.vgai-worktree-row-title {
+  display: flex;
+  align-items: center;
+  gap: var(--vgai-space-2);
+  font-size: var(--vgai-font-base);
+}
+
+.vgai-worktree-row-detail {
+  color: var(--vgai-content-dim);
+  font-size: var(--vgai-font-xs);
+}
+
+.vgai-worktree-empty,
+.vgai-worktree-error,
+.vgai-worktree-more,
+.vgai-worktree-notice {
+  padding: var(--vgai-space-3) var(--vgai-space-4);
+}
+
+.vgai-worktree-notice {
+  max-height: 140px;
+  overflow: auto;
+  border-top: 1px solid var(--vgai-boundary-default);
+  color: var(--vgai-content-muted);
+  white-space: pre-wrap;
+}
+
+.vgai-worktree-delegate {
+  display: grid;
+  gap: var(--vgai-space-2);
+  padding: var(--vgai-space-3);
+}
+
+.vgai-worktree-delegate textarea {
+  min-height: 72px;
+  resize: vertical;
+}
+
+.vgai-worktree-delegate label {
+  display: grid;
+  grid-template-columns: 70px minmax(0, 1fr);
+  align-items: center;
+  gap: var(--vgai-space-2);
+  color: var(--vgai-content-dim);
+  font-size: var(--vgai-font-xs);
+}
+
+/* Structural only: the label grid's minmax(0, 1fr) column needs the control to
+   be allowed to shrink. All paint belongs to the canonical `.vgai-select`. */
+.vgai-worktree-delegate select {
+  min-width: 0;
+}
+
+.vgai-worktree-delegate-open {
+  width: 100%;
+  justify-content: center;
+}