@vgai/editor-sdk 0.5.41 → 0.5.44

package/src/types.ts

@@ -11,6 +11,16 @@ export type ViewportTab = 'edit' | 'play';
 
 export type AssetKind = 'model' | 'image' | 'audio' | 'animation' | 'json' | 'prefab' | 'source';
 
+/**
+ * The editor's NAMED WORKSPACES — task-named layout memories over the one
+ * physical dock (ARCHITECTURE-CORE §Editor chrome). Named for the TASK, each
+ * borrowing the arrangement of the tool that does it best; `game` is the
+ * default and is the editor's standing arrangement. Restated here (rather than
+ * imported from the editor) for the same reason every other id union in this
+ * file is: the SDK is a wire client and must not depend on the editor bundle.
+ */
+export type EditorWorkspaceName = 'game' | 'model' | 'sculpt' | 'texture' | 'animate' | 'look';
+
 export interface HelperVisibility {
   bounds: boolean;
   lights: boolean;
@@ -50,6 +60,30 @@ export interface ViewportCapture {
   mimeType: 'image/png';
 }
 
+/**
+ * How an animated look move on the open Object3D document ended. Never an
+ * error: the camera is SHARED with the person watching, so "they grabbed it
+ * mid-orbit" is an outcome to read, not a failure to handle.
+ */
+export interface DocumentLookOutcome {
+  /** True only when the whole move was drawn. */
+  completed: boolean;
+  /** Why it stopped early: a human drag, a later look verb, or a closed document. */
+  cancelledBy?: 'human' | 'superseded' | 'closed';
+  /** Where the camera ended up, radians around the framed subject. */
+  azimuth: number;
+  /** Radians above the subject's horizon. */
+  elevation: number;
+  /** Seconds of the move that were actually drawn. */
+  seconds: number;
+}
+
+/** Where the open document's camera is standing and what it is aimed at. */
+export interface DocumentCameraPose {
+  position: [number, number, number];
+  target: [number, number, number];
+}
+
 /** Result of the editor's native Asset Lab ragdoll-generation operation. */
 export interface RagdollGenerationResult {
   capability: 'added' | 'present';
@@ -98,6 +132,15 @@ export interface GameCapture {
   /** True when the host loop was starved and the runtime rendered one
    *  deterministic tick to produce this frame. */
   loopRecoveryFrame?: boolean;
+  /** Present when this frame came out of a RECORDED run (every `vgai play`
+   *  records). The still is delivered either way; `notice` is the sentence
+   *  naming the clip, its offset-0 wall clock, and what a still cannot answer —
+   *  shown verbatim, never re-derived by the caller. */
+  recording?: {
+    path: string;
+    startedAt: string;
+    notice: string;
+  };
 }
 
 /** Options for recording the clean running-game composite. */
@@ -141,11 +184,30 @@ export interface GameplayRecordingCapture extends GameplayRecordingStarted {
   hidden: boolean;
 }
 
+/** A position on the active recorder's authoritative monotonic timeline.
+ * `startedAt` identifies the recording; `elapsedMs` shares the exact origin
+ * used to calculate the finalized capture's `durationMs`. */
+export interface GameplayRecordingTimeline {
+  startedAt: string;
+  elapsedMs: number;
+}
+
+/** What Play can report while its recording is still open. Geometry, layers, media cadence, and
+ * final health are deliberately absent: those facts are only authoritative after Stop finalizes
+ * the capture. */
+export interface PlayRecordingStatus {
+  path: string;
+  startedAt: string;
+  rotates: boolean;
+  logFile: string | null;
+  idleAutoStopMs: number;
+}
+
 /** What `play` reports back once the run is up and recording. */
 export interface PlayStarted {
   /** Absent only when the recorder could not start; play is up either way and
    *  the editor console carries the reason. */
-  recording?: GameplayRecordingStarted;
+  recording?: PlayRecordingStatus;
 }
 
 export type AssetPreviewView = 'front' | 'right' | 'top' | 'perspective';
@@ -185,16 +247,61 @@ export type AssetPreviewSource =
  */
 export type AssetPreviewStage = 'lab' | 'scene';
 
+/**
+ * A free capture camera for the Asset Lab legs (`vgai screenshot`'s
+ * `--azimuth/--elevation/--distance`): ONE view from a chosen angle instead
+ * of the fixed four. Angles are relative to the subject's AUTHORED front —
+ * azimuth 0 photographs the declared front, 90 walks toward the side the
+ * turntable's yaw-90 shot shows; elevation raises the camera (degrees above
+ * level); `distance` is meters from the framing center, auto-fit when
+ * omitted.
+ */
+export interface AssetPreviewCameraChoice {
+  azimuthDegrees: number;
+  elevationDegrees: number;
+  distance?: number;
+}
+
+/**
+ * Pose an animated subject before capturing (`vgai screenshot`'s
+ * `--clip <name> --time <t>`): the named clip is sampled at `timeSeconds`
+ * on the capture's disposable snapshot — the source is never mutated. The
+ * capture fails loudly (naming the clips that DO exist) when the subject
+ * carries no clip by this name.
+ */
+export interface AssetPreviewPose {
+  clip: string;
+  timeSeconds: number;
+}
+
 export interface AssetPreviewOptions {
   width?: number;
   height?: number;
   background?: AssetPreviewBackground;
   stage?: AssetPreviewStage;
+  camera?: AssetPreviewCameraChoice;
+  pose?: AssetPreviewPose;
+}
+
+/**
+ * How the captured subject was oriented relative to its AUTHORED coordinates.
+ * The editor yaw-normalizes a subject so the front camera photographs its
+ * declared front; a 180-degree yaw maps authored +X to screen-LEFT in the
+ * front view. The yaw is reported here (and stamped onto the images' own
+ * pixels as `+X>` / `<+X` markers) so it is never applied silently.
+ */
+export interface AssetPreviewOrientation {
+  /** The subject's declared forward, `[0,0,1]` when it declares none. */
+  forward: [number, number, number];
+  /** Yaw applied to face the front camera; 0 means authored axes = world axes. */
+  yawDegrees: number;
 }
 
 export interface AssetPreviewCapture {
   width: number;
   height: number;
+  /** Absent from editors that predate orientation reporting. */
+  orientation?: AssetPreviewOrientation;
   views: Array<ViewportCapture & { view: AssetPreviewView }>;
   contactSheet: ViewportCapture & { width: number; height: number };
 }
@@ -212,6 +319,13 @@ export interface StoryCaptureOptions {
    *  because a UI story is not the Asset Lab's square 3D view. */
   width?: number;
   height?: number;
+  /** Free capture camera for THREE stories (same contract as the Asset Lab's
+   *  {@link AssetPreviewCameraChoice}). A selected story that renders on the
+   *  DOM leg refuses these BY NAME rather than silently ignoring them. */
+  camera?: AssetPreviewCameraChoice;
+  /** Clip pose for THREE stories (same contract as the Asset Lab's
+   *  {@link AssetPreviewPose}); DOM-leg stories refuse it by name. */
+  pose?: AssetPreviewPose;
 }
 
 export interface StoryVariantImage extends ViewportCapture {
@@ -313,11 +427,27 @@ export interface ShotSetPoseMorph {
   influence: number;
 }
 
-/** One step of a named pose. A flat union rather than two parallel lists: a
+/** The TRANSLATION channel of a pose: a joint displaced along its own local
+ *  axis. Rotations alone cannot state a gait's vertical truth — a crouch, a
+ *  jump apex, the hip dip that makes a walk read as weighted — because those
+ *  are the root/hips MOVING, not a joint bending (round-4 finding: shot sets
+ *  could not photograph a gait). Same delta semantics as the rotation: the
+ *  capture engine applies `bone.translateX/Y/Z(meters)`, composing onto
+ *  whatever local position the GLB baked. */
+export interface ShotSetPoseTranslation {
+  bone: string;
+  axis: 'x' | 'y' | 'z';
+  /** A DELTA along the bone's own local axis, in meters, relative to the
+   *  loaded GLB's baked rest position. */
+  meters: number;
+}
+
+/** One step of a named pose. A flat union rather than parallel lists: a
  *  single expression is normally one rotation AND one morph (a jaw ROTATION
  *  plus a brow MORPH), so keeping them in one ordered list means a definition
- *  never has to zip them. */
-export type ShotSetPoseStep = ShotSetPoseRotation | ShotSetPoseMorph;
+ *  never has to zip them. Discriminated by field name: `radians` is a
+ *  rotation, `meters` a translation, `influence` a morph. */
+export type ShotSetPoseStep = ShotSetPoseRotation | ShotSetPoseMorph | ShotSetPoseTranslation;
 
 export type ShotSetShot =
   | { label: string; view: 'turntable'; yaw: number; pose?: string | undefined }
@@ -717,7 +847,14 @@ export interface EditorState {
 }
 
 export type ViewPreset = 'top' | 'front' | 'right' | 'perspective';
-export type ShadingMode = 'solid' | 'clay' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
+export type ShadingMode =
+  | 'solid'
+  | 'clay'
+  | 'unlit'
+  | 'wireframe'
+  | 'matcap'
+  | 'normals'
+  | 'overdraw';
 
 /** One operation on the active native animation document's recorder. */
 export type AnimationCaptureAction = 'start' | 'stop' | 'review' | 'commit' | 'discard';
@@ -822,6 +959,9 @@ export type EditorViewDocument =
   | { kind: 'asset'; path: string; entityId?: never; assetKind?: AssetKind }
   | { kind: 'asset'; entityId: string; path?: never; assetKind?: 'model' }
   | { kind: 'tool'; id: string }
+  /** A document the adapter's table lists (a model, a page) — `id` is the
+   *  table entry's id — opened in the editor registered for its kind. */
+  | { kind: 'document'; id: string }
   | { kind: 'world'; id: string }
   | { kind: 'story'; modulePath: string; storyName: string; mode?: 'preview' | 'docs' }
   | { kind: 'project-tool'; name: string }
@@ -829,6 +969,15 @@ export type EditorViewDocument =
   | {
       kind: 'workspace';
       id: EditorViewWorkspaceDocumentId;
+      /**
+       * For a COMPONENT BOARD document: the portable story frame to open on
+       * — a story id, or a unique CSF export name or label (an ambiguous or
+       * unknown value refuses loudly, listing candidates). Emitted back by
+       * the board's own presentation so a captured view round-trips. This is
+       * the design ledger's "board story selector": without it only the
+       * derived default story could ever be addressed.
+       */
+      story?: string;
     };
 
 export interface EditorView {
@@ -852,9 +1001,36 @@ export interface PresentedEditorView {
   warnings: string[];
 }
 
+/**
+ * How big a capture comes back.
+ *
+ * A NUMBER is a square of that size, and square stays the default — an
+ * unstaged look at a model is a square question. `{width, height}` is for the
+ * shaped answer: a video-aspect frame that needs no crop afterwards, which is
+ * what the model/module lanes' looks are actually for.
+ *
+ * Both are bounded by the EDITOR's own ceiling — 64..1024 per side, plus a
+ * total no larger than a 1024 square. That is the relay budget, not a taste:
+ * the pixels cross the editor relay as base64 JSON, and 1024 is where even
+ * incompressible RGBA still fits its 50 MB request limit (`asset-preview.ts`'s
+ * `MIN_SIZE`/`MAX_SIZE`). For more picture, take more views, not bigger ones.
+ */
+export type CaptureDimensions = number | { readonly width: number; readonly height: number };
+
 /** The pixels of the active center document, with enough provenance for an
  * agent to prove which user-visible subject it captured. Editor chrome is
  * deliberately excluded. */
+/** A photograph of the editor PAGE — every panel as the person sees it
+ *  (`capture-editor-chrome`; the door that lets a skin, a workspace or a
+ *  contributed panel be judged sighted through the product). */
+export interface EditorChromeCapture extends ViewportCapture {
+  view: EditorView;
+  /** The page's on-screen size in CSS pixels — the frame's own size. */
+  size: { width: number; height: number };
+  layers: { canvases: number; domOverlays: number };
+  flatness?: { degenerate: boolean; warning?: string };
+}
+
 export interface ActiveDocumentCapture extends ViewportCapture {
   document: {
     id: string;
@@ -921,8 +1097,9 @@ export type {
 export type InspectionSurface = 'three' | 'canvas' | 'dom' | 'asset-lab';
 
 /** Which LAYOUT the one inspector box is in: the compact box over the
- *  viewport, or the same sections stacked in the dock column. */
-export type InspectionPresentationKind = 'card' | 'column';
+ *  viewport, the same sections stacked in the dock column, or that column
+ *  with the sections tabbed behind a vertical rail (`properties`). */
+export type InspectionPresentationKind = 'card' | 'column' | 'properties';
 
 /** One inspected field: a stable scriptable `path` and the value at it. */
 export interface InspectedField {
@@ -946,10 +1123,15 @@ export interface InspectedField {
 
 /** A section's content. Custom RENDERING remains opaque — the wire never
  *  introspects React — while any ordinary descriptor channel that chrome owns
- *  remains visible as `fields`, including its write-refusal reasons. The two
- *  opaque kinds are distinguished because "this subject has a live preview"
- *  is a real fact about it: `custom` is a contributed block, `preview` is the
- *  subject's own square view of itself.
+ *  IS a `fields` body here, including its write-refusal reasons: nothing is
+ *  rendered on this wire, so naming chrome a reader cannot see while hiding
+ *  the fields it can use is the wrong half. (Measured: the whole react/DOM
+ *  lane draws its own widgets over the style descriptors, so every one of its
+ *  sections reported `custom` and `inspect()` enumerated zero fields for a DOM
+ *  element.) The two opaque kinds are distinguished because "this subject has
+ *  a live preview" is a real fact about it: `custom` is a contributed block
+ *  with no descriptor channel of its own, `preview` is the subject's own
+ *  square view of itself.
  *
  *  A custom body carries `data` when it can say what it DISPLAYS — the keys
  *  are the section's own vocabulary, not a shared schema. The shipped case is
@@ -963,7 +1145,6 @@ export type InspectedSectionBody =
       id: string;
       title: string;
       data?: Record<string, unknown>;
-      fields?: readonly InspectedField[];
     }
   | { kind: 'preview'; id: string; title: string };
 
@@ -1057,6 +1238,54 @@ export interface InspectedFieldWrite {
   write: InspectedWriteDestination;
 }
 
+/**
+ * The STRUCTURE verbs — the hierarchy context menu's own ops, addressable.
+ *
+ * The names are the menu's, not the provider's, because the menu is the
+ * surface a human uses and an agent is doing the same thing through a
+ * different door (`delete` covers the provider's `remove`/`removeMany`: a
+ * multi-id delete is ONE undoable op when the adapter can batch it).
+ */
+export type StructureOp =
+  | 'create'
+  | 'delete'
+  | 'duplicate'
+  | 'reparent'
+  | 'reorder'
+  | 'wrap'
+  | 'unwrap'
+  | 'group'
+  | 'ungroup'
+  | 'copy'
+  | 'cut'
+  | 'paste';
+
+/** Arguments for one {@link StructureOp}. Everything is optional: `id`/`ids`
+ *  default to the current selection, the menu's own subject. */
+export interface StructureOpOptions {
+  id?: string;
+  ids?: readonly string[];
+  /** `create`: which creatable kind (see the adapter's `creatableKinds`). */
+  kind?: string;
+  /** `create`/`reparent`/`paste`: the destination; `null`/absent = document root. */
+  parentId?: string;
+  /** `reorder`: move immediately before this sibling; absent = to the end. */
+  beforeSiblingId?: string;
+  /** `wrap`: the wrapper tag; absent = the adapter's own default. */
+  tag?: string;
+}
+
+/** What one structure op answers. `write` is the same per-edit ack
+ *  `editor.setField()` carries — `persisted: false` means the tree moved and
+ *  no byte did. `id`/`ids` name what the op produced, when it produces one. */
+export interface StructureOpResult {
+  id?: string | null;
+  ids?: readonly string[];
+  write?: InspectedWriteDestination;
+  /** `copy` only: whether the clipboard actually took the payload. */
+  copied?: boolean;
+}
+
 // ---------------------------------------------------------------- hierarchy
 //
 // The wire mirror of the editor's own `SerializedHierarchyPanel`