@volter/editor-core 0.5.57

package/src/document-preview-source.ts

@@ -0,0 +1,20 @@
+import type { EditorCameraState } from '@volter/editor-sdk';
+
+export const DOCUMENT_PREVIEW_WIDTH = 320;
+export const DOCUMENT_PREVIEW_HEIGHT = 180;
+export const DOCUMENT_PREVIEW_RECIPE = 'document-preview-v4';
+
+export interface DocumentPreviewCaptureRequest {
+  readonly width: number;
+  readonly height: number;
+  readonly camera?: EditorCameraState | undefined;
+}
+
+/** The document owner supplies pixels and dependency identity; the host owns
+ * scheduling, disk cache, visibility priority, and tile state. */
+export interface DocumentPreviewSource {
+  /** Stable identity for source and imported-dependency state. */
+  revision(): string;
+  subscribe(listener: () => void): () => void;
+  capture(request: DocumentPreviewCaptureRequest): Promise<string>;
+}

package/src/document-renderer-session.ts

@@ -0,0 +1,138 @@
+import {
+  isEditorPresentationActive,
+  subscribeEditorPresentationActivity,
+} from './editor-presentation-activity';
+
+/**
+ * The frame-loop + renderer lifetime for one Object3D document viewport.
+ *
+ * Deactivate ≠ dispose.
+ *
+ * The layout host keeps every open document mounted. A tab
+ * flip only flips `active`. Destroying the `WebGLRenderer` on deactivate is
+ * a full context teardown + recreate on the next flip — measured live on
+ * `examples/third-person` at 4296 ms for the first 3D-board activation and
+ * 4015 ms for the second (doctor `--timings-only`). Pause the RAF loop
+ * instead; the canvas keeps its last frame and the program cache / IBL bake
+ * survive. Real document CLOSE unmounts the host, and {@link dispose} is the
+ * one path that frees the context.
+ */
+
+export class DocumentRendererSession {
+  private rafId = 0;
+  private running = false;
+  private disposed = false;
+  private active = false;
+  private readonly unsubscribeActivity: () => void;
+
+  constructor(
+    private readonly frame: (time: number, resumed: boolean) => void,
+    private readonly releaseRenderer: () => void,
+  ) {
+    this.unsubscribeActivity = subscribeEditorPresentationActivity(() => this.syncActivity());
+  }
+
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Tab flip. `false` pauses the loop and keeps the GPU surface. `true`
+   * resumes it. Neither constructs nor disposes a renderer.
+   */
+  setActive(active: boolean): void {
+    if (this.disposed) return;
+    this.active = active;
+    this.syncActivity();
+  }
+
+  private syncActivity(): void {
+    if (this.active && isEditorPresentationActive()) this.start();
+    else this.stop();
+  }
+
+  /** Resizing clears the drawing buffer. Repaint immediately while visible;
+   * a suspended document redraws as soon as its presentation resumes. */
+  redraw(): void {
+    if (this.running && !this.disposed && isEditorPresentationActive()) {
+      this.guardedFrame(performance.now());
+    }
+  }
+
+  /** The one teardown path — document CLOSE / host unmount. */
+  dispose(): void {
+    this.stop();
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unsubscribeActivity();
+    this.releaseRenderer();
+  }
+
+  private start(): void {
+    if (this.disposed || this.running) return;
+    this.running = true;
+    // A tab activation is a direct request to present this document. Draw one
+    // frame in the activation turn, then join the browser's animation clock.
+    // Waiting for the first rAF made a visible tab inherit Chromium's former
+    // background cadence (the 1 Hz signature) even when the page itself was
+    // visible; users saw the old canvas for that whole interval. Subsequent
+    // presentation remains ordinary rAF-driven work.
+    // Let content reset its delta baseline without advancing by the hidden interval.
+    this.guardedFrame(performance.now(), true);
+    if (!this.running || this.disposed) return;
+    this.rafId = requestAnimationFrame(this.tick);
+  }
+
+  /** The last frame's failure text, so a persistent fault narrates ONCE
+   *  rather than sixty times a second, and a recovered loop resets. */
+  private lastFrameFailure: string | null = null;
+
+  /**
+   * One frame, and the loop survives it. A throw out of a rAF callback used
+   * to be the end of this document's presentation: the exception left
+   * `tick` before it rescheduled, so the stage froze on whatever it last
+   * drew and nothing said why. Measured (2026-09-04, the mesh document's
+   * session swap): three's "Cannot read properties of null (reading
+   * 'precision')" from one frame drawn between a disposed overlay and the
+   * scene swap killed the stage for the rest of the session. The frame's
+   * failure goes to the console WITH its stack — that is what reaches the
+   * doors — and the next frame is drawn, because a transient race recovers
+   * on its own and a persistent fault is still better shown than frozen.
+   */
+  private guardedFrame(time: number, resumed = false): void {
+    try {
+      this.frame(time, resumed);
+      this.lastFrameFailure = null;
+    } catch (caught) {
+      const text = caught instanceof Error ? caught.message : String(caught);
+      if (text !== this.lastFrameFailure) {
+        this.lastFrameFailure = text;
+        // biome-ignore lint/suspicious/noConsole: a document frame that threw must narrate itself
+        console.error('[document renderer] a frame threw; the loop continues:', caught);
+      }
+    }
+  }
+
+  private stop(): void {
+    this.running = false;
+    if (this.rafId !== 0) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = 0;
+    }
+  }
+
+  private readonly tick = (time: number): void => {
+    if (!this.running || this.disposed) return;
+    if (!isEditorPresentationActive()) {
+      this.stop();
+      return;
+    }
+    this.guardedFrame(time);
+    if (!this.running || this.disposed) return;
+    this.rafId = requestAnimationFrame(this.tick);
+  };
+}

