@volter/editor-core 0.5.57

package/src/components/DefaultEditorLayout.tsx

@@ -0,0 +1,106 @@
+import { lazy, Suspense, use, useEffect, useSyncExternalStore } from 'react';
+import { connectAssetEvents } from '../asset-events';
+import { installAssetSelectionAutoClear } from '../asset-selection';
+import { registerEditorShellHotkeys } from '../editor-hotkeys';
+import {
+  useEditorInit,
+  useEditorStore,
+  useHistoryCommands,
+  useHistoryService,
+} from '../editor-runtime';
+import { installAuxiliaryEvents } from '../workspace-aux-commands';
+import { installUtilityAutoOpen } from '../workspace-utility-commands';
+import { AgentPresentationNotice } from './AgentPresentationNotice';
+import { useCenterDocuments } from './CenterDocuments';
+import { ensureCoreUtilitiesRegistered } from './core-utilities';
+import { installKindDocumentRefresh } from './kind-documents';
+import { ProjectLayout } from './ProjectLayout';
+import { PaletteActionPublisher } from './palette-action-publisher';
+import { ensureCoreStatusContributionsRegistered } from './status-contributions';
+import { installStandingToolDocuments } from './tool-documents';
+import { setWorkspaceHistoryService } from './workspace-history';
+
+// Session discovery remains alive even when every document tab is closed.
+const ProjectAuthoringBootstrap = lazy(async () => {
+  const module = await import('./NonThreeAuthoringBootstrap');
+  return { default: module.ProjectAuthoringBootstrap };
+});
+
+export function DefaultEditorLayout() {
+  const store = useEditorStore();
+  const history = useHistoryService();
+  const historyCommands = useHistoryCommands();
+  use(useEditorInit()); // suspends until project is detected
+
+  // Subscribe to store changes: the reads below are what need it; the version
+  // itself is not read.
+  useSyncExternalStore(store.subscribe, store.getShellSnapshot ?? store.getSnapshot);
+  // W1 — install the authored document plus the warm runtime host (whose Game
+  // tab is rail-visible only while active) and keep registry activation synced
+  // with the store's activeViewportTab (T6.3 gate).
+  useCenterDocuments(store);
+  // W3 (workspace-shell §9/W3) — the shell contributions the new center
+  // documents ride on:
+  //  - the STANDING tool documents (`installStandingToolDocuments`): every
+  //    discovered document contribution the project declares `standing` opens
+  //    as a pinned board beside `3D`/`UI`/`Dev` and stays in step with
+  //    discovery, so a capability added mid-session brings its tab with it and
+  //    a deleted one takes its tab away. The editor owns no per-asset
+  //    documents of its own — a capability's own tool is what puts a board
+  //    here (the `data-tables` Data tab is the worked case);
+  //  - the Build Output utility + build-progress status contribution
+  //    (server mode only — builds spawn npm scripts server-side).
+  // W4 (workspace-shell §9/W4) — status-bar contributions register BEFORE the
+  // build ensure below so the order-0 items sequence save-status first; the
+  // utility auto-open watcher (save/build failure → the right utility) is
+  // per-store. Core utilities register before the host reconciles.
+  useEffect(() => ensureCoreStatusContributionsRegistered(), []);
+  useEffect(() => ensureCoreUtilitiesRegistered(), []);
+  useEffect(() => installUtilityAutoOpen(history), [history]);
+  useEffect(() => installAuxiliaryEvents(), []);
+  useEffect(() => installStandingToolDocuments(store), [store]);
+  useEffect(() => installKindDocumentRefresh(store), [store]);
+  useEffect(() => setWorkspaceHistoryService(history), [history]);
+  // Undo/redo/save/delete live here, not on the world root's stage: a canvas-only
+  // project never mounts that panel, and Ctrl+Z was a silent no-op there.
+  useEffect(() => registerEditorShellHotkeys(store, historyCommands), [store, historyCommands]);
+  // W2 (§5.1) — an ENTITY selection change drops the asset selection, so the
+  // Inspector goes back to being purely entity-contextual (asset-selection.ts).
+  useEffect(() => installAssetSelectionAutoClear(store), [store]);
+
+  // Subscribe to server-sent asset move events (file watcher)
+  useEffect(() => {
+    // Purely a REFRESH signal. Documents that carry asset refs are rewritten
+    // by `project-asset-operations.ts` as part of the move itself, so nothing
+    // here rewrites anything in memory.
+    return connectAssetEvents(
+      () => window.dispatchEvent(new CustomEvent('editor:assets-changed')),
+      (detail) => window.dispatchEvent(new CustomEvent('editor:assets-changed', { detail })),
+    );
+  }, []);
+
+  // There is deliberately NO shell-level document reload watcher here: each
+  // adapter owns its own external-change contract
+  // (`PersistenceProvider.applyExternal`), because only the adapter knows how
+  // to read its own truth back.
+
+  return (
+    <>
+      {/* Edit-time audio is `@vgai/game`'s `edit-mode-audio.service.ts`: the
+          graph it installs is the engine's audio RUNTIME, and the shell used to
+          import it for every project including one that plays nothing. */}
+      {/* Edit-time networking config (declared server + authored identity) for a
+          multiplayer project, with no game running. No-op for single-player. */}
+      <Suspense fallback={null}>
+        <ProjectAuthoringBootstrap store={store} />
+      </Suspense>
+      <ProjectLayout />
+      <AgentPresentationNotice />
+      {/* THE PALETTE IS THE WORKBENCH'S (⌘⇧P). This publishes the editor's live
+          action table to the bridge, which registers one
+          `MenuId.CommandPalette` item per entry with our own label — so the
+          workbench's palette lists OUR actions, and there is no second one. */}
+      <PaletteActionPublisher />
+    </>
+  );
+}

