@volter/editor-core 0.5.57

package/src/components/core-utilities.tsx

@@ -0,0 +1,90 @@
+/**
+ * The editor's built-in DRAWER utilities, registered through the same
+ * W0 workspace-utility registry every other utility uses, so the utility
+ * region is registry-driven end to end:
+ *
+ *  - **Console** (B3): always available; its error/warn count becomes the
+ *    registry `badge()` in the open tab, plus the three standard level counts
+ *    in the status line while the drawer is hidden.
+ *    Ordinary log traffic never auto-opens the region; only actionable
+ *    failures reveal it automatically (today: a world that failed to mount —
+ *    `workspace-utility-commands.ts`).
+ * Animation and Behavior are deliberately absent: each is an authored center
+ * document (animation inside its owning Asset Lab; XState as an inspect-only
+ * Behavior document), not a global debugger drawer instrument.
+ * The Profiler bench and State Watch are deliberately absent: both moved to
+ * `@vgai/game` as the `profiler.utility` / `state-watch.utility`
+ * contributions (WORKBENCH.md §The invariants — the host imports no package).
+ * GENERATIONS is absent for the same reason: the paid-provider lane's gallery
+ * is `@vgai/game`'s `generation.service.ts`, which registers the tab (badge and
+ * all) through this same registry.
+ * *
+ * PROBLEMS (§4.1 mock's `Problems` tab) is deliberately NOT registered —
+ * the W4 decision, recorded in the inventory: no truthful problem SOURCE
+ * exists today (there is no in-editor typecheck surface; scene-validation
+ * and mount failures already surface as console errors plus their own
+ * status-bar items), and
+ * §4.3's spirit forbids fabricating a surface with nothing real to feed it.
+ * The status bar's console counters (`status-contributions.tsx`) read the
+ * same real source — the truthful signal that does exist. A real Problems
+ * utility lands when a real diagnostics source does.
+ *
+ * Idempotent-ensure idiom mirrors `build-documents.tsx`'s
+ * `ensureBuildContributionsRegistered`.
+ */
+
+import { editorConsole } from '../editor-console';
+import { createHmrRegistrationGroup } from '../hmr-registration-group';
+import { CORE_WORKSPACE_UTILITIES } from '../workspace-core-utilities';
+import {
+  registerWorkspaceUtility,
+  type WorkspaceUtilityBadge,
+} from '../workspace-utility-registry';
+import { ConsolePanel } from './ConsolePanel';
+import { LightExplorerPanel } from './LightExplorerPanel';
+
+const registrationGroup = createHmrRegistrationGroup(import.meta.hot, 'core-utilities');
+
+/** The Console tab's attention badge: error count (error severity) else
+ *  warn count (warn severity) else none. Exported for tests. */
+export function consoleUtilityBadge(): WorkspaceUtilityBadge | null {
+  const { error, warn } = editorConsole.counts;
+  if (error > 0) return { count: error + warn, severity: 'error' };
+  if (warn > 0) return { count: warn, severity: 'warn' };
+  return null;
+}
+
+/** Idempotent one-time registration of the built-in workspace utilities. */
+export function ensureCoreUtilitiesRegistered(): void {
+  registrationGroup.ensure((track) => {
+    track(
+      registerWorkspaceUtility({
+        ...CORE_WORKSPACE_UTILITIES.console,
+        order: -100, // first utility tab, matching the §4.1 mock's tab order
+        Content: ConsolePanel,
+        badge: consoleUtilityBadge,
+        subscribeBadge: editorConsole.subscribe,
+        badgeSnapshot: editorConsole.getSnapshot,
+        visibleByDefault: false,
+        closeable: true,
+      }),
+    );
+    track(
+      // Scene-wide light inventory over the active authoring adapter's real
+      // hierarchy + inspector fields. Closed by default and opened from the
+      // viewport display toolbar or Window menu; no parallel light registry.
+      registerWorkspaceUtility({
+        ...CORE_WORKSPACE_UTILITIES.lightExplorer,
+        order: 21,
+        Content: LightExplorerPanel,
+        visibleByDefault: false,
+        closeable: true,
+      }),
+    );
+  });
+}
+
+/** Test-only: allow re-registration after a registry reset. */
+export function __resetCoreUtilitiesForTest(): void {
+  registrationGroup.reset();
+}

