@volter/live 0.0.0-stage → 0.5.204

package/dist/member-hints.d.ts

@@ -0,0 +1,29 @@
+/**
+ * NAMES AN AGENT REACHES FOR THAT THE FAÇADE DOES NOT HAVE, and where the
+ * thing it wanted actually lives.
+ *
+ * Why this exists (measured 2026-10, an agent building an obby in the Model
+ * Editor): it called `editor.setCamera(...)`, got the engine's bare
+ * "editor.setCamera is not a function", searched for a camera verb, and in the
+ * end improvised a pose from `frame()` and `orbit()`. The camera was reachable
+ * the whole time — through `editor.present`'s `viewport.camera` — but the
+ * failure said nothing about it. The refusal is the one moment the caller is
+ * certainly reading, so that is where the pointer goes.
+ *
+ * TARGETED, NOT A CATCH-ALL. Only the names below are intercepted, each with
+ * the door it was looking for. Every other missing member keeps JavaScript's
+ * own behaviour (`undefined`, then the engine's TypeError), so this table can
+ * never turn a typo into a wrong suggestion — it only ever adds what is known.
+ */
+/** The pointer for a member `editor` does not have, or undefined when there is none to give. */
+export declare function editorMemberHint(member: PropertyKey): string | undefined;
+/**
+ * `editor` as `eval` binds it: the same object, except that reading one of the
+ * hinted names it does NOT have throws the hint, naming `binding.member`.
+ * Thrown on READ, not on call, so `editor.camera.position` is caught as well as
+ * `editor.setCamera(...)`.
+ *
+ * Methods come back bound to the real object: `LiveEditor` keeps its client in
+ * a `#`-private field, which a call whose `this` is the proxy cannot read.
+ */
+export declare function withEditorMemberHints<T extends object>(target: T, binding?: string): T;

package/dist/session.d.ts

@@ -0,0 +1,32 @@
+/** Resolve an existing session for exactly one project.
+ * Prefer the project's hint, verify it against the served canonical path,
+ * then consult the shared registry. Never fall back to another project.
+ * Storage identifiers move with the server in the coordinated migration. */
+import { type SessionListingTransport as SessionDiscoveryTransport } from '@volter/sdk/session/discovery';
+/** Nearest ancestor containing the project's canonical manifest. */
+export declare function findProjectRootFrom(dir: string): string | null;
+/** The minimal slice of `EditorTransport` `resolveSession` actually needs — narrower than the full interface so a test double only has to implement one method. */
+export type SessionListingTransport = SessionDiscoveryTransport;
+export interface ResolvedSession {
+    /** Editor dev-server port the resolved session is listening on. */
+    port: number;
+    /** Absolute project root — the nearest ancestor of the requested directory containing `volter.project.json`. */
+    projectRoot: string;
+}
+export interface SessionResolutionDeps {
+    /** Session listing + liveness verification — defaults to a real `HttpSessionDiscovery`. Overridable for tests. */
+    transport?: SessionListingTransport;
+    /** Project-root discovery — defaults to the real fs walk (`findProjectRootFrom` above). Overridable for tests. */
+    findProjectRootFrom?: (dir: string) => string | null;
+    /** Project-local session hint reader. Defaults to `.volter/session.json`. */
+    readProjectSession?: (projectRoot: string) => ProjectSessionHint | null;
+    /** Exact-session verifier. Defaults to GET /__editor/project + canonical project matching. */
+    verifyProjectSession?: (hint: ProjectSessionHint, projectRoot: string) => Promise<boolean>;
+}
+export interface ProjectSessionHint {
+    port: number;
+    pid: number;
+    url: string;
+    startedAt: string;
+}
+export declare function resolveSession(projectDir?: string, deps?: SessionResolutionDeps): Promise<ResolvedSession>;

package/dist/singleton.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A tiny memoized-async-factory primitive — the machinery behind
+ * `index.ts`'s lazy top-level `editor`/`tools` singletons. Pulled into
+ * its own module (rather than inlined) so it's independently unit-testable
+ * with a fake factory, with no need to exercise a real `connect()` (session
+ * discovery, network) just to prove "two accesses, one connect".
+ *
+ * Caches the in-flight PROMISE, not just the resolved value — two callers
+ * racing `ensure()` before the first resolves still share the SAME
+ * connection attempt, not two independent ones.
+ */
+export interface LazySession<T> {
+    /** Returns the memoized promise, creating it via `factory()` on first call. */
+    ensure(): Promise<T>;
+    /** Clears the memo — the NEXT `ensure()` calls `factory()` again. Exposed for tests (and for a caller that deliberately wants to reconnect); not needed in ordinary use. */
+    reset(): void;
+}
+export declare function createLazySession<T>(factory: () => Promise<T>): LazySession<T>;

