@volter/editor-core 0.5.57

package/src/workspace-document-restore.ts

@@ -0,0 +1,145 @@
+/**
+ * A CONTRIBUTED DOCUMENT KIND OWNS ITS OWN PERSISTED STATE — the other half
+ * of `WorkspaceDocumentDescriptor.persist` (docs/WORKBENCH.md §host versus
+ * package).
+ *
+ * THE RULE. `workspace-state-persistence.ts` stores, per open document, an
+ * OPAQUE blob under that document's kind and id. It never reads inside the
+ * blob and it names no document module: on the next boot it looks the kind up
+ * here and hands the blob back. A kind with no restorer registered — a module
+ * that is gone, a package this project no longer depends on, a record written
+ * by another build — restores NOTHING, silently. That is the entire
+ * compatibility story for a blob: it carries no version field of its own and
+ * no migration.
+ *
+ * WHY IT EXISTS. Before this, the host switched on every document kind by
+ * name (the story documents and their registry, the adapter-table documents,
+ * the tool documents, the asset documents), so moving ANY of them into a
+ * package meant editing that one host file — which serialized every
+ * extraction against every other, and reverted one of them rather than land
+ * a half-move (measured 2026-09-18).
+ *
+ * WHAT A RESTORER IS FOR. `restore` reopens ONE document from its own blob
+ * and answers whether it could: `false` is the honest answer for a module
+ * that no longer loads, a story that is no longer exported, a file that is
+ * gone. Verification belongs HERE, not in the host, because only the kind
+ * knows what "still true" means for its subject. `prepare` is the kind's own
+ * async settling step (refresh the registry this kind reads), awaited ONCE
+ * before its documents restore and only when at least one is present.
+ * `persistKindState`/`beginRestore` carry the state that belongs to the KIND
+ * rather than to one open document — a discovery baseline, a "what opens when
+ * this project has never recorded anything" rule.
+ */
+
+import type { ViewportTab } from './editor-shell-store';
+
+/** The narrow store surface every document open function declares (the T6.3
+ *  input-gate hand-off). Defined here, beside the restore seam, so a document
+ *  module can accept it without importing the persistence host. */
+export interface WorkspaceStateStore {
+  setActiveViewportTab(tab: ViewportTab): void;
+  /** Live play state — the write-through gate reads it so no layout write can
+   *  land while a game is playing/paused, even if the play-transition
+   *  suppression flag is momentarily out of phase during a chaotic teardown
+   *  (a transient-renderer error-boundary rebuild that tears play down and
+   *  re-enters). Optional so unit-test fakes need not supply it (treated as
+   *  'stopped'). */
+  readonly playState?: 'stopped' | 'playing' | 'paused';
+}
+
+/** What {@link WorkspaceDocumentRestorer.restore} is handed for one document. */
+export interface WorkspaceDocumentRestoreContext {
+  /** The document id that was open — the same id `persist` was called under. */
+  readonly id: string;
+  /** Exactly what this document's `persist` returned last session. Opaque to
+   *  the host, so a restorer must treat it as untrusted input. */
+  readonly state: unknown;
+  /** Whether this document was the ACTIVE tab. A kind that opens
+   *  asynchronously must activate itself, because the host has already asked
+   *  for the stored active id by the time a late open lands. */
+  readonly active: boolean;
+  readonly store: WorkspaceStateStore;
+}
+
+/** What {@link WorkspaceDocumentRestorer.beginRestore} is handed, once per
+ *  session, for every registered kind. */
+export interface WorkspaceDocumentKindRestoreContext {
+  /** Whatever `persistKindState` returned last session, or `undefined`. */
+  readonly state: unknown;
+  /**
+   * Whether this session has any persisted document to BRING BACK. `false` is
+   * the moment a kind may open the project's own default document.
+   *
+   * It used to ask a narrower question — "does this project have a documents
+   * record at all" — and the two decorrelate in the one case that hurts: a
+   * record that EXISTS and lists nothing. Closing the last document writes
+   * exactly that (`{"open":[],"activeId":"tool:blender-timeline.document"}`,
+   * measured on a `model-editor create` scaffold, walk 5 beat 0), and from
+   * then on every boot of that project restored nothing, opened no default,
+   * and left the workspace with no document a person is in — which on the
+   * model editor is the product's cover waiting out its whole 90 s budget and
+   * then blaming Blender for a model nobody ever asked it to open. A closed
+   * tab is not a standing instruction across page loads; "nothing to restore"
+   * is one fact however the record spells it.
+   */
+  readonly hasDocumentsToRestore: boolean;
+  readonly store: WorkspaceStateStore;
+}
+
+export interface WorkspaceDocumentRestorer {
+  /** The `WorkspaceDocumentDescriptor.kind` this restores. Several modules
+   *  may share one kind (a `world` is a three story here and a manifest root
+   *  there); each registers its own restorer and the host tries them in
+   *  registration order until one answers `true`. */
+  readonly kind: string;
+  /** Which module owns it. Re-registering the same owner+kind REPLACES, so a
+   *  module re-evaluated by HMR leaves one restorer, not two. */
+  readonly owner: string;
+  /** Awaited once before this kind's documents restore, and only when the
+   *  record holds at least one. Restorers that share a settling step share
+   *  the FUNCTION (the host dedupes by identity), so one refresh runs once. */
+  readonly prepare?: () => Promise<void>;
+  /** Reopen one persisted document. `false` = it cannot truthfully reopen,
+   *  and the stale entry is reconciled away. */
+  readonly restore: (context: WorkspaceDocumentRestoreContext) => boolean | Promise<boolean>;
+  /** This kind's own session state, persisted beside the open set under the
+   *  kind key. Read on every write-through, so keep it cheap. */
+  readonly persistKindState?: () => unknown;
+  /** Called once per session for EVERY registered kind, before the persisted
+   *  documents reopen — whether or not this kind has any. */
+  readonly beginRestore?: (context: WorkspaceDocumentKindRestoreContext) => void;
+}
+
+const _restorers = new Map<string, WorkspaceDocumentRestorer[]>();
+
+/** Install a kind's restorer. Returns the teardown. */
+export function registerWorkspaceDocumentRestorer(restorer: WorkspaceDocumentRestorer): () => void {
+  const existing = _restorers.get(restorer.kind) ?? [];
+  const next = existing.filter((item) => item.owner !== restorer.owner);
+  next.push(restorer);
+  _restorers.set(restorer.kind, next);
+  return () => {
+    const current = _restorers.get(restorer.kind);
+    if (!current) return;
+    const remaining = current.filter((item) => item !== restorer);
+    if (remaining.length === 0) _restorers.delete(restorer.kind);
+    else _restorers.set(restorer.kind, remaining);
+  };
+}
+
+/** Every restorer registered for `kind`, in registration order. */
+export function workspaceDocumentRestorers(kind: string): readonly WorkspaceDocumentRestorer[] {
+  return _restorers.get(kind) ?? [];
+}
+
+/** Every registered restorer, in kind registration order. */
+export function workspaceDocumentRestorerEntries(): readonly WorkspaceDocumentRestorer[] {
+  const all: WorkspaceDocumentRestorer[] = [];
+  for (const list of _restorers.values()) all.push(...list);
+  return all;
+}
+
+/** Test-only reset (mirrors the document registry's own). */
+export function __resetWorkspaceDocumentRestorersForTest(): void {
+  _restorers.clear();
+}

