@vulfram/engine 0.5.8-alpha → 0.17.1-alpha

package/src/types/cmds/geometry.ts

@@ -1,4 +1,5 @@
 import type { PrimitiveShape } from '../kinds';
+import type { ResourceEntry } from './resources';
 
 /** Primitive attribute semantic identifiers. */
 export type GeometryPrimitiveType =
@@ -31,35 +32,35 @@ export interface GeometryPrimitiveEntry {
 
 /** Command payload for creating geometry from buffers. */
 export interface CmdGeometryCreateArgs {
-  windowId: number;
   geometryId: number;
   label?: string;
   entries: GeometryPrimitiveEntry[];
 }
 
-/** Result payload for geometry create. */
-export interface CmdResultGeometryCreate {
-  success: boolean;
-  message: string;
-}
-
 /** Command payload for updating geometry buffers or label. */
 export interface CmdGeometryUpdateArgs {
-  windowId: number;
   geometryId: number;
   label?: string;
-  entries: GeometryPrimitiveEntry[];
+  entries?: GeometryPrimitiveEntry[];
 }
 
-/** Result payload for geometry update. */
-export interface CmdResultGeometryUpdate {
+/** Result payload for geometry upsert. */
+export interface CmdResultGeometryUpsert {
   success: boolean;
   message: string;
 }
 
+/** Upsert payload accepted by the core (`create` or `update`). */
+export type CmdGeometryUpsertArgs =
+  | CmdGeometryCreateArgs
+  | CmdGeometryUpdateArgs;
+
+/** Backward-compatible aliases. */
+export type CmdResultGeometryCreate = CmdResultGeometryUpsert;
+export type CmdResultGeometryUpdate = CmdResultGeometryUpsert;
+
 /** Command payload for disposing geometry. */
 export interface CmdGeometryDisposeArgs {
-  windowId: number;
   geometryId: number;
 }
 
@@ -120,11 +121,10 @@ export type PrimitiveOptions =
 
 /** Command payload for creating a primitive geometry. */
 export interface CmdPrimitiveGeometryCreateArgs {
-  windowId: number;
   geometryId: number;
   label?: string;
   shape: PrimitiveShape;
-  options: PrimitiveOptions;
+  options?: PrimitiveOptions;
 }
 
 /** Result payload for primitive geometry create. */
@@ -134,11 +134,13 @@ export interface CmdResultPrimitiveGeometryCreate {
 }
 
 /** Command payload for listing geometry resources. */
-export interface CmdGeometryListArgs {}
+export interface CmdGeometryListArgs {
+  windowId: number;
+}
 
 /** Result payload for geometry list. */
 export interface CmdResultGeometryList {
   success: boolean;
   message: string;
-  content: number[]; // List of geometry IDs
+  geometries: ResourceEntry[];
 }

package/src/types/cmds/index.ts

@@ -1,107 +1,157 @@
-import * as Sys from './system';
-import * as Win from './window';
+import * as Audio from './audio';
 import * as Cam from './camera';
-import * as Mod from './model';
+import * as Env from './environment';
+import * as Geo from './geometry';
+import * as Giz from './gizmo';
 import * as Lite from './light';
 import * as Mat from './material';
+import * as Mod from './model';
+import * as Realm from './realm';
+import * as Sys from './system';
+import * as Target from './target';
 import * as Tex from './texture';
-import * as Geo from './geometry';
-import * as Shad from './shadow';
-import * as Giz from './gizmo';
-import * as Env from './environment';
+import * as Ui from './ui';
+import * as Win from './window';
 
-export * from './system';
-export * from './window';
+export * from './audio';
 export * from './camera';
-export * from './model';
+export * from './environment';
+export * from './geometry';
+export * from './gizmo';
 export * from './light';
 export * from './material';
-export * from './texture';
-export * from './geometry';
+export * from './model';
+export * from './realm';
+export * from './render-graph';
+export * from './resources';
 export * from './shadow';
-export * from './gizmo';
-export * from './environment';
+export * from './system';
+export * from './target';
+export * from './texture';
+export * from './ui';
+export * from './window';
 
-/** Discriminated union of all core commands. */
+/**
+ * Discriminated union of all commands accepted by core.
+ *
+ * Routing convention:
+ * - world-scoped commands are dispatched through the world command queue
+ * - global commands are dispatched through the global command queue
+ */
 export type EngineCmd =
   | { type: 'cmd-notification-send'; content: Sys.CmdNotificationSendArgs }
+  | {
+      type: 'cmd-system-diagnostics-set';
+      content: Sys.CmdSystemDiagnosticsSetArgs;
+    }
   | { type: 'cmd-window-create'; content: Win.CmdWindowCreateArgs }
   | { type: 'cmd-window-close'; content: Win.CmdWindowCloseArgs }
-  | { type: 'cmd-window-set-title'; content: Win.CmdWindowSetTitleArgs }
-  | { type: 'cmd-window-set-position'; content: Win.CmdWindowSetPositionArgs }
-  | { type: 'cmd-window-get-position'; content: Win.CmdWindowGetPositionArgs }
-  | { type: 'cmd-window-set-size'; content: Win.CmdWindowSetSizeArgs }
-  | { type: 'cmd-window-get-size'; content: Win.CmdWindowGetSizeArgs }
+  | { type: 'cmd-window-measurement'; content: Win.CmdWindowMeasurementArgs }
+  | { type: 'cmd-window-cursor'; content: Win.CmdWindowCursorArgs }
+  | { type: 'cmd-window-state'; content: Win.CmdWindowStateArgs }
   | {
-      type: 'cmd-window-get-outer-size';
-      content: Win.CmdWindowGetOuterSizeArgs;
+      type: 'cmd-upload-buffer-discard-all';
+      content: Sys.CmdUploadBufferDiscardAllArgs;
     }
+  | { type: 'cmd-camera-upsert'; content: Cam.CmdCameraUpsertArgs }
+  | { type: 'cmd-camera-dispose'; content: Cam.CmdCameraDisposeArgs }
+  | { type: 'cmd-model-upsert'; content: Mod.CmdModelUpsertArgs }
+  | { type: 'cmd-pose-update'; content: Mod.CmdPoseUpdateArgs }
+  | { type: 'cmd-model-dispose'; content: Mod.CmdModelDisposeArgs }
+  | { type: 'cmd-light-upsert'; content: Lite.CmdLightUpsertArgs }
+  | { type: 'cmd-light-dispose'; content: Lite.CmdLightDisposeArgs }
+  | { type: 'cmd-material-upsert'; content: Mat.CmdMaterialUpsertArgs }
+  | { type: 'cmd-material-dispose'; content: Mat.CmdMaterialDisposeArgs }
   | {
-      type: 'cmd-window-get-surface-size';
-      content: Win.CmdWindowGetSurfaceSizeArgs;
+      type: 'cmd-texture-create-from-buffer';
+      content: Tex.CmdTextureCreateFromBufferArgs;
     }
-  | { type: 'cmd-window-set-state'; content: Win.CmdWindowSetStateArgs }
-  | { type: 'cmd-window-get-state'; content: Win.CmdWindowGetStateArgs }
-  | { type: 'cmd-window-set-icon'; content: Win.CmdWindowSetIconArgs }
   | {
-      type: 'cmd-window-set-decorations';
-      content: Win.CmdWindowSetDecorationsArgs;
+      type: 'cmd-texture-create-solid-color';
+      content: Tex.CmdTextureCreateSolidColorArgs;
     }
+  | { type: 'cmd-texture-dispose'; content: Tex.CmdTextureDisposeArgs }
+  | { type: 'cmd-texture-bind-target'; content: Tex.CmdTextureBindTargetArgs }
   | {
-      type: 'cmd-window-has-decorations';
-      content: Win.CmdWindowHasDecorationsArgs;
+      type: 'cmd-audio-listener-upsert';
+      content: Audio.CmdAudioListenerUpsertArgs;
     }
-  | { type: 'cmd-window-set-resizable'; content: Win.CmdWindowSetResizableArgs }
-  | { type: 'cmd-window-is-resizable'; content: Win.CmdWindowIsResizableArgs }
   | {
-      type: 'cmd-window-request-attention';
-      content: Win.CmdWindowRequestAttentionArgs;
+      type: 'cmd-audio-listener-dispose';
+      content: Audio.CmdAudioListenerDisposeArgs;
     }
-  | { type: 'cmd-window-focus'; content: Win.CmdWindowFocusArgs }
   | {
-      type: 'cmd-window-set-cursor-visible';
-      content: Win.CmdWindowSetCursorVisibleArgs;
+      type: 'cmd-audio-source-upsert';
+      content: Audio.CmdAudioSourceUpsertArgs;
     }
   | {
-      type: 'cmd-window-set-cursor-grab';
-      content: Win.CmdWindowSetCursorGrabArgs;
+      type: 'cmd-audio-resource-upsert';
+      content: Audio.CmdAudioResourceUpsertArgs;
     }
   | {
-      type: 'cmd-window-set-cursor-icon';
-      content: Win.CmdWindowSetCursorIconArgs;
+      type: 'cmd-audio-source-transport';
+      content: Audio.CmdAudioSourceTransportArgs;
     }
-  | { type: 'cmd-camera-create'; content: Cam.CmdCameraCreateArgs }
-  | { type: 'cmd-camera-update'; content: Cam.CmdCameraUpdateArgs }
-  | { type: 'cmd-camera-dispose'; content: Cam.CmdCameraDisposeArgs }
-  | { type: 'cmd-model-create'; content: Mod.CmdModelCreateArgs }
-  | { type: 'cmd-model-update'; content: Mod.CmdModelUpdateArgs }
-  | { type: 'cmd-model-dispose'; content: Mod.CmdModelDisposeArgs }
-  | { type: 'cmd-light-create'; content: Lite.CmdLightCreateArgs }
-  | { type: 'cmd-light-update'; content: Lite.CmdLightUpdateArgs }
-  | { type: 'cmd-light-dispose'; content: Lite.CmdLightDisposeArgs }
-  | { type: 'cmd-material-create'; content: Mat.CmdMaterialCreateArgs }
-  | { type: 'cmd-material-update'; content: Mat.CmdMaterialUpdateArgs }
-  | { type: 'cmd-material-dispose'; content: Mat.CmdMaterialDisposeArgs }
+  | { type: 'cmd-audio-state-get'; content: Audio.CmdAudioStateGetArgs }
   | {
-      type: 'cmd-texture-create-from-buffer';
-      content: Tex.CmdTextureCreateFromBufferArgs;
+      type: 'cmd-audio-source-dispose';
+      content: Audio.CmdAudioSourceDisposeArgs;
     }
   | {
-      type: 'cmd-texture-create-solid-color';
-      content: Tex.CmdTextureCreateSolidColorArgs;
+      type: 'cmd-audio-resource-dispose';
+      content: Audio.CmdAudioResourceDisposeArgs;
     }
-  | { type: 'cmd-texture-dispose'; content: Tex.CmdTextureDisposeArgs }
-  | { type: 'cmd-geometry-create'; content: Geo.CmdGeometryCreateArgs }
-  | { type: 'cmd-geometry-update'; content: Geo.CmdGeometryUpdateArgs }
+  | { type: 'cmd-geometry-upsert'; content: Geo.CmdGeometryUpsertArgs }
   | { type: 'cmd-geometry-dispose'; content: Geo.CmdGeometryDisposeArgs }
   | {
       type: 'cmd-primitive-geometry-create';
       content: Geo.CmdPrimitiveGeometryCreateArgs;
     }
-  | { type: 'cmd-environment-create'; content: Env.CmdEnvironmentCreateArgs }
-  | { type: 'cmd-environment-update'; content: Env.CmdEnvironmentUpdateArgs }
-  | { type: 'cmd-environment-dispose'; content: Env.CmdEnvironmentDisposeArgs }
-  | { type: 'cmd-shadow-configure'; content: Shad.CmdShadowConfigureArgs }
+  | { type: 'cmd-environment-upsert'; content: Env.CmdEnvironmentUpsertArgs }
+  | {
+      type: 'cmd-environment-dispose';
+      content: Env.CmdEnvironmentDisposeArgs;
+    }
+  | { type: 'cmd-shadow-configure'; content: import('./shadow').CmdShadowConfigureArgs }
+  | { type: 'cmd-realm-create'; content: Realm.CmdRealmCreateArgs }
+  | { type: 'cmd-realm-dispose'; content: Realm.CmdRealmDisposeArgs }
+  | { type: 'cmd-target-upsert'; content: Target.CmdTargetUpsertArgs }
+  | { type: 'cmd-target-dispose'; content: Target.CmdTargetDisposeArgs }
+  | {
+      type: 'cmd-target-layer-upsert';
+      content: Target.CmdTargetLayerUpsertArgs;
+    }
+  | {
+      type: 'cmd-target-layer-dispose';
+      content: Target.CmdTargetLayerDisposeArgs;
+    }
+  | { type: 'cmd-ui-theme-define'; content: Ui.CmdUiThemeDefineArgs }
+  | { type: 'cmd-ui-theme-dispose'; content: Ui.CmdUiThemeDisposeArgs }
+  | { type: 'cmd-ui-document-create'; content: Ui.CmdUiDocumentCreateArgs }
+  | { type: 'cmd-ui-document-dispose'; content: Ui.CmdUiDocumentDisposeArgs }
+  | { type: 'cmd-ui-document-set-rect'; content: Ui.CmdUiDocumentSetRectArgs }
+  | { type: 'cmd-ui-document-set-theme'; content: Ui.CmdUiDocumentSetThemeArgs }
+  | { type: 'cmd-ui-document-get-tree'; content: Ui.CmdUiDocumentGetTreeArgs }
+  | {
+      type: 'cmd-ui-document-get-layout-rects';
+      content: Ui.CmdUiDocumentGetLayoutRectsArgs;
+    }
+  | { type: 'cmd-ui-apply-ops'; content: Ui.CmdUiApplyOpsArgs }
+  | { type: 'cmd-ui-debug-set'; content: Ui.CmdUiDebugSetArgs }
+  | { type: 'cmd-ui-focus-set'; content: Ui.CmdUiFocusSetArgs }
+  | { type: 'cmd-ui-focus-get'; content: Ui.CmdUiFocusGetArgs }
+  | { type: 'cmd-ui-event-trace-set'; content: Ui.CmdUiEventTraceSetArgs }
+  | {
+      type: 'cmd-ui-image-create-from-buffer';
+      content: Ui.CmdUiImageCreateFromBufferArgs;
+    }
+  | { type: 'cmd-ui-image-dispose'; content: Ui.CmdUiImageDisposeArgs }
+  | { type: 'cmd-ui-clipboard-paste'; content: Ui.CmdUiClipboardPasteArgs }
+  | { type: 'cmd-ui-screenshot-reply'; content: Ui.CmdUiScreenshotReplyArgs }
+  | {
+      type: 'cmd-ui-access-kit-action-request';
+      content: Ui.CmdUiAccessKitActionRequestArgs;
+    }
   | { type: 'cmd-model-list'; content: Mod.CmdModelListArgs }
   | { type: 'cmd-material-list'; content: Mat.CmdMaterialListArgs }
   | { type: 'cmd-texture-list'; content: Tex.CmdTextureListArgs }
@@ -111,83 +161,118 @@ export type EngineCmd =
   | { type: 'cmd-gizmo-draw-line'; content: Giz.CmdGizmoDrawLineArgs }
   | { type: 'cmd-gizmo-draw-aabb'; content: Giz.CmdGizmoDrawAabbArgs };
 
-/** Discriminated union of all core command responses. */
+/** Discriminated union of all command responses returned by core. */
 export type CommandResponse =
   | { type: 'notification-send'; content: Sys.CmdResultNotificationSend }
+  | {
+      type: 'system-diagnostics-set';
+      content: Sys.CmdResultSystemDiagnosticsSet;
+    }
   | { type: 'window-create'; content: Win.CmdResultWindowCreate }
   | { type: 'window-close'; content: Win.CmdResultWindowClose }
-  | { type: 'window-set-title'; content: Win.CmdResultWindowSetTitle }
-  | { type: 'window-set-position'; content: Win.CmdResultWindowSetPosition }
-  | { type: 'window-get-position'; content: Win.CmdResultWindowGetPosition }
-  | { type: 'window-set-size'; content: Win.CmdResultWindowSetSize }
-  | { type: 'window-get-size'; content: Win.CmdResultWindowGetSize }
-  | { type: 'window-get-outer-size'; content: Win.CmdResultWindowGetOuterSize }
+  | { type: 'window-measurement'; content: Win.CmdResultWindowMeasurement }
+  | { type: 'window-cursor'; content: Win.CmdResultWindowCursor }
+  | { type: 'window-state'; content: Win.CmdResultWindowState }
   | {
-      type: 'window-get-surface-size';
-      content: Win.CmdResultWindowGetSurfaceSize;
+      type: 'upload-buffer-discard-all';
+      content: Sys.CmdResultUploadBufferDiscardAll;
     }
-  | { type: 'window-set-state'; content: Win.CmdResultWindowSetState }
-  | { type: 'window-get-state'; content: Win.CmdResultWindowGetState }
-  | { type: 'window-set-icon'; content: Win.CmdResultWindowSetIcon }
+  | { type: 'camera-upsert'; content: Cam.CmdResultCameraUpsert }
+  | { type: 'camera-dispose'; content: Cam.CmdResultCameraDispose }
+  | { type: 'model-upsert'; content: Mod.CmdResultModelUpsert }
+  | { type: 'pose-update'; content: Mod.CmdResultPoseUpdate }
+  | { type: 'model-dispose'; content: Mod.CmdResultModelDispose }
+  | { type: 'light-upsert'; content: Lite.CmdResultLightUpsert }
+  | { type: 'light-dispose'; content: Lite.CmdResultLightDispose }
+  | { type: 'material-upsert'; content: Mat.CmdResultMaterialUpsert }
+  | { type: 'material-dispose'; content: Mat.CmdResultMaterialDispose }
   | {
-      type: 'window-set-decorations';
-      content: Win.CmdResultWindowSetDecorations;
+      type: 'texture-create-from-buffer';
+      content: Tex.CmdResultTextureCreateFromBuffer;
     }
   | {
-      type: 'window-has-decorations';
-      content: Win.CmdResultWindowHasDecorations;
+      type: 'texture-create-solid-color';
+      content: Tex.CmdResultTextureCreateSolidColor;
     }
-  | { type: 'window-set-resizable'; content: Win.CmdResultWindowSetResizable }
-  | { type: 'window-is-resizable'; content: Win.CmdResultWindowIsResizable }
+  | { type: 'texture-dispose'; content: Tex.CmdResultTextureDispose }
+  | { type: 'texture-bind-target'; content: Tex.CmdResultTextureBindTarget }
   | {
-      type: 'window-request-attention';
-      content: Win.CmdResultWindowRequestAttention;
+      type: 'audio-listener-upsert';
+      content: Audio.CmdResultAudioListenerUpsert;
     }
-  | { type: 'window-focus'; content: Win.CmdResultWindowFocus }
   | {
-      type: 'window-set-cursor-visible';
-      content: Win.CmdResultWindowSetCursorVisible;
+      type: 'audio-listener-dispose';
+      content: Audio.CmdResultAudioListenerDispose;
     }
   | {
-      type: 'window-set-cursor-grab';
-      content: Win.CmdResultWindowSetCursorGrab;
+      type: 'audio-source-upsert';
+      content: Audio.CmdResultAudioSourceUpsert;
     }
   | {
-      type: 'window-set-cursor-icon';
-      content: Win.CmdResultWindowSetCursorIcon;
+      type: 'audio-resource-upsert';
+      content: Audio.CmdResultAudioResourceUpsert;
     }
-  | { type: 'camera-create'; content: Cam.CmdResultCameraCreate }
-  | { type: 'camera-update'; content: Cam.CmdResultCameraUpdate }
-  | { type: 'camera-dispose'; content: Cam.CmdResultCameraDispose }
-  | { type: 'model-create'; content: Mod.CmdResultModelCreate }
-  | { type: 'model-update'; content: Mod.CmdResultModelUpdate }
-  | { type: 'model-dispose'; content: Mod.CmdResultModelDispose }
-  | { type: 'light-create'; content: Lite.CmdResultLightCreate }
-  | { type: 'light-update'; content: Lite.CmdResultLightUpdate }
-  | { type: 'light-dispose'; content: Lite.CmdResultLightDispose }
-  | { type: 'material-create'; content: Mat.CmdResultMaterialCreate }
-  | { type: 'material-update'; content: Mat.CmdResultMaterialUpdate }
-  | { type: 'material-dispose'; content: Mat.CmdResultMaterialDispose }
   | {
-      type: 'texture-create-from-buffer';
-      content: Tex.CmdResultTextureCreateFromBuffer;
+      type: 'audio-source-transport';
+      content: Audio.CmdResultAudioSourceTransport;
     }
+  | { type: 'audio-state-get'; content: Audio.CmdResultAudioStateGet }
   | {
-      type: 'texture-create-solid-color';
-      content: Tex.CmdResultTextureCreateSolidColor;
+      type: 'audio-source-dispose';
+      content: Audio.CmdResultAudioSourceDispose;
     }
-  | { type: 'texture-dispose'; content: Tex.CmdResultTextureDispose }
-  | { type: 'geometry-create'; content: Geo.CmdResultGeometryCreate }
-  | { type: 'geometry-update'; content: Geo.CmdResultGeometryUpdate }
+  | {
+      type: 'audio-resource-dispose';
+      content: Audio.CmdResultAudioResourceDispose;
+    }
+  | { type: 'geometry-upsert'; content: Geo.CmdResultGeometryUpsert }
   | { type: 'geometry-dispose'; content: Geo.CmdResultGeometryDispose }
   | {
       type: 'primitive-geometry-create';
       content: Geo.CmdResultPrimitiveGeometryCreate;
     }
-  | { type: 'environment-create'; content: Env.CmdResultEnvironment }
-  | { type: 'environment-update'; content: Env.CmdResultEnvironment }
+  | { type: 'environment-upsert'; content: Env.CmdResultEnvironment }
   | { type: 'environment-dispose'; content: Env.CmdResultEnvironment }
-  | { type: 'shadow-configure'; content: Shad.CmdResultShadowConfigure }
+  | {
+      type: 'shadow-configure';
+      content: import('./shadow').CmdResultShadowConfigure;
+    }
+  | { type: 'realm-create'; content: Realm.CmdResultRealmCreate }
+  | { type: 'realm-dispose'; content: Realm.CmdResultRealmDispose }
+  | { type: 'target-upsert'; content: Target.CmdResultTargetUpsert }
+  | { type: 'target-dispose'; content: Target.CmdResultTargetDispose }
+  | {
+      type: 'target-layer-upsert';
+      content: Target.CmdResultTargetLayerUpsert;
+    }
+  | {
+      type: 'target-layer-dispose';
+      content: Target.CmdResultTargetLayerDispose;
+    }
+  | { type: 'ui-theme-define'; content: Ui.CmdResultUiThemeDefine }
+  | { type: 'ui-theme-dispose'; content: Ui.CmdResultUiThemeDispose }
+  | { type: 'ui-document-create'; content: Ui.CmdResultUiDocumentCreate }
+  | { type: 'ui-document-dispose'; content: Ui.CmdResultUiDocumentDispose }
+  | { type: 'ui-document-set-rect'; content: Ui.CmdResultUiDocumentSetRect }
+  | { type: 'ui-document-set-theme'; content: Ui.CmdResultUiDocumentSetTheme }
+  | { type: 'ui-document-get-tree'; content: Ui.CmdResultUiDocumentGetTree }
+  | {
+      type: 'ui-document-get-layout-rects';
+      content: Ui.CmdResultUiDocumentGetLayoutRects;
+    }
+  | { type: 'ui-apply-ops'; content: Ui.CmdResultUiApplyOps }
+  | { type: 'ui-debug-set'; content: Ui.CmdResultUiDebugSet }
+  | { type: 'ui-focus-set'; content: Ui.CmdResultUiFocusSet }
+  | { type: 'ui-focus-get'; content: Ui.CmdResultUiFocusGet }
+  | { type: 'ui-event-trace-set'; content: Ui.CmdResultUiEventTraceSet }
+  | {
+      type: 'ui-image-create-from-buffer';
+      content: Ui.CmdResultUiImageCreateFromBuffer;
+    }
+  | { type: 'ui-image-dispose'; content: Ui.CmdResultUiImageDispose }
+  | { type: 'ui-clipboard-paste'; content: Ui.CmdResultUiInputEvent }
+  | { type: 'ui-screenshot-reply'; content: Ui.CmdResultUiInputEvent }
+  | { type: 'ui-access-kit-action-request'; content: Ui.CmdResultUiInputEvent }
   | { type: 'model-list'; content: Mod.CmdResultModelList }
   | { type: 'material-list'; content: Mat.CmdResultMaterialList }
   | { type: 'texture-list'; content: Tex.CmdResultTextureList }
@@ -197,35 +282,21 @@ export type CommandResponse =
   | { type: 'gizmo-draw-line'; content: Giz.CmdResultGizmoDraw }
   | { type: 'gizmo-draw-aabb'; content: Giz.CmdResultGizmoDraw };
 
-/** Envelope used when batching commands to the core. */
+/** Command envelope used in batched transport payloads. */
 export interface EngineCmdEnvelope {
   id: number;
   type: EngineCmd['type'];
   content: EngineCmd['content'];
 }
 
-/** Envelope used when decoding responses from the core. */
+/** Response envelope returned by queue polling and routed by command id. */
 export interface CommandResponseEnvelope {
   id: number;
   type: CommandResponse['type'];
   content: CommandResponse['content'];
 }
 
-/** Batch of commands sent in a single tick. */
+/** Batched commands payload sent to transport. */
 export type EngineBatchCmds = EngineCmdEnvelope[];
-
-/** Batch of responses received from the core. */
+/** Batched responses payload decoded from transport. */
 export type EngineBatchResponses = CommandResponseEnvelope[];
-
-/** Result codes returned by core entrypoints. */
-export enum VulframResult {
-  Success = 0,
-  UnknownError = 1,
-  NotInitialized = 2,
-  AlreadyInitialized = 3,
-  WrongThread = 4,
-  CmdInvalidMessagePackError = 5,
-  BufferNotFound = 6,
-  BufferIdCollision = 7,
-  InvalidUploadType = 8,
-}

package/src/types/cmds/light.ts

@@ -1,8 +1,9 @@
 import type { LightKind } from '../kinds';
+import type { ResourceEntry } from './resources';
 
 /** Command payload for creating a light. */
 export interface CmdLightCreateArgs {
-  windowId: number;
+  realmId: number;
   lightId: number;
   label?: string;
   kind?: LightKind;
@@ -17,15 +18,9 @@ export interface CmdLightCreateArgs {
   castShadow?: boolean;
 }
 
-/** Result payload for light create. */
-export interface CmdResultLightCreate {
-  success: boolean;
-  message: string;
-}
-
 /** Command payload for updating a light. */
 export interface CmdLightUpdateArgs {
-  windowId: number;
+  realmId: number;
   lightId: number;
   label?: string;
   kind?: LightKind;
@@ -40,15 +35,22 @@ export interface CmdLightUpdateArgs {
   castShadow?: boolean;
 }
 
-/** Result payload for light update. */
-export interface CmdResultLightUpdate {
+/** Result payload for light upsert. */
+export interface CmdResultLightUpsert {
   success: boolean;
   message: string;
 }
 
+/** Upsert payload accepted by the core (`create` or `update`). */
+export type CmdLightUpsertArgs = CmdLightCreateArgs | CmdLightUpdateArgs;
+
+/** Backward-compatible aliases. */
+export type CmdResultLightCreate = CmdResultLightUpsert;
+export type CmdResultLightUpdate = CmdResultLightUpsert;
+
 /** Command payload for disposing a light. */
 export interface CmdLightDisposeArgs {
-  windowId: number;
+  realmId: number;
   lightId: number;
 }
 
@@ -59,11 +61,13 @@ export interface CmdResultLightDispose {
 }
 
 /** Command payload for listing lights. */
-export interface CmdLightListArgs {}
+export interface CmdLightListArgs {
+  windowId: number;
+}
 
 /** Result payload for light list. */
 export interface CmdResultLightList {
   success: boolean;
   message: string;
-  content: number[]; // List of light IDs
+  lights: ResourceEntry[];
 }

package/src/types/cmds/material.ts

@@ -1,4 +1,5 @@
 import type { MaterialKind, TransparencyMode, SamplerMode } from '../kinds';
+import type { ResourceEntry } from './resources';
 
 /** Standard material options. */
 export interface StandardOptions {
@@ -47,37 +48,35 @@ export type MaterialOptions =
 
 /** Command payload for creating a material. */
 export interface CmdMaterialCreateArgs {
-  windowId: number;
   materialId: number;
   label?: string;
   kind: MaterialKind;
   options?: MaterialOptions;
 }
 
-/** Result payload for material create. */
-export interface CmdResultMaterialCreate {
-  success: boolean;
-  message: string;
-}
-
 /** Command payload for updating a material. */
 export interface CmdMaterialUpdateArgs {
-  windowId: number;
   materialId: number;
   label?: string;
   kind?: MaterialKind;
   options?: MaterialOptions;
 }
 
-/** Result payload for material update. */
-export interface CmdResultMaterialUpdate {
+/** Result payload for material upsert. */
+export interface CmdResultMaterialUpsert {
   success: boolean;
   message: string;
 }
 
+/** Upsert payload accepted by the core (`create` or `update`). */
+export type CmdMaterialUpsertArgs = CmdMaterialCreateArgs | CmdMaterialUpdateArgs;
+
+/** Backward-compatible aliases. */
+export type CmdResultMaterialCreate = CmdResultMaterialUpsert;
+export type CmdResultMaterialUpdate = CmdResultMaterialUpsert;
+
 /** Command payload for disposing a material. */
 export interface CmdMaterialDisposeArgs {
-  windowId: number;
   materialId: number;
 }
 
@@ -88,11 +87,13 @@ export interface CmdResultMaterialDispose {
 }
 
 /** Command payload for listing materials. */
-export interface CmdMaterialListArgs {}
+export interface CmdMaterialListArgs {
+  windowId: number;
+}
 
 /** Result payload for material list. */
 export interface CmdResultMaterialList {
   success: boolean;
   message: string;
-  content: number[]; // List of material IDs
+  materials: ResourceEntry[];
 }