@volter/editor-core 0.5.57

package/src/workspace-areas.ts

@@ -0,0 +1,156 @@
+/**
+ * THE ACTIVE WORKSPACE'S EDITOR AREAS — the live store the dock reads, and the
+ * one place an area document is opened and closed.
+ *
+ * **A Blender editor AREA is an editor group; the drawer holds utilities**
+ * (orchestrator ruling 2026-09-19; WORK.md §Inspection parity I5). Blender's UV
+ * Editing is a side-by-side split of the centre, Shading and Animation a
+ * top/bottom split, and both the dock and the Code-OSS frame have exactly that
+ * shape in editor groups. So a workspace's second editor is a
+ * `workspace.document` contribution opened into a second group — never a
+ * drawer utility — and this module is the seam: `workspace-presets.ts`
+ * publishes the active workspace's `areas` here on every switch, and this
+ * module opens what that list names and closes what it no longer does.
+ *
+ * WHY THE OPEN LIVES HERE AND NOT IN THE DOCK. The dock is a RECONCILER: it
+ * draws whatever the document registry holds, and `reconcileWorkspace` runs on
+ * every mutation, so opening a document from inside it is a write during a
+ * read. The registry is the truth; the frame places it (`vgaiDocuments.ts`'s
+ * `reconcileAreaDocumentPanels`), and under the frame the layout host places
+ * the same registry entry in a VS Code editor group instead. One list, two
+ * hosts — the shape every U8 seam takes.
+ *
+ * WHY IT IS A MODULE AND NOT A REACT EFFECT. A workspace switch arrives from
+ * four places (the menu, a registered action, `editor.workspace(id)`, the
+ * per-project restore at boot) and three of them have no component mounted to
+ * run an effect. `setWorkspaceAreas` is called by the same function that
+ * publishes the regions, so the two halves of "apply this workspace" cannot
+ * drift apart.
+ */
+
+import type { WorkspaceAreaContribution } from '@volter/editor-sdk/layout-arrangements';
+import { openToolDocument, toolDocumentId } from './components/tool-documents';
+import { subscribeToolContributions } from './tool-loader';
+import { closeWorkspaceDocument, openWorkspaceDocuments } from './workspace-document-registry';
+
+let _areas: readonly WorkspaceAreaContribution[] = [];
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+/** The active workspace's areas, in declaration order. */
+export function activeWorkspaceAreas(): readonly WorkspaceAreaContribution[] {
+  return _areas;
+}
+
+/** Monotonic counter behind {@link subscribeWorkspaceAreas}. */
+export function workspaceAreasVersion(): number {
+  return _version;
+}
+
+export function subscribeWorkspaceAreas(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => _listeners.delete(listener);
+}
+
+/** The area one open document fills, or `null` — the dock's lookup. */
+export function workspaceAreaFor(documentId: string): WorkspaceAreaContribution | null {
+  return _areas.find((area) => toolDocumentId(area.document) === documentId) ?? null;
+}
+
+/**
+ * THE WHOLE OPEN PASS LEAVES THE MODULE EVALUATION, and this is the second and
+ * correct form of a fix the first attempt got half right.
+ *
+ * MEASURED TWICE, live, on a fresh `--template models` scaffold:
+ *  1. `subscribeToolContributions(...)` at this file's top level →
+ *     "editor app failed to start: ReferenceError: Cannot access 'listeners'
+ *     before initialization at subscribeToolContributions
+ *     (tool-loader.ts:372) at workspace-areas.ts:41", x3. The WHOLE editor
+ *     down, not a degraded panel.
+ *  2. The same subscription moved to the first `setWorkspaceAreas` call →
+ *     the SAME error, one frame deeper: `... at ensureSubscribedToContributions
+ *     ... at setWorkspaceAreas ... at publishWorkspaceRegions
+ *     (workspace-presets.ts:119) at workspace-presets.ts:164`.
+ *
+ * The second reading is the one that names the real shape:
+ * `workspace-presets.ts` calls `publishWorkspaceRegions()` AT MODULE SCOPE
+ * (line 389 in source), so "the first publish" IS during module evaluation —
+ * deferring to it deferred nothing. And this module is in one import cycle
+ * with `tool-loader` (`workspace-areas` -> `components/tool-documents` ->
+ * `tool-loader`), so every binding over there is still in its temporal dead
+ * zone at that moment. `subscribeToolContributions` was merely the first of
+ * this module's reaches into it; `openToolDocument` is the other, and it
+ * would have thrown next.
+ *
+ * So the pass is queued as a MICROTASK. ES module evaluation is synchronous
+ * end to end, so a microtask queued during it runs after the last module has
+ * finished — every binding initialized, no ordering to reason about. The
+ * publish itself stays synchronous: `_areas`, the version and the listeners
+ * are this module's own state and nothing else's, and the dock must see the
+ * new list on the same tick the workspace changed.
+ */
+let subscribed = false;
+let pendingPass = false;
+
+function runOpenPass(): void {
+  pendingPass = false;
+  if (!subscribed) {
+    subscribed = true;
+    // THE CONTRIBUTIONS ARRIVE AFTER THE WORKSPACE, EVERY TIME. A project's
+    // packages import asynchronously, so the workspace restored at boot
+    // publishes its `areas` while `blender-uv-editor.document` is still
+    // loading and `openToolDocument` truthfully opens nothing. Contributions
+    // changing is the other half of the same event — including a SAVE, which
+    // re-evaluates the module and must re-open the document against the fresh
+    // component.
+    subscribeToolContributions(scheduleOpenPass);
+  }
+  const areas = _areas;
+  const wanted = new Set(areas.map((area) => toolDocumentId(area.document)));
+  // CLOSING IS BY AREA, NOT BY ID SET DIFFERENCE. A document that is open and
+  // carries an `area` but is not in the new list is this module's to close,
+  // and nothing else in the editor opens one — so the sweep reads the registry
+  // rather than remembering what it opened, which is what survives a reload
+  // that rebuilt the registry underneath.
+  for (const open of openWorkspaceDocuments()) {
+    if (!open.descriptor.area) continue;
+    if (wanted.has(open.descriptor.id)) continue;
+    closeWorkspaceDocument(open.descriptor.id);
+  }
+  for (const area of areas) {
+    // `openToolDocument` is self-verifying: a contribution that has not loaded
+    // yet opens nothing and answers false, and the subscription above runs
+    // this pass again when it arrives. No queue, no retry timer.
+    openToolDocument(null, area.document, { activate: false }, area.id);
+  }
+}
+
+function scheduleOpenPass(): void {
+  if (pendingPass) return;
+  pendingPass = true;
+  queueMicrotask(runOpenPass);
+}
+
+function areasKey(areas: readonly WorkspaceAreaContribution[]): string {
+  return areas.map((area) => `${area.id}|${area.document}|${area.place}|${area.ratio}`).join(' ');
+}
+
+/**
+ * Publish the active workspace's areas (`workspace-presets.ts`), opening the
+ * documents it names and closing the ones the previous workspace had.
+ */
+export function setWorkspaceAreas(areas: readonly WorkspaceAreaContribution[]): void {
+  const changed = areasKey(areas) !== areasKey(_areas);
+  _areas = areas;
+  scheduleOpenPass();
+  if (!changed) return;
+  _version += 1;
+  for (const listener of _listeners) listener();
+}
+
+/** Re-run the open pass without changing the list — the door for "the
+ *  contributions finished loading", which is when a workspace applied at boot
+ *  can finally find the document it named. */
+export function reopenWorkspaceAreas(): void {
+  scheduleOpenPass();
+}