package/src/workspace-host-commands.ts

@@ -0,0 +1,141 @@
+import type { WorkspaceStaticPanelKind } from './workspace-static-panels';
+
+/**
+ * THE IMPERATIVE BOUNDARY between the editor's semantic commands and whatever
+ * layout host is mounted — today the Code-OSS frame, which installs the
+ * implementations from `frame/bridge.tsx` and answers them with the
+ * workbench's own views and editor groups.
+ *
+ * Callers ask to reveal a capability by stable ID and never encode its current
+ * coordinates: a person may have moved that view since startup, and the host
+ * is the only thing that knows where it is now. A command asked before a host
+ * has installed is QUEUED and flushes on the install, so a startup gesture is
+ * never lost to boot order.
+ */
+
+export interface WorkspaceHostCommands {
+  /** Capture only the utility presentation a temporary layout behavior will change. */
+  captureUtilities?(ids: readonly string[]): () => void;
+  /** Focus one of the editor's built-in persistent panels. The vocabulary is
+   *  the static-panel REGISTRY (`workspace-static-panels.ts`) — the host maps
+   *  a kind to its own surface, and no caller keeps a second list. */
+  showStaticPanel(kind: WorkspaceStaticPanelKind): void;
+  /** Materialize an on-demand utility tab without opening the utility region:
+   *  the drawer presents itself collapsed to its tab strip, so the new tab and
+   *  its badge are discoverable while the body stays closed. */
+  ensureUtility?(id: string): void;
+  showUtility(id: string): void;
+  toggleUtility(id: string): void;
+  /** Remove a transient utility from wherever the host put it. Hosts restore
+   * the utility that was active before it was revealed, or collapse the
+   * utility region when it was opened only for this one. */
+  closeUtility?(id: string): void;
+  showAuxiliary(id: 'undo-history'): void;
+  toggleFocus(): void;
+  setFocus?(focused: boolean): void;
+}
+
+let commands: WorkspaceHostCommands | null = null;
+let pending: Array<(value: WorkspaceHostCommands) => void> = [];
+let activeUtilityId: string | null = null;
+let activeStaticPanel: WorkspaceStaticPanelKind | null = null;
+let _utilityVersion = 0;
+const utilityListeners = new Set<() => void>();
+let utilityTabIds: readonly string[] = [];
+const utilityTabsListeners = new Set<() => void>();
+
+export function setActiveWorkspaceUtility(id: string | null): void {
+  if (activeUtilityId === id) return;
+  activeUtilityId = id;
+  _utilityVersion++;
+  for (const listener of utilityListeners) listener();
+}
+
+export function activeWorkspaceUtility(): string | null {
+  return activeUtilityId;
+}
+
+export function subscribeActiveWorkspaceUtility(listener: () => void): () => void {
+  utilityListeners.add(listener);
+  return () => utilityListeners.delete(listener);
+}
+
+/** The static panel holding the dock's focus, or `null` when a document or a
+ *  drawer utility does. The dock reports it from its own active-panel event,
+ *  so this is what a human is looking at — not the last thing asked for. */
+export function setActiveWorkspaceStaticPanel(kind: WorkspaceStaticPanelKind | null): void {
+  activeStaticPanel = kind;
+}
+
+export function activeWorkspaceStaticPanel(): WorkspaceStaticPanelKind | null {
+  return activeStaticPanel;
+}
+
+/** The utility tabs the host currently holds, in its own order. The host owns
+ * the tab strip's presentation; this list is the semantic readout of it
+ * (stories, and callers asking what exists). */
+export function setWorkspaceUtilityTabs(ids: readonly string[]): void {
+  if (
+    ids.length === utilityTabIds.length &&
+    ids.every((id, index) => id === utilityTabIds[index])
+  ) {
+    return;
+  }
+  utilityTabIds = [...ids];
+  for (const listener of utilityTabsListeners) listener();
+}
+
+export function workspaceUtilityTabs(): readonly string[] {
+  return utilityTabIds;
+}
+
+function invoke(operation: (value: WorkspaceHostCommands) => void): void {
+  if (commands) operation(commands);
+  else pending.push(operation);
+}
+
+export function installWorkspaceHostCommands(next: WorkspaceHostCommands): () => void {
+  commands = next;
+  const queued = pending;
+  pending = [];
+  for (const operation of queued) operation(next);
+  return () => {
+    if (commands === next) commands = null;
+  };
+}
+
+export function showWorkspaceUtility(id: string): void {
+  invoke((value) => value.showUtility(id));
+}
+
+export function ensureWorkspaceUtility(id: string): void {
+  invoke((value) => value.ensureUtility?.(id));
+}
+
+export function showWorkspaceStaticPanel(kind: WorkspaceStaticPanelKind): void {
+  invoke((value) => value.showStaticPanel(kind));
+}
+
+export function toggleWorkspaceUtility(id: string): void {
+  invoke((value) => value.toggleUtility(id));
+}
+
+export function closeWorkspaceUtility(id: string): void {
+  invoke((value) => value.closeUtility?.(id));
+}
+
+export function showWorkspaceAuxiliary(id: 'undo-history'): void {
+  invoke((value) => value.showAuxiliary(id));
+}
+
+export function toggleWorkspaceFocus(): void {
+  invoke((value) => value.toggleFocus());
+}
+
+export function setWorkspaceFocus(focused: boolean): void {
+  invoke((value) => value.setFocus?.(focused));
+}
+
+export function captureWorkspaceUtilities(ids: readonly string[]): () => void {
+  return commands?.captureUtilities?.(ids) ?? (() => {});
+}

