@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/components/tool-documents.tsx

@@ -0,0 +1,110 @@
+import { themeVars } from '../design-system';
+/**
+ * Project-tool DOCUMENTS (W3, docs/EDITOR-WORKSPACE-SHELL-TODO.md §7.2/§9 W3
+ * — inventory rows B12/T2-behavior/T3): a `placement: 'document'` project
+ * tool (including every legacy `'dock'` tool — the W0 alias rule,
+ * docs/workspace-shell/W0-INVENTORY.md §2) opens as a CENTER workspace
+ * document (kind `'tool'`, title = the tool's own declared title per §8),
+ * hosted in the same error-boundaried `ToolHost` the bottom ⚙ tabs used.
+ * `placement: 'utility'` tools stay in the bottom area — registered in the
+ * workspace-utility registry by the tool-loader itself (see
+ * `tool-loader.ts`'s publish step). The ⚙ dock-tab row is gone.
+ *
+ * Open gesture: one `Open Tool: <title>` command-palette action per
+ * discovered document tool (`buildToolActions`) — the fixed-layout menu the
+ * ⚙ row used to be, now a searchable command. The template's `Tuning`
+ * example tool is the live proof.
+ *
+ * HMR/lifecycle: the document's CONTENT reads the LIVE tool store — an HMR
+ * reload bumps the tool's `version`, which re-keys the mount (fresh
+ * component + cleared error boundary, the same physics the dock tabs had);
+ * a deleted tool file leaves an honest "no longer available" message in any
+ * open document (discovery is the folder scan, D3).
+ */
+
+import { useSyncExternalStore } from 'react';
+import type { EditorAction } from '../action-registry';
+import { getDocumentTools, getGlobalTools, subscribeGlobalTools } from '../tool-loader';
+import {
+  openWorkspaceDocument,
+  type WorkspaceDocumentContentProps,
+} from '../workspace-document-registry';
+import { ToolHost } from './ToolHost';
+
+/** The narrow store surface tool documents need (T6.3 tab hand-off). */
+export interface ToolDocumentStore {
+  setActiveViewportTab(tab: 'scene' | 'game'): void;
+}
+
+/** Stable §7.1 identity for one project tool's document. */
+export function toolDocumentId(toolId: string): string {
+  return `tool:${toolId}`;
+}
+
+/**
+ * Open (or activate) the center document for one document-placement project
+ * tool. Returns `false` (opens nothing) when no discovered document tool
+ * carries that id — no fabricated documents for deleted/renamed tools.
+ */
+export function openToolDocument(store: ToolDocumentStore, toolId: string): boolean {
+  const tool = getDocumentTools().find((t) => t.id === toolId);
+  if (!tool) return false;
+  openWorkspaceDocument({
+    id: toolDocumentId(toolId),
+    // §8: the tool's own declared title (`Tuning`), never a tech bucket.
+    title: tool.title,
+    kind: 'tool',
+    provenance: { sourcePath: tool.file },
+    Content: ToolDocumentContent,
+    closeable: true,
+    onActivate: () => store.setActiveViewportTab('scene'),
+  });
+  return true;
+}
+
+/** `Open Tool: <title>` palette actions — one per discovered document tool
+ *  (the B12 discovery gesture). */
+export function buildToolActions(store: ToolDocumentStore): EditorAction[] {
+  return getDocumentTools().map((t) => ({
+    id: `tool-doc:${t.id}`,
+    label: `Open Tool: ${t.title}`,
+    category: 'action' as const,
+    execute: () => void openToolDocument(store, t.id),
+  }));
+}
+
+/** Content host: resolves the LIVE tool by id on every render (HMR re-key,
+ *  honest deleted-tool state). */
+export function ToolDocumentContent({ documentId }: WorkspaceDocumentContentProps) {
+  useSyncExternalStore(subscribeGlobalTools, getGlobalTools);
+  const toolId = documentId.startsWith('tool:') ? documentId.slice('tool:'.length) : documentId;
+  const tool = getDocumentTools().find((t) => t.id === toolId);
+  if (!tool) {
+    return (
+      <div
+        style={{ padding: 12, fontSize: 12, color: themeVars.content.muted, pointerEvents: 'auto' }}
+      >
+        This tool is no longer available (its `src/tools/` file was deleted or renamed) — close this
+        document.
+      </div>
+    );
+  }
+  return (
+    <div
+      key={`${tool.id}:${tool.version}`}
+      data-testid={`tool-document:${tool.id}`}
+      style={{
+        flex: 1,
+        minHeight: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        pointerEvents: 'auto',
+        // B-11: the editor-provided baseline breathing room every hosted
+        // surface's content root has by convention (carried from the dock).
+        padding: 12,
+      }}
+    >
+      <ToolHost tool={tool} />
+    </div>
+  );
+}