package/dist/tools.d.ts

@@ -0,0 +1,23 @@
+/** Registered project tools over the current shared editor session. */
+import type { EditorClient, ProjectToolCatalog, ProjectToolCatalogEntry, ProjectToolOutcome } from '@volter/sdk';
+export declare class LiveTools {
+    #private;
+    constructor(client: EditorClient);
+    /** Enumerate the exact `package.json#volter.tools` catalog without executing it. */
+    list(): Promise<ProjectToolCatalog>;
+    /** Return one tool's discoverable metadata, or `null` when it is not registered. */
+    describe(name: string): Promise<ProjectToolCatalogEntry | null>;
+    /**
+     * Invoke the same validated callable used by the editor and CLI.
+     *
+     * `instance` names WHICH mounted instance the tool should drive when several
+     * are live (multiplayer authoring) — it reaches the tool as `ctx.instance`,
+     * and a tool that drives the game binds
+     * `game.instance(ctx.instance)` from it. Omitted is the single-instance case;
+     * the tool then targets the sole live instance, exactly as before.
+     */
+    run(name: string, input?: unknown, options?: {
+        confirm?: boolean;
+        instance?: string;
+    }): Promise<ProjectToolOutcome>;
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@volter/live",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "author": "Volter AI, Inc.",
+  "version": "0.5.204",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Attach to Volter Editor sessions for document and modeling automation.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/editor.git",
+    "directory": "packages/live"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md",
+    "BUNDLED_NOTICES"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@volter/sdk": "0.5.204",
+    "@volter/project": "0.5.204",
+    "undici": "^7.28.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.25.12"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json && node build.mjs",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test test/session.test.mjs"
+  }
+}

package/src/editor-document.ts

