@volter/editor-sdk 0.5.57

package/src/document-probe.ts

@@ -0,0 +1,237 @@
+/**
+ * The wire vocabulary of the EDITOR-SURFACE probe — the scoped editor-chrome
+ * door (`packages/editor/src/editor-document-probe.ts` implements it,
+ * `@vgai/live`'s `editor.document` binds it, and that module's header carries
+ * the design decision and the scope contract).
+ *
+ * Deliberately NOT a page-automation vocabulary: there is no navigation, no
+ * waiting, no frame/window addressing, and no selector rooted anywhere but one
+ * of the NAMED surfaces in {@link DocumentProbeScope}. Eight actions, each one
+ * a gesture or a read an agent cannot otherwise perform through the product.
+ */
+
+/**
+ * WHICH NAMED SURFACE a step runs against — the whole addressing vocabulary of
+ * this door, and the reason it is a vocabulary rather than a free selector.
+ *
+ * Every name here resolves to ONE live element the person is looking at, found
+ * by a stamp that surface's own owner wrote (`data-vgai-part` on the element
+ * the workbench handed over for a registered view; the document surface's own
+ * `data-testid`), never by walking the page for a class that looks right. A
+ * name whose surface is not on screen is REFUSED by name — an agent learns the
+ * Properties view is closed instead of reading an empty match list.
+ *
+ *  - `document` — the ACTIVE centre document's whole box: its content, its
+ *    header strip and its shelf rail. The default, and what this door meant
+ *    before there were names.
+ *  - `header` / `shelf` — the active document's toolbar strip and its tool
+ *    rail, each on its own. Both are INSIDE `document`; they exist as names so
+ *    a selector that also matches in the content (`button`, `[role=tab]`) can
+ *    be aimed without an index.
+ *  - `rail` — the Properties view (`vgai.properties`): its vertical tab rail,
+ *    the active tab's sections and their fields.
+ *  - `outliner` — the Outliner view (`vgai.outliner`): its rows, their
+ *    expand/eye/camera controls, and its header.
+ *  - `content` — the Content view (`vgai.content`): its categories and asset
+ *    rows.
+ *
+ * `rail`, `outliner`, and `content` are EDITOR CHROME and do not belong to the active
+ * document, so they stay reachable while the Game document is active — the
+ * Game refusal is about driving a game through synthetic gestures, and reading
+ * the panel that reports its selection is not that.
+ */
+export type DocumentProbeScope = 'document' | 'header' | 'shelf' | 'rail' | 'outliner' | 'content';
+
+/** One element as the probe reports it — everything a caller needs to assert
+ *  on, and nothing that requires a second round trip. */
+export interface ProbedElement {
+  /** Position within the match list this element came from. */
+  index: number;
+  tag: string;
+  /** `innerText`, trimmed and capped. */
+  text: string;
+  attributes: Record<string, string>;
+  rect: { x: number; y: number; width: number; height: number };
+  /** Present for form controls. */
+  value?: string;
+  checked?: boolean;
+  disabled?: boolean;
+  /** Resolved style, present only for the names {@link DocumentQueryStep.styles}
+   *  asked for. A standard property carries the browser's own resolved value
+   *  (`backgroundColor` → `rgb(52, 52, 52)`); a custom property carries what it
+   *  PAINTS when it resolves as a colour, and its declared text otherwise. */
+  styles?: Record<string, string>;
+}
+
+export interface DocumentProbeResult {
+  /** The surface the step ran against — echoed so a transcript proves WHICH
+   *  one was read or driven, not merely that something was. `name` is the
+   *  vocabulary word; `id`/`title` are that surface's own identity (a
+   *  document's id and title, or the registered view's). */
+  scope: { name: DocumentProbeScope; id: string; title: string };
+  /** Total matches inside the scope, before any `limit`. */
+  matched: number;
+  elements: ProbedElement[];
+}
+
+/** Which named surface a step runs against; `document` when omitted. */
+interface ScopedStep {
+  scope?: DocumentProbeScope;
+}
+
+/** Read what a surface rendered. */
+export interface DocumentQueryStep extends ScopedStep {
+  action: 'query';
+  selector: string;
+  /** Cap on returned elements (default 25); `matched` still reports the total. */
+  limit?: number;
+  /**
+   * Style property names to resolve on each match — standard
+   * (`backgroundColor`, `borderInlineStartWidth`) or custom (`--vgai-…`).
+   *
+   * Ask for the STANDARD property to learn what a surface PAINTS: a theme
+   * token is an expression (`color-mix(…)`), and the element that uses it is
+   * where the browser turns that expression into a colour. A custom property
+   * is resolved here too, through a real paint property, so a token answers
+   * with the rgb it would paint rather than its own algebra — which is the
+   * only way a `:hover` colour can be measured at all, `:hover` being a
+   * browser state no synthetic event can enter. An UNDECLARED custom
+   * property answers `""`, so "does this palette declare this group" is a
+   * question this door can be trusted with.
+   *
+   * The value is the browser's, in the browser's own spelling: a token built
+   * by `color-mix()` answers as `color(srgb …)` with float channels, a plain
+   * one as `rgb(…)`. Both are the paint; multiply a float by 255 to compare
+   * against a reference frame's 8-bit levels.
+   */
+  styles?: string[];
+}
+
+/** A real pointer gesture on one matched element. */
+export interface DocumentClickStep extends ScopedStep {
+  action: 'click';
+  selector: string;
+  /** Which match (default 0). */
+  index?: number;
+  /**
+   * Clicks in the gesture (default 1). `2` is a REAL double click: the second
+   * press carries `detail: 2` and is followed by a `dblclick`, which is the
+   * only event `onDoubleClick` listens for.
+   *
+   * It is on `click` rather than a verb of its own because it is the same
+   * gesture with the same target — and it is here at all because a double
+   * click is the OUTLINER'S OWN rename gesture (`GameHierarchy.tsx`'s
+   * `onDoubleClick` → `onStartEditing`), so without it a rename could only be
+   * driven through `editor.setField`, which is not the control.
+   */
+  clicks?: number;
+}
+
+/**
+ * TYPE into a focused field, character by character, and commit with Enter the
+ * way a person does.
+ *
+ * `paste` cannot stand in for this: an untrusted `ClipboardEvent` performs no
+ * default action, so a plain `<input>` with no paste handler keeps its old
+ * value. And a direct `element.value = x` is invisible to React, which caches
+ * the last value it wrote on the node — the same trap `select` documents. So
+ * each character goes through the prototype's own value setter (leaving
+ * React's tracker stale, which is what makes the following `input` read as a
+ * real edit), between a real `keydown`/`keyup` for that character, so a field
+ * that commits on a KEY rather than on `input` sees the keys too.
+ */
+export interface DocumentTypeStep extends ScopedStep {
+  action: 'type';
+  text: string;
+  /** The field; omitted means whatever inside the scope has focus. */
+  selector?: string;
+  index?: number;
+  /** Replace what the field holds first, the way a person selects-all and
+   *  types over it (default true). `false` appends at the end. */
+  replace?: boolean;
+  /** Press Enter after the text (default true) — the commit gesture for the
+   *  Outliner's rename field and every numeric field in the Properties rail. */
+  enter?: boolean;
+}
+
+/**
+ * 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 extends ScopedStep {
+  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 extends ScopedStep {
+  action: 'key';
+  key: string;
+  code?: string;
+  selector?: string;
+  index?: number;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+  altKey?: boolean;
+}
+
+/** A real `ClipboardEvent` carrying `text/plain` — the only way to exercise a
+ *  paste handler, and the gesture the Sheets build could not verify. */
+export interface DocumentPasteStep extends ScopedStep {
+  action: 'paste';
+  text: string;
+  selector?: string;
+  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 extends ScopedStep {
+  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
+  | DocumentSelectStep
+  | DocumentTypeStep;

package/src/editor-view.ts

@@ -0,0 +1,220 @@
+import type { AssetKind, EditorCameraState, EditorView, ViewPreset } from './types.js';
+import { EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS, isEditorViewUtility } from './types.js';
+
+const PREFIX = 'view.';
+const MAX_QUERY_LENGTH = 4096;
+const WORKSPACE_DOCUMENT_IDS = new Set<string>(EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS);
+const ASSET_KINDS = new Set<AssetKind>([
+  'model',
+  'image',
+  'audio',
+  'animation',
+  'json',
+  'prefab',
+  'source',
+]);
+const CAMERAS = new Set<ViewPreset | 'isometric'>([
+  'top',
+  'front',
+  'right',
+  'perspective',
+  'isometric',
+]);
+type EditorViewDiagnostic = NonNullable<NonNullable<EditorView['viewport']>['diagnostic']>;
+const DIAGNOSTICS = new Set<EditorViewDiagnostic>([
+  'solid',
+  'unlit',
+  'wireframe',
+  'normals',
+  'overdraw',
+  'uv',
+  'vertex-colors',
+  'bounds',
+  'skeleton',
+]);
+function nonEmpty(value: string | null): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function writeDocument(params: URLSearchParams, document: EditorView['document']): void {
+  if (!document) return;
+  params.set(`${PREFIX}docKind`, document.kind);
+  if (document.kind === 'asset' && document.entityId) {
+    params.set(`${PREFIX}doc`, document.entityId);
+    params.set(`${PREFIX}assetSource`, 'entity');
+  } else if (document.kind === 'asset') {
+    params.set(`${PREFIX}doc`, document.path!);
+  } else if (document.kind === 'scene') {
+    params.set(`${PREFIX}doc`, document.path);
+  } else if (document.kind === 'story') {
+    params.set(`${PREFIX}doc`, document.modulePath);
+    params.set(`${PREFIX}story`, document.storyName);
+    if (document.mode === 'docs') params.set(`${PREFIX}storyMode`, 'docs');
+  } else if (document.kind === 'project-tool') {
+    params.set(`${PREFIX}doc`, document.name);
+  } else {
+    params.set(`${PREFIX}doc`, document.id);
+  }
+  if (document.kind === 'asset' && document.assetKind) {
+    params.set(`${PREFIX}assetKind`, document.assetKind);
+  }
+}
+
+function writeViewport(params: URLSearchParams, viewport: EditorView['viewport']): void {
+  if (!viewport) return;
+  if (typeof viewport.camera === 'string') params.set(`${PREFIX}camera`, viewport.camera);
+  else if (viewport.camera) {
+    params.set(`${PREFIX}camera`, 'pose');
+    params.set(
+      `${PREFIX}cameraPosition`,
+      [viewport.camera.position.x, viewport.camera.position.y, viewport.camera.position.z].join(
+        ',',
+      ),
+    );
+    params.set(
+      `${PREFIX}cameraTarget`,
+      [viewport.camera.target.x, viewport.camera.target.y, viewport.camera.target.z].join(','),
+    );
+    if (viewport.camera.fov !== undefined)
+      params.set(`${PREFIX}cameraFov`, String(viewport.camera.fov));
+  }
+  if (viewport.diagnostic) params.set(`${PREFIX}diagnostic`, viewport.diagnostic);
+  if (viewport.frame) params.set(`${PREFIX}frame`, viewport.frame);
+  if (viewport.grid !== undefined) params.set(`${PREFIX}grid`, viewport.grid ? '1' : '0');
+}
+
+function parseVec3(value: string | null): EditorCameraState['position'] | null {
+  if (!value) return null;
+  const parts = value.split(',').map(Number);
+  if (parts.length !== 3 || parts.some((part) => !Number.isFinite(part))) return null;
+  return { x: parts[0]!, y: parts[1]!, z: parts[2]! };
+}
+
+function parseCamera(params: URLSearchParams): NonNullable<EditorView['viewport']>['camera'] {
+  const camera = params.get(`${PREFIX}camera`);
+  if (camera && CAMERAS.has(camera as ViewPreset | 'isometric')) {
+    return camera as ViewPreset | 'isometric';
+  }
+  if (camera !== 'pose') return undefined;
+  const position = parseVec3(params.get(`${PREFIX}cameraPosition`));
+  const target = parseVec3(params.get(`${PREFIX}cameraTarget`));
+  const fovValue = params.get(`${PREFIX}cameraFov`);
+  const fov = fovValue === null ? undefined : Number(fovValue);
+  if (!position || !target || (fov !== undefined && !Number.isFinite(fov))) return undefined;
+  return { position, target, ...(fov !== undefined ? { fov } : {}) };
+}
+
+function parseStoryDocument(params: URLSearchParams, modulePath: string): EditorView['document'] {
+  const storyName = nonEmpty(params.get(`${PREFIX}story`));
+  if (!storyName) return undefined;
+  return {
+    kind: 'story',
+    modulePath,
+    storyName,
+    ...(params.get(`${PREFIX}storyMode`) === 'docs' ? { mode: 'docs' as const } : {}),
+  };
+}
+
+function parseAssetDocument(params: URLSearchParams, value: string): EditorView['document'] {
+  const assetKind = params.get(`${PREFIX}assetKind`);
+  if (params.get(`${PREFIX}assetSource`) === 'entity') {
+    return { kind: 'asset', entityId: value, assetKind: 'model' };
+  }
+  return {
+    kind: 'asset',
+    path: value,
+    ...(assetKind && ASSET_KINDS.has(assetKind as AssetKind)
+      ? { assetKind: assetKind as AssetKind }
+      : {}),
+  };
+}
+
+function parseDocument(params: URLSearchParams): EditorView['document'] {
+  const kind = params.get(`${PREFIX}docKind`);
+  const value = nonEmpty(params.get(`${PREFIX}doc`));
+  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 };
+  if (kind === 'story') return parseStoryDocument(params, value);
+  if (kind === 'workspace' && WORKSPACE_DOCUMENT_IDS.has(value)) {
+    return {
+      kind,
+      id: value as Extract<NonNullable<EditorView['document']>, { kind: 'workspace' }>['id'],
+    };
+  }
+  return kind === 'asset' ? parseAssetDocument(params, value) : undefined;
+}
+
+function parseViewport(params: URLSearchParams): EditorView['viewport'] {
+  const camera = parseCamera(params);
+  const diagnostic = params.get(`${PREFIX}diagnostic`);
+  const frame = params.get(`${PREFIX}frame`);
+  const grid = params.get(`${PREFIX}grid`);
+  const viewport = {
+    ...(camera ? { camera } : {}),
+    ...(diagnostic && DIAGNOSTICS.has(diagnostic as EditorViewDiagnostic)
+      ? { diagnostic: diagnostic as EditorViewDiagnostic }
+      : {}),
+    ...(frame === 'document' || frame === 'selection'
+      ? { frame: frame as 'document' | 'selection' }
+      : {}),
+    ...(grid === '0' || grid === '1' ? { grid: grid === '1' } : {}),
+  };
+  return Object.keys(viewport).length > 0 ? viewport : undefined;
+}
+
+/** Apply only the view-owned query parameters, preserving project/scene routing params. */
+export function editorViewUrl(view: EditorView, baseUrl: string | URL): string {
+  const url = new URL(baseUrl);
+  for (const key of [...url.searchParams.keys()]) {
+    if (key.startsWith(PREFIX)) url.searchParams.delete(key);
+  }
+  url.searchParams.set(`${PREFIX}v`, '1');
+  writeDocument(url.searchParams, view.document);
+  if (view.selection?.ids.length) {
+    for (const id of view.selection.ids) url.searchParams.append(`${PREFIX}select`, id);
+    if (view.selection.focus) url.searchParams.set(`${PREFIX}focus`, '1');
+  }
+  writeViewport(url.searchParams, view.viewport);
+  if (view.workspace) url.searchParams.set(`${PREFIX}workspace`, view.workspace);
+  if (view.panel) url.searchParams.set(`${PREFIX}panel`, view.panel);
+  if (view.utility) url.searchParams.set(`${PREFIX}utility`, view.utility);
+  if (url.search.length > MAX_QUERY_LENGTH) {
+    throw new Error(`Editor view URL exceeds the ${MAX_QUERY_LENGTH}-character share limit.`);
+  }
+  return url.toString();
+}
+
+/** Parse a shareable editor projection. Malformed projections are ignored at boot. */
+export function editorViewFromUrl(value: string | URL): EditorView | null {
+  const url = value instanceof URL ? value : new URL(value, 'http://editor.invalid');
+  const params = url.searchParams;
+  if (params.get(`${PREFIX}v`) !== '1') return null;
+  const view: EditorView = { version: 1 };
+  const document = parseDocument(params);
+  if (document) view.document = document;
+  const ids = params
+    .getAll(`${PREFIX}select`)
+    .filter((id) => id.length > 0)
+    .slice(0, 32);
+  if (ids.length) view.selection = { ids, focus: params.get(`${PREFIX}focus`) === '1' };
+  const viewport = parseViewport(params);
+  if (viewport) view.viewport = viewport;
+  // Shape check only: a `tool:` id names a utility the OPEN PROJECT
+  // contributes, so the URL cannot know whether it exists. The editor
+  // validates it against its live registry when the view is presented.
+  const workspace = params.get(`${PREFIX}workspace`);
+  if (workspace) view.workspace = workspace;
+  // Shape check only, like `workspace` above: which panels exist is the open
+  // editor's registry, and it answers at present-time.
+  const panel = params.get(`${PREFIX}panel`);
+  if (panel) view.panel = panel;
+  const utility = params.get(`${PREFIX}utility`);
+  if (utility && isEditorViewUtility(utility)) view.utility = utility;
+  return view;
+}

package/src/extension.ts

@@ -0,0 +1,40 @@
+/**
+ * Extension contract (W3a) — the published surface a game project uses to
+ * contribute to the editor, with the degradation ladder made API.
+ *
+ * A project extends the editor through exactly three surfaces:
+ *
+ * (a) **Editor panels** — registered into the workspace as documents
+ *     or utilities via a tool contribution (`package.json#vgai.tools` →
+ *     `contributes: [{ point: 'workspace.document' | 'workspace.utility' | 'workspace.analytics' }]`).
+ *     Types: `ToolContributionProps` in `@volter/editor-sdk/contributions`.
+ *     Panels are never a parallel rail — the frame owns all layout.
+ * (b) **Inspector sections** — `point: 'selection.inspector'` /
+ *     `'asset.inspector'` tool contributions with an exported `match`.
+ *     Types: `ToolInspectorContributionProps` and friends, same module.
+ * (c) **System adapters** — runtime capabilities (networking, debug, …)
+ *     registered from game code via `ctx.registerSystemAdapter?.(kind, impl)`
+ *     (`SystemAdapters` in `@volter/editor-project`'s
+ *     `adapter/system-adapter`). Deliberately NOT re-exported here: the
+ *     engine already publishes that seam and every consumer of it also
+ *     imports the engine — an alias would be a dead surface.
+ *
+ * Outcomes (the anti-shim rule, as API): every contribution resolves to an
+ * {@link ExtensionContributionState} —
+ *
+ * - `'active'` — the contribution loaded and produced its surface.
+ * - `'absent'` — nothing was contributed. The editor HIDES the surface
+ *   entirely; it never fabricates placeholder data for a missing
+ *   contribution.
+ * - `'failed'` — the contribution exists but threw / violated the contract.
+ *   The failure is contained per-contribution (the editor never crashes),
+ *   the surface is hidden, and the error is reported LOUDLY (editor
+ *   console) — never silently swallowed into fake output.
+ */
+
+/**
+ * The terminal state of a single extension contribution (see the module doc
+ * above for the exact semantics). Not a grade and not an ordering: `absent`
+ * and `failed` both hide the surface, and `failed` is reported loudly.
+ */
+export type ExtensionContributionState = 'active' | 'absent' | 'failed';

package/src/generations.ts

@@ -0,0 +1,178 @@
+import { z } from 'zod';
+
+/**
+ * First-party generation JOB vocabulary.
+ *
+ * Providers keep their native request and result schemas. This deliberately
+ * normalizes only the lifecycle that is genuinely shared by Fal, Tripo,
+ * World Labs, and future generators: durable identity, state, resumption,
+ * acceptance, and the charge shown to the user.
+ */
+
+export const GenerationJobStatusSchema = z.enum([
+  'queued',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+]);
+
+export const GenerationBillingSchema = z.discriminatedUnion('route', [
+  z.object({ route: z.literal('mock') }).strict(),
+  z
+    .object({
+      route: z.literal('managed'),
+      estimatedCredits: z.number().nonnegative().optional(),
+      settledCredits: z.number().nonnegative().optional(),
+    })
+    .strict(),
+  z
+    .object({
+      route: z.literal('byok'),
+      currency: z.literal('USD'),
+      estimatedAmount: z.number().nonnegative().optional(),
+      settledAmount: z.number().nonnegative().optional(),
+    })
+    .strict(),
+]);
+
+const GenerationOperationReferenceSchema = z
+  .object({
+    tool: z.string().min(1),
+    input: z.unknown(),
+  })
+  .strict();
+
+export const GenerationJobSchema = z
+  .object({
+    id: z.string().min(1),
+    provider: z.string().min(1),
+    externalId: z.string().min(1),
+    label: z.string().min(1),
+    operation: z.string().min(1),
+    mode: z.enum(['mock', 'direct', 'managed']),
+    status: GenerationJobStatusSchema,
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    progress: z.number().min(0).max(1).optional(),
+    providerStatus: z.string().optional(),
+    queuePosition: z.number().int().nonnegative().optional(),
+    message: z.string().optional(),
+    lastPolledAt: z.string().datetime().optional(),
+    lastProviderChangeAt: z.string().datetime().optional(),
+    pollError: z.string().optional(),
+    pollErrorAt: z.string().datetime().optional(),
+    pollFailureCount: z.number().int().nonnegative().optional(),
+    nextPollAt: z.string().datetime().optional(),
+    billing: GenerationBillingSchema,
+    poll: GenerationOperationReferenceSchema,
+    cancel: GenerationOperationReferenceSchema.optional(),
+    accept: GenerationOperationReferenceSchema.optional(),
+    acceptedAt: z.string().datetime().optional(),
+    /** Last time a human/agent opened the native result. A later provider
+     * update makes the terminal result unread again without changing status. */
+    readAt: z.string().datetime().optional(),
+    provenanceOperationId: z.string().optional(),
+    outputPaths: z.array(z.string()).optional(),
+  })
+  .strict();
+
+export const GenerationJobsDocumentSchema = z
+  .object({
+    version: z.literal(1),
+    jobs: z.array(GenerationJobSchema),
+  })
+  .strict();
+
+export type GenerationJobStatus = z.infer<typeof GenerationJobStatusSchema>;
+export type GenerationBilling = z.infer<typeof GenerationBillingSchema>;
+export type GenerationJob = z.infer<typeof GenerationJobSchema>;
+export type GenerationJobsDocument = z.infer<typeof GenerationJobsDocumentSchema>;
+
+/** The MANAGED arm of {@link GenerationBilling} — vgai credits, not currency. */
+export type ManagedGenerationBilling = Extract<GenerationBilling, { route: 'managed' }>;
+
+/**
+ * The managed-route billing leg of a provider tool's `toUpdate`, spread-ready.
+ *
+ * Every provider poll tool needs the same three-part decision — is this run on
+ * the managed route at all, did the provider report either credit figure, and
+ * which of the two are present — and Fal, Tripo, World Labs and OpenRouter had
+ * each spelled it out identically, fourteen lines apiece. The conditions are
+ * not obvious enough to retype safely: reporting `route: 'managed'` with both
+ * figures absent claims a charge nobody measured, and writing
+ * `estimatedCredits: undefined` is NOT the same as omitting it under
+ * `exactOptionalPropertyTypes` — it fails the schema rather than leaving the
+ * field unset.
+ *
+ * Call it with the parsed result itself; only the two credit fields are read.
+ *
+ *     ...managedBilling(input.mode, result),
+ */
+export function managedBilling(
+  mode: string,
+  credits: {
+    readonly estimatedCredits?: number | undefined;
+    readonly settledCredits?: number | undefined;
+  },
+): { billing?: ManagedGenerationBilling } {
+  if (mode !== 'managed') return {};
+  const { estimatedCredits, settledCredits } = credits;
+  if (estimatedCredits === undefined && settledCredits === undefined) return {};
+  return {
+    billing: {
+      route: 'managed',
+      ...(estimatedCredits === undefined ? {} : { estimatedCredits }),
+      ...(settledCredits === undefined ? {} : { settledCredits }),
+    },
+  };
+}
+
+export interface GenerationJobDraft {
+  provider: string;
+  externalId: string;
+  label: string;
+  operation: string;
+  mode: 'mock' | 'direct' | 'managed';
+  status: GenerationJobStatus;
+  progress?: number;
+  providerStatus?: string;
+  queuePosition?: number;
+  message?: string;
+  billing: GenerationBilling;
+  poll: { tool: string; input: unknown };
+  cancel?: { tool: string; input: unknown };
+  accept?: { tool: string; input: unknown };
+}
+
+export interface GenerationJobUpdate {
+  provider: string;
+  externalId: string;
+  status?: GenerationJobStatus;
+  progress?: number;
+  providerStatus?: string;
+  queuePosition?: number;
+  message?: string;
+  billing?: GenerationBilling;
+  cancel?: { tool: string; input: unknown };
+  /** `null` withdraws an acceptance action after polling proves that a
+   * successful operation produced no downloadable project output. */
+  accept?: { tool: string; input: unknown } | null;
+  accepted?: {
+    provenanceOperationId: string;
+    outputPaths: string[];
+  };
+}
+
+/** Provider-owned mapping attached to a registered native operation module. */
+export type GenerationToolContribution =
+  | {
+      role: 'submit';
+      provider: string;
+      toJob(input: unknown, result: unknown): GenerationJobDraft;
+    }
+  | {
+      role: 'poll' | 'cancel' | 'accept';
+      provider: string;
+      toUpdate(input: unknown, result: unknown): GenerationJobUpdate;
+    };