package/src/components/workspace-dock.css

@@ -0,0 +1,293 @@
+.dockview-theme-vgai {
+  --dv-group-view-background-color: var(--vgai-bg-1);
+  --dv-tabs-and-actions-container-background-color: var(--vgai-bg-2);
+  --dv-activegroup-visiblepanel-tab-background-color: transparent;
+  --dv-activegroup-hiddenpanel-tab-background-color: transparent;
+  --dv-inactivegroup-visiblepanel-tab-background-color: transparent;
+  --dv-inactivegroup-hiddenpanel-tab-background-color: transparent;
+  --dv-activegroup-visiblepanel-tab-color: var(--vgai-text-1);
+  --dv-activegroup-hiddenpanel-tab-color: var(--vgai-text-2);
+  --dv-inactivegroup-visiblepanel-tab-color: var(--vgai-text-2);
+  --dv-inactivegroup-hiddenpanel-tab-color: var(--vgai-text-3);
+  --dv-tab-divider-color: var(--vgai-border-1);
+  /* The sash paints the separator so the 1px line is centered inside its
+     larger 4px hit target instead of sitting on one panel edge. */
+  --dv-separator-border: transparent;
+  --dv-paneview-header-border-color: var(--vgai-border-1);
+  --dv-paneview-active-outline-color: var(--vgai-accent);
+  --dv-tabs-and-actions-container-height: var(--vgai-panel-header-height);
+  --dv-tabs-and-actions-container-font-size: var(--vgai-font-md);
+  --dv-tab-font-size: var(--vgai-font-md);
+  --dv-icon-hover-background-color: var(--vgai-bg-3);
+  --dv-drag-over-background-color: var(--vgai-accent-muted);
+  --dv-drag-over-border-color: var(--vgai-accent);
+  --dv-sash-color: transparent;
+  --dv-active-sash-color: transparent;
+  --dv-active-sash-transition-delay: 0s;
+  --dv-active-sash-transition-duration: 0.1s;
+  --dv-floating-border: var(--vgai-stroke-resting) solid var(--vgai-border-2);
+  --dv-floating-box-shadow: var(--vgai-shadow-lg);
+  --dv-floating-titlebar-height: 20px;
+  --dv-border-radius: 0;
+  --dv-tab-border-radius: 0;
+  --dv-tab-margin: 0;
+  --dv-spacing-padding: 0;
+  --dv-scrollbar-background-color: color-mix(in srgb, var(--vgai-content-primary) 28%, transparent);
+  font-family: var(--vgai-font-sans);
+}
+
+.vgai-workspace-dock {
+  position: relative;
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  pointer-events: auto;
+  overflow: hidden;
+  background: var(--vgai-bg-1);
+}
+
+.vgai-workspace-dock > .dockview-theme-vgai {
+  width: 100%;
+  height: 100%;
+}
+
+.vgai-dock-panel,
+.vgai-dock-document,
+.vgai-dock-document-content {
+  min-width: 0;
+  min-height: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.vgai-dock-panel,
+.vgai-dock-document,
+.vgai-dock-document-content {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  background: var(--vgai-bg-1);
+  pointer-events: auto;
+}
+
+.vgai-dock-document-toolbar {
+  flex: 0 0 auto;
+  min-height: var(--vgai-local-toolbar-height);
+  border-bottom: var(--vgai-stroke-resting) solid var(--vgai-border-1);
+  background: var(--vgai-bg-1);
+  pointer-events: auto;
+}
+
+.vgai-dock-empty {
+  padding: var(--vgai-space-6);
+  color: var(--vgai-text-3);
+  background: var(--vgai-bg-1);
+}
+
+.vgai-dock-tab {
+  display: flex;
+  align-items: center;
+  height: 100%;
+  min-width: 0;
+}
+
+.vgai-dock-tab > .dv-default-tab {
+  min-width: 0;
+}
+
+/* Runtime/world surfaces and file-backed resource documents are different
+   navigation families. The adjacent-family selector makes the seam follow
+   the actual Dockview rail when the user moves tabs. */
+.dockview-theme-vgai .dv-tab:has(.vgai-dock-tab[data-document-family="world"])
+  + .dv-tab:has(.vgai-dock-tab[data-document-family="resource"])
+  .vgai-dock-tab {
+  position: relative;
+  margin-left: var(--vgai-space-4);
+}
+
+.dockview-theme-vgai
+  .dv-tab:has(.vgai-dock-tab[data-document-family="world"])
+  + .dv-tab:has(.vgai-dock-tab[data-document-family="resource"])
+  .vgai-dock-tab::before {
+  position: absolute;
+  top: 50%;
+  left: calc(-1 * var(--vgai-space-3));
+  width: var(--vgai-stroke-resting);
+  height: 16px;
+  background: var(--vgai-border-2);
+  content: "";
+  transform: translateY(-50%);
+  pointer-events: none;
+}
+
+.dockview-theme-vgai .dv-tab {
+  padding: 0 10px;
+  border-radius: 0;
+  font-weight: 400;
+  transition:
+    background-color 80ms ease,
+    color 80ms ease;
+}
+
+.dockview-theme-vgai .dv-tabs-and-actions-container {
+  border-bottom: var(--vgai-stroke-resting) solid var(--vgai-border-1);
+}
+
+.dockview-theme-vgai .dv-tab.dv-inactive-tab:hover {
+  color: var(--vgai-text-1);
+  background: var(--vgai-bg-3);
+}
+
+.dockview-theme-vgai .dv-tabs-and-actions-container:not(.dv-single-tab) .dv-tabs-container {
+  gap: 2px;
+  padding: 0 3px;
+}
+
+/* Dockview's default separators make the rail resemble stock library tabs.
+   The editor uses whitespace and one active marker instead. */
+.dockview-theme-vgai .dv-tabs-container.dv-horizontal .dv-tab:not(:first-child)::before {
+  display: none;
+}
+
+/* Dockview intentionally removes all padding in full-width single-tab mode.
+   Keep the full-width hit target, but restore the label inset and make the
+   result read as a panel heading rather than one enormous selected tab. */
+.dockview-theme-vgai .dv-tabs-and-actions-container.dv-single-tab.dv-full-width-single-tab
+  .dv-tabs-container
+  .dv-tab {
+  margin: 0;
+  padding: 0 12px;
+  border-radius: 0;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+}
+
+.vgai-dock-tab-dirty {
+  width: 6px;
+  height: 6px;
+  margin-right: 6px;
+  flex: 0 0 auto;
+  border-radius: 50%;
+  background: var(--vgai-warn);
+}
+
+.vgai-dock-tab-unsaved {
+  gap: 4px;
+  padding: 0 5px 0 8px;
+  color: var(--vgai-text-1);
+  background: var(--vgai-warn-muted);
+}
+
+.vgai-dock-tab-unsaved-label {
+  margin-right: 2px;
+  color: var(--vgai-warn);
+  font-weight: 600;
+}
+
+.vgai-dock-tab-unsaved button {
+  height: 20px;
+  padding: 0 5px;
+  border: var(--vgai-stroke-resting) solid var(--vgai-border-2);
+  border-radius: 3px;
+  color: var(--vgai-text-1);
+  background: var(--vgai-bg-2);
+  font: inherit;
+  cursor: pointer;
+}
+
+.vgai-dock-tab-unsaved button:hover:not(:disabled),
+.vgai-dock-tab-unsaved button:focus-visible {
+  border-color: var(--vgai-accent);
+  color: var(--vgai-content-primary);
+}
+
+.vgai-dock-tab-unsaved button:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+
+.vgai-dock-tab-badge {
+  min-width: 14px;
+  height: 14px;
+  margin-right: 5px;
+  padding: 0 3px;
+  border-radius: 7px;
+  font-size: 9px;
+  line-height: 14px;
+  text-align: center;
+  color: var(--vgai-bg-0);
+  background: var(--vgai-text-2);
+}
+
+.vgai-dock-tab-badge-warn {
+  background: var(--vgai-warn);
+}
+
+.vgai-dock-tab-badge-error {
+  background: var(--vgai-danger);
+}
+
+.dockview-theme-vgai .dv-tabs-container .dv-tab.dv-active-tab {
+  box-shadow: none;
+  font-weight: 500;
+}
+
+.dockview-theme-vgai
+  .dv-tabs-and-actions-container:not(.dv-single-tab)
+  .dv-tabs-container
+  .dv-tab.dv-active-tab::before {
+  position: absolute;
+  right: 10px;
+  bottom: 0;
+  left: 10px;
+  display: block;
+  width: auto;
+  height: var(--vgai-stroke-active);
+  border-radius: 2px 2px 0 0;
+  background: var(--vgai-accent);
+  content: "";
+}
+
+.dockview-theme-vgai .dv-split-view-container.dv-horizontal > .dv-sash-container > .dv-sash {
+  background: linear-gradient(
+    to right,
+    transparent 1.5px,
+    var(--vgai-border-1) 1.5px 2.5px,
+    transparent 2.5px
+  );
+}
+
+.dockview-theme-vgai .dv-split-view-container.dv-vertical > .dv-sash-container > .dv-sash {
+  background: linear-gradient(
+    to bottom,
+    transparent 1.5px,
+    var(--vgai-border-1) 1.5px 2.5px,
+    transparent 2.5px
+  );
+}
+
+.dockview-theme-vgai .dv-split-view-container.dv-horizontal > .dv-sash-container > .dv-sash:hover,
+.dockview-theme-vgai
+  .dv-split-view-container.dv-horizontal
+  > .dv-sash-container
+  > .dv-sash.dv-active {
+  background: linear-gradient(
+    to right,
+    transparent 1px,
+    var(--vgai-accent) 1px 3px,
+    transparent 3px
+  );
+}
+
+.dockview-theme-vgai .dv-split-view-container.dv-vertical > .dv-sash-container > .dv-sash:hover,
+.dockview-theme-vgai
+  .dv-split-view-container.dv-vertical
+  > .dv-sash-container
+  > .dv-sash.dv-active {
+  background: linear-gradient(
+    to bottom,
+    transparent 1px,
+    var(--vgai-accent) 1px 3px,
+    transparent 3px
+  );
+}

package/src/components/workspace-history.ts

@@ -0,0 +1,33 @@
+/**
+ * Workspace history bridge (W3) — the session `HistoryService` handed to
+ * workspace-document content modules (`data-documents.tsx`,
+ * `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 — the old
+ * `DataPanel` took `history` as a PROP for exactly this reason, 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/world-documents.tsx

@@ -0,0 +1,145 @@
+import { themeVars } from '../design-system';
+/**
+ * Edit-time documents for manifest worlds that do not use the editor's
+ * native Three.js scene renderer. Runtime composition belongs to Game;
+ * authoring gives each React/Pixi world its own full-bleed center document.
+ */
+
+import { useEffect, useRef, useSyncExternalStore } from 'react';
+import { getActiveAuthoring } from '../authoring/active-adapter';
+import type { CompositeAuthoringAdapter } from '../authoring/composite-authoring-adapter';
+import {
+  type DesignTimeWorldDescriptor,
+  designTimeWorldDescriptors,
+  mountDesignTimeLayers,
+} from '../authoring/design-time-layers';
+import { resolveViewportToolContext } from '../authoring/viewport-tool-context';
+import type { EditorStore } from '../editor-store';
+import { SCENE_DOCUMENT_ID } from '../workspace-document-ids';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  closeWorkspaceDocument,
+  openWorkspaceDocument,
+  type WorkspaceDocumentContentProps,
+} from '../workspace-document-registry';
+import { registerWorldDocumentRoute } from '../world-document-routing';
+import { ReactCanvasControls } from './ReactCanvasControls';
+import { WorldSelectionOverlay } from './WorldSelectionOverlay';
+
+export function worldDocumentId(worldId: string): string {
+  return `workspace:world:${worldId}`;
+}
+
+function WorldDocumentContent({
+  active,
+  composite,
+  descriptor,
+  store,
+}: WorkspaceDocumentContentProps & {
+  composite: CompositeAuthoringAdapter;
+  descriptor: DesignTimeWorldDescriptor;
+  store: EditorStore;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const disposeMountRef = useRef<(() => void) | null>(null);
+  useSyncExternalStore(store.subscribe, store.getSnapshot);
+
+  // Dockview keeps documents warm. Defer the relatively expensive Pixi/React
+  // mount until the world is first visited, then retain it across tab changes
+  // so hierarchy identity, story selection, and source editing remain stable.
+  useEffect(() => {
+    if (!active || disposeMountRef.current || !containerRef.current) return;
+    disposeMountRef.current = mountDesignTimeLayers(containerRef.current, composite, store, [
+      descriptor,
+    ]);
+  }, [active, composite, descriptor, store]);
+
+  useEffect(
+    () => () => {
+      disposeMountRef.current?.();
+      disposeMountRef.current = null;
+    },
+    [],
+  );
+
+  const selectedContext = resolveViewportToolContext(
+    getActiveAuthoring(store),
+    store.selectedEntityIds,
+  );
+  const context = selectedContext?.worldId === descriptor.worldId ? selectedContext : null;
+
+  return (
+    <div
+      ref={containerRef}
+      data-testid={`world-document:${descriptor.worldId}`}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        overflow: 'hidden',
+        pointerEvents: 'auto',
+        backgroundColor: themeVars.surface.raised,
+        backgroundImage:
+          `linear-gradient(45deg, ${themeVars.surface.chrome} 25%, transparent 25%, transparent 75%, ${themeVars.surface.chrome} 75%), ` +
+          `linear-gradient(45deg, ${themeVars.surface.chrome} 25%, transparent 25%, transparent 75%, ${themeVars.surface.chrome} 75%)`,
+        backgroundPosition: '0 0, 8px 8px',
+        backgroundSize: '16px 16px',
+      }}
+    >
+      <WorldSelectionOverlay />
+      <ReactCanvasControls containerRef={containerRef} context={context} />
+    </div>
+  );
+}
+
+/** Install one pinned document per non-Three manifest world and map every
+ * Three world to the native scene document. Returns the project/rebuild
+ * disposer; it closes only the documents installed by this call. */
+export function installWorldDocuments(
+  store: EditorStore,
+  composite: CompositeAuthoringAdapter,
+): () => void {
+  const previouslyActive = activeWorkspaceDocumentId();
+  const installedIds: string[] = [];
+  const unregisterRoutes: Array<() => void> = [];
+
+  for (const child of composite.childAdapters()) {
+    if (child.role === 'world' && child.kind === 'threejs') {
+      unregisterRoutes.push(registerWorldDocumentRoute(child.worldId, SCENE_DOCUMENT_ID));
+    }
+  }
+
+  for (const descriptor of designTimeWorldDescriptors(composite)) {
+    const id = worldDocumentId(descriptor.worldId);
+    unregisterRoutes.push(registerWorldDocumentRoute(descriptor.worldId, id));
+    installedIds.push(id);
+    const Content = (props: WorkspaceDocumentContentProps) => (
+      <WorldDocumentContent
+        {...props}
+        composite={composite}
+        descriptor={descriptor}
+        store={store}
+      />
+    );
+    openWorkspaceDocument({
+      id,
+      title: descriptor.worldId,
+      kind: 'world',
+      provenance: {
+        rootId: descriptor.worldId,
+        ...(descriptor.path ? { sourcePath: descriptor.path } : {}),
+      },
+      Content,
+      closeable: false,
+      onActivate: () => store.setActiveViewportTab('scene'),
+    });
+  }
+
+  if (previouslyActive) activateWorkspaceDocument(previouslyActive);
+  else activateWorkspaceDocument(SCENE_DOCUMENT_ID);
+
+  return () => {
+    for (const unregister of unregisterRoutes) unregister();
+    for (const id of installedIds) closeWorkspaceDocument(id, { discardDirty: true });
+  };
+}