package/src/workspace-aux-commands.ts

@@ -0,0 +1,11 @@
+import { showWorkspaceAuxiliary } from './workspace-host-commands';
+
+export function openUndoHistory(): void {
+  showWorkspaceAuxiliary('undo-history');
+}
+
+export function installAuxiliaryEvents(): () => void {
+  const onShowHistory = () => openUndoHistory();
+  window.addEventListener('editor:show-history-tab', onShowHistory);
+  return () => window.removeEventListener('editor:show-history-tab', onShowHistory);
+}

package/src/workspace-available-documents.ts

@@ -0,0 +1,127 @@
+/** Discoverable documents are independent of open tabs. Closing a tab keeps its
+ * project-owned descriptor available to Content and to session restoration. */
+
+import {
+  closeWorkspaceDocument,
+  openWorkspaceDocument,
+  WORKSPACE_DOCUMENT_KINDS,
+  type WorkspaceDocumentDescriptor,
+} from './workspace-document-registry';
+import { registerWorkspaceDocumentRestorer } from './workspace-document-restore';
+
+export interface AvailableWorkspaceDocument {
+  readonly descriptor: WorkspaceDocumentDescriptor;
+  readonly category: string;
+  /** Set only when this is the root's own document, never an isolated scene. */
+  readonly rootId?: string | undefined;
+  readonly default: boolean;
+}
+let documents: readonly AvailableWorkspaceDocument[] = [];
+const listeners = new Set<() => void>();
+const pending = new Map<string, boolean>();
+let sessionStarted = false;
+let hasDocumentsRestoring = false;
+let defaultOpened = false;
+export function requestAvailableWorkspaceDocument(id: string, active = true): void {
+  pending.set(id, active);
+  restoreAvailableDocuments();
+}
+const notify = () => {
+  for (const listener of listeners) listener();
+};
+export const availableWorkspaceDocuments = () => documents;
+export function subscribeAvailableWorkspaceDocuments(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function openAvailableWorkspaceDocument(id: string, activate = true): boolean {
+  const entry = documents.find((item) => item.descriptor.id === id);
+  if (!entry) return false;
+  openWorkspaceDocument(
+    { ...entry.descriptor, closeable: true, persist: () => ({ availableDocumentId: id }) },
+    { activate },
+  );
+  return true;
+}
+
+function restoreAvailableDocuments(): void {
+  for (const [id, active] of pending) {
+    if (openAvailableWorkspaceDocument(id, active)) pending.delete(id);
+  }
+  if (sessionStarted && !hasDocumentsRestoring && !defaultOpened) {
+    const entry = documents.find((item) => item.default);
+    if (entry) {
+      defaultOpened = true;
+      openAvailableWorkspaceDocument(entry.descriptor.id);
+    }
+  }
+}
+
+export function registerAvailableWorkspaceDocument(
+  descriptor: WorkspaceDocumentDescriptor,
+  options: { category: string; default?: boolean; rootId?: string | undefined },
+): string {
+  const previous = documents.find((item) => item.descriptor.id === descriptor.id);
+  if (
+    previous?.descriptor.Content === descriptor.Content &&
+    previous?.descriptor.title === descriptor.title &&
+    previous.descriptor.provenance?.sourcePath === descriptor.provenance?.sourcePath &&
+    previous.descriptor.provenance?.rootId === descriptor.provenance?.rootId &&
+    previous.descriptor.Toolbar === descriptor.Toolbar &&
+    previous.descriptor.Shelf === descriptor.Shelf &&
+    previous.descriptor.preview === descriptor.preview &&
+    previous.default === (options.default ?? false) &&
+    previous.category === options.category &&
+    previous.rootId === options.rootId
+  )
+    return descriptor.id;
+  const entry = {
+    descriptor,
+    category: options.category,
+    default: options.default ?? false,
+    rootId: options.rootId,
+  };
+  documents = previous
+    ? documents.map((item) => (item.descriptor.id === descriptor.id ? entry : item))
+    : [...documents, entry];
+  notify();
+  restoreAvailableDocuments();
+  return descriptor.id;
+}
+
+export function unregisterAvailableWorkspaceDocument(id: string): void {
+  if (!documents.some((item) => item.descriptor.id === id)) return;
+  documents = documents.filter((item) => item.descriptor.id !== id);
+  closeWorkspaceDocument(id, { discardDirty: true });
+  notify();
+}
+
+for (const kind of WORKSPACE_DOCUMENT_KINDS) {
+  registerWorkspaceDocumentRestorer({
+    kind,
+    owner: 'workspace-available-documents',
+    restore: ({ state, active }) => {
+      const id = (state as { availableDocumentId?: unknown } | null)?.availableDocumentId;
+      if (typeof id !== 'string') return false;
+      pending.set(id, active);
+      restoreAvailableDocuments();
+      return true;
+    },
+    beginRestore: ({ hasDocumentsToRestore }) => {
+      sessionStarted = true;
+      hasDocumentsRestoring = hasDocumentsToRestore;
+      restoreAvailableDocuments();
+    },
+  });
+}
+export function resetAvailableWorkspaceDocuments(): void {
+  documents = [];
+  pending.clear();
+  sessionStarted = false;
+  hasDocumentsRestoring = false;
+  defaultOpened = false;
+  notify();
+}

package/src/workspace-core-utilities.ts

@@ -0,0 +1,31 @@
+/** The identity inventory of the HOST's own utility tabs — the ones
+ *  `components/core-utilities.tsx` registers. */
+export const CORE_WORKSPACE_UTILITIES = {
+  console: { id: 'console', title: 'Console' },
+  lightExplorer: { id: 'light-explorer', title: 'Light Explorer' },
+} as const;
+
+/**
+ * Utility tabs a PACKAGE registers, whose ids the host still declares.
+ *
+ * A tab id keys persisted dock state and is part of the shareable view address
+ * space (`EDITOR_VIEW_BUILT_IN_UTILITY_IDS` in `@volter/editor-sdk`, which this
+ * list must equal), so the address is the host's even when the surface is not:
+ * the package imports its row from here rather than spelling the id twice.
+ * `@vgai/game` registers all four — the story trio through
+ * `story-documents.service.ts`, Generations through `generation.service.ts`.
+ * Build Output is NOT here: it is a `workspace.utility` CONTRIBUTION, so the
+ * loader namespaces its id as `tool:build-output.utility` and no host
+ * declaration exists.
+ */
+export const CONTRIBUTED_WORKSPACE_UTILITIES = {
+  storyActions: { id: 'story-actions', title: 'Actions' },
+  storyInteractions: { id: 'story-interactions', title: 'Interactions' },
+  storyAccessibility: { id: 'story-accessibility', title: 'Accessibility' },
+  generations: { id: 'generations', title: 'Generations' },
+} as const;
+
+export const BUILT_IN_WORKSPACE_UTILITIES = [
+  ...Object.values(CORE_WORKSPACE_UTILITIES),
+  ...Object.values(CONTRIBUTED_WORKSPACE_UTILITIES),
+] as const;

package/src/workspace-document-ids.ts

@@ -0,0 +1,59 @@
+/** Stable ids for the editor-owned PINNED center documents. Kept outside their
+ * React implementations so root-document routing and the center tab-strip
+ * order contract can name them without
+ * importing the stage host or the three board. */
+export const GAME_DOCUMENT_ID = 'workspace:game';
+export const SCENE_DOCUMENT_ID = 'workspace:scene';
+
+/**
+ * THE canvas root's Scene document.
+ *
+ * A three project's `Scene` is the one stage host showing the world root — the editor's own WebGL
+ * viewport, which a canvas world has no use for (it draws through its own Pixi
+ * renderer). So a canvas project's scene is a document of its own, presenting
+ * the native display tree through an independent world-space editor camera.
+ * It takes the same `Scene` TITLE and the same slot in the pinned strip,
+ * because to the author it is the same thing: the game's world composition.
+ *
+ * Separate ID rather than a second Content behind {@link SCENE_DOCUMENT_ID}
+ * because `CenterDocuments.syncCenterDocuments` owns that id's whole lifetime
+ * and CLOSES it on every store notify for a project with no three root — two
+ * owners for one id is a fight, not a design.
+ */
+export const CANVAS_SCENE_DOCUMENT_ID = 'workspace:canvas-scene';
+
+/**
+ * THE project's 3D board — the three-side design document. The board is a
+ * project-wide singleton: one generated view of one registry, under a stable
+ * project-level id, so a persisted layout never strands the panel when a root
+ * or file is renamed.
+ */
+export const THREE_COMPONENTS_DOCUMENT_ID = 'workspace:3d-components';
+
+/**
+ * THE project's 2D board — the canvas-side design document, and the exact
+ * counterpart of {@link THREE_COMPONENTS_DOCUMENT_ID} on the Pixi surface.
+ */
+export const CANVAS_COMPONENTS_DOCUMENT_ID = 'workspace:2d-components';
+
+/**
+ * THE project's UI board — one document per PROJECT, not one per root, and the
+ * exact counterpart of {@link THREE_COMPONENTS_DOCUMENT_ID} on the dom side.
+ */
+export const UI_COMPONENTS_DOCUMENT_ID = 'workspace:ui-components';
+
+/**
+ * The pinned documents whose registration is ASYNC — a project's own
+ * authoring bootstrap opens them, after the workspace restore has already
+ * asked for the stored active tab. Restoring one as the active document
+ * therefore REMEMBERS the request until that stable descriptor opens
+ * (`restorePinnedWorkspaceDocumentActivation`), which arbitrary ids may not
+ * do: a persisted tool/asset id that never reopens would otherwise become
+ * latent state that steals activation from a standing tab much later.
+ */
+export const PINNED_ASYNC_DOCUMENT_IDS: ReadonlySet<string> = new Set([
+  CANVAS_SCENE_DOCUMENT_ID,
+  CANVAS_COMPONENTS_DOCUMENT_ID,
+  THREE_COMPONENTS_DOCUMENT_ID,
+  UI_COMPONENTS_DOCUMENT_ID,
+]);