@volter/editor-core 0.5.57

package/src/components/use-project-image-assets.ts

@@ -0,0 +1,86 @@
+/**
+ * The project's own IMAGE assets, for the inspector's `asset` slots.
+ *
+ * This is the existing asset-workflow seam and nothing new: the same
+ * `listAssets` walk over `public/` that the Asset Browser's Content gallery
+ * runs (`collectProjectContentAssets`), narrowed with the same facet
+ * classifier (`projectContentAssetFacet`). A texture slot must offer the same
+ * files the Asset Browser shows, so it reads them from the same place rather
+ * than growing a second listing.
+ *
+ * ONE scan is shared by every slot on screen — a `MeshStandardMaterial`
+ * publishes six of them, and six independent walks of `public/` per selection
+ * is the kind of quiet cost a panel never recovers from. The cached scan
+ * expires so an asset imported mid-session shows up on the next selection
+ * without a reload; the Asset Browser is still the surface that IMPORTS.
+ */
+
+import { useEffect, useState } from 'react';
+import {
+  collectProjectContentAssets,
+  projectContentAssetFacet,
+} from '../asset-workflow/project-content';
+import { listAssets } from '../editor-api';
+
+/** How long a scan is reused. Long enough to cover one selection's worth of
+ *  slots mounting together, short enough that a just-imported texture appears
+ *  without a reload. */
+const CACHE_MS = 10_000;
+
+export interface ProjectImageAssets {
+  /** Public-root-relative paths, sorted. */
+  readonly paths: readonly string[];
+  /** Directories whose listing FAILED — an empty picker over a failed scan
+   *  would tell the author their project has no textures. */
+  readonly failures: readonly string[];
+}
+
+const EMPTY: ProjectImageAssets = { paths: [], failures: [] };
+
+let cached: { at: number; scan: Promise<ProjectImageAssets> } | null = null;
+
+async function scanProjectImageAssets(): Promise<ProjectImageAssets> {
+  // SHIPPED IMAGES ONLY. A material slot names a file the GAME loads at
+  // runtime, and reference material is never exported — offering a moodboard
+  // plate here would author a texture path that 404s in the built game.
+  const listed = await collectProjectContentAssets(listAssets, ['public']);
+  return {
+    paths: listed.assets
+      .filter((asset) => projectContentAssetFacet(asset.entry.name) === 'image')
+      .map((asset) => asset.path)
+      .sort((a, b) => a.localeCompare(b)),
+    failures: listed.failedListings,
+  };
+}
+
+/** The shared scan, refreshed when the cached one has expired. */
+export function projectImageAssets(): Promise<ProjectImageAssets> {
+  const now = Date.now();
+  if (!cached || now - cached.at > CACHE_MS) {
+    cached = {
+      at: now,
+      scan: scanProjectImageAssets().catch((error: unknown) => {
+        cached = null;
+        return { paths: [], failures: [error instanceof Error ? error.message : String(error)] };
+      }),
+    };
+  }
+  return cached.scan;
+}
+
+/** Read the shared scan into a component. `enabled: false` skips it entirely,
+ *  so a panel with no asset row never walks `public/`. */
+export function useProjectImageAssets(enabled: boolean): ProjectImageAssets {
+  const [assets, setAssets] = useState<ProjectImageAssets>(EMPTY);
+  useEffect(() => {
+    if (!enabled) return;
+    let live = true;
+    void projectImageAssets().then((next) => {
+      if (live) setAssets(next);
+    });
+    return () => {
+      live = false;
+    };
+  }, [enabled]);
+  return assets;
+}

package/src/components/viewport-header-controls.css