package/src/editor-api.ts

@@ -0,0 +1,46 @@
+/**
+ * Editor server SDK.
+ *
+ * All frontend code should use this module instead of calling fetch()/EventSource
+ * with raw endpoint URLs.
+ *
+ * The project's `public/` file operations (`listAssets`, `saveFile`) are routed
+ * through the backend-agnostic `StorageBackend` (see ./storage): `HttpStorage`
+ * over the same `/__editor/*` routes, wrapped by the frame's file door once
+ * that lands. The remaining endpoints are NOT `public/` file ops — the
+ * launcher's own reads, the play-log writes, the asset library, and the
+ * user-triggered actions (`createProject`, `browseFolder`,
+ * `openProjectOnServer`, `revealInFinder`, `startExport`,
+ * `downloadOnlineAsset`).
+ */
+
+export type { EditorEventSource } from './editor-presence';
+export { connectEvents, connectTabPresence, reportTabRoute } from './editor-presence';
+
+// ---------------------------------------------------------------------------
+// The families. This path stays the ONE import site for the editor server SDK
+// — every name below was exported from here before the split and still is, so
+// no caller changed. What changed is that a reader looking for "how does the
+// editor talk to the worktree board" now opens `api/worktrees.ts` instead of
+// scrolling an 1,900-line file.
+// ---------------------------------------------------------------------------
+
+// `./api/agents` is DELIBERATELY NOT RE-EXPORTED HERE (phase 1 unit 22). It is
+// the page-side client for the coding-harness routes, and `@vgai/agents`'s
+// modules have always imported `@editor/api/agents` directly rather than
+// through this barrel — so the family's claim above ("every name was exported
+// from here before the split and still is") was already not how its one
+// consumer reads it. What the row bought instead was a static edge from every
+// importer of this file into the agents lane's whole wire, which is what held
+// four files in the editor's eager closure after the last host caller left.
+// The rule is unit 13's, found on the view presenter: a door every package
+// calls must not carry every lane's implementation.
+export * from './api/assets';
+export * from './api/build';
+export * from './api/logs';
+export * from './api/project-identity';
+export * from './api/project-open';
+export * from './api/project-source';
+export * from './api/project-state';
+export * from './api/relay';
+export * from './api/worktrees';

package/src/editor-chrome-capture.ts

