@vgai/sdk 0.4.0-canary.20260715.0

package/src/types.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared vocabulary for the operation registry (B1,
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B1 / §5.7 / §3.4).
+ */
+
+/** The four namespaces every operation name must live under (§5.7). */
+export const OPERATION_NAMESPACES = ['project', 'editor', 'play', 'cinematic'] as const;
+export type OperationNamespace = (typeof OPERATION_NAMESPACES)[number];
+
+/**
+ * Which of the three hosts an operation executes on (§8 B1, the
+ * review-hardened addition):
+ *  - `node` — runs in the SDK's own Node process against files (or, for
+ *    long-running jobs like `cinematic.render`, launches its own browser).
+ *  - `editor-browser` — invoked through the existing
+ *    `POST /__editor/command` SSE relay in
+ *    `packages/editor/server/editor-server.ts`, which broadcasts to the
+ *    connected browser editor and awaits its callback under a short timeout
+ *    (~5s; 120s for `play`). The projection generates the relay stub.
+ *  - `runtime-page` — invoked through the play/render harness in a launched
+ *    runtime page.
+ *
+ * `cinematic.render` is pinned `node` and MUST NOT ride the editor relay's
+ * short timeout — it is a long-running job (see `longRunning` on
+ * `OperationDefinition`).
+ */
+export type ExecutionHost = 'node' | 'editor-browser' | 'runtime-page';
+
+/** Which live contexts an operation needs before it can run. */
+export interface ExecutionRequirements {
+  /** Needs a project directory on disk (no editor process required). */
+  project?: boolean;
+  /** Needs an existing, connected editor session. */
+  editor?: boolean;
+  /** Needs a playable runtime (starts or targets one). */
+  play?: boolean;
+  /** Needs a controlled render runtime. */
+  render?: boolean;
+}
+
+/** Coarse risk classification surfaced to permission-gated callers (agents, HTTP/MCP auth). */
+export type PermissionRisk = 'read' | 'write' | 'destructive';
+
+export interface PermissionMetadata {
+  risk: PermissionRisk;
+  /** Human summary of what this operation is permitted to touch or do. */
+  summary: string;
+}
+
+/** One completed file handed to the host-managed generated-output boundary. */
+export interface ProjectOutputFile {
+  /** Project-relative destination. Slice 1 deliberately permits only public/**. */
+  path: string;
+  content: string | Uint8Array;
+  mediaType?: string;
+  role?: 'asset' | 'prefab' | 'provenance' | 'other';
+}
+
+/** JSON-safe summary returned after an atomic generated-output transaction. */
+export interface ProjectGeneratedOutputFile {
+  path: string;
+  bytes: number;
+  mediaType?: string;
+  role?: ProjectOutputFile['role'];
+}
+
+export interface ProjectGeneratedOutput {
+  files: ProjectGeneratedOutputFile[];
+  totalBytes: number;
+  dryRun: boolean;
+}
+
+/**
+ * Host capability supplied only to Node-hosted project operations. Generator
+ * implementations may stay ordinary native JS; their thin operation wrapper
+ * calls this once it has a complete batch ready to commit.
+ */
+export interface ProjectOutputWriter {
+  write(
+    files: readonly ProjectOutputFile[],
+    options?: { dryRun?: boolean },
+  ): Promise<ProjectGeneratedOutput>;
+}
+
+/**
+ * Runtime context passed to every operation's `impl`. Intentionally an open
+ * record (`[key: string]: unknown`) — later units (B2-B8) will grow this with
+ * concrete fields (editor session ids, play session handles, render job
+ * state); B1 only needs the two seams its sample operations touch.
+ */
+export interface OperationContext {
+  /** Absolute path to the target project's root, for `project`-context ops. */
+  projectRoot?: string;
+  /** Base URL of a connected editor session, for `editor`-context ops. */
+  editorUrl?: string;
+  /** Cooperative cancellation for long-running (`node`, `longRunning`) ops. */
+  signal?: AbortSignal;
+  /** Atomic writer for generated project assets (Node project operations). */
+  projectOutputs?: ProjectOutputWriter;
+  [key: string]: unknown;
+}