package/src/components/editor-notifications.css

@@ -0,0 +1,40 @@
+/* The notification stack: bottom right, clear of the status bar, newest at
+   the bottom. A card is the banner's paint with VS Code's two-row layout —
+   the message across the full width, the actions on their own row beneath,
+   right-aligned — and an OPAQUE surface, because it sits over whatever is
+   there (measured: the conversation composer). */
+.vgai-notifications {
+  position: fixed;
+  right: var(--vgai-space-4);
+  bottom: calc(var(--vgai-status-bar-height, 28px) + var(--vgai-space-4));
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--vgai-space-2);
+  width: min(420px, calc(100vw - 2 * var(--vgai-space-4)));
+  z-index: var(--vgai-z-toast, 1100);
+  pointer-events: none;
+}
+.vgai-notifications .vgai-notification {
+  width: 100%;
+  flex-wrap: wrap;
+  pointer-events: auto;
+  background-color: var(--vgai-surface-raised);
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
+  box-shadow: var(--vgai-shadow-lg, 0 8px 24px rgba(0, 0, 0, 0.35));
+}
+.vgai-notifications .vgai-notification .vgai-banner-content {
+  flex: 1 1 0;
+  min-width: 0;
+}
+.vgai-notifications .vgai-notification .vgai-banner-actions {
+  flex: 1 1 100%;
+  justify-content: flex-end;
+  margin-top: var(--vgai-space-2);
+}
+.vgai-notification-detail {
+  display: block;
+  margin-top: var(--vgai-space-1);
+  color: var(--vgai-content-muted);
+}

package/src/components/engine-workspace.css

