@volter/editor-core 0.5.57

package/src/hierarchy-walk.ts

@@ -0,0 +1,86 @@
+/**
+ * ONE breadth-first walk of an authoring hierarchy, and the reason it is not
+ * written inline four more times.
+ *
+ * WHAT THIS REPLACES, AND WHY IT IS A BUG AND NOT A STYLE PREFERENCE. Four
+ * modules carried the same hand-rolled BFS — `activeHierarchyRows`,
+ * `authoringDocumentSourcePath`, the Content panel's `hierarchyNodes`, the
+ * composite adapter's `childAssetEntries`, the Light Explorer's `lightNodes` —
+ * and every one of them drained its queue with `Array.prototype.shift()`.
+ * `shift` is not O(1) on a large array: V8 moves the remaining elements down,
+ * so a queue that grows to thousands makes the walk QUADRATIC in node count.
+ *
+ * Measured with the page's own `Profiler` on the scale harness's 20 000-node
+ * canvas world (2026-08-20), profiling the 1.4s window around one relayed
+ * `select`: **1471 of 1606 samples were inside `activeHierarchyRows`** — one
+ * deferred `collectState` refresh spending 1.4 seconds walking a tree whose
+ * every other reader answers in single-digit milliseconds. The study's
+ * superlinear growth ratios (canvas ×22-×55, three ×12-×42 from N=1000 to
+ * N=5000, where linear is ×5) are what a quadratic walk read through a
+ * linear-looking API produces.
+ *
+ * The cursor below is the whole fix. Nothing about the traversal ORDER,
+ * de-duplication, or the set of nodes visited changes — a caller gets exactly
+ * the sequence its own loop produced, and the dedup guard (first occurrence
+ * wins, a cycle terminates) is the one every copy already had.
+ */
+
+import type { EditorNode, HierarchyProvider } from '@volter/editor-project/adapter';
+
+/** The two members every walker here needs; deliberately not the whole provider. */
+export type WalkableHierarchy = Pick<HierarchyProvider, 'roots' | 'node'>;
+
+export interface HierarchyWalkOptions {
+  /**
+   * Extra children to enqueue behind `id`'s own — the Light Explorer's revealed
+   * internals, which are reachable through the adapter but not through
+   * `childIds`. Already-visited ids are dropped by the same guard as any other
+   * child, so an internal that is also a projected child is visited once.
+   */
+  readonly extraChildren?: (id: string) => Iterable<EditorNode> | undefined;
+}
+
+/**
+ * Visit every reachable node breadth-first, each id exactly once.
+ *
+ * Return `false` from `visit` to STOP the walk — the early-exit searches
+ * (`authoringDocumentSourcePath`) are why this takes a callback rather than
+ * only returning an array: a search that answers on the first row must not pay
+ * for a full walk of a 20 000-node tree first.
+ */
+export function forEachHierarchyNode(
+  hierarchy: WalkableHierarchy,
+  visit: (node: EditorNode) => boolean | void,
+  options: HierarchyWalkOptions = {},
+): void {
+  const queue: EditorNode[] = [...hierarchy.roots()];
+  const seen = new Set<string>();
+  // A CURSOR, never `shift()`. See this file's header for the measurement.
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const node = queue[cursor]!;
+    if (seen.has(node.id)) continue;
+    seen.add(node.id);
+    if (visit(node) === false) return;
+    for (const childId of node.childIds) {
+      const child = hierarchy.node(childId);
+      if (child) queue.push(child);
+    }
+    for (const extra of options.extraChildren?.(node.id) ?? []) queue.push(extra);
+  }
+}
+
+/** Every reachable node, breadth-first, de-duplicated by id. */
+export function hierarchyNodesBreadthFirst(
+  hierarchy: WalkableHierarchy,
+  options: HierarchyWalkOptions = {},
+): EditorNode[] {
+  const nodes: EditorNode[] = [];
+  forEachHierarchyNode(
+    hierarchy,
+    (node) => {
+      nodes.push(node);
+    },
+    options,
+  );
+  return nodes;
+}

package/src/history/editor-session.ts

@@ -0,0 +1,25 @@
+import { HistoryCommands } from './history-commands';
+import { connectHistoryLimitNotices } from './history-limit-notices';
+import { HistoryService, type HistoryServiceOptions } from './history-service';
+
+/** Owns project-lifetime editor services; disposed when EditorProvider unmounts. */
+export class EditorSession {
+  readonly history: HistoryService;
+  readonly historyCommands: HistoryCommands;
+  private readonly releaseLimitNotices: () => void;
+
+  constructor(
+    readonly projectIdentity: string,
+    historyOptions: HistoryServiceOptions = {},
+  ) {
+    this.history = new HistoryService(historyOptions);
+    this.historyCommands = new HistoryCommands(this.history);
+    this.releaseLimitNotices = connectHistoryLimitNotices(this.history);
+  }
+
+  dispose(): void {
+    this.releaseLimitNotices();
+    this.historyCommands.dispose();
+    this.history.dispose();
+  }
+}