@@ -0,0 +1,139 @@
+/**
+ * THE CHROME-CAPTURE DOOR: photograph the editor PAGE — every panel, every
+ * tab strip, the Inspector, the viewport inside it — as the person is seeing
+ * it. `vgai screenshot editor` / `editor.captureEditorChrome()`.
+ *
+ * WHY IT EXISTS. Every other capture door photographs a SUBJECT: the running
+ * game, the active document, the Scene viewport, a model. None photographs
+ * the editor itself, so a contribution author — human or agent — could not
+ * run the sighted render→look→revise loop on a panel through the product, and
+ * every dev-surface wave so far was built blind, on DOM probes (WORK.md, "The
+ * chrome-capture door"). A skin, a workspace arrangement or a new region
+ * cannot be judged at all without this.
+ *
+ * HOW. The same compositor the active-document door uses
+ * (`composite-screenshot.ts`), pointed at `#editor-chrome-root` — the ONE
+ * theme scope (ARCHITECTURE-CORE §Editor chrome) — with `includeDocumentStyles`
+ * on, so the design system's stylesheet rides the clone and chrome
+ * photographs as it appears. Three kinds of canvas sit inside that root and
+ * only one of them can be read late:
+ *
+ *  - the Scene viewport's canvas has no `preserveDrawingBuffer`; its pixels
+ *    come from its registered presenter, including camera preview and helpers;
+ *    the store's offscreen render is the fallback before registration;
+ *  - an Asset Lab 3D document's canvas is the same story through its
+ *    session (`Object3DDocumentSession.captureImage`);
+ *  - a live game or Pixi canvas goes through the one `canvasFrame` seam
+ *    every pixel door shares (`live-canvas-frame.ts`).
+ *
+ * Everything else reads directly. A canvas this module cannot recognise or
+ * re-render photographs as the browser hands it back — possibly black — and
+ * `layers.canvases` says how many were drawn, so a reader can tell a black
+ * panel from a missing one.
+ */
+
+import type { EditorView } from '@volter/editor-sdk';
+import { allObject3DDocumentSessions } from './authoring/object3d-document-session-registry';
+import { type CompositeCapture, capturePlayComposite } from './composite-screenshot';
+import { currentEditorView } from './editor-current-view';
+import type { EditorShellStore } from './editor-shell-store';
+import { liveCanvasFrame } from './live-canvas-frame';
+
+export const EDITOR_CHROME_ROOT_ID = 'editor-chrome-root';
+
+export interface EditorChromeCapture extends CompositeCapture {
+  /** The view the page was showing when the frame was taken. */
+  view: EditorView;
+  /** The frame's own size, in OUTPUT pixels. */
+  size: { width: number; height: number };
+  /** Output pixels per CSS pixel — what one pixel of {@link size} is. A
+   *  reference frame captured on a 2x display is judged against `scale: 2`. */
+  scale: number;
+}
+
+export interface EditorChromeCaptureOptions {
+  /**
+   * Output pixels per CSS pixel. Defaults to the page's own
+   * `devicePixelRatio`, so the default frame is the pixels the display holds.
+   *
+   * A stroke weight, a 1 px border or a glyph edge cannot be judged below the
+   * resolution it is being compared against — on a DPR-1 monitor the default
+   * is 1 and a reference captured at 2x is only comparable if this is asked
+   * for explicitly. It scales the DOM leg by rasterizing it through a viewBox
+   * (crisp at any factor); canvases are limited by their own backing store and
+   * are upscaled past it.
+   */
+  scale?: number;
+}
+
+/** A data URL as something `drawImage` accepts. */
+async function imageOf(dataUrl: string): Promise<HTMLImageElement> {
+  const image = new Image();
+  image.src = dataUrl;
+  await image.decode();
+  return image;
+}
+
+/**
+ * Same-frame pixels for every canvas the page holds — the seam described in
+ * the header. `null` means "read the canvas directly".
+ */
+function chromeCanvasFrame(store: EditorShellStore, scale: number) {
+  return async (canvas: HTMLCanvasElement): Promise<CanvasImageSource | null> => {
+    // The re-render fallbacks below draw at a size WE choose, so they are asked
+    // for the frame's own scale — a 2x capture whose viewport had to be
+    // re-rendered gets a 2x render, not a 1x one stretched. The presented-frame
+    // paths above them hand back the live buffer at its own backing-store size,
+    // which is the ceiling those legs have.
+    const size = {
+      width: Math.max(1, Math.round(canvas.clientWidth * scale)),
+      height: Math.max(1, Math.round(canvas.clientHeight * scale)),
+    };
+    if (store.viewportCanvas() === canvas) {
+      const presented = await liveCanvasFrame(canvas);
+      if (presented) return presented;
+      const dataUrl = store.captureViewportImage(size);
+      return dataUrl ? imageOf(dataUrl) : null;
+    }
+    for (const session of allObject3DDocumentSessions()) {
+      if (session.renderer.domElement !== canvas) continue;
+      // The PRESENTED frame first: everything the host drew over the
+      // document's own render — the compass above all — lives only in the
+      // default framebuffer, and `captureImage` is an offscreen re-render of
+      // the subject alone (see `requestPresentedFrame`). Falling back to it
+      // keeps a stopped loop photographable.
+      const presented = await session.requestPresentedFrame();
+      if (presented) return presented;
+      const dataUrl = session.captureImage(size);
+      return dataUrl ? imageOf(dataUrl) : null;
+    }
+    return liveCanvasFrame(canvas);
+  };
+}
+
+/** Photograph the editor page. Throws, by name, when the chrome root is not
+ *  mounted — a page that is not the editor has nothing to photograph. */
+export async function captureEditorChrome(
+  store: EditorShellStore,
+  options?: EditorChromeCaptureOptions,
+): Promise<EditorChromeCapture> {
+  const root = document.getElementById(EDITOR_CHROME_ROOT_ID);
+  if (!root) {
+    throw new Error(
+      `The editor chrome root (#${EDITOR_CHROME_ROOT_ID}) is not mounted, so there is no editor ` +
+        'page to photograph.',
+    );
+  }
+  const scale = options?.scale ?? window.devicePixelRatio ?? 1;
+  const rect = root.getBoundingClientRect();
+  const size = {
+    width: Math.max(1, Math.round(rect.width * scale)),
+    height: Math.max(1, Math.round(rect.height * scale)),
+  };
+  const composite = await capturePlayComposite(root, {
+    canvasFrame: chromeCanvasFrame(store, scale),
+    includeDocumentStyles: true,
+    size,
+  });
+  return { ...composite, view: currentEditorView(store), size, scale };
+}

