@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/document-viewports.ts

@@ -0,0 +1,120 @@
+/**
+ * A DOCUMENT'S VIEWPORT, as the stage that shows it answers for it: the camera,
+ * the diagnostic view, the grid, framing, a document's own selection and a
+ * photograph of what it draws. The kit's view presentation and its current-view
+ * readout (`EditorView.viewport`) ask here for the active document, so a view
+ * link reaches whichever medium draws that document. A document no stage
+ * registered has no viewport, which is what `EditorView` then says.
+ */
+import type { ComponentType } from 'react';
+import type { CaptureDimensions, EditorView } from '../types';
+
+export type EditorViewViewport = NonNullable<EditorView['viewport']>;
+
+export interface DocumentViewport {
+  /** Camera pose, diagnostic and grid now; null while nothing is drawn yet. */
+  read(): Pick<EditorViewViewport, 'camera' | 'diagnostic' | 'grid'> | null;
+  /** False when this viewport has no such diagnostic view. */
+  setDiagnostic(diagnostic: NonNullable<EditorViewViewport['diagnostic']>): boolean;
+  /** False when this viewport has no such camera. */
+  setCamera(camera: NonNullable<EditorViewViewport['camera']>): boolean;
+  /** False when there is nothing to frame. */
+  frame(target: NonNullable<EditorViewViewport['frame']>): boolean;
+  /** A document that keeps its own selection (an Object3D document) answers
+   *  and applies it here; one that does not uses the shell's. */
+  readonly selection?: {
+    read(): readonly string[];
+    apply(ids: readonly string[]): void;
+  };
+  /** The ids of the objects this stage draws under `name` (a layout selecting
+   *  one named native object). */
+  idsNamed?(name: string): readonly string[];
+  /** Arm the stage's own transform gizmo. */
+  setTransformMode?(mode: 'combined' | 'translate' | 'rotate' | 'scale'): void;
+  /** A PNG data URL of what it draws, when it can render one on demand. */
+  capture?(size?: CaptureDimensions): string | null;
+  /** Settles before a view is applied (an asynchronously mounting document). */
+  prepare?(): Promise<void>;
+  /** The controls this stage adds to its document's header (its shading,
+   *  helpers and capture menus). */
+  readonly HeaderControls?: ComponentType<{ readonly documentId: string; readonly assetPath?: string }>;
+  /**
+   * What the host's transform tools drive on this stage right now: `gizmo` (the
+   * stage's own transform handles, whose header wells configure them), `modal`
+   * (the stage transforms through a door it declared, and has no gizmo to
+   * configure) or `none` (nothing of this stage takes them).
+   */
+  transformTools?(): 'gizmo' | 'modal' | 'none';
+  /** The transform tool strip on the document's shelf. */
+  readonly TransformTools?: ComponentType<{ readonly documentId: string }>;
+  /** The gizmo's header wells (orientation, pivot, snap, options). */
+  readonly TransformControls?: ComponentType<{ readonly documentId: string }>;
+}
+
+const viewports = new Map<string, DocumentViewport>();
+const listeners = new Set<() => void>();
+let version = 0;
+let notificationPending = false;
+
+function changed(): void {
+  // A stage registers from a contribution root's effect. Keep the viewport
+  // immediately readable, but publish its React snapshot outside that commit
+  // so a host subscriber cannot re-enter a pending host commit through it.
+  if (notificationPending) return;
+  notificationPending = true;
+  queueMicrotask(() => {
+    notificationPending = false;
+    version += 1;
+    for (const listener of [...listeners]) listener();
+  });
+}
+
+/** Register the viewport of one document. Returns the removal. */
+export function registerDocumentViewport(documentId: string, viewport: DocumentViewport): () => void {
+  viewports.set(documentId, viewport);
+  changed();
+  return () => {
+    if (viewports.get(documentId) !== viewport) return;
+    viewports.delete(documentId);
+    changed();
+  };
+}
+
+export function subscribeDocumentViewports(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function documentViewportsVersion(): number {
+  return version;
+}
+
+export function documentViewport(documentId: string | null | undefined): DocumentViewport | null {
+  return documentId ? (viewports.get(documentId) ?? null) : null;
+}
+
+const announced = new Map<string, number>();
+
+/**
+ * A DOCUMENT'S STAGE ANNOUNCES ITSELF AS IT RENDERS, before the viewport it will
+ * register exists — the fact an opener's `ready` needs and cannot get from
+ * anywhere else: whether a document mounts a stage is a fact of its MOUNT,
+ * never of its address. Counted, so overlapping mounts of one document (a
+ * revision swap) release in any order. Returns the release.
+ */
+export function announceDocumentStage(documentId: string): () => void {
+  announced.set(documentId, (announced.get(documentId) ?? 0) + 1);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const open = (announced.get(documentId) ?? 0) - 1;
+    if (open > 0) announced.set(documentId, open);
+    else announced.delete(documentId);
+  };
+}
+
+/** Whether a stage for this document has begun mounting. */
+export function documentStageAnnounced(documentId: string): boolean {
+  return (announced.get(documentId) ?? 0) > 0;
+}