package/src/history/history-commands.ts

@@ -0,0 +1,147 @@
+import type { HistoryService } from './history-service';
+
+export interface HistoryCommandSnapshot {
+  readonly version: number;
+  readonly busy: boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  readonly undoLabel: string | null;
+  readonly redoLabel: string | null;
+}
+
+/** Shell command surface for the one project HistoryService timeline. */
+export class HistoryCommands {
+  private tail: Promise<void> = Promise.resolve();
+  private readonly listeners = new Set<() => void>();
+  private pending = 0;
+  private version = 0;
+  private disposed = false;
+  private readonly idleWaiters = new Set<{
+    unsubscribe: () => void;
+    reject: (error: Error) => void;
+  }>();
+  private readonly unsubscribeHistory: () => void;
+  private snapshot: HistoryCommandSnapshot;
+
+  constructor(private readonly history: HistoryService) {
+    this.snapshot = this.buildSnapshot();
+    this.unsubscribeHistory = history.subscribe(this.notify);
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    if (this.disposed) return () => undefined;
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  getSnapshot = (): HistoryCommandSnapshot => this.snapshot;
+
+  undo(): Promise<boolean> {
+    return this.enqueue(async () => {
+      await this.waitForServiceIdle();
+      this.assertNotDisposed();
+      return this.history.undo();
+    });
+  }
+
+  redo(): Promise<boolean> {
+    return this.enqueue(async () => {
+      await this.waitForServiceIdle();
+      this.assertNotDisposed();
+      return this.history.redo();
+    });
+  }
+
+  jumpTo(cursor: number): Promise<boolean> {
+    return this.enqueue(async () => {
+      await this.waitForServiceIdle();
+      this.assertNotDisposed();
+      return this.history.jumpTo(cursor);
+    });
+  }
+
+  get canUndo(): boolean {
+    return this.snapshot.canUndo;
+  }
+
+  get canRedo(): boolean {
+    return this.snapshot.canRedo;
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unsubscribeHistory();
+    const error = new Error('History commands are disposed.');
+    for (const waiter of this.idleWaiters) {
+      waiter.unsubscribe();
+      waiter.reject(error);
+    }
+    this.idleWaiters.clear();
+    this.listeners.clear();
+    this.notify();
+  }
+
+  private enqueue(operation: () => Promise<boolean>): Promise<boolean> {
+    if (this.disposed) return Promise.reject(new Error('History commands are disposed.'));
+    this.pending++;
+    this.notify();
+    const run = () => {
+      if (this.disposed) throw new Error('History commands are disposed.');
+      return operation();
+    };
+    const result = this.tail.then(run, run);
+    this.tail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result.finally(() => {
+      this.pending--;
+      this.notify();
+    });
+  }
+
+  private assertNotDisposed(): void {
+    if (this.disposed) throw new Error('History commands are disposed.');
+  }
+
+  private waitForServiceIdle(): Promise<void> {
+    if (this.disposed) return Promise.reject(new Error('History commands are disposed.'));
+    if (!this.history.getSnapshot().busy) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const waiter: {
+        unsubscribe: () => void;
+        reject: (error: Error) => void;
+      } = { unsubscribe: () => undefined, reject };
+      const finish = () => {
+        waiter.unsubscribe();
+        this.idleWaiters.delete(waiter);
+      };
+      waiter.unsubscribe = this.history.subscribe(() => {
+        if (this.history.getSnapshot().busy) return;
+        finish();
+        resolve();
+      });
+      this.idleWaiters.add(waiter);
+    });
+  }
+
+  private notify = (): void => {
+    this.version++;
+    this.snapshot = this.buildSnapshot();
+    for (const listener of this.listeners) listener();
+  };
+
+  private buildSnapshot(): HistoryCommandSnapshot {
+    const current = this.history.getSnapshot();
+    const busy = this.pending > 0 || current.busy;
+    return {
+      version: this.version,
+      busy,
+      canUndo: !this.disposed && !busy && current.canUndo,
+      canRedo: !this.disposed && !busy && current.canRedo,
+      undoLabel: current.undoLabel,
+      redoLabel: current.redoLabel,
+    };
+  }
+}

package/src/history/history-delegate.ts