@@ -0,0 +1,90 @@
+/* THE VIEWPORT HEADER'S TRANSCRIBED CONTROLS — the shading group
+ * (`ViewportShadingMenu.tsx`) and the overlays toggle
+ * (`ViewportOverlaysMenu.tsx`). One sheet because they are one row of chrome
+ * and share the icon rung below.
+ *
+ * THE SHADING CONTROL AS BLENDER DRAWS IT — a joined group of mode cells and
+ * a chevron, in place of a word dropdown. These rules only ever apply where a
+ * caller passes `segments`; the stage's floating shading trigger passes none
+ * and keeps its labelled button.
+ *
+ * The cells JOIN: square inner corners and a shared border, so the group is
+ * one widget with one cell lit rather than four boxes with daylight between
+ * them. Transcribed from the sibling group in this same header
+ * (`@vgai/blender`'s select-mode cells), whose own comment records why. */
+.vgai-viewport-shading-segments {
+  display: inline-flex;
+}
+
+/* EACH CELL ARRIVES WRAPPED IN A TOOLTIP ANCHOR, so the group's children are
+ * anchors and the buttons sit one level down — a `>` rule aimed at the button
+ * matched nothing and the group rendered as four separate rounded boxes with
+ * daylight between them. Both shapes are addressed here so a cell that loses
+ * its tooltip still joins. */
+.vgai-viewport-shading-segments > * {
+  display: inline-flex;
+}
+
+/* The DIVIDER between two cells is the left one's own right border: every
+ * cell but the first drops its left border rather than collapsing onto its
+ * neighbour with a negative margin, so the group carries exactly Blender's
+ * one-pixel separator and this sheet spends no pixel literal to get it. */
+.vgai-viewport-shading-segments > :not(:first-child) .vgai-btn,
+.vgai-viewport-shading-segments > .vgai-btn:not(:first-child) {
+  border-top-left-radius: 0;
+  border-bottom-left-radius: 0;
+  border-left-width: 0;
+}
+
+.vgai-viewport-shading-segments > :not(:last-child) .vgai-btn,
+.vgai-viewport-shading-segments > .vgai-btn:not(:last-child) {
+  border-top-right-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+/* The pressed cell rides ABOVE its neighbours so the shared border it owns is
+ * its own, not the unpressed cell's drawn over it. */
+.vgai-viewport-shading-segments .vgai-btn[aria-pressed="true"] {
+  position: relative;
+  z-index: 1;
+}
+
+/* Sized off the ICON scale like every `EditorIcon` beside it, so a style that
+ * moves the chrome's glyph size moves these three with it. */
+.vgai-viewport-shading-glyph {
+  width: var(--vgai-icon-md);
+  height: var(--vgai-icon-md);
+  overflow: visible;
+}
+
+/* Blender keeps its lighting rows INSIDE the shading popover, under the modes.
+ * The grid matches the preview popover these rows came from. */
+.vgai-viewport-shading-options {
+  display: grid;
+  gap: var(--vgai-space-2);
+  padding: var(--vgai-space-2) var(--vgai-space-3);
+}
+
+.vgai-viewport-shading-options > label {
+  display: grid;
+  grid-template-columns: 68px minmax(0, 1fr) auto;
+  align-items: center;
+  gap: var(--vgai-space-2);
+  color: var(--vgai-text-2);
+  font-size: var(--vgai-font-xs);
+}
+
+.vgai-viewport-shading-options select {
+  grid-column: 2 / -1;
+}
+
+.vgai-viewport-shading-options input[type="range"] {
+  width: 120px;
+}
+
+/* The overlays mark sits on the same rung as the shading cells' glyphs. */
+.vgai-viewport-overlays-glyph {
+  width: var(--vgai-icon-md);
+  height: var(--vgai-icon-md);
+  overflow: visible;
+}

package/src/components/viewport-surface-status.tsx

@@ -0,0 +1,55 @@
+/**
+ * The 3D board's empty-viewport vocabulary, reused by every other design
+ * surface that would otherwise sit blank while it builds. Scene's root-aware
+ * loading/failure/empty states live in `SurfaceStateOverlay`; this compact
+ * label remains for object/board construction whose subject is already known.
+ *
+ * Idle / building / ready is viewport STATE, not a new overlay channel —
+ * the board already owns this shape (`ThreeBoardDocument`: idle "Open this
+ * tab…", building "Settling N stories…"). Scene's first design
+ * mount and `Object3DDocumentViewport`'s first construct are the same wait
+ * with different subjects. Copy names the subject being prepared; it does not
+ * claim a narrower phase (such as physics settling) while indexing, mounting,
+ * bounds/layout, or renderer setup is actually in flight.
+ */
+
+import { themeVars } from '@volter/editor-sdk/widgets';
+import type { ReactNode } from 'react';
+
+/** Fixed construct tail after the board scene exists — viewport-bind, not settle. */
+export const OBJECT3D_SURFACE_BUILDING = 'Preparing the viewport…';
+
+/** Whole 3D-board construction, from component index through mounted previews. */
+export const THREE_BOARD_BUILDING = 'Preparing 3D component previews…';
+
+/** Name the candidate count when we already know it. Never a progress fraction. */
+export function threeBoardBuildingCopy(storyCount: number): string {
+  if (!Number.isFinite(storyCount) || storyCount < 1) return THREE_BOARD_BUILDING;
+  return storyCount === 1
+    ? 'Preparing 1 component preview…'
+    : `Preparing ${storyCount} component previews…`;
+}
+
+export function ViewportSurfaceStatus({
+  testId,
+  children,
+}: {
+  readonly testId: string;
+  readonly children: ReactNode;
+}) {
+  return (
+    <div
+      data-testid={testId}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        padding: 16,
+        fontSize: 12,
+        color: themeVars.content.muted,
+        pointerEvents: 'none',
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/components/workspace-history.ts

@@ -0,0 +1,32 @@
+/**
+ * Workspace history bridge (W3) — the session `HistoryService` handed to
+ * workspace-document content modules (`build-documents.tsx`) WITHOUT them
+ * importing `EditorContext`.
+ *
+ * Why not `useOptionalHistoryService()`: `EditorContext`'s import graph
+ * pulls the whole editor boot (initial-scene → engine renderer stack), which
+ * document-content modules must not drag into their own graph, and the
+ * headless jsdom tests that mount document content rely on the light graph.
+ * `DefaultEditorLayout` (which already lives on the heavy side) sets the
+ * live service here; content reads it at commit time. Null (e.g. in tests,
+ * or before the layout mounts) degrades to the raw POST/save write paths —
+ * the same degrade the old prop-less mounts had.
+ */
+
+import type { HistoryService } from '../history/history-service';
+
+let _history: HistoryService | null = null;
+
+/** Set (or clear) the live session history service. Returns a cleanup that
+ *  clears it only if it is still this service. */
+export function setWorkspaceHistoryService(history: HistoryService | null): () => void {
+  _history = history;
+  return () => {
+    if (_history === history) _history = null;
+  };
+}
+
+/** The live session history service, or `null`. */
+export function workspaceHistoryService(): HistoryService | null {
+  return _history;
+}

package/src/components/workspace-static-panel-registry.tsx

@@ -0,0 +1,152 @@
+import type { EditorRegionName, WorkspacePanelGlyphName } from '@volter/editor-sdk/widgets';
+import { Button } from '@volter/editor-sdk/widgets';
+import { Component, type ComponentType, type ErrorInfo, type ReactNode } from 'react';
+import { editorConsole } from '../editor-console';
+import { WORKSPACE_STATIC_PANELS, type WorkspaceStaticPanelKind } from '../workspace-static-panels';
+import { AssetBrowser, type AssetBrowserServices } from './AssetBrowser';
+import { ChromeSlot } from './ChromeSlot';
+import { GameHierarchy } from './GameHierarchy';
+import { Inspector } from './Inspector';
+
+export interface WorkspaceStaticPanelDependencies {
+  readonly assets?: AssetBrowserServices;
+}
+
+interface WorkspaceStaticPanelContentProps {
+  readonly dependencies?: WorkspaceStaticPanelDependencies | undefined;
+}
+
+export interface WorkspaceStaticPanelRegistration {
+  readonly kind: WorkspaceStaticPanelKind;
+  readonly title: string;
+  readonly hotkeyScope: (typeof WORKSPACE_STATIC_PANELS)[number]['hotkeyScope'];
+  readonly selectableText: boolean;
+  /** The EDITOR-AREA fill this panel claims (`workspace-static-panels.ts`);
+   *  absent means the one fill every dock group shares. */
+  readonly region?: EditorRegionName;
+  /** The glyph this panel shows in Blender's editor-type well
+   *  (`workspace-static-panels.ts`; the well is `groupTabs: 'well'`). */
+  readonly icon?: WorkspacePanelGlyphName;
+  readonly Content: ComponentType<WorkspaceStaticPanelContentProps>;
+}
+
+const CONTENT_BY_KIND: Readonly<
+  Record<WorkspaceStaticPanelKind, ComponentType<WorkspaceStaticPanelContentProps>>
+> = {
+  // The CONVERSATIONS panel's place is the host's; its surface is not. The
+  // agent-harness conversation UI is `@vgai/agents`, filling the `panel:agent`
+  // chrome slot (`chrome-slot-registry.ts`); a build without that package
+  // shows an empty panel rather than an imported one.
+  agent: () => <ChromeSlot slot="panel:agent" />,
+  // The PROJECT WORK panel's place is the host's; its surface is not. A
+  // `ztrack` board of the worktree's open work, with "work on this with an
+  // agent" beside it, is `@vgai/agents` — the same reasoning as the two rows
+  // around it, and the same door. Its `services` prop came with it: nothing in
+  // the product ever supplied one (only a design-system story did), so the
+  // panel's own defaults are what ran.
+  'project-work': () => <ChromeSlot slot="panel:project-work" />,
+  hierarchy: GameHierarchy,
+  assets: ({ dependencies }) => <AssetBrowser services={dependencies?.assets} />,
+  // The LIBRARY panel's place is the host's; its surface is not. Browsing an
+  // external provider's catalog is `@vgai/asset-library`, filling the
+  // `panel:asset-library` chrome slot (`chrome-slot-registry.ts`) exactly as
+  // the `agent` row above does; a build without that package — the
+  // open-source core+Blender cut — shows an empty panel rather than an
+  // imported managed-service client.
+  'asset-library': () => <ChromeSlot slot="panel:asset-library" />,
+  inspector: Inspector,
+};
+
+/**
+ * A crash inside ONE static panel stays inside that panel.
+ *
+ * Without this, a panel's render throw climbed to `EditorRuntimeBoundary`
+ * (AppRoot), which replaces the WHOLE editor with the startup-error screen:
+ * the dock, the viewport and the game container all unmount, so play refuses
+ * ("the game container is not mounted"), and React's recovery re-creates the
+ * crashed subtree from scratch — a panel that crashes deterministically then
+ * crashes again on every recovery. The blind modeling bench measured the
+ * whole chain from a single Agents-panel throw (a duplicate `session-1` row
+ * key from the harness UI, then "Maximum update depth exceeded"): 53
+ * recoveries, the main thread pegged, the WebSocket dropped with 1006, the
+ * tab's heartbeat silent for 30 s, the tab declared departed, and every
+ * `vgai screenshot` refused with "No tab has been present" until the agent
+ * ran `vgai edit` again — in four of five sessions.
+ *
+ * The boundary reports the throw ONCE to the editor console (so `vgai
+ * console` carries it and its component stack), renders a small notice in the
+ * panel's own space, and remounts the panel ONLY when the user clicks Retry —
+ * never automatically, because an automatic remount of a deterministic crash
+ * is the loop above.
+ */
+class StaticPanelCrashBoundary extends Component<
+  { readonly title: string; readonly children: ReactNode },
+  { readonly error: Error | null }
+> {
+  override state: { readonly error: Error | null } = { error: null };
+
+  static getDerivedStateFromError(error: Error): { readonly error: Error } {
+    return { error };
+  }
+
+  override componentDidCatch(error: Error, info: ErrorInfo): void {
+    editorConsole.error(
+      `The ${this.props.title} panel crashed and was taken down alone (the rest of the editor ` +
+        `stays up; Retry in the panel remounts it): ${error.message}\n${info.componentStack ?? ''}`,
+      'editor',
+    );
+  }
+
+  override render(): ReactNode {
+    if (!this.state.error) return this.props.children;
+    return (
+      <div
+        role="alert"
+        data-testid="static-panel-crashed"
+        style={{ padding: 12, display: 'grid', gap: 8, alignContent: 'start' }}
+      >
+        <strong>{this.props.title} crashed.</strong>
+        <span style={{ opacity: 0.8, wordBreak: 'break-word' }}>{this.state.error.message}</span>
+        <div>
+          <Button
+            type="button"
+            variant="outline"
+            size="compact"
+            onClick={() => this.setState({ error: null })}
+          >
+            Retry
+          </Button>
+        </div>
+      </div>
+    );
+  }
+}
+
+/** Canonical realization of the static-panel inventory. Every host — the
+ * frame, a bounded production host, a story fixture — consumes this same
+ * registry; there is no second switch or story-only component map to drift. */
+export const WORKSPACE_STATIC_PANEL_REGISTRY: readonly WorkspaceStaticPanelRegistration[] =
+  WORKSPACE_STATIC_PANELS.map((panel) => {
+    const Inner = CONTENT_BY_KIND[panel.kind];
+    const Content: ComponentType<WorkspaceStaticPanelContentProps> = (props) => (
+      <StaticPanelCrashBoundary title={panel.title}>
+        <Inner {...props} />
+      </StaticPanelCrashBoundary>
+    );
+    Content.displayName = `StaticPanel(${panel.kind})`;
+    return { ...panel, Content };
+  });
+
+export function workspaceStaticPanelRegistration(
+  kind: WorkspaceStaticPanelKind,
+): WorkspaceStaticPanelRegistration {
+  return WORKSPACE_STATIC_PANEL_REGISTRY.find((panel) => panel.kind === kind)!;
+}
+
+export function WorkspaceStaticPanelSurface({
+  kind,
+  dependencies,
+}: WorkspaceStaticPanelContentProps & { readonly kind: WorkspaceStaticPanelKind }) {
+  const { Content } = workspaceStaticPanelRegistration(kind);
+  return <Content dependencies={dependencies} />;
+}