@@ -0,0 +1,270 @@
+/**
+ * `editor.document` — the session binding for the scoped editor-chrome door.
+ *
+ * WHY IT IS A SEPARATE OBJECT, and why the verbs are these, is recorded once
+ * in the implementation's header
+ * (`packages/sdk/src/kit/editor-document-probe.ts`); the short version is that
+ * `game.page()` is play-mode-gated and rooted at the GAME container, so an
+ * editor surface that is not a running game could be neither read nor driven
+ * through the product.
+ *
+ * WHAT IT ADDRESSES is a closed VOCABULARY of named surfaces, passed as
+ * `{ scope }` on every verb:
+ *
+ *   `document` (default) the active centre document's whole box
+ *   `header` / `shelf`   that document's toolbar strip / tool rail
+ *   `rail`               the PROPERTIES view — its tabs, sections and fields
+ *   `outliner`           the OUTLINER view — its rows and their controls
+ *   `content`            the CONTENT view — its categories and asset rows
+ *   `menubar`            the APPLICATION MENUS (Edit, View, …) and the menus they open
+ *
+ *   await editor.document.click('[data-testid=app-menu-edit]', { scope: 'menubar' });
+ *   await editor.document.query('[role=tab]', { scope: 'rail' });
+ *   await editor.document.click('[data-testid=properties-tab-modifiers]', { scope: 'rail' });
+ *   await editor.document.click('[data-ingest-name=Cube]', { scope: 'outliner', clicks: 2 });
+ *   await editor.document.type('Wheel', { scope: 'outliner' });
+ *
+ * It is not page automation: a selector resolving outside the named surface is
+ * refused by a message naming the scope and listing the others. `rail` and
+ * `outliner`, and `content` are editor chrome and stay readable while the Game document is
+ * active; `editor.hierarchy()` / `editor.inspect()` keep answering what those
+ * panels RESOLVED, where this door answers what they DREW.
+ *
+ * A field on `LiveEditor` rather than methods on it, so the editor's `eval --list` command
+ * shows the verbs as one named surface — the same reason `game.input`
+ * and `game.events` are instance fields.
+ */
+
+import type {
+  DocumentProbeResult,
+  DocumentProbeScope,
+  DocumentProbeStep,
+  EditorClient,
+} from '@volter/sdk';
+
+/** Which named surface a verb runs against; `document` when omitted. */
+export interface DocumentScopeOption {
+  scope?: DocumentProbeScope;
+}
+
+/** Modifier/targeting options shared by the gesture verbs. */
+export interface DocumentGestureOptions extends DocumentScopeOption {
+  /** Which match to drive when the selector matches several (default 0). */
+  index?: number;
+}
+
+export interface DocumentKeyOptions extends DocumentGestureOptions {
+  /** Target one element instead of whatever inside the scope has focus. */
+  selector?: string;
+  code?: string;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+  altKey?: boolean;
+  /** Hold the key this long before releasing it (a person holding W).
+   * Finite, nonnegative, and at most 120,000 ms. */
+  holdMs?: number;
+}
+
+export interface DocumentPasteOptions extends DocumentGestureOptions {
+  selector?: string;
+}
+
+export interface DocumentTypeOptions extends DocumentGestureOptions {
+  /** The field; omitted types into whatever inside the scope has focus. */
+  selector?: string;
+  /** Replace what the field holds first (default true). */
+  replace?: boolean;
+  /** Press Enter after the text (default true). */
+  enter?: boolean;
+}
+
+export class LiveEditorDocument {
+  readonly #client: EditorClient;
+
+  constructor(client: EditorClient) {
+    this.#client = client;
+  }
+
+  /**
+   * Read matching elements inside the active document: tag, text, attributes,
+   * value/checked/disabled and rect. `matched` is the total before `limit`.
+   *
+   * `styles` additionally resolves named properties per match — and resolving
+   * is the point, because a theme token is an expression until an element
+   * paints it. Ask for the standard property to learn the colour a person
+   * sees; ask for a `--volter-…` custom property to learn what a rule WOULD
+   * paint, which is the only way to measure a `:hover` colour (`:hover` is a
+   * browser state no synthetic event can enter, so there is deliberately no
+   * hover verb on this door).
+   *
+   *   await editor.document.query('.volter-tree-row', {
+   *     styles: ['backgroundColor', '--volter-widget-regular-hover'],
+   *   });
+   */
+  async query(
+    selector: string,
+    options?: DocumentScopeOption & { limit?: number; styles?: readonly string[] },
+  ): Promise<DocumentProbeResult> {
+    return this.#probe({
+      action: 'query',
+      selector,
+      ...(options?.scope === undefined ? {} : { scope: options.scope }),
+      ...(options?.limit === undefined ? {} : { limit: options.limit }),
+      ...(options?.styles === undefined ? {} : { styles: [...options.styles] }),
+    });
+  }
+
+  /** A REAL pointer gesture (pointerdown/mousedown/focus/pointerup/mouseup/click)
+   *  — not `element.click()`, which a `pointerdown` listener never sees. */
+  async click(
+    selector: string,
+    options?: DocumentGestureOptions & {
+      clicks?: number;
+      at?: [number, number];
+      altKey?: boolean;
+      ctrlKey?: boolean;
+      metaKey?: boolean;
+      shiftKey?: boolean;
+    },
+  ): Promise<DocumentProbeResult> {
+    // An option this door does not know is refused, never dropped: a dropped `position` clicked
+    // the element's centre and answered as if it had clicked where it was asked.
+    const known = ['scope', 'index', 'clicks', 'at', 'altKey', 'ctrlKey', 'metaKey', 'shiftKey'];
+    const unknown = Object.keys(options ?? {}).filter((key) => !known.includes(key));
+    if (unknown.length > 0) throw new Error(`click has no option ${unknown.map((key) => `\`${key}\``).join(', ')}; its options are scope, index, clicks, at ([x, y] fractions of the element's box) and the modifier keys altKey, ctrlKey, metaKey and shiftKey.`);
+    return this.#probe({
+      action: 'click',
+      selector,
+      ...(options?.scope === undefined ? {} : { scope: options.scope }),
+      ...(options?.index === undefined ? {} : { index: options.index }),
+      ...(options?.clicks === undefined ? {} : { clicks: options.clicks }),
+      ...(options?.at === undefined ? {} : { at: options.at }),
+      ...(options?.altKey ? { altKey: true } : {}),
+      ...(options?.ctrlKey ? { ctrlKey: true } : {}),
+      ...(options?.metaKey ? { metaKey: true } : {}),
+      ...(options?.shiftKey ? { shiftKey: true } : {}),
+    });
+  }
+
+  /**
+   * TYPE into a field and commit with Enter, the way a person does — one
+   * character at a time through the prototype's value setter, between real
+   * `keydown`/`keyup`.
+   *
+   * `paste` is not a substitute: an untrusted `ClipboardEvent` performs no
+   * default action, so a plain `<input>` with no paste handler keeps its old
+   * value. Omit `selector` to type into whatever inside the scope has focus —
+   * which is what a rename field is, one gesture after
+   * `click(row, { clicks: 2 })`.
+   */
+  async type(text: string, options?: DocumentTypeOptions): Promise<DocumentProbeResult> {
+    return this.#probe({ action: 'type', text, ...(options ?? {}) });
+  }
+
+  /**
+   * A real pointer DRAG across one matched element — press at `from`, move,
+   * release at `to`. The gesture a direct-manipulation canvas needs; a
+   * zero-length drag is a click at that fraction, which `click` (always the
+   * center) cannot place.
+   *
+   * `from`, `to` and every point in `via` are `[x, y]` FRACTIONS OF THE
+   * MATCHED ELEMENT'S BOX, 0..1 from its top-left — NEVER pixels and never
+   * page coordinates. `[0.5, 0.5]` is its center, `[1, 0]` its top-right.
+   * Compute a pixel target by measuring the element first: `query` answers
+   * its `rect`, and `(px - rect.x) / rect.width` is the fraction to pass.
+   */
+  async drag(
+    selector: string,
+    options: DocumentGestureOptions & {
+      from: [number, number];
+      to: [number, number];
+      via?: [number, number][];
+      steps?: number;
+      altKey?: boolean;
+      ctrlKey?: boolean;
+      metaKey?: boolean;
+      shiftKey?: boolean;
+      /** 0 primary (default), 1 middle, 2 secondary. */
+      button?: 0 | 1 | 2;
+      /** `via`/`to` may leave the element's box after the press (a handle drag). */
+      leave?: boolean;
+      /** Keep the button down at `to`, for readings taken mid-gesture; {@link release} lets go. */
+      hold?: boolean;
+    },
+  ): Promise<DocumentProbeResult> {
+    return this.#probe({
+      action: 'drag',
+      selector,
+      ...(options.scope === undefined ? {} : { scope: options.scope }),
+      from: options.from,
+      to: options.to,
+      ...(options.via === undefined ? {} : { via: options.via }),
+      ...(options.steps === undefined ? {} : { steps: options.steps }),
+      ...(options.index === undefined ? {} : { index: options.index }),
+      ...(options.altKey === undefined ? {} : { altKey: options.altKey }),
+      ...(options.ctrlKey === undefined ? {} : { ctrlKey: options.ctrlKey }),
+      ...(options.metaKey === undefined ? {} : { metaKey: options.metaKey }),
+      ...(options.shiftKey === undefined ? {} : { shiftKey: options.shiftKey }),
+      ...(options.button === undefined ? {} : { button: options.button }),
+      ...(options.leave === undefined ? {} : { leave: options.leave }),
+      ...(options.hold === undefined ? {} : { hold: options.hold }),
+    });
+  }
+
+  /** Lets go of the drag `hold: true` left pressed, where it was left. */
+  async release(options?: DocumentGestureOptions): Promise<DocumentProbeResult> {
+    return this.#probe({ action: 'release', ...(options?.scope === undefined ? {} : { scope: options.scope }) });
+  }
+
+  /** A real keydown/keyup on the target, or on whatever inside the document has focus. */
+  async key(key: string, options?: DocumentKeyOptions): Promise<DocumentProbeResult> {
+    return this.#probe({ action: 'key', key, ...(options ?? {}) });
+  }
+
+  /** A real `ClipboardEvent` carrying `text/plain` — the gesture nothing else
+   *  in the product can produce. */
+  async paste(text: string, options?: DocumentPasteOptions): Promise<DocumentProbeResult> {
+    return this.#probe({ action: 'paste', text, ...(options ?? {}) });
+  }
+
+  /**
+   * Choose `value` on a `<select>` — a native dropdown's options are drawn by
+   * the OS, so `click` has nothing in the document to resolve, and a plain
+   * `element.value =` is invisible to React. Set through the prototype's own
+   * value setter plus `input`/`change`; `value` is the option's `value`, not
+   * its label. An unknown value is refused with the options it does offer.
+   */
+  async select(
+    selector: string,
+    value: string,
+    options?: DocumentGestureOptions,
+  ): Promise<DocumentProbeResult> {
+    return this.#probe({
+      action: 'select',
+      selector,
+      value,
+      ...(options?.scope === undefined ? {} : { scope: options.scope }),
+      ...(options?.index === undefined ? {} : { index: options.index }),
+    });
+  }
+
+  /**
+   * THE REPL over the open document: run `step` in the editor page against the
+   * object the ACTIVE document published as its context (the mesh document
+   * publishes its `MeshEditSession`, whose `ctx` is the bpy-shaped edit
+   * context — `ctx.ops.mesh.bevel({ offset: 0.1 })`, `ctx.selection`,
+   * `ctx.history`, `session.commit()`). Edit mode, no play. Serialized like
+   * `game.page`: the step's own source travels, so inline every value it
+   * needs and return plain data.
+   */
+  async run<T = unknown>(
+    step: (ctx: unknown, info: { documentId: string }) => T | Promise<T>,
+  ): Promise<T> {
+    return this.#client.documentScript<T>(step.toString());
+  }
+
+  #probe(step: DocumentProbeStep): Promise<DocumentProbeResult> {
+    return this.#client.documentProbe(step);
+  }
+}