@@ -0,0 +1,274 @@
+.vgai-engine-workspace {
+  display: grid;
+  grid-template-columns: 210px minmax(380px, 1fr) 240px;
+  min-width: 0;
+  min-height: 0;
+  height: 100%;
+  background: var(--vgai-surface-inset);
+  color: var(--vgai-content-primary);
+}
+
+.vgai-engine-workspace > * {
+  min-width: 0;
+  min-height: 0;
+}
+
+.vgai-engine-workspace[data-testid="behavior-utility"] > .vgai-engine-graph {
+  grid-column: 2 / 4;
+}
+
+.vgai-engine-browser,
+.vgai-engine-details {
+  overflow: auto;
+  background: var(--vgai-surface-panel);
+}
+
+.vgai-engine-browser {
+  border-right: 1px solid var(--vgai-boundary-default);
+}
+
+.vgai-engine-details {
+  border-left: 1px solid var(--vgai-boundary-default);
+}
+
+.vgai-engine-pane-heading {
+  height: 25px;
+  padding: 0 var(--vgai-space-4);
+  display: flex;
+  align-items: center;
+  border-bottom: 1px solid var(--vgai-boundary-default);
+  background: var(--vgai-surface-chrome);
+  color: var(--vgai-content-dim);
+  font-size: var(--vgai-font-sm);
+  font-weight: 700;
+  letter-spacing: 0.45px;
+  text-transform: uppercase;
+}
+
+.vgai-engine-browser-row {
+  width: 100%;
+  min-height: 31px;
+  padding: var(--vgai-space-2) var(--vgai-space-4);
+  border-radius: 0;
+  display: grid;
+  justify-items: start;
+  border-bottom: 1px solid var(--vgai-boundary-default);
+}
+
+.vgai-engine-browser-row > span:first-child {
+  color: var(--vgai-content-primary);
+  font-size: var(--vgai-font-base);
+}
+
+.vgai-engine-browser-row > span:last-child {
+  color: var(--vgai-content-dim);
+  font-size: var(--vgai-font-xs);
+  font-family: var(--vgai-font-mono);
+}
+
+.vgai-engine-browser-row[data-selected="true"] {
+  background: var(--vgai-selection-bg);
+  box-shadow: inset 2px 0 var(--vgai-accent);
+}
+
+.vgai-engine-property-row,
+.vgai-engine-empty-row {
+  min-height: 25px;
+  padding: 5px 8px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--vgai-space-4);
+  border-bottom: 1px solid var(--vgai-boundary-default);
+  font-size: var(--vgai-font-xs);
+}
+
+.vgai-engine-property-row > span:last-child {
+  color: var(--vgai-content-muted);
+  font-family: var(--vgai-font-mono);
+}
+
+.vgai-engine-empty-row {
+  color: var(--vgai-content-dim);
+  font-style: italic;
+}
+
+.vgai-engine-graph {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  background-color: var(--vgai-surface-inset);
+  background-image: radial-gradient(var(--vgai-boundary-default) 0.7px, transparent 0.7px);
+  background-size: 16px 16px;
+}
+
+.vgai-engine-graph-toolbar {
+  height: 29px;
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  gap: var(--vgai-space-6);
+  padding: 0 9px;
+  border-bottom: 1px solid var(--vgai-boundary-default);
+  background: var(--vgai-surface-panel);
+  font-size: var(--vgai-font-sm);
+}
+
+.vgai-engine-graph-toolbar > span:nth-child(2) {
+  color: var(--vgai-content-dim);
+}
+
+.vgai-runtime-indicator {
+  margin-left: auto;
+  color: var(--vgai-accent);
+  font-size: var(--vgai-font-xs);
+  font-weight: 700;
+}
+
+.vgai-runtime-indicator[data-live="true"] {
+  color: var(--vgai-success);
+}
+
+.vgai-engine-details dl {
+  display: grid;
+  grid-template-columns: 70px minmax(0, 1fr);
+  margin: 0;
+  font-size: var(--vgai-font-sm);
+}
+
+.vgai-engine-details dt,
+.vgai-engine-details dd {
+  margin: 0;
+  min-height: 25px;
+  padding: var(--vgai-space-3) var(--vgai-space-4);
+  border-bottom: 1px solid var(--vgai-boundary-default);
+}
+
+.vgai-engine-details dt {
+  color: var(--vgai-content-dim);
+}
+
+.vgai-engine-details dd {
+  overflow: hidden;
+  color: var(--vgai-content-primary);
+  font-family: var(--vgai-font-mono);
+  text-overflow: ellipsis;
+}
+
+.vgai-mixer-canvas {
+  overflow: auto;
+  padding: 14px;
+}
+
+.vgai-mixer-action-table,
+.vgai-mixer-transition {
+  border: 1px solid var(--vgai-boundary-default);
+  background: var(--vgai-surface-panel);
+}
+
+.vgai-mixer-transition {
+  margin-bottom: var(--vgai-space-6);
+  padding: 9px;
+}
+
+.vgai-mixer-transition > div,
+.vgai-mixer-transition > small {
+  display: flex;
+  justify-content: space-between;
+  gap: var(--vgai-space-5);
+}
+
+.vgai-mixer-transition > i {
+  display: block;
+  height: 6px;
+  margin: 7px 0;
+  background: var(--vgai-boundary-default);
+}
+
+.vgai-mixer-transition > i > span {
+  display: block;
+  height: 100%;
+  background: var(--vgai-accent);
+}
+
+.vgai-mixer-transition > small {
+  color: var(--vgai-content-muted);
+  font-family: var(--vgai-font-mono);
+}
+
+.vgai-mixer-transition-history {
+  display: grid;
+  gap: var(--vgai-space-1);
+  padding: var(--vgai-space-3) var(--vgai-space-4);
+  border-bottom: 1px solid var(--vgai-boundary-default);
+  font-size: var(--vgai-font-xs);
+}
+
+.vgai-mixer-transition-history > span,
+.vgai-mixer-transition-history > small {
+  color: var(--vgai-content-muted);
+}
+
+.vgai-mixer-transition-history > b {
+  overflow: hidden;
+  font-family: var(--vgai-font-mono);
+  font-weight: 500;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.vgai-mixer-table-head,
+.vgai-mixer-action-row {
+  display: grid;
+  grid-template-columns: minmax(130px, 1fr) minmax(120px, 1fr) 64px 64px;
+}
+
+.vgai-mixer-table-head {
+  color: var(--vgai-content-dim);
+  background: var(--vgai-surface-chrome);
+  font-size: var(--vgai-font-xs);
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.vgai-mixer-table-head span,
+.vgai-mixer-action-row > span {
+  min-width: 0;
+  padding: var(--vgai-space-3) var(--vgai-space-4);
+  border-right: 1px solid var(--vgai-boundary-default);
+  border-bottom: 1px solid var(--vgai-boundary-default);
+}
+
+.vgai-mixer-action-row {
+  font-size: var(--vgai-font-sm);
+  font-family: var(--vgai-font-mono);
+}
+
+.vgai-mixer-weight {
+  position: relative;
+  display: flex;
+  align-items: center;
+  background: var(--vgai-surface-inset);
+}
+
+.vgai-mixer-weight i {
+  position: absolute;
+  inset: 4px auto 4px 4px;
+  background: color-mix(in srgb, var(--vgai-success) 40%, transparent);
+}
+
+.vgai-mixer-weight b {
+  position: relative;
+  margin-left: auto;
+  font-weight: 500;
+}
+
+@media (max-width: 950px) {
+  .vgai-engine-workspace {
+    grid-template-columns: 170px minmax(320px, 1fr);
+  }
+
+  .vgai-engine-details {
+    display: none;
+  }
+}

package/src/components/inspector-preview-section.tsx

@@ -0,0 +1,238 @@
+/**
+ * The PREVIEW section's body — a live square view of whatever the subject is,
+ * with the subject's `preview`-placed verbs sitting in the box over it.
+ *
+ * It lives in its own light module for one reason: `inspection/compose.ts`
+ * builds the preview section, and the preview drags the whole render stack
+ * (three.quarks, realism-effects) behind it. The heavy component stays behind
+ * `lazy()` here, so a headless composer — every unit test of the model, and
+ * `editor.inspect`, which never renders — pays nothing for it.
+ *
+ * `render` fills its host at any size, which is what lets the section body and
+ * the minimized card's round thumb be the SAME function off the SAME subject
+ * (`components/CompactInspectorCard.tsx`) rather than two derivations of what
+ * the thing looks like. What differs between those hosts is CHROME, not the
+ * picture — see {@link InspectionPreviewMode}.
+ */
+
+import { Button } from '@volter/editor-sdk/widgets';
+import { lazy, Suspense } from 'react';
+import type * as THREE from 'three';
+import type { ContentEntry, ContentEntrySource } from '../content-entry-source-registry';
+import type { InspectionAction, InspectionPreviewMode } from '../inspection/model';
+import { useAfterPaint } from './use-after-paint';
+
+const InspectorObjectPreview = lazy(() =>
+  import('./InspectorObjectPreview').then((m) => ({ default: m.InspectorObjectPreview })),
+);
+const InspectorCanvasPreview = lazy(() =>
+  import('./InspectorCanvasPreview').then((m) => ({ default: m.InspectorCanvasPreview })),
+);
+
+export function InspectorPreviewBody({
+  object,
+  displayName,
+  previewKey,
+  actions,
+  mode = 'section',
+}: {
+  /** The live object to preview. The composer only builds a preview section
+   *  when it HAS one, so this is never a lookup that can come up empty — the
+   *  honest alternative to a fabricated render is no section at all. */
+  readonly object: THREE.Object3D;
+  readonly displayName: string;
+  /** Stable identity for the isolated preview document (the subject's node
+   *  id) — remounts when the subject changes, not on every compose. */
+  readonly previewKey: string;
+  readonly actions: readonly InspectionAction[];
+  /** Which host this is rendering into. Default `section` — the full box. */
+  readonly mode?: InspectionPreviewMode;
+}) {
+  // A thumbnail host is a small clipped shape that owns its own single press,
+  // so the body gives it the PICTURE and nothing else: it fills the host
+  // exactly, and the verbs stay in the section, which is where they are
+  // reachable and readable.
+  const thumbnail = mode === 'thumbnail';
+  // The picture arrives a frame after the box does: mounting it is scene and GL
+  // work, and doing it in the selection's own commit is what used to make the
+  // whole inspector wait on it (`components/use-after-paint.ts`).
+  const showPicture = useAfterPaint(previewKey);
+  return (
+    <div
+      data-testid={thumbnail ? 'inspection-preview-thumbnail' : 'inspection-preview'}
+      style={
+        thumbnail
+          ? { position: 'absolute', inset: 0, overflow: 'hidden' }
+          : {
+              position: 'relative',
+              width: 'calc(100% - 24px)',
+              aspectRatio: '1 / 1',
+              flexShrink: 0,
+              margin: 12,
+              overflow: 'hidden',
+              border: '1px solid var(--vgai-structural-divider)',
+              borderRadius: 'var(--dv-group-border-radius, 8px)',
+            }
+      }
+    >
+      {showPicture && (
+        <Suspense fallback={null}>
+          <InspectorObjectPreview
+            previewKey={previewKey}
+            object={object}
+            displayName={displayName}
+            fill
+          />
+        </Suspense>
+      )}
+      {!thumbnail &&
+        actions.map((action) => (
+          <Button
+            key={action.id}
+            data-testid={action.id}
+            size="compact"
+            disabled={action.disabled}
+            title={action.title}
+            onClick={action.run}
+            style={{ position: 'absolute', right: 8, bottom: 8 }}
+          >
+            {action.label}
+          </Button>
+        ))}
+    </div>
+  );
+}
+
+/** The same Preview-section chrome around a COMPONENT's own picture, painted by
+ * whichever content source admits it (`content-entry-source-registry.ts`).
+ * Canvas entities are Pixi display objects rather than Object3Ds, so the
+ * picture Content already shows is the honest preview authority here too; the
+ * shell never substitutes the Transform icon for a picture, and never knows
+ * what the picture IS. */
+export function InspectorComponentPreviewBody({
+  source,
+  entry,
+  previewKey,
+  actions,
+  mode = 'section',
+}: {
+  readonly source: ContentEntrySource;
+  readonly entry: ContentEntry;
+  readonly previewKey: string;
+  readonly actions: readonly InspectionAction[];
+  readonly mode?: InspectionPreviewMode;
+}) {
+  const thumbnail = mode === 'thumbnail';
+  const showPicture = useAfterPaint(previewKey);
+  return (
+    <div
+      data-testid={thumbnail ? 'inspection-preview-thumbnail' : 'inspection-preview'}
+      style={
+        thumbnail
+          ? { position: 'absolute', inset: 0, overflow: 'hidden' }
+          : {
+              position: 'relative',
+              width: 'calc(100% - 24px)',
+              aspectRatio: '1 / 1',
+              flexShrink: 0,
+              margin: 12,
+              overflow: 'hidden',
+              border: '1px solid var(--vgai-structural-divider)',
+              borderRadius: 'var(--dv-group-border-radius, 8px)',
+            }
+      }
+    >
+      {showPicture && (
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            overflow: 'hidden',
+            background: 'var(--vgai-bg-inset)',
+          }}
+        >
+          <source.Thumbnail
+            entry={entry}
+            previewRevision={0}
+            width={thumbnail ? 96 : 256}
+            height={thumbnail ? 96 : 256}
+          />
+        </div>
+      )}
+      {!thumbnail &&
+        actions.map((action) => (
+          <Button
+            key={action.id}
+            data-testid={action.id}
+            size="compact"
+            disabled={action.disabled}
+            title={action.title}
+            onClick={action.run}
+            style={{ position: 'absolute', right: 8, bottom: 8 }}
+          >
+            {action.label}
+          </Button>
+        ))}
+    </div>
+  );
+}
+
+/** The selected live Canvas subtree in the same Preview-section shell used by
+ * Three and by story fallbacks. */
+export function InspectorCanvasPreviewBody({
+  capture,
+  previewKey,
+  actions,
+  mode = 'section',
+}: {
+  readonly capture: (size: number) => Promise<string | null>;
+  readonly previewKey: string;
+  readonly actions: readonly InspectionAction[];
+  readonly mode?: InspectionPreviewMode;
+}) {
+  const thumbnail = mode === 'thumbnail';
+  const showPicture = useAfterPaint(previewKey);
+  return (
+    <div
+      data-testid={thumbnail ? 'inspection-preview-thumbnail' : 'inspection-preview'}
+      style={
+        thumbnail
+          ? { position: 'absolute', inset: 0, overflow: 'hidden' }
+          : {
+              position: 'relative',
+              width: 'calc(100% - 24px)',
+              aspectRatio: '1 / 1',
+              flexShrink: 0,
+              margin: 12,
+              overflow: 'hidden',
+              border: '1px solid var(--vgai-structural-divider)',
+              borderRadius: 'var(--dv-group-border-radius, 8px)',
+            }
+      }
+    >
+      {showPicture && (
+        <Suspense fallback={null}>
+          <InspectorCanvasPreview
+            capture={capture}
+            previewKey={previewKey}
+            size={thumbnail ? 96 : 256}
+          />
+        </Suspense>
+      )}
+      {!thumbnail &&
+        actions.map((action) => (
+          <Button
+            key={action.id}
+            data-testid={action.id}
+            size="compact"
+            disabled={action.disabled}
+            title={action.title}
+            onClick={action.run}
+            style={{ position: 'absolute', right: 8, bottom: 8 }}
+          >
+            {action.label}
+          </Button>
+        ))}
+    </div>
+  );
+}