@@ -0,0 +1,163 @@
+/**
+ * THERE IS ONE UNDO STACK AND IT IS VS CODE'S `IUndoRedoService`
+ * (ARCHITECTURE-CORE §The core is Code-OSS, "there is one Cmd+Z").
+ *
+ * Two directions cross this module:
+ *
+ * 1. **OUT** — every committed transaction is offered as an ELEMENT
+ *    ({@link emitHistoryElement}), keyed on the document's own file, and the
+ *    frame pushes it as an `IResourceUndoRedoElement` (or an
+ *    `IWorkspaceUndoRedoElement` when it spans several). That is the one-stack
+ *    property: a drag on `MainScene.tsx` and a keystroke in `MainScene.tsx`'s
+ *    text editor undo in order from one list. Elements are recorded even
+ *    before the delegate arrives, so a frame that mounts after the editor's
+ *    first edits pushes what it missed, in order, rather than starting with a
+ *    stack missing its beginning.
+ *
+ * 2. **IN** — the DELEGATE, the frame's own undo, because the editor has undo
+ *    affordances that are not the keyboard: its Edit menu's "Undo <label>",
+ *    the palette, `vgai eval`'s undo verb. Every one of them must reach the
+ *    ONE stack. Without it the Edit menu still names the step (the label comes
+ *    from the last recorded entry) while the click refuses, which is worse
+ *    than no menu item at all.
+ *
+ * `history-service.ts` is the RECORDER: it still stages, applies and can
+ * revert ONE entry by id, and it no longer decides which entry is next.
+ */
+/** One recorded edit, as the owner of undo sees it. */
+export interface HistoryElement {
+  /** The transaction's id — stable, and what {@link HistoryElement.undo}
+   *  addresses back in the service. */
+  readonly id: string;
+  /** User-presentable, already trimmed ("Transform Selection"). */
+  readonly label: string;
+  /**
+   * The project-relative files this edit changed, in the order the
+   * transaction declared them. EMPTY for a session-scoped edit (a live
+   * journal), which is a fact the frame must decide about rather than a
+   * default it may paper over.
+   */
+  readonly resources: readonly string[];
+  /**
+   * THE WORKSPACE DOCUMENT THIS EDIT WAS MADE IN, at the moment it was
+   * recorded — the id, or null when nothing was active.
+   *
+   * MEASURED, and the reason it exists (2026-09-19, the game template in the
+   * frame): a three root's document is NOT one file. Its adapter's own source
+   * path is the root entry `src/world.tsx`, while a gizmo drag on the scene's
+   * HeroBox instance writes `src/scenes/MainScene.tsx` — so "the document's
+   * resource" is a SET that grows with what the person edits, and asking the
+   * undo service about the entry file alone would find nothing to undo. The
+   * document id is the stable thing; WHICH FILE its next undo acts on is the
+   * newest element recorded in it, and this is what lets the frame ask that.
+   *
+   * It is also what keeps the stacks apart: a component view's elements carry
+   * that view's own document id, so a ⌘Z there can never reach the main
+   * scene's — which is the whole of "Component-view Ctrl+Z acts on the MAIN
+   * scene's history".
+   */
+  readonly document: string | null;
+  /** Revert this one entry. `false` when the service refused (conflict,
+   *  expired resource, blocked history) — never a silent no-op. */
+  undo(): Promise<boolean>;
+  redo(): Promise<boolean>;
+}
+
+/**
+ * WHAT THE FRAME DOES WHEN THE EDITOR'S OWN UNDO IS ASKED FOR.
+ *
+ * The keyboard door has `invoke` (frame → editor); this is the other
+ * direction, and it exists because the editor has undo AFFORDANCES that are
+ * not the keyboard: its Edit menu's "Undo <label>", the command palette, and
+ * `vgai eval`'s undo verb all call the same `edit.undo` action. Under the
+ * frame that action must reach the ONE stack, not walk a cursor nobody is
+ * driving — so the frame installs its own undo here and every one of those
+ * affordances keeps working, unchanged, against VS Code's service.
+ *
+ * MEASURED (2026-09-19, the game template in the frame): without this the Edit
+ * menu still read "Undo Set position" — the label comes from the last recorded
+ * entry — while the click refused. A menu that names the step it will not take
+ * is worse than one that is absent.
+ */
+export interface HistoryDelegate {
+  undo(): void;
+  redo(): void;
+  canUndo(): boolean;
+  canRedo(): boolean;
+}
+
+let delegate: HistoryDelegate | null = null;
+/** Who can say which document is active. The host door installs it (that is
+ *  the module that already reads the workspace registry); without one every
+ *  element is honestly document-less rather than wrongly attributed. */
+let documentResolver: (() => string | null) | null = null;
+const ownerListeners = new Set<() => void>();
+const elementListeners = new Set<(element: HistoryElement) => void>();
+/** Everything recorded while a delegate was installed, so a LATE subscriber
+ *  (the bridge mounts after the editor's first edits are possible) can catch
+ *  up rather than start with a stack that is missing its beginning. */
+let recorded: HistoryElement[] = [];
+
+/**
+ * Is the delegate installed? False until it lands — later than the mount,
+ * because a `ServicesAccessor` is valid only for a command's synchronous part,
+ * so the contribution hands the delegate over after the editor is running.
+ * Until then the editor's own cursor answers, which is a real undo with
+ * nowhere else to go rather than a refusal.
+ */
+export function historyDelegateInstalled(): boolean {
+  return delegate !== null;
+}
+
+/**
+ * Install the undo stack every gesture records into, or `null` to withdraw it
+ * — the stack is the workbench's, and a workbench that went away takes it (and
+ * the catch-up buffer of elements recorded for it) with it.
+ */
+export function setHistoryDelegate(next: HistoryDelegate | null): void {
+  if (delegate === next) return;
+  delegate = next;
+  if (!delegate) recorded = [];
+  for (const listener of ownerListeners) listener();
+}
+
+/** The installed delegate, or `null` before it lands. */
+export function historyDelegate(): HistoryDelegate | null {
+  return delegate;
+}
+
+export function subscribeHistoryDelegate(listener: () => void): () => void {
+  ownerListeners.add(listener);
+  return () => ownerListeners.delete(listener);
+}
+
+/**
+ * Offer one committed transaction to the frame. Recorded even before the
+ * delegate arrives — that buffer is what lets a frame that mounts after the
+ * editor's first edits push what it missed, in order, rather than start with a
+ * stack missing its beginning.
+ */
+export function emitHistoryElement(element: Omit<HistoryElement, 'document'>): void {
+  const stamped: HistoryElement = { ...element, document: documentResolver?.() ?? null };
+  recorded.push(stamped);
+  for (const listener of elementListeners) listener(stamped);
+}
+
+/** Install the reader of "which document is active". Called once by the host
+ *  door at boot; passing null removes it (tests). */
+export function setHistoryDocumentResolver(next: (() => string | null) | null): void {
+  documentResolver = next;
+}
+
+/**
+ * Every element recorded so far under frame ownership. The frame reads this
+ * once when it subscribes and pushes what it missed, in order.
+ */
+export function recordedHistoryElements(): readonly HistoryElement[] {
+  return recorded;
+}
+
+export function onHistoryElement(listener: (element: HistoryElement) => void): () => void {
+  elementListeners.add(listener);
+  return () => elementListeners.delete(listener);
+}