package/src/editor-commands.ts

@@ -0,0 +1,164 @@
+/**
+ * THE EDITOR'S COMMANDS: the ONE table of what its palette actions ARE, and
+ * the ONE door to running a command by id.
+ *
+ * 1. **The ACTION TABLE.** What the palette lists, published as DATA so the
+ *    frame can register one VS Code command plus one
+ *    `MenuId.CommandPalette` item per entry — which is what makes ⌘⇧P list
+ *    OUR actions with OUR labels. `components/palette-action-publisher.tsx`
+ *    is its one author.
+ *
+ * ## Why this is published at RUNTIME and the keymap is GENERATED
+ *
+ * The chords are a generated built-in extension because a keybinding rule
+ * registered after `workbench.common.main.ts` has loaded is INERT, and the
+ * chords are package data known at build time. Neither half holds here,
+ * measured 2026-09-19:
+ *
+ *   - A MENU ITEM registered late is not inert. `MenuRegistry` fires
+ *     `onDidChangeMenu` and the palette rebuilds its picks on every open
+ *     (`commandsQuickAccess.ts`'s `getGlobalCommandPicks`), which is how
+ *     every extension-contributed command reaches ⌘⇧P.
+ *   - The table is not static. Its ids are a different namespace from the
+ *     keymap's (`editor.undo` here, `edit.undo` there), several labels are
+ *     templated per selection (`View Through <camera name>`), and the
+ *     entity, tool-document, board-open and package-contributed (`tool:*`)
+ *     entries do not exist until something mounts or a package loads.
+ *
+ * So the generator is left alone and the frame reads a live table instead.
+ *
+ * 2. **`editor.command(id, args)`**, the door a product surface drives a VIEW
+ *    through. `editor.document.*` reaches only the ACTIVE CENTRE DOCUMENT by
+ *    its own contract, so every drawer utility — Console, Profiler, Network,
+ *    the node editor — was undrivable until this existed; a walk looking for
+ *    one tried `editor.view`, `editor.frame` and `editor.present` in turn and
+ *    was refused by each, because there was no door.
+ *
+ *    It is the frame's `ICommandService.executeCommand`, installed by the
+ *    contribution, so ANY workbench command id is reachable — ours and
+ *    upstream's alike. That is the point of running inside a workbench.
+ *    Before the executor lands, a `vgai.<view>.<verb>` id still resolves off
+ *    `@volter/editor-sdk/views` — the same table the frame's command would have
+ *    called — and any OTHER id is refused BY NAME, because a silent nothing
+ *    is how an agent concludes a command "did not work".
+ */
+/**
+ * How the frame opens ITS palette when one of our own actions asks for one
+ * (`view.commandPalette`, whose chord U6 left unbound under the frame because
+ * ⌘K is VS Code's chord prefix). Installed by the contribution after the
+ * bridge has mounted; absent, the action is refused rather than silently
+ * toggling a palette nobody renders.
+ */
+let paletteOpener: (() => void) | null = null;
+
+export function setPaletteOpener(open: (() => void) | null): void {
+  paletteOpener = open;
+}
+
+/** Open the command palette. `false` before the opener lands — the window
+ *  between the bridge mounting and the contribution's `setPaletteOpener`. */
+export function openCommandPalette(): boolean {
+  if (!paletteOpener) return false;
+  paletteOpener();
+  return true;
+}
+
+export interface PaletteActionEntry {
+  readonly id: string;
+  readonly label: string;
+  /** `action` | `entity` | `asset`, as `action-registry.ts` spells it. */
+  readonly category: string;
+  readonly run: () => void | Promise<void>;
+}
+
+let entries: readonly PaletteActionEntry[] = [];
+let entriesVersion = 0;
+const entryListeners = new Set<() => void>();
+
+/**
+ * Publish the table the palette would list. Called from the editor's own
+ * tree (`components/palette-action-publisher.tsx`) so the hooks that build it
+ * — the shell store, the history commands, the contributed-chrome version —
+ * are read exactly where React reads them, rather than reached for out of
+ * band. The array is replaced, never merged: the builders return the whole
+ * live set each time.
+ */
+export function publishPaletteActions(next: readonly PaletteActionEntry[]): void {
+  entries = next;
+  entriesVersion++;
+  for (const listener of entryListeners) listener();
+}
+
+/** Every palette action the editor currently offers. */
+export function paletteActions(): readonly PaletteActionEntry[] {
+  return entries;
+}
+
+export function paletteActionsVersion(): number {
+  return entriesVersion;
+}
+
+export function subscribePaletteActions(listener: () => void): () => void {
+  entryListeners.add(listener);
+  return () => entryListeners.delete(listener);
+}
+
+/**
+ * Run one palette action by id — the door the workbench's own command calls.
+ * `false` means the editor no longer has that entry (a selection changed, a
+ * tool document closed, a package unloaded), which the caller reports by name
+ * rather than swallowing.
+ */
+export function invokePaletteAction(id: string): boolean {
+  const entry = entries.find((candidate) => candidate.id === id);
+  if (!entry) return false;
+  void entry.run();
+  return true;
+}
+
+/**
+ * The workbench's command service, handed over by the contribution once it has
+ * one. Installed AFTER the bridge mounts, for the reason every other seam
+ * here states: a `ServicesAccessor` is valid only inside the synchronous part
+ * of a command's invocation.
+ */
+let commandExecutor: ((id: string, args?: unknown) => unknown) | null = null;
+
+export function setCommandExecutor(run: ((id: string, args?: unknown) => unknown) | null): void {
+  commandExecutor = run;
+}
+
+/** The `vgai.<view>.<verb>` shape the views registry keys, and the ONLY id
+ *  shape standalone can answer. */
+const VIEW_VERB_COMMAND = /^vgai\.([^.]+)\.(.+)$/;
+
+/**
+ * Run a command by id — `editor.command(id, args)`'s one implementation.
+ *
+ * The workbench's `ICommandService` when it has landed; before that, the
+ * views registry, reached through a DYNAMIC import so a module only a
+ * `vgai eval` reaches never joins the editor entry's static closure.
+ *
+ * A refusal is always BY NAME. `invokeViewVerb` names the view's whole
+ * vocabulary when it does not carry the verb (that refusal is the VIEW's, and
+ * moving it here would put it somewhere the view does not draw), and an id
+ * that is not a view verb at all is refused with the shape that would have
+ * worked.
+ */
+export async function executeCommand(id: string, args?: unknown): Promise<unknown> {
+  if (commandExecutor) return await commandExecutor(id, args);
+  const parts = VIEW_VERB_COMMAND.exec(id);
+  if (!parts) {
+    throw new Error(
+      `No command "${id}". Without the Code-OSS frame there is no command service, so the ` +
+        "only commands this editor answers are a view's own verbs, spelled " +
+        'vgai.<view>.<verb> (for example vgai.blender-node-view.view-all).',
+    );
+  }
+  const { invokeViewVerb } = await import('@volter/editor-sdk/views');
+  return invokeViewVerb(
+    parts[1] as string,
+    parts[2] as string,
+    args as Record<string, unknown> | undefined,
+  );
+}