package/src/components/DocumentHeaderStrip.tsx

@@ -0,0 +1,96 @@
+import { type ReactNode, useSyncExternalStore } from 'react';
+import {
+  object3DDocumentSession,
+  object3DDocumentSessionsVersion,
+  subscribeObject3DDocumentSessions,
+} from '../authoring/object3d-document-session-registry';
+import { chromeRegionsKey, subscribeChromeRegions } from '../workspace-regions';
+import { Object3DDocumentToolbar } from './Object3DDocumentToolbar';
+
+/**
+ * THE DOCUMENT HEADER STRIP — the one region every document's header lives
+ * in, drawn by the host. Three kinds of content share the row:
+ *
+ *  - the document's OWN header (`children`: the descriptor's `Toolbar`, or a
+ *    contribution's `export const Toolbar` mounted through `ToolHost`), which
+ *    keeps the leading, full-width part of the row;
+ *  - the host's TRANSFORM controls (`transformControls`: orientation, pivot,
+ *    snap, transform options), for a document whose stage takes them — they
+ *    are HEADER controls in Blender's 3D viewport, not tool-shelf ones, and
+ *    the shelf holds tools only;
+ *  - the host's 3D controls (`Object3DDocumentToolbar`: frame, camera,
+ *    shading, environment, preview capture) for ANY document that has
+ *    mounted an Object3D session — asset models, scene isolation, three
+ *    stories, the 3D board, a project's mesh document — found through the
+ *    session registry, so no descriptor has to declare them. A chromeless
+ *    mount (an inspector preview) registers no session and gets no strip.
+ *
+ * The strip renders when either kind has something to show. Exported so the
+ * bounded host, which mounts a document without the dock, draws the
+ * SAME strip instead of a copy.
+ */
+export function DocumentHeaderStrip({
+  documentId,
+  runtime = false,
+  island = false,
+  assetPath,
+  transformControls,
+  children,
+}: {
+  readonly documentId: string;
+  /** Runtime controls belong to the live view, independent of authoring chrome. */
+  readonly runtime?: boolean;
+  /** The floating-composition island treatment for a world document. */
+  readonly island?: boolean;
+  /** The asset this document opened, when it is an asset document — the
+   *  caller that knows (the dock, through `assetDocumentSpec`) passes it, so
+   *  this module never imports the asset-document machinery and a host
+   *  without it (a bounded host) pays only for the toolbar. */
+  readonly assetPath?: string | undefined;
+  /** The host's TRANSFORM controls (`TransformHeaderControls`), passed by the
+   *  caller that knows whether this document's stage takes them — the GIZMO
+   *  arm of the same `stageTransformDriver` answer that gates the shelf's tool
+   *  strip, because every one of these four wells configures the editor
+   *  viewport's gizmo and a stage with none has nothing for them to set. They
+   *  render at the trailing edge beside the 3D controls, which is where
+   *  Blender's viewport header carries them. */
+  readonly transformControls?: ReactNode;
+  readonly children?: ReactNode;
+}) {
+  useSyncExternalStore(
+    subscribeObject3DDocumentSessions,
+    object3DDocumentSessionsVersion,
+    object3DDocumentSessionsVersion,
+  );
+  const regionsVersion = useSyncExternalStore(
+    subscribeChromeRegions,
+    chromeRegionsKey,
+    chromeRegionsKey,
+  );
+  const session = object3DDocumentSession(documentId);
+  if (!children && !session && !transformControls) return null;
+  // The workspace's knob, not the document's: a skin that hides headers hides
+  // them for every document in that workspace (`EditorWorkspaceRegions`).
+  if (!runtime && regionsVersion.includes('header:hidden')) return null;
+  return (
+    <div
+      className={
+        island
+          ? 'vgai-dock-document-toolbar vgai-chrome-island vgai-glass-island'
+          : 'vgai-dock-document-toolbar'
+      }
+      data-runtime-toolbar={runtime || undefined}
+      data-island-scale="compact"
+      data-testid={`document-header:${documentId}`}
+    >
+      {children ? <div className="vgai-dock-document-toolbar-own">{children}</div> : null}
+      {transformControls}
+      {session ? (
+        <Object3DDocumentToolbar
+          documentId={documentId}
+          {...(assetPath && !assetPath.startsWith('online:') ? { assetPath } : {})}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/components/DocumentShelfRail.tsx

@@ -0,0 +1,45 @@
+import { type ReactNode, useSyncExternalStore } from 'react';
+import { chromeRegionsKey, subscribeChromeRegions } from '../workspace-regions';
+
+/**
+ * THE DOCUMENT SHELF — Blender's tool shelf (T), the host's second region
+ * after the header strip (`DocumentHeaderStrip`): a vertical rail at the
+ * leading edge of a document's content box, drawn by the host, contents
+ * contributed: the host's transform tools on top for every three stage
+ * (`WorkspaceDocumentSurface`, selection or not — Blender's rail is
+ * persistent), then the document's own — the mesh document its operators, a
+ * project's own document whatever it exports as `Shelf`. The rail sits INSIDE the content box (absolute, over the stage —
+ * the position `.vgai-dock-document-content` now provides), so the header
+ * strip above it is never covered and the stage keeps its full size.
+ *
+ * Nothing renders when there is nothing to show; a document without a shelf
+ * has no rail, not an empty one.
+ */
+export function DocumentShelfRail({
+  documentId,
+  children,
+}: {
+  readonly documentId: string;
+  readonly children?: ReactNode;
+}) {
+  const regionsVersion = useSyncExternalStore(
+    subscribeChromeRegions,
+    chromeRegionsKey,
+    chromeRegionsKey,
+  );
+  if (!children) return null;
+  // The workspace's knob (`EditorWorkspaceRegions.shelf`), the same way the
+  // header strip reads its own.
+  if (regionsVersion.includes('shelf:hidden')) return null;
+  return (
+    <div
+      className="vgai-dock-document-shelf"
+      data-testid={`document-shelf:${documentId}`}
+      role="toolbar"
+      aria-orientation="vertical"
+      aria-label="Document tools"
+    >
+      {children}
+    </div>
+  );
+}

package/src/components/DocumentThumbnail.tsx

@@ -0,0 +1,345 @@
+import { fontSizeVar, text } from '@volter/editor-sdk/widgets';
+import { MANIFEST_FILENAME } from '@volter/editor-project/manifest/filename';
+import { useEffect, useRef, useState } from 'react';
+import { listProjectSourceFiles, readProjectTextFile } from '../api/project-source';
+import {
+  loadProjectThumbnailManifest,
+  resetProjectThumbnailManifestCache,
+  THUMBNAIL_MANIFEST_PATH,
+  ThumbnailJobQueue,
+} from '../asset-workflow/thumbnail-system';
+import {
+  DOCUMENT_PREVIEW_HEIGHT,
+  DOCUMENT_PREVIEW_RECIPE,
+  DOCUMENT_PREVIEW_WIDTH,
+  type DocumentPreviewSource,
+} from '../document-preview-source';
+import { projectFiles } from '../files/project-files';
+import { getCurrentProject } from '../project-manager';
+import { getStorageBackend } from '../storage';
+
+interface CaptureJob {
+  readonly run: () => Promise<string>;
+  readonly consumers: Set<AbortSignal>;
+}
+const captureJobs = new Map<string, CaptureJob>();
+const captureQueue = new ThumbnailJobQueue<string>(async (key) => {
+  const job = captureJobs.get(key)!;
+  await new Promise<void>((resume) => {
+    if (typeof requestIdleCallback === 'function')
+      requestIdleCallback(() => resume(), { timeout: 1000 });
+    else setTimeout(resume, 0);
+  });
+  if ([...job.consumers].every((consumer) => consumer.aborted)) {
+    throw new DOMException('Preview demand was cancelled.', 'AbortError');
+  }
+  return job.run();
+}, 1);
+let dependencyFingerprint: Promise<string> | null = null;
+let dependencyProject: string | undefined;
+let dependencyWatchDispose: (() => void) | null = null;
+const dependencyListeners = new Set<() => void>();
+
+async function listPublicDependencyFacts(path: string): Promise<string[]> {
+  const backend = getStorageBackend();
+  let entries: Awaited<ReturnType<typeof backend.list>>;
+  try {
+    entries = await backend.list(path);
+  } catch {
+    return [];
+  }
+  const facts: string[] = [];
+  for (const entry of entries) {
+    if (entry.type === 'dir') facts.push(...(await listPublicDependencyFacts(entry.path)));
+    else facts.push(`${entry.path}:${entry.size ?? 0}:${entry.mtime ?? 0}`);
+  }
+  return facts;
+}
+
+async function projectDependencyFingerprint(): Promise<string> {
+  const project = getCurrentProject()?.rootPath;
+  if (dependencyProject !== project) {
+    dependencyProject = project;
+    dependencyFingerprint = null;
+  }
+  dependencyFingerprint ??= Promise.all([
+    listProjectSourceFiles([
+      MANIFEST_FILENAME,
+      'vgai.adapter.ts',
+      '.storybook/**/*',
+      'src/**/*.ts',
+      'src/**/*.tsx',
+      'src/**/*.js',
+      'src/**/*.jsx',
+      'src/**/*.mjs',
+      'src/**/*.cjs',
+      'src/**/*.json',
+      'src/**/*.css',
+    ]).then(async (paths) =>
+      Promise.all(paths.map(async (path) => `${path}:${(await readProjectTextFile(path)) ?? ''}`)),
+    ),
+    listPublicDependencyFacts(''),
+  ]).then(([source, assets]) => digest([...source, ...assets].sort().join('\n')));
+  return dependencyFingerprint;
+}
+
+function subscribeProjectDependencies(listener: () => void): () => void {
+  dependencyListeners.add(listener);
+  dependencyWatchDispose ??= projectFiles.watch((event) => {
+    if (event.path === THUMBNAIL_MANIFEST_PATH) {
+      resetProjectThumbnailManifestCache();
+      for (const current of dependencyListeners) current();
+      return;
+    }
+    if (
+      !/^(src|public|\.storybook)\//.test(event.path) &&
+      event.path !== MANIFEST_FILENAME &&
+      event.path !== 'vgai.adapter.ts'
+    )
+      return;
+    dependencyFingerprint = null;
+    for (const current of dependencyListeners) current();
+  });
+  return () => {
+    dependencyListeners.delete(listener);
+    if (dependencyListeners.size === 0) {
+      dependencyWatchDispose?.();
+      dependencyWatchDispose = null;
+      dependencyFingerprint = null;
+    }
+  };
+}
+
+async function serializedCapture(
+  key: string,
+  signal: AbortSignal,
+  run: () => Promise<string>,
+): Promise<string> {
+  signal.throwIfAborted();
+  let job = captureJobs.get(key);
+  if (!job) {
+    job = { run, consumers: new Set() };
+    captureJobs.set(key, job);
+  }
+  job.consumers.add(signal);
+  const request = captureQueue.request(key, 1);
+  signal.addEventListener('abort', request.cancel, { once: true });
+  try {
+    return await request.promise;
+  } finally {
+    signal.removeEventListener('abort', request.cancel);
+    job.consumers.delete(signal);
+    if (job.consumers.size === 0 && captureJobs.get(key) === job) captureJobs.delete(key);
+  }
+}
+
+async function digest(value: string): Promise<string> {
+  const bytes = new TextEncoder().encode(value);
+  const hash = await crypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(hash)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+function decodeDataUrl(value: string): { mime: string; bytes: Uint8Array } {
+  const match = /^data:([^;,]+);base64,(.*)$/s.exec(value);
+  if (!match) throw new Error('Document preview owner returned an invalid image data URL.');
+  const binary = atob(match[2]!);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+  return { mime: match[1]!, bytes };
+}
+
+function blobUrl(bytes: Uint8Array, mime = 'image/png'): string {
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return URL.createObjectURL(new Blob([copy.buffer], { type: mime }));
+}
+
+async function previewCamera(documentId: string) {
+  const read = await loadProjectThumbnailManifest();
+  if (read.status !== 'ok') return undefined;
+  const framing = read.manifest.entries[`document:${documentId}`]?.framing;
+  return framing
+    ? {
+        position: { x: framing.position[0], y: framing.position[1], z: framing.position[2] },
+        target: { x: framing.target[0], y: framing.target[1], z: framing.target[2] },
+        ...(framing.fov === undefined ? {} : { fov: framing.fov }),
+      }
+    : undefined;
+}
+
+async function resolvePreview(
+  documentId: string,
+  source: DocumentPreviewSource,
+  force: number,
+  signal: AbortSignal,
+): Promise<string> {
+  const projectId = getCurrentProject()?.rootPath ?? 'no-project';
+  const camera = await previewCamera(documentId);
+  const identity = JSON.stringify({
+    projectId,
+    documentId,
+    recipe: DOCUMENT_PREVIEW_RECIPE,
+    revision: source.revision(),
+    dependencies: await projectDependencyFingerprint(),
+    camera,
+  });
+  signal.throwIfAborted();
+  const key = await digest(identity);
+  const path = `.vgai/cache/document-previews/${key}.png`;
+  if (force === 0 && (await projectFiles.exists(path))) {
+    return blobUrl(await projectFiles.readBytes(path));
+  }
+  const dataUrl = await serializedCapture(key, signal, () =>
+    source.capture({
+      width: DOCUMENT_PREVIEW_WIDTH,
+      height: DOCUMENT_PREVIEW_HEIGHT,
+      ...(camera ? { camera } : {}),
+    }),
+  );
+  signal.throwIfAborted();
+  const image = decodeDataUrl(dataUrl);
+  await projectFiles.write(path, image.bytes);
+  return blobUrl(image.bytes, image.mime);
+}
+
+export function DocumentThumbnail({
+  documentId,
+  source,
+  previewRevision,
+}: {
+  readonly documentId: string;
+  readonly source: DocumentPreviewSource;
+  readonly previewRevision: number;
+}) {
+  const [url, setUrl] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [sourceRevision, setSourceRevision] = useState(0);
+  const [retry, setRetry] = useState(0);
+  const [refreshing, setRefreshing] = useState(true);
+  const [visible, setVisible] = useState(false);
+  const host = useRef<HTMLDivElement>(null);
+  const demand = useRef<AbortController | null>(null);
+  const liveUrl = useRef<string | null>(null);
+  const lastRefresh = useRef({ previewRevision, retry });
+
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const invalidate = () => {
+      demand.current?.abort();
+      setRefreshing(true);
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => setSourceRevision((value) => value + 1), 750);
+    };
+    const unsubscribeSource = source.subscribe(invalidate);
+    // Imported modules are part of the rendered document even when the entry
+    // registry itself does not republish. The project watcher is the broad,
+    // truthful invalidation signal for that dependency graph.
+    const unsubscribeFiles = subscribeProjectDependencies(invalidate);
+    return () => {
+      if (timer) clearTimeout(timer);
+      unsubscribeSource();
+      unsubscribeFiles();
+    };
+  }, [source]);
+
+  useEffect(
+    () => () => {
+      if (liveUrl.current?.startsWith('blob:')) URL.revokeObjectURL(liveUrl.current);
+    },
+    [],
+  );
+
+  useEffect(() => {
+    const element = host.current;
+    if (!element) return;
+    const observer = new IntersectionObserver(([entry]) =>
+      setVisible(entry?.isIntersecting ?? false),
+    );
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => {
+    if (!visible) return;
+    const controller = new AbortController();
+    demand.current = controller;
+    const force =
+      lastRefresh.current.previewRevision !== previewRevision || lastRefresh.current.retry !== retry
+        ? 1
+        : 0;
+    setError(null);
+    setRefreshing(true);
+    void resolvePreview(documentId, source, force, controller.signal)
+      .then((resolved) => {
+        if (controller.signal.aborted) {
+          URL.revokeObjectURL(resolved);
+          return;
+        }
+        if (liveUrl.current) URL.revokeObjectURL(liveUrl.current);
+        lastRefresh.current = { previewRevision, retry };
+        liveUrl.current = resolved;
+        setUrl(resolved);
+        setRefreshing(false);
+      })
+      .catch((reason: unknown) => {
+        if (controller.signal.aborted) return;
+        setError(reason instanceof Error ? reason.message : String(reason));
+        setRefreshing(false);
+      });
+    return () => controller.abort();
+  }, [documentId, previewRevision, retry, source, sourceRevision, visible]);
+
+  return (
+    <div
+      ref={host}
+      style={{
+        width: '100%',
+        height: '100%',
+        position: 'relative',
+        display: 'grid',
+        placeItems: 'center',
+      }}
+    >
+      {url && (
+        <img
+          src={url}
+          alt={`${documentId} preview`}
+          style={{ width: '100%', height: '100%', objectFit: 'contain' }}
+        />
+      )}
+      {error ? (
+        <button
+          type="button"
+          title={error}
+          onClick={(event) => {
+            event.stopPropagation();
+            setRetry((value) => value + 1);
+          }}
+          style={{
+            position: 'absolute',
+            bottom: 0,
+            border: 0,
+            background: 'var(--vscode-editor-background)',
+            color: text[3],
+            pointerEvents: 'auto',
+          }}
+        >
+          Preview unavailable · Retry
+        </button>
+      ) : refreshing ? (
+        <span
+          role="status"
+          style={{
+            position: 'absolute',
+            bottom: 0,
+            background: 'var(--vscode-editor-background)',
+            color: text[3],
+            fontSize: fontSizeVar.xs,
+          }}
+        >
+          {url ? 'Refreshing preview…' : 'Loading preview…'}
+        </span>
+      ) : null}
+    </div>
+  );
+}