package/src/components/inspector-property-grouping.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure grouping logic behind the generic adapter-driven inspector's
+ * `PropertyDescriptor.group?` rendering (T3.4 slice 2). Extracted out of
+ * `Inspector.tsx`'s (formerly `IngestPanels.tsx`'s `GenericInspector`)
+ * inspector shell component (a react component with no jsdom/testing-library
+ * in this repo — `vitest.config.ts` runs `environment: 'node'`) so this can
+ * be unit-tested directly as data-in/data-out, matching the repo's existing
+ * "test the pure logic headlessly" convention.
+ *
+ * Ungrouped fields keep their original relative order (byte-stable with the
+ * pre-`group` flat-list rendering); named groups are returned in FIRST-SEEN
+ * order, each carrying a slugified, testid-safe `groupId` (lowercase,
+ * non-alphanumeric runs collapsed to a single `-`, no leading/trailing `-`).
+ */
+
+import type { PropertyDescriptor } from '@volter/editor-project/adapter';
+
+export interface PropertyGroup {
+  name: string;
+  /** Slugified group name — the suffix of the rendered section's
+   *  `data-testid="ingest-group-<groupId>"`. */
+  groupId: string;
+  properties: PropertyDescriptor[];
+}
+
+export interface GroupedProperties {
+  ungrouped: PropertyDescriptor[];
+  groups: PropertyGroup[];
+}
+
+/** Lowercase, non-alphanumeric runs -> single `-`, no leading/trailing `-`. */
+export function slugifyGroupName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+export function groupProperties(props: readonly PropertyDescriptor[]): GroupedProperties {
+  const ungrouped: PropertyDescriptor[] = [];
+  const order: string[] = [];
+  const byName = new Map<string, PropertyDescriptor[]>();
+
+  for (const p of props) {
+    if (p.group) {
+      if (!byName.has(p.group)) {
+        byName.set(p.group, []);
+        order.push(p.group);
+      }
+      byName.get(p.group)!.push(p);
+    } else {
+      ungrouped.push(p);
+    }
+  }
+
+  return {
+    ungrouped,
+    groups: order.map((name) => ({
+      name,
+      groupId: slugifyGroupName(name),
+      properties: byName.get(name)!,
+    })),
+  };
+}