package/src/workspace-persistence-gate.ts

@@ -0,0 +1,40 @@
+/**
+ * Tiny shared gate: while suppressed, workspace-layout persistence
+ * (`workspace-state-persistence.ts`) drops every write-through/flush.
+ *
+ * Immersive Glass + Floating play hides the dock chrome for the whole play
+ * session (`play-transition.ts`); the resulting hidden-group layout is
+ * transient presentation, not user intent, and must never overwrite the
+ * saved layout — including via the `pagehide` flush if the tab closes
+ * mid-play. Classic/Docked play never enables this gate. Kept in its
+ * own module (not in workspace-state-persistence.ts) so play-transition can
+ * set it without importing the persistence module's heavy dependency graph.
+ *
+ * The flag lives on `globalThis`, not a module-local `let`: the play-mode
+ * boot path dynamically imports the project bundle (`play-mode.ts`'s
+ * `/@fs/…?t=…` / `import(modulePath)`), and Vite dev can then serve a SECOND
+ * evaluated copy of this gate module through that graph. A module-local flag
+ * would split — `play-transition` setting `true` on one copy while
+ * `workspace-state-persistence` reads `false` on the other (proven: the
+ * hidden-chrome layout leaked into localStorage during play, 71-play-
+ * transition). A single `globalThis` cell is shared by every copy and is a
+ * plain boolean in production (no duplication, zero overhead).
+ */
+
+const GATE_KEY = '__vgaiWorkspacePersistenceSuppressed';
+
+interface GateHost {
+  [GATE_KEY]?: boolean;
+}
+
+function host(): GateHost {
+  return globalThis as unknown as GateHost;
+}
+
+export function setWorkspacePersistenceSuppressed(suppressed: boolean): void {
+  host()[GATE_KEY] = suppressed;
+}
+
+export function isWorkspacePersistenceSuppressed(): boolean {
+  return host()[GATE_KEY] === true;
+}