package/src/history/history-limit-notices.ts

@@ -0,0 +1,43 @@
+/**
+ * Puts undo-depth pressure in front of the user through the editor's EXISTING
+ * non-fatal channels — no new notification system.
+ *
+ * - `showTransientHint` is the editor's one toast: it reaches a user whose
+ *   History panel is closed, which is the normal case while editing.
+ * - `editorConsole.warn` is the durable log, so someone who has already lost
+ *   undo depth can find out that it happened and why.
+ *
+ * The same two snapshot fields are also readable through the history door;
+ * this module is only the "you are not looking at that panel" half.
+ *
+ * Evictions are logged but deliberately NOT hinted: once a budget is at its
+ * ceiling every further commit evicts, and a toast per commit is noise. The
+ * eviction message carries no running total precisely so `editorConsole`'s
+ * consecutive-duplicate folding collapses the repeats into one counted entry.
+ */
+
+import { editorConsole } from '../editor-console';
+import { showTransientHint } from '../transient-hint';
+import type { HistoryService } from './history-service';
+import type { HistoryEviction, HistoryLimitWarning } from './types';
+
+export function connectHistoryLimitNotices(history: HistoryService): () => void {
+  let seenWarning: HistoryLimitWarning | null = history.getSnapshot().limitWarning;
+  let seenEviction: HistoryEviction | null = history.getSnapshot().lastEviction;
+  return history.subscribe(() => {
+    const { limitWarning, lastEviction } = history.getSnapshot();
+    if (limitWarning !== seenWarning) {
+      seenWarning = limitWarning;
+      // A still-standing warning keeps its object identity, so this fires once
+      // per crossing rather than once per commit spent over the threshold.
+      if (limitWarning) {
+        showTransientHint(limitWarning.message);
+        editorConsole.warn(limitWarning.message, 'history');
+      }
+    }
+    if (lastEviction !== seenEviction) {
+      seenEviction = lastEviction;
+      if (lastEviction) editorConsole.warn(lastEviction.message, 'history');
+    }
+  });
+}