package/src/kit/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 `@volter/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 '@volter/sdk/kit/api-build';
+export * from '@volter/sdk/kit/api-logs';
+export * from '@volter/sdk/kit/api-project-identity';
+export * from './api/project-open';
+export * from './api/project-source';
+export * from './api/project-state';
+export * from './api/relay';
+export * from '@volter/sdk/kit/api-worktrees';

package/src/kit/editor-chrome-capture.ts

@@ -0,0 +1,136 @@
+/**
+ * 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. the editor's `screenshot editor` command / `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:
+ *
+ *  - a canvas a medium re-renders at a chosen size — a three.js viewport or
+ *    Object3D document with no `preserveDrawingBuffer` — is drawn by that
+ *    medium (`@volter/sdk/kit/canvas-frames`'s `renderedCanvasFrame`);
+ *  - a live game or Pixi canvas goes through the one `canvasFrame` seam
+ *    every pixel door shares (`live-canvas-frame.ts`).
+ *
+ * Visible iframes are refused: cloning a frame does not capture its browsing
+ * context, so an extension's working UI would otherwise look blank.
+ * 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 { EditorChromeCaptureOptions, EditorView } from '@volter/sdk';
+import { renderedCanvasFrame } from '@volter/sdk/kit/canvas-frames';
+import { type CompositeCapture, capturePlayComposite } from '@volter/sdk/kit/composite-screenshot';
+import { currentEditorView } from './editor-current-view';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import { liveCanvasFrame } from '@volter/sdk/kit/live-canvas-frame';
+import { activeDocumentContainer } from './editor-document-probe';
+import { activeWorkspaceDocumentId } from '@volter/sdk/kit/workspace-document-registry';
+
+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;
+}
+
+/** The capture's options: the SDK's public type, so the client and this kit cannot drift. */
+export type { EditorChromeCaptureOptions };
+
+/** A data URL as something `drawImage` accepts. */
+/**
+ * Same-frame pixels for every canvas the page holds — the seam described in
+ * the header. `null` means "read the canvas directly".
+ */
+function chromeCanvasFrame(scale: number) {
+  return async (canvas: HTMLCanvasElement): Promise<CanvasImageSource | null> => {
+    // A medium's re-render draws at a size WE choose, so it is 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 (`@volter/sdk/kit/canvas-frames`).
+    const size = {
+      width: Math.max(1, Math.round(canvas.clientWidth * scale)),
+      height: Math.max(1, Math.round(canvas.clientHeight * scale)),
+    };
+    return (await renderedCanvasFrame(canvas, size)) ?? 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: ShellStore,
+  options?: EditorChromeCaptureOptions,
+): Promise<EditorChromeCapture> {
+  const page = document.getElementById(EDITOR_CHROME_ROOT_ID);
+  if (!page) {
+    throw new Error(
+      `The editor chrome root (#${EDITOR_CHROME_ROOT_ID}) is not mounted, so there is no editor ` +
+        'page to photograph.',
+    );
+  }
+  // THE DOCUMENT REGION: the same compositor over the active document's own box, so a stage is
+  // photographed with what the person sees over it (its navigation gizmo, its readouts), not
+  // as the document's render alone.
+  let root: HTMLElement = page;
+  if (options?.region === 'document' || options?.region === 'play') {
+    const documentId = activeWorkspaceDocumentId();
+    const box = documentId ? activeDocumentContainer(documentId) : null;
+    if (!box) throw new Error('No active document is showing, so there is no document region to photograph.');
+    root = box;
+    if (options.region === 'play') {
+      const frame = box.querySelector<HTMLElement>('[data-volter-play-frame]');
+      if (!frame || !frame.checkVisibility({checkVisibilityCSS: true, checkOpacity: true})) {
+        throw new Error('The active document has no visible live frame to photograph.');
+      }
+      root = frame;
+    }
+  }
+  const scale = options?.scale ?? window.devicePixelRatio ?? 1;
+  const rect = root.getBoundingClientRect();
+  // cloneNode does not copy a frame's browsing context. In particular, a
+  // working extension webview becomes an empty rectangle in the SVG clone.
+  // Refuse that misleading evidence instead of reporting a successful capture.
+  // The workbench also has a zero-size extension-host frame; it paints nothing.
+  for (const frame of root.querySelectorAll('iframe')) {
+    const box = frame.getBoundingClientRect();
+    if (
+      box.width <= 0 || box.height <= 0 || box.right <= rect.left ||
+      box.left >= rect.right || box.bottom <= rect.top || box.top >= rect.bottom ||
+      !frame.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })
+    ) continue;
+    throw new Error(
+      'Editor chrome capture cannot include a visible iframe or extension webview. ' +
+      'Its content would be missing from the image; this does not mean the live panel is blank. ' +
+      'Use a browser window capture for the whole page, or region: "document" for the active document.',
+    );
+  }
+  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(scale),
+    includeDocumentStyles: true,
+    size,
+  });
+  return { ...composite, view: currentEditorView(store), size, scale };
+}

package/src/kit/editor-commands.ts

@@ -0,0 +1,176 @@
+/**
+ * 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 `volter.<view>.<verb>` id still resolves off
+ *    `@volter/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>;
+  /** The application menu it is an item of, and its label there. */
+  readonly menu?: { readonly id: string; readonly label: string };
+}
+
+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;
+}
+
+/**
+ * Reveal a workbench view by id (`volter.properties`, `volter.outliner`) through its `.focus`
+ * command, which the workbench registers for every view. Without the Code-OSS frame there is
+ * no workbench and the editor's own panels are in the page, so there is nothing to reveal.
+ */
+export function revealWorkbenchView(viewId: string): void {
+  if (!commandExecutor) return;
+  void Promise.resolve(commandExecutor(`${viewId}.focus`)).catch(() => {});
+}
+
+/** The `volter.<view>.<verb>` shape the views registry keys, and the ONLY id
+ *  shape standalone can answer. */
+const VIEW_VERB_COMMAND = /^volter\.([^.]+)\.(.+)$/;
+
+/**
+ * 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
+ * the editor's `eval` command 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 " +
+        'volter.<view>.<verb> (for example volter.blender-node-view.view-all).',
+    );
+  }
+  const { invokeViewVerb } = await import('@volter/sdk/views');
+  return invokeViewVerb(
+    parts[1] as string,
+    parts[2] as string,
+    args as Record<string, unknown> | undefined,
+  );
+}