package/src/workspace-play-utilities.ts

@@ -0,0 +1,44 @@
+import { adapterEditorConfiguration } from './adapter-editor-config';
+import { editorConsole } from './editor-console';
+import { layoutPolicy } from './layout-policy';
+import { captureWorkspaceUtilities, showWorkspaceUtility } from './workspace-host-commands';
+import { activeChromeRegions } from './workspace-regions';
+import { availableWorkspaceUtilities } from './workspace-utility-registry';
+
+let contributionsReady = false;
+let pending: readonly string[] = [];
+let restore: (() => void) | undefined;
+
+function flush(): void {
+  if (!contributionsReady || pending.length === 0) return;
+  const requested = pending;
+  pending = [];
+  if (activeChromeRegions().drawer === 'hidden') return;
+  restore ??= captureWorkspaceUtilities(requested);
+  const available = new Set(availableWorkspaceUtilities().map((utility) => utility.id));
+  for (const id of requested) {
+    if (available.has(id)) showWorkspaceUtility(id);
+    else
+      editorConsole.error(
+        `vgai.adapter.ts: editor.playUtilities names unavailable utility "${id}".`,
+        'adapter',
+      );
+  }
+}
+
+/** Discovery may finish after Play. No contribution kind implicitly opens a panel. */
+export function publishPlayUtilitiesReady(ready: boolean): void {
+  contributionsReady = ready;
+  flush();
+}
+
+export function revealWorkspacePlayUtilities(): void {
+  pending = layoutPolicy()?.playUtilities ?? adapterEditorConfiguration().playUtilities ?? [];
+  flush();
+}
+
+export function cancelPendingWorkspacePlayUtilities(): void {
+  pending = [];
+  restore?.();
+  restore = undefined;
+}