@vgai/editor-sdk 0.5.42 → 0.5.44

package/src/contributions.ts

@@ -138,6 +138,15 @@ export interface ToolObject3DAuthoringProps {
   /** Explicit flat scene background. Omit it to inherit the editor's standard
    *  viewport dressing (environment, gradient backdrop, key light). */
   readonly background?: ColorRepresentation;
+  /**
+   * The Asset Lab's IMPORT AUDIT on this document's inspector — the Geometry
+   * block (triangle counts, GPU estimate, LODs, collision, invalid values)
+   * and the Source row. Default on: it is what an imported model's inspector
+   * is for. A modeling document that carries its own data panel (the mesh
+   * document's Data / Modifiers sections) passes `false`, the way Blender's
+   * Object Data tab is the mesh's own, not an importer's report.
+   */
+  readonly audit?: boolean;
   readonly cameraDirection?: readonly [number, number, number];
   /**
    * Optional binding from live native clips back to ordinary project source.
@@ -153,6 +162,9 @@ export interface ToolObject3DAuthoringProps {
    * The project owns the format and the host never interprets its contents.
    */
   readonly persistence?: ToolObject3DDocumentPersistence;
+  /** Project-owned serialization of this document into ONE source module,
+   * written through the editor's source seam (see the binding's docs). */
+  readonly documentSource?: ToolDocumentSourceBinding;
   /** Replace the default native-tree projection with a semantic adapter. The
    * default adapter is provided for delegation, so a project can add terrain
    * layers, bones, or mesh elements without rebuilding Object3D projection. */
@@ -282,6 +294,27 @@ export interface ToolObject3DDocumentInteraction {
   setup(context: ToolObject3DInteractionContext): ToolObject3DInteractionExtension;
 }
 
+/**
+ * Project-owned serialization of a WHOLE Asset Lab document into one ordinary
+ * source file — what {@link ToolAnimationSourceBinding} is for clips, for a
+ * document whose truth is a TypeScript module (a modeling session's mesh
+ * module). The editor owns the checksum-guarded whole-file write through the
+ * source seam and records it in canonical history; executable source never
+ * travels through {@link ToolObject3DAuthoringProps.persistence}'s resource
+ * route, which the server refuses by rule. A document declares either this or
+ * `persistence`, never both. MUST be referentially stable across renders.
+ */
+export interface ToolDocumentSourceBinding {
+  /** Project-relative source file below src/. */
+  readonly path: string;
+  /** Undo/redo label shown by the editor history. */
+  readonly label?: string;
+  /** The exact bytes of the module for this document state — or `null` for
+   *  "nothing changed, write nothing", so a gesture that ended without an
+   *  edit leaves the file byte-for-byte alone. */
+  readonly serialize: (document: ToolObject3DDocumentState) => string | null;
+}
+
 export interface ToolAnimationSourceBinding {
   /** Project-relative TypeScript file below src/. */
   readonly path: string;
@@ -443,9 +476,56 @@ export interface ToolContributionPlay {
   readonly recording: ToolContributionRecording;
 }
 
+/**
+ * THE DOCUMENT HEADER REGION, as a project contribution sees it.
+ *
+ * A `workspace.document` module may `export const Toolbar` beside its default
+ * component. The editor renders it in the host-owned header strip above the
+ * document — the same strip the Game and Story documents use — with the SAME
+ * props the content receives, so a header and its body read one state. The
+ * host draws the strip identically for every document (height, divider,
+ * island treatment under the floating composition); the contribution supplies
+ * only what goes in it. A document that hand-draws a bar inside its own body
+ * instead is a document whose header no skin, preset or region rule can
+ * reach — which is the whole reason the strip is the host's.
+ */
+export type ToolDocumentToolbar = import('react').ComponentType<ToolContributionProps>;
+
+/**
+ * THE DOCUMENT SHELF REGION — Blender's tool shelf — as a project sees it:
+ * `export const Shelf` on a `workspace.document` module. The editor draws it
+ * as a vertical rail over the leading edge of the document's content box,
+ * with the same props as the body. Same contract as {@link ToolDocumentToolbar}.
+ */
+export type ToolDocumentShelf = import('react').ComponentType<ToolContributionProps>;
+
+/**
+ * A document the adapter's table lists — a model, a page — as handed to the
+ * editor registered for its kind (ARCHITECTURE-CORE §The project model,
+ * "Documents, not scenes"). A `workspace.document` contribution declares the
+ * kind it edits with `export const documentKind = 'model'`; the host then
+ * opens every table entry of that kind as its OWN document — titled by the
+ * entry's label, one per entry, restored across reloads by the entry's id —
+ * and mounts the contribution with the entry here. Nothing else is looked
+ * up: the entry names the module (`source`) and the contribution does the
+ * rest through `importProjectModule`.
+ */
+export interface ToolDocumentEntry {
+  /** The table entry's id (`model:src/models/cage.ts`). */
+  readonly id: string;
+  readonly kind: string;
+  /** The entry's display label — the document's title (`cage`). */
+  readonly label: string;
+  /** The module that IS the document, when the entry has one. */
+  readonly source?: { readonly path: string; readonly export?: string };
+}
+
 export interface ToolContributionProps {
   /** The exact registered callable this contribution presents. */
   readonly tool: ProjectToolCatalogEntry;
+  /** Present when mounted as the editor of a table document of the kind this
+   *  contribution declared (`export const documentKind`). */
+  readonly document?: ToolDocumentEntry;
   /** Stable id of this presentation within the registered callable. */
   readonly contributionId?: string;
   /** Direct editor SDK client; invoke with `client.runProjectTool(tool.name, ...)`. */
@@ -460,6 +540,39 @@ export interface ToolContributionProps {
   readonly documentId?: string;
   /** Whether that workspace document is the active center subject. */
   readonly active?: boolean;
+  /**
+   * Present with `documentId`. Hand the host the ONE object this document
+   * edits through — its live session — and `editor.document.run(ctx => …)`
+   * (`vgai eval`) runs a step against it in Edit mode, without play: the
+   * agent's REPL over the document. Re-publish whenever that object changes
+   * (a reload that swaps a session); the return value unpublishes.
+   */
+  readonly publishContext?: (context: unknown) => () => void;
+  /**
+   * Raise a card on the editor's bottom-right notification stack — the ONE
+   * shape an event takes (ARCHITECTURE-CORE §Editor chrome, "Notices take
+   * VS Code's shape"): a refusal, a failed write, a no-op the user should
+   * hear about. Never paint these into a document's own chrome. Plain
+   * `info` hides itself; warnings and errors stay until dismissed. The
+   * return value dismisses the card early.
+   */
+  readonly notify?: (notice: ToolNotice) => () => void;
+  /**
+   * Tell the host what this contribution is about to do on the page's main
+   * thread — `work('building src/models/x.ts')` before running a module's
+   * `build()`, `work(null)` after. A command that times out meanwhile is
+   * refused naming that work instead of "the page never answered".
+   */
+  readonly work?: (label: string | null) => void;
+}
+
+/** A card for {@link ToolContributionProps.notify}. */
+export interface ToolNotice {
+  readonly tone: 'info' | 'warning' | 'error';
+  /** One line, bold — what happened. */
+  readonly title: string;
+  /** The rest, plain — what it means, what to do. */
+  readonly detail?: string;
 }
 
 /**
@@ -518,8 +631,46 @@ export interface ToolContributionAsset {
   readonly sourcePath?: string;
 }
 
-export interface ToolAssetInspectorContributionProps extends ToolContributionProps {
+/** An `asset.inspector`'s props — the same relaxation as the two other
+ *  PRESENTING points ({@link ToolUtilityContributionProps},
+ *  {@link ToolInspectorContributionProps}): it presents what an ASSET is, not
+ *  one callable's output, so `tool` may be absent — and a section that
+ *  declares none also loads on the browser tier, whose callable catalog is
+ *  empty by design. */
+/**
+ * A verb an `asset.inspector` contribution offers for the asset it is
+ * showing — the SAME thing a built-in Inspector button is: it appears in the
+ * panel's identity row, `editor.inspect().quickActions` lists it, and
+ * `editor.runAction(id)` runs exactly this `run`. A section publishes its
+ * verbs with {@link ToolAssetInspectorContributionProps.setActions} when it
+ * knows them, which is what gives a project's own Inspector door a place in
+ * the control API instead of a mouse only.
+ */
+export interface ToolAssetInspectorAction {
+  /** Stable id, unique within the contribution (`mesh-edit.open`). */
+  readonly id: string;
+  /** Accessible name and tooltip. */
+  readonly title: string;
+  /** Visible button text. */
+  readonly label?: string;
+  readonly disabled?: boolean;
+  readonly run: () => void | Promise<void>;
+}
+
+export interface ToolAssetInspectorContributionProps extends Omit<ToolContributionProps, 'tool'> {
+  readonly tool?: ProjectToolCatalogEntry;
   readonly asset: ToolContributionAsset | null;
+  /**
+   * Publish the verbs this section offers for the asset it is showing — see
+   * {@link ToolAssetInspectorAction}. Call it with the list when the answer
+   * is known (a section that probes asynchronously calls it from the effect
+   * that resolves), and with `[]` when the answer is no. The editor renders
+   * them in the identity row and serves them to
+   * `editor.inspect().quickActions` / `editor.runAction(id)`, so the panel
+   * and the control API always show one list. Not calling it means "no
+   * verbs", which is what a section that only displays should do.
+   */
+  readonly setActions: (actions: readonly ToolAssetInspectorAction[]) => void;
 }
 
 /** Optional named export required by `asset.inspector` contributions. */
@@ -574,3 +725,59 @@ export type ToolInspectorContributionMatch = (
   adapter: unknown,
   context: ToolInspectorContributionMatchContext,
 ) => boolean;
+
+// ---------------------------------------------------------------------------
+// Project modules, through the host's own door
+// ---------------------------------------------------------------------------
+
+/**
+ * How THIS tier loads a project module for a contribution: the dev/packaged
+ * host serves it through its own Vite (`/@fs/…`, with a URL a live re-import
+ * can stamp); the browser tier bundles it from storage and has no URL for it.
+ * The host registers one loader per project (`tool-loader.ts`); a
+ * contribution that needs a project module — a model's Edit Mesh door
+ * importing `build()` — asks {@link importProjectModule} and never spells a
+ * tier's mechanics itself.
+ */
+export interface ProjectModuleLoader {
+  readonly import: (path: string) => Promise<Record<string, unknown>>;
+  /** The module's servable URL, or `null` on a tier that serves none. */
+  readonly url: (path: string) => URL | null;
+  /** The module's SOURCE TEXT as it is on disk (or in storage) right now —
+   *  what a contribution that writes the module back (a model's mesh
+   *  editor appending a line) patches. */
+  readonly source: (path: string) => Promise<string>;
+}
+
+let projectModuleLoader: ProjectModuleLoader | null = null;
+
+/** Host side: install (or clear) the active project's module loader. */
+export function registerProjectModuleLoader(loader: ProjectModuleLoader | null): void {
+  projectModuleLoader = loader;
+}
+
+/** Contribution side: a project module (`src/models/cage.ts`), loaded the
+ *  way this tier loads project modules. Refuses by name with no host. */
+export function importProjectModule(path: string): Promise<Record<string, unknown>> {
+  if (!projectModuleLoader) {
+    return Promise.reject(
+      new Error(`importProjectModule(${path}): no host has registered a project module loader`),
+    );
+  }
+  return projectModuleLoader.import(path);
+}
+
+/** The module's servable URL on this tier, or `null` (the browser tier). */
+export function projectModuleUrl(path: string): URL | null {
+  return projectModuleLoader?.url(path) ?? null;
+}
+
+/** Contribution side: the module's current source text. Refuses by name with no host. */
+export function readProjectModuleSource(path: string): Promise<string> {
+  if (!projectModuleLoader) {
+    return Promise.reject(
+      new Error(`readProjectModuleSource(${path}): no host has registered a project module loader`),
+    );
+  }
+  return projectModuleLoader.source(path);
+}

package/src/document-probe.ts

@@ -6,7 +6,7 @@
  *
  * Deliberately NOT a page-automation vocabulary: there is no navigation, no
  * waiting, no frame/window addressing and no selector rooted anywhere but the
- * active document's own container. Four actions, each one a gesture or a read
+ * active document's own container. Five actions, each one a gesture or a read
  * an agent cannot otherwise perform through the product.
  */
 
@@ -51,6 +51,35 @@ export interface DocumentClickStep {
   index?: number;
 }
 
+/**
+ * A real pointer DRAG across one matched element: `pointerdown` at `from`,
+ * `steps` `pointermove`s along the way, `pointerup` at `to` — the sequence a
+ * mouse produces, so a canvas that begins a gesture on press and previews on
+ * move (an Asset Lab document's direct manipulation) sees the whole gesture.
+ * `from`/`to` are FRACTIONS of the element's box (`[0.5, 0.5]` is its
+ * center), so a caller reasons in the element's own space, not the screen's.
+ * A zero-length drag is a click at that fraction.
+ */
+export interface DocumentDragStep {
+  action: 'drag';
+  selector: string;
+  /** Which match (default 0). */
+  index?: number;
+  from: [number, number];
+  to: [number, number];
+  /** Waypoints the pointer passes through between `from` and `to`, in
+   *  order — what a lasso or a knife stroke needs, since a straight drag
+   *  encloses nothing. Each leg gets `steps` moves. */
+  via?: [number, number][];
+  /** Intermediate `pointermove`s between consecutive points (default 8). */
+  steps?: number;
+  /** Modifier keys held for the whole gesture (a Shift-extend, an Alt-click). */
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+}
+
 /** A real key on the explicit target, else whatever inside the document has focus. */
 export interface DocumentKeyStep {
   action: 'key';
@@ -73,8 +102,32 @@ export interface DocumentPasteStep {
   index?: number;
 }
 
+/**
+ * Choose a value on a `<select>` — the gesture `click` cannot make.
+ *
+ * A native dropdown's option list is rendered by the OS, not by the DOM, so
+ * there is nothing inside the document's container for a pointer gesture to
+ * resolve against: `click` on the `<select>` opens a menu no synthetic event
+ * can reach. Assigning `element.value` is equally useless on a React
+ * controlled component — React caches the last value it wrote on the node, so
+ * a direct write is not seen as a change and the next render puts the old
+ * value straight back. The implementation goes through the prototype's own
+ * value setter and then dispatches `input`/`change`, which is the ONE spelling
+ * React's synthetic-event layer honours.
+ */
+export interface DocumentSelectStep {
+  action: 'select';
+  selector: string;
+  /** The option's `value` (not its label). */
+  value: string;
+  /** Which match (default 0). */
+  index?: number;
+}
+
 export type DocumentProbeStep =
   | DocumentQueryStep
   | DocumentClickStep
+  | DocumentDragStep
   | DocumentKeyStep
-  | DocumentPasteStep;
+  | DocumentPasteStep
+  | DocumentSelectStep;

package/src/editor-view.ts

@@ -136,6 +136,7 @@ function parseDocument(params: URLSearchParams): EditorView['document'] {
   if (!value) return undefined;
   if (kind === 'scene') return { kind, path: value };
   if (kind === 'tool') return { kind, id: value };
+  if (kind === 'document') return { kind, id: value };
   if (kind === 'world') return { kind, id: value };
   if (kind === 'project-tool') return { kind, name: value };
   if (kind === 'generation') return { kind, id: value };

package/src/index.ts

@@ -28,25 +28,33 @@ export type {
   DocumentProbeResult,
   DocumentProbeStep,
   DocumentQueryStep,
+  DocumentSelectStep,
   ProbedElement,
 } from './document-probe.js';
 export { editorViewFromUrl, editorViewUrl } from './editor-view.js';
 export type { ExtensionContributionState } from './extension.js';
 export type {
   ActiveDocumentCapture,
+  EditorChromeCapture,
   AnimationCaptureAction,
   AssetCompareCapture,
   AssetCompareOptions,
   AssetCompareView,
   AssetKind,
   AssetPreviewBackground,
+  AssetPreviewCameraChoice,
   AssetPreviewCapture,
   AssetPreviewOptions,
+  AssetPreviewOrientation,
+  AssetPreviewPose,
   AssetPreviewShotSetDefinition,
   AssetPreviewShotWarning,
   AssetPreviewSource,
   AssetPreviewStage,
   AssetPreviewView,
+  CaptureDimensions,
+  DocumentCameraPose,
+  DocumentLookOutcome,
   EditorCameraState,
   EditorEntitySummary,
   EditorState,
@@ -54,6 +62,7 @@ export type {
   EditorViewBuiltInUtilityId,
   EditorViewDocument,
   EditorViewUtility,
+  EditorWorkspaceName,
   GameCapture,
   GameplayRecordingCapture,
   GameplayRecordingOptions,
@@ -74,8 +83,8 @@ export type {
   InspectionPresentationKind,
   InspectionSurface,
   LabeledShotSetCapture,
-  PlayStarted,
   PlayRecordingStatus,
+  PlayStarted,
   PresentedEditorView,
   ProjectInfo,
   ProjectTemplate,
@@ -89,10 +98,14 @@ export type {
   ShotSetPoseMorph,
   ShotSetPoseRotation,
   ShotSetPoseStep,
+  ShotSetPoseTranslation,
   ShotSetShot,
   StoryCaptureOptions,
   StoryVariantCapture,
   StoryVariantImage,
+  StructureOp,
+  StructureOpOptions,
+  StructureOpResult,
   TransformMode,
   TransformSpace,
   Vec3Value,