@galfus/transport-types 0.31.0-alpha → 0.31.1-alpha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@galfus/transport-types",
-  "version": "0.31.0-alpha",
+  "version": "0.31.1-alpha",
   "description": "Shared TypeScript types and protocol definitions for Galfus Engine transports",
   "author": "Renato Rodrigues (morbden) <renato@vulppi.dev>",
   "license": "Apache-2.0",

package/src/sdk/galfus.ts

@@ -0,0 +1,1213 @@
+/* Automatically generated by Galfus Engine codegen. Do not edit directly. */
+/* Canonical shared domain types and payload specifications for Galfus Engine host bindings. */
+
+/** Value object used for frequent 3D transform updates. */
+export interface Transform3D {
+  position: [number, number, number];
+  rotation?: [number, number, number, number];
+  scale?: [number, number, number];
+}
+
+/** Value object used for frequent 2D transform updates. */
+export interface Transform2D {
+  position: [number, number];
+  rotation?: number;
+  scale?: [number, number];
+  zLayer?: number;
+  drawOrder?: number;
+}
+
+/** Optional world-space target used by a 3D camera. */
+export interface CameraLookAt3D {
+  target: [number, number, number];
+  up?: [number, number, number];
+}
+
+/** Platform environment capabilities as structured data. */
+export interface PlatformCapabilities {
+  supportsMultipleWindows: boolean;
+  supportsWindowPositioning: boolean;
+  supportsCursorGrab: boolean;
+  supportsGamepad: boolean;
+  supportsAudio: boolean;
+  isHeadless: boolean;
+}
+
+/** Initial or requested window presentation state. */
+export type WindowState = "windowed" | "minimized" | "maximized" | "fullscreen" | "borderlessFullscreen";
+
+/** Configuration options used to create a new surface or window. */
+export interface WindowConfig {
+  id: number;
+  title: string;
+  size?: [number, number];
+  position?: [number, number];
+  resizable?: boolean;
+  decorations?: boolean;
+  transparent?: boolean;
+  initialState?: WindowState;
+  canvasId?: string;
+}
+
+/** Physical kind of pointing device. */
+export type PointerType = "mouse" | "touch" | "pen";
+
+/** Button identifier for pointer events. */
+export type PointerButton =
+  | "primary"
+  | "secondary"
+  | "auxiliary"
+  | "back"
+  | "forward"
+  | { other: number };
+
+/** State of a pointer button action. */
+export type PointerButtonState = "pressed" | "released";
+
+/** Pointer scroll offset unit and magnitude. */
+export type ScrollDelta =
+  | { lines: [number, number] }
+  | { pixels: [number, number] };
+
+/** Pointer movement, action, and lifecycle events. */
+export type PointerEvent =
+  | { kind: "pointer"; type: "move"; windowId: number; pointerId: number; pointerType: PointerType; position: [number, number]; delta: [number, number]; pressure: number }
+  | { kind: "pointer"; type: "button"; windowId: number; pointerId: number; pointerType: PointerType; position: [number, number]; button: PointerButton; state: PointerButtonState; pressure: number }
+  | { kind: "pointer"; type: "enter"; windowId: number; pointerId: number; pointerType: PointerType; position: [number, number] }
+  | { kind: "pointer"; type: "leave"; windowId: number; pointerId: number; pointerType: PointerType; position: [number, number] }
+  | { kind: "pointer"; type: "cancel"; windowId: number; pointerId: number; pointerType: PointerType; position: [number, number] }
+  | { kind: "pointer"; type: "scroll"; windowId: number; pointerId: number; pointerType: PointerType; position: [number, number]; delta: ScrollDelta };
+
+/** Active modifier keys on keyboard or input events. */
+export interface ModifiersState {
+  shift: boolean;
+  ctrl: boolean;
+  alt: boolean;
+  superKey: boolean;
+}
+
+/** Logical key representation: normalized key string. */
+export type LogicalKey = string;
+
+/** State of a keyboard or button element. */
+export type ElementState = "pressed" | "released";
+
+/** Keyboard, committed text, modifier, and input method events. Use textInput as the single stream of committed text. */
+export type KeyboardEvent =
+  | { kind: "keyboard"; type: "input"; windowId: number; physicalKey: string; logicalKey: LogicalKey; text?: string; state: ElementState; modifiers: ModifiersState; repeat: boolean }
+  | { kind: "keyboard"; type: "modifiersChanged"; windowId: number; modifiers: ModifiersState }
+  | { kind: "keyboard"; type: "imeEnabled"; windowId: number }
+  | { kind: "keyboard"; type: "imeDisabled"; windowId: number }
+  | { kind: "keyboard"; type: "imePreedit"; windowId: number; text: string; selection?: [number, number] }
+  | { kind: "keyboard"; type: "imeCommit"; windowId: number; text: string }
+  | { kind: "keyboard"; type: "textInput"; windowId: number; text: string };
+
+/** Window lifecycle, resize, move, and focus events. */
+export type WindowEvent =
+  | { kind: "window"; type: "resized"; windowId: number; width: number; height: number; scaleFactor: number }
+  | { kind: "window"; type: "moved"; windowId: number; x: number; y: number }
+  | { kind: "window"; type: "closeRequested"; windowId: number }
+  | { kind: "window"; type: "focusChanged"; windowId: number; focused: boolean }
+  | { kind: "window"; type: "occluded"; windowId: number; occluded: boolean }
+  | { kind: "window"; type: "scaleFactorChanged"; windowId: number; scaleFactor: number }
+  | { kind: "window"; type: "redrawRequested"; windowId: number };
+
+/** Standard gamepad buttons or custom other button index. */
+export type GamepadButton =
+  | "south"
+  | "east"
+  | "west"
+  | "north"
+  | "leftBumper"
+  | "rightBumper"
+  | "leftTrigger"
+  | "rightTrigger"
+  | "select"
+  | "start"
+  | "guide"
+  | "leftThumbstick"
+  | "rightThumbstick"
+  | "dpadUp"
+  | "dpadDown"
+  | "dpadLeft"
+  | "dpadRight"
+  | { other: number };
+
+/** Standard gamepad axes or custom other axis index. */
+export type GamepadAxis =
+  | "leftStickX"
+  | "leftStickY"
+  | "rightStickX"
+  | "rightStickY"
+  | "leftTrigger"
+  | "rightTrigger"
+  | { other: number };
+
+/** Gamepad button pressed or released state. */
+export type GamepadButtonState = "pressed" | "released";
+
+/** Metadata describing a connected gamepad device. */
+export interface GamepadInfo {
+  id: number;
+  name: string;
+  supportsRumble: boolean;
+}
+
+/** Gamepad lifecycle, button, and axis movement events. */
+export type GamepadEvent =
+  | { kind: "gamepad"; type: "connected"; gamepadId: number; name: string }
+  | { kind: "gamepad"; type: "disconnected"; gamepadId: number }
+  | { kind: "gamepad"; type: "button"; gamepadId: number; button: GamepadButton; state: GamepadButtonState }
+  | { kind: "gamepad"; type: "axis"; gamepadId: number; axis: GamepadAxis; value: number };
+
+/** 3D/2D spatial transform for positional audio emitters and listener ears/microphones. */
+export interface SpatialTransform {
+  position: [number, number, number];
+  rotation?: [number, number, number, number];
+}
+
+/** Configuration parameters for spatial sound attenuation and stereo panning. */
+export interface SpatialAudioConfig {
+  volume?: number;
+  minDistance?: number;
+  maxDistance?: number;
+  rolloff?: number;
+  speed?: number;
+  looping?: boolean;
+}
+
+/** Complete spatial playback state used for frequent voice updates. */
+export interface SpatialAudio {
+  emitter: SpatialTransform;
+  listener: SpatialTransform;
+  config: SpatialAudioConfig;
+}
+
+/** Root enum of all events dispatched from the platform layer. */
+export type PlatformEvent =
+  | WindowEvent
+  | PointerEvent
+  | KeyboardEvent
+  | GamepadEvent;
+
+/** Target type: window surface swapchain or offscreen GPU texture. */
+export type TargetKind =
+  | { type: "window"; windowId: number }
+  | { type: "texture"; width: number; height: number; format?: string };
+
+/** Descriptor for creating a Target in the Multiverse. */
+export interface TargetDesc {
+  kind: TargetKind;
+  size?: [number, number];
+}
+
+/** Horizontal viewport anchor alignment. */
+export type AnchorX = "left" | "center" | "right";
+
+/** Vertical viewport anchor alignment. */
+export type AnchorY = "top" | "center" | "bottom";
+
+/** Measurement unit for viewport dimensions and offsets (pixels or percentage of width/height). */
+export type UnitValue =
+  | { px: number }
+  | { vw: number }
+  | { vh: number };
+
+/** Viewport rectangle defined via responsive anchors (CSS px, vw, vh). */
+export interface ViewportRect {
+  anchorX?: AnchorX;
+  anchorY?: AnchorY;
+  offsetX?: UnitValue;
+  offsetY?: UnitValue;
+  width: UnitValue;
+  height: UnitValue;
+}
+
+/** Filter pass applied after a Realm renders to its Target. */
+export type InvocationFilter =
+  | "sepia"
+  | "grayscale"
+  | "invert"
+  | "vignette"
+  | "tonemapAces"
+  | "chromaticAberration"
+  | "filmGrain"
+  | "edgeOutline"
+  | "posterize"
+  | "blur"
+  | "sharpen"
+  | "fxaa"
+  | "smaa"
+  | "taa"
+  | "ssaaDownsample"
+  | { custom: { shaderId: number; textures?: number[]; samplerIndex?: number } };
+
+/** Anti-aliasing mode: none, fxaa, smaa, taa, ssaa2x, ssaa4x, msaa2x, msaa4x, msaa8x, msaa16x. */
+export type AntiAliasingMode = "none" | "fxaa" | "smaa" | "taa" | "ssaa2x" | "ssaa4x" | "msaa2x" | "msaa4x" | "msaa8x" | "msaa16x";
+
+/** Descriptor linking a Realm to a Target with optional viewport and filters. */
+export interface InvocationDesc {
+  realmId: number;
+  targetId: number;
+  cameraSlot?: number;
+  viewport?: ViewportRect;
+  filters?: InvocationFilter[];
+  zIndex?: number;
+  enabled?: boolean;
+  clearColor?: [number, number, number, number];
+  antiAliasing?: AntiAliasingMode;
+}
+
+/** Binds an output Target texture to a Realm input slot. */
+export interface TargetTextureBinding {
+  sourceTargetId: number;
+  realmId: number;
+  slot: string;
+}
+
+/** Resolved step in the Multiverse frame schedule. */
+export interface ResolvedInvocationStep {
+  invocationId: number;
+  realmId: number;
+  cameraSlot?: number;
+  resolvedViewport: [number, number, number, number];
+  zIndex: number;
+  clearColor?: [number, number, number, number];
+  filters: InvocationFilter[];
+  antiAliasing?: AntiAliasingMode;
+}
+
+/** Group of ordered invocations targeting a single render target. */
+export interface TargetExecutionBlock {
+  targetId: number;
+  invocations: ResolvedInvocationStep[];
+}
+
+/** Complete execution graph schedule resolved for a frame. */
+export interface MultiverseSchedule {
+  targetBlocks: TargetExecutionBlock[];
+  softCutEdges?: ([number, number])[];
+}
+
+/** Normalized pixel format for GPU textures. The format is the single source of truth for texture color space: *Srgb formats decode RGB to linear light when sampled. */
+export type NormalizedTextureFormat = "r8Unorm" | "rg8Unorm" | "rgba8Unorm" | "rgba8UnormSrgb" | "bgra8Unorm" | "bgra8UnormSrgb" | "r16Float" | "rg16Float" | "rgba16Float" | "r32Float" | "rg32Float" | "rgba32Float" | "depth32Float" | "depth24Plus" | "depth24PlusStencil8";
+
+/** Dimensionality of a GPU texture. */
+export type TextureDimension = "d1" | "d2" | "d3";
+
+/** GPU texture usage flags. */
+export interface TextureUsageFlags {
+  copySrc?: boolean;
+  copyDst?: boolean;
+  textureBinding?: boolean;
+  storageBinding?: boolean;
+  renderAttachment?: boolean;
+}
+
+/** Descriptor for creating or allocating a GPU texture. */
+export interface GpuTextureDesc {
+  label?: string;
+  width: number;
+  height: number;
+  depthOrLayers?: number;
+  mipLevels?: number;
+  sampleCount?: number;
+  dimension?: TextureDimension;
+  /** Pixel format and texture color-space contract. Use an *Srgb format for sRGB-encoded pixels; all other formats are linear. */
+  format: NormalizedTextureFormat;
+  usages?: TextureUsageFlags;
+}
+
+/** Sub-rectangle destination coordinates for updating a texture region. */
+export interface TextureUpdateDesc {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** GPU buffer usage flags. */
+export interface BufferUsageFlags {
+  vertex?: boolean;
+  index?: boolean;
+  uniform?: boolean;
+  storage?: boolean;
+  copySrc?: boolean;
+  copyDst?: boolean;
+}
+
+/** Descriptor for creating a shared GPU buffer. */
+export interface BufferDesc {
+  label?: string;
+  usages: BufferUsageFlags;
+}
+
+/** Shared sampler preset selected independently for each 3D material texture slot. */
+export type TextureSampler3D = "linearRepeat" | "linearClamp" | "nearestRepeat" | "nearestClamp";
+
+/** An optional sampler override for one material texture slot. */
+export type TextureSamplerSelection3D = TextureSampler3D | null;
+
+/** Canonical vertex texture-coordinate set selected for a 3D material texture slot. */
+export type TextureUvSet3D = "uv0" | "uv1";
+
+/** Triangle faces rendered by a 3D material. */
+export type MaterialSide3D = "front" | "back" | "double";
+
+/** World-space target and preferred up direction used to derive a 3D camera view. */
+export interface CameraLookAt3DDesc {
+  target: [number, number, number];
+  up?: [number, number, number];
+}
+
+/** Current optional look-at configuration of a 3D camera. */
+export interface CameraLookAt3DStateDesc {
+  enabled: boolean;
+  target?: [number, number, number];
+  up?: [number, number, number];
+}
+
+/** 3D spatial transform containing position, rotation quaternion, and scale. */
+export interface Transform3DDesc {
+  position?: [number, number, number];
+  rotation?: [number, number, number, number];
+  scale?: [number, number, number];
+}
+
+/** 3D Camera configuration supporting perspective and orthographic projection with Reverse-Z. */
+export interface Camera3DDesc {
+  kind?: "perspective" | "orthographic";
+  fovY?: number;
+  near?: number;
+  far?: number;
+  orthoScale?: number;
+  cameraSlot?: number;
+  lookAt?: CameraLookAt3DDesc;
+}
+
+/** PBR 3D material properties and surface configuration. */
+export interface Material3DDesc {
+  surfaceType?: "opaque" | "transparent" | "masked" | "additive" | "refractive" | "mirror" | "portal";
+  /** Alpha threshold for masked surfaces. Defaults to 0.5. */
+  alphaCutoff?: number;
+  /** Triangle faces to render. Defaults to front. */
+  side?: MaterialSide3D;
+  /** sRGB base-color factor. Realm3D converts RGB to linear light before GPU upload. */
+  baseColor?: [number, number, number, number];
+  /** sRGB emissive factor. Realm3D converts RGB to linear light before GPU upload. */
+  emissiveColor?: [number, number, number, number];
+  roughness?: number;
+  metallic?: number;
+  reflectance?: number;
+  refractionIndex?: number;
+  refractionDistortion?: number;
+  /** Base-color texture. Its resource format alone determines whether it is sampled as sRGB or linear. */
+  albedoTextureId?: number;
+  /** Tangent-space normal texture. Its resource format alone determines its sampled color space. */
+  normalTextureId?: number;
+  /** Tangent-space normal map strength. Defaults to 1.0. */
+  normalScale?: number;
+  /** Metallic-roughness texture. Its resource format alone determines its sampled color space. */
+  metallicRoughnessTextureId?: number;
+  /** Ambient-occlusion texture. Its resource format alone determines its sampled color space. */
+  occlusionTextureId?: number;
+  /** Ambient occlusion texture influence from 0.0 to 1.0. Defaults to 1.0. */
+  occlusionStrength?: number;
+  /** Emissive texture. Its resource format alone determines whether it is sampled as sRGB or linear. */
+  emissiveTextureId?: number;
+  /** Canonical texture slots. Each binding inherits color space from its linked texture resource format. */
+  textureSlots?: number[];
+  /** Per-slot sampler presets. Omitted or null slots use linearRepeat. */
+  textureSamplers?: TextureSamplerSelection3D[];
+  /** Per-slot canonical UV sets. Omitted entries use uv0. */
+  textureUvSets?: TextureUvSet3D[];
+  shaderEffect?: string;
+  customParams?: ([number, number, number, number])[];
+}
+
+/** 3D model instance binding a geometry and material. */
+export interface Model3DDesc {
+  geometryId: number;
+  materialId: number;
+  castShadow?: boolean;
+  receiveShadow?: boolean;
+  castOutline?: boolean;
+  /** sRGB outline color; RGB is converted to linear light before GPU upload. */
+  outlineColor?: [number, number, number, number];
+  boneOffset?: number;
+  boneCount?: number;
+  active?: boolean;
+}
+
+/** 3D dynamic light source (directional, point, or spot). */
+export interface Light3DDesc {
+  kind?: "directional" | "point" | "spot";
+  /** sRGB light color; RGB is converted to linear light before GPU upload. */
+  color?: [number, number, number];
+  intensity?: number;
+  range?: number;
+  spotInnerAngleRad?: number;
+  spotOuterAngleRad?: number;
+  castShadow?: boolean;
+}
+
+/** Atmospheric procedural skybox gradient and sun parameters. */
+export interface SkyboxConfig3DDesc {
+  mode?: "none" | "procedural" | "cubemap";
+  /** sRGB sky color; RGB is converted to linear light before GPU upload. */
+  skyColor?: [number, number, number, number];
+  /** sRGB horizon color; RGB is converted to linear light before GPU upload. */
+  horizonColor?: [number, number, number, number];
+  /** sRGB ground color; RGB is converted to linear light before GPU upload. */
+  groundColor?: [number, number, number, number];
+  sunDirection?: [number, number, number, number];
+  /** sRGB sun color; RGB is converted to linear light before GPU upload. The alpha component is linear intensity. */
+  sunColor?: [number, number, number, number];
+  intensity?: number;
+  sunSize?: number;
+  rotation?: number;
+  textureId?: number;
+}
+
+/** Screen-space silhouette outline dilation settings for Realm 3D. */
+export interface OutlineConfig3DDesc {
+  enabled?: boolean;
+  width?: number;
+  threshold?: number;
+  strength?: number;
+}
+
+/** Screen-space ambient occlusion (SSAO) configuration parameters. */
+export interface SsaoConfig3DDesc {
+  enabled?: boolean;
+  radius?: number;
+  bias?: number;
+  power?: number;
+  intensity?: number;
+  blurRadius?: number;
+}
+
+/** Global atmospheric, fog, and ambient lighting parameters for Realm 3D. */
+export interface EnvironmentRealm3DDesc {
+  /** sRGB ambient color; RGB is converted to linear light before GPU upload. */
+  ambientColor?: [number, number, number, number];
+  /** sRGB clear color. */
+  clearColor?: [number, number, number, number];
+  /** sRGB fog color; RGB is converted to linear light before GPU upload. */
+  fogColor?: [number, number, number, number];
+  fogMode?: "none" | "linear" | "exponential";
+  fogStart?: number;
+  fogEnd?: number;
+  fogDensity?: number;
+  exposure?: number;
+  skybox?: SkyboxConfig3DDesc;
+  outline?: OutlineConfig3DDesc;
+  ssao?: SsaoConfig3DDesc;
+  bloom?: BloomConfig3DDesc;
+}
+
+/** Screen-space multi-scale Bloom HDR glow parameters. */
+export interface BloomConfig3DDesc {
+  enabled?: boolean;
+  threshold?: number;
+  knee?: number;
+  intensity?: number;
+  scatter?: number;
+}
+
+/** 3D particle emission shape (point, sphere, box, cone, cylinder). */
+export interface EmissionShape3DDesc {
+  type: "point" | "sphere" | "box" | "cone" | "cylinder";
+  radius?: number;
+  extents?: [number, number, number];
+  angleRad?: number;
+  height?: number;
+}
+
+/** Planar mirror or optical portal gateway configuration. */
+export interface Portal3DDesc {
+  /** Entrance model ID defining portal surface and spatial transform. */
+  modelId: number;
+  /** Optional destination transform. If omitted, operates as a planar mirror. */
+  exitTransform?: Transform3DDesc;
+  /** Whether the mirror/portal is active. */
+  active?: boolean;
+  /** Offscreen buffer resolution scale factor (default 1.0). */
+  resolutionScale?: number;
+}
+
+/** 3D particle emitter configuration (rates, lifetime, speed, colors, sizes, gravity, drag). */
+export interface ParticleEmitter3DDesc {
+  label?: string;
+  materialId?: number;
+  maxParticles?: number;
+  spawnRate?: number;
+  lifetimeRange?: [number, number];
+  speedRange?: [number, number];
+  direction?: [number, number, number];
+  spreadAngleRad?: number;
+  gravity?: [number, number, number];
+  drag?: number;
+  startSizeRange?: [number, number];
+  endSizeRange?: [number, number];
+  /** sRGB particle start color; RGB is converted to linear light before GPU upload. */
+  startColor?: [number, number, number, number];
+  /** sRGB particle end color; RGB is converted to linear light before GPU upload. */
+  endColor?: [number, number, number, number];
+  rotationSpeedRange?: [number, number];
+  uvRect?: [number, number, number, number];
+  emissionShape?: EmissionShape3DDesc;
+  active?: boolean;
+}
+
+/** Instanced 3D model configuration linking a geometry and material to an instanced GPU collection. */
+export interface InstancedModel3DDesc {
+  geometryId: number;
+  materialId: number;
+  capacity?: number;
+  castShadow?: boolean;
+  receiveShadow?: boolean;
+  active?: boolean;
+}
+
+/** A shaped cluster. Byte offsets index the normalized UTF-8 chunk; transform is in SVG viewport coordinates. */
+export interface SvgTextCluster {
+  chunkIndex: number;
+  byteStart: number;
+  byteEnd: number;
+  transform: [number, number, number, number, number, number];
+  advance: number;
+  ascent: number;
+  descent: number;
+  rightToLeft: boolean;
+}
+
+export interface SvgTextLayout {
+  chunks: string[];
+  clusters: SvgTextCluster[];
+  viewportWidth: number;
+  viewportHeight: number;
+}
+
+export interface SvgTextLayoutResult {
+  layout?: SvgTextLayout;
+}
+
+/** Geometric bounds in SVG viewport coordinates. */
+export interface SvgElementRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  viewportWidth: number;
+  viewportHeight: number;
+}
+
+export interface SvgElementRectResult {
+  rect?: SvgElementRect;
+}
+
+/** 2D spatial transform containing position, rotation angle (radians), scale, and z-layer order. */
+export interface Transform2DDesc {
+  position: [number, number];
+  rotation?: number;
+  scale?: [number, number];
+  zLayer?: number;
+  drawOrder?: number;
+}
+
+/** 2D orthographic camera with Reverse-Z depth mapping. */
+export interface Camera2DDesc {
+  orthoScale: number;
+  near?: number;
+  far?: number;
+  layerMask?: number;
+  order?: number;
+  cameraSlot?: number;
+  active?: boolean;
+}
+
+/** 2D material properties with surface classification, texture ID, and optional WGSL surface effect. */
+export interface Material2DDesc {
+  baseColor?: [number, number, number, number];
+  surfaceType?: "opaque" | "transparent" | "masked" | "additive";
+  textureId?: number;
+  normalTextureId?: number;
+  emissiveTextureId?: number;
+  textureSlots?: number[];
+  samplerIndex?: number;
+  alphaCutoff?: number;
+  shaderEffect?: string;
+  customParams?: ([number, number, number, number])[];
+}
+
+/** 2D instanced sprite quad with texture mapping, UV rects, and shadow occlusion. */
+export interface Sprite2DDesc {
+  dimensions: [number, number];
+  pivot?: [number, number];
+  uvRect?: [number, number, number, number];
+  materialId?: number;
+  castShadow?: boolean;
+  receiveShadow?: boolean;
+  occluderOnly?: boolean;
+  shadowHeight?: number;
+  shadowLayerMask?: number;
+  heightRange?: [number, number];
+  drawOrder?: number;
+}
+
+/** 2D vector shape (Rectangle, Circle, or N-gon Polygon) with procedural SDF shading and silhouette shadows. */
+export interface Shape2DDesc {
+  kind: "rectangle" | "circle" | "polygon";
+  size?: [number, number];
+  radius?: number;
+  segments?: number;
+  vertices?: ([number, number])[];
+  materialId?: number;
+  castShadow?: boolean;
+  receiveShadow?: boolean;
+  occluderOnly?: boolean;
+  shadowHeight?: number;
+  shadowLayerMask?: number;
+  heightRange?: [number, number];
+  drawOrder?: number;
+}
+
+/** 2D point light with radial attenuation, penumbra softening, and shadow casting. */
+export interface Light2DDesc {
+  position?: [number, number];
+  z?: number;
+  color: [number, number, number];
+  intensity: number;
+  range: number;
+  lightRadius?: number;
+  shadowLayerMask?: number;
+  castShadow?: boolean;
+  active?: boolean;
+}
+
+/** Global 2D polar shadow map tuning parameters. */
+export interface Shadow2DConfigDesc {
+  shadowContactOffset?: number;
+  ambient?: number;
+  lightRadius?: number;
+  angularResolution?: number;
+}
+
+/** 2D particle emission shape (point, circle, rectangle, line). */
+export interface EmissionShape2DDesc {
+  type: "point" | "circle" | "rectangle" | "line";
+  radius?: number;
+  extents?: [number, number];
+  direction?: [number, number];
+  length?: number;
+}
+
+/** 2D particle emitter configuration (rates, lifetime, speed, colors, sizes, gravity, drag). */
+export interface ParticleEmitter2DDesc {
+  materialId?: number;
+  maxParticles?: number;
+  spawnRate?: number;
+  lifetimeRange?: [number, number];
+  speedRange?: [number, number];
+  direction?: [number, number];
+  spreadAngleRad?: number;
+  gravity?: [number, number];
+  drag?: number;
+  startSizeRange?: [number, number];
+  endSizeRange?: [number, number];
+  startColor?: [number, number, number, number];
+  endColor?: [number, number, number, number];
+  rotationSpeedRange?: [number, number];
+  uvRect?: [number, number, number, number];
+  emissionShape?: EmissionShape2DDesc;
+  zLayer?: number;
+  castShadow?: boolean;
+  receiveShadow?: boolean;
+  active?: boolean;
+}
+
+/** 2D SVG vector entity with mutable DOM and GPU rasterization synchronization. */
+export interface Svg2DDesc {
+  label?: string;
+  source: string;
+  dimensions?: [number, number];
+  scaleFactor?: number;
+  materialId?: number;
+  castShadow?: boolean;
+  receiveShadow?: boolean;
+  shadowHeight?: number;
+  shadowLayerMask?: number;
+  heightRange?: [number, number];
+  occluderOnly?: boolean;
+  drawOrder?: number;
+}
+
+/** Repetition behavior for animation transitions. */
+export type LoopMode = "once" | "loop" | "pingPong";
+
+/** Execution status of an active animation transition. */
+export type TransitionStatus = "idle" | "delay" | "running" | "completed";
+
+/** Lifecycle event classification emitted during transition playback. */
+export type AnimationEventType = "started" | "completed" | "looped";
+
+/** Mathematical easing curve or spring profile for property transitions. */
+export type Easing = "linear" | "easeInQuad" | "easeOutQuad" | "easeInOutQuad" | "easeInCubic" | "easeOutCubic" | "easeInOutCubic" | "easeInQuart" | "easeOutQuart" | "easeInOutQuart" | "easeInQuint" | "easeOutQuint" | "easeInOutQuint" | "easeInSine" | "easeOutSine" | "easeInOutSine" | "easeInExpo" | "easeOutExpo" | "easeInOutExpo" | "easeInCirc" | "easeOutCirc" | "easeInOutCirc" | "easeInBack" | "easeOutBack" | "easeInOutBack" | "easeInElastic" | "easeOutElastic" | "easeInOutElastic" | "easeInBounce" | "easeOutBounce" | "easeInOutBounce";
+
+/** Polymorphic value for animatable properties. */
+export type AnimValue =
+  | { type: "scalar"; value: number }
+  | { type: "vec2"; value: [number, number] }
+  | { type: "vec3"; value: [number, number, number] }
+  | { type: "vec4"; value: [number, number, number, number] }
+  | { type: "quat"; value: [number, number, number, number] }
+  | { type: "transform3D"; value: [number, number, number, number, number, number, number, number, number, number] }
+  | { type: "transform2D"; value: [number, number, number, number, number, number] };
+
+/** Identifies the destination property animated by a transition. */
+export type AnimationTarget =
+  | { kind: "modelTransform3D"; realmId: number; modelId: number }
+  | { kind: "camera3DTransform"; realmId: number; cameraId: number }
+  | { kind: "camera3DLookAt"; realmId: number; cameraId: number }
+  | { kind: "material3DBaseColor"; realmId: number; materialId: number }
+  | { kind: "light3DColor"; realmId: number; lightId: number }
+  | { kind: "light3DTransform"; realmId: number; lightId: number }
+  | { kind: "spriteTransform2D"; realmId: number; spriteId: number }
+  | { kind: "camera2DTransform"; realmId: number; cameraId: number }
+  | { kind: "material2DColor"; realmId: number; materialId: number }
+  | { kind: "shapeTransform2D"; realmId: number; shapeId: number }
+  | { kind: "svgTransform2D"; realmId: number; svgId: number }
+  | { kind: "svgOpacity"; realmId: number; svgId: number }
+  | { kind: "svgAttributeColor"; realmId: number; svgId: number; elementId: string; attribute: string }
+  | { kind: "svgAttributeScalar"; realmId: number; svgId: number; elementId: string; attribute: string }
+  | { kind: "svgAttributeVec2"; realmId: number; svgId: number; elementId: string; attribute: string }
+  | { kind: "invocationClearColor"; invocationId: number }
+  | { kind: "invocationZIndex"; invocationId: number }
+  | { kind: "customChannel"; channelId: number };
+
+/** Configuration specifying duration, delay, curve, and repetition for a transition. */
+export interface TransitionConfig {
+  duration: number;
+  delay?: number;
+  easing?: Easing;
+  loopMode?: LoopMode;
+}
+
+/** Snapshot query state of an active transition. */
+export interface TransitionState {
+  status: TransitionStatus;
+  progress: number;
+  elapsed: number;
+  remainingDelay: number;
+  currentValue: AnimValue;
+  startValue: AnimValue;
+  targetValue: AnimValue;
+}
+
+/** Lifecycle event emitted during transition execution. */
+export interface AnimationEvent {
+  transitionId: number;
+  eventType: AnimationEventType;
+  target?: AnimationTarget;
+  value: AnimValue;
+  elapsed: number;
+}
+
+/** Target evaluated animation value format produced by the path follower. */
+export type PathValueType = "transform3D" | "position3D" | "transform2D" | "position2D";
+
+/** Declarative SVG-like path motion commands with individual duration and easing. */
+export type PathCommand =
+  | { type: "moveTo"; to: number[] }
+  | { type: "lineTo"; to: number[]; duration?: number; easing?: Easing }
+  | { type: "quadTo"; control: number[]; to: number[]; duration?: number; easing?: Easing }
+  | { type: "cubicTo"; control1: number[]; control2: number[]; to: number[]; duration?: number; easing?: Easing }
+  | { type: "smoothTo"; to: number[]; duration?: number; easing?: Easing }
+  | { type: "pause"; duration: number }
+  | { type: "close"; duration?: number; easing?: Easing };
+
+/** Configuration for path follow traversal. */
+export interface PathFollowConfig {
+  duration?: number;
+  delay?: number;
+  easing?: Easing;
+  loopMode?: LoopMode;
+  orientToPath?: boolean;
+  valueType?: PathValueType;
+}
+
+/** Snapshot query state of an active path follower. */
+export interface PathFollowState {
+  status: TransitionStatus;
+  progress: number;
+  elapsed: number;
+  remainingDelay: number;
+  currentValue: AnimValue;
+}
+
+/** Ergonomic helper factories for ViewportRect responsive descriptors. */
+export const ViewportRect = {
+  full(): ViewportRect {
+    return {
+      width: { vw: 100 },
+      height: { vh: 100 }
+    };
+  },
+  px(x: number, y: number, width: number, height: number): ViewportRect {
+    return {
+      offsetX: { px: x },
+      offsetY: { px: y },
+      width: { px: width },
+      height: { px: height }
+    };
+  },
+  pip(
+    anchorX: AnchorX = 'right',
+    anchorY: AnchorY = 'bottom',
+    widthVw = 30,
+    heightVh = 30,
+    marginPx = 20
+  ): ViewportRect {
+    return {
+      anchorX,
+      anchorY,
+      offsetX: { px: marginPx },
+      offsetY: { px: marginPx },
+      width: { vw: widthVw },
+      height: { vh: heightVh }
+    };
+  }
+};
+
+/** Native interface signature exposed by Galfus Engine (Node-API / Bun). */
+export interface GalfusEngine {
+  /** Initializes the global platform coordinator. */
+  platformInit(): void;
+  /** Initializes the global platform coordinator in headless mode. */
+  platformInitHeadless(): void;
+  /** Shuts down and cleans up the platform coordinator. */
+  platformShutdown(): void;
+  /** Retrieves the last recorded error message. */
+  getLastError(): string;
+  /** Retrieves platform environment capabilities as structured data. */
+  platformGetCapabilities(): PlatformCapabilities;
+  /** Creates a new window or binds a surface from a configuration. */
+  windowCreate(config: WindowConfig | string): number;
+  /** Closes and destroys a window by its logical ID. */
+  windowClose(windowId: number): void;
+  /** Updates the title bar of a window. */
+  windowSetTitle(windowId: number, title: string): void;
+  /** Requests keyboard focus for a window input surface. */
+  windowRequestInputFocus(windowId: number): void;
+  /** Configures whether a focused browser window captures Tab key navigation. */
+  windowSetTabCapture(windowId: number, enabled: number): void;
+  /** Enables or disables input method composition for a window. */
+  windowSetImeAllowed(windowId: number, allowed: number): void;
+  /** Sets the input method candidate area in physical window pixels. */
+  windowSetImeCursorArea(windowId: number, x: number, y: number, width: number, height: number): void;
+  /** Updates the cursor grab mode (0: None, 1: Confined, 2: Locked). */
+  windowSetCursorGrab(windowId: number, mode: number): void;
+  /** Updates the visual appearance icon of the cursor. */
+  windowSetCursorIcon(windowId: number, icon: number): void;
+  /** Sets the visual application icon of a window using raw encoded image bytes (ICO, PNG, WebP, JPEG). */
+  windowSetIcon(windowId: number, data: any, dataLen: number): void;
+  /** Pumps platform input events into a fixed-layout batch; its pointers expire on release or shutdown. */
+  platformPumpEvents(): PlatformEvent[];
+  /** Releases an event batch and invalidates its native pointer ranges. */
+  platformReleaseEventBatch(batchId: number): void;
+  /** Retrieves all currently connected gamepads and their capabilities. */
+  gamepadGetConnected(): GamepadInfo[];
+  /** Triggers rumble vibration on a connected gamepad. */
+  gamepadSetRumble(gamepadId: number, strongMagnitude: number, weakMagnitude: number, durationMs: number): void;
+  /** Loads raw audio data bytes (WAV, MP3, OGG, FLAC) from memory under a host logical ID. */
+  audioLoadSound(soundId: number, data: any, dataLen: number): void;
+  /** Plays a registered sound resource and returns its controllable voice ID. */
+  audioPlaySound(soundId: number, volume: number, panning: number, speed: number, looping: boolean): number;
+  /** Plays a spatial sound and returns its controllable voice ID. */
+  audioPlaySoundSpatial(soundId: number, spatial: SpatialAudio): number;
+  /** Updates spatial positioning of an active sound voice relative to a listener ear. */
+  audioUpdateSoundSpatial(voiceId: number, spatial: SpatialAudio): void;
+  /** Pauses a playing sound voice. */
+  audioPauseSound(voiceId: number): void;
+  /** Resumes a paused sound voice. */
+  audioResumeSound(voiceId: number): void;
+  /** Stops a playing or paused sound voice. */
+  audioStopSound(voiceId: number): void;
+  /** Updates the volume of an active sound voice. */
+  audioSetVolume(voiceId: number, volume: number): void;
+  /** Updates the panning of an active sound voice. */
+  audioSetPanning(voiceId: number, panning: number): void;
+  /** Unloads a registered sound resource from memory. */
+  audioUnloadSound(soundId: number): void;
+  /** Reads the physical inner size (width, height) of a Platform window into two uint32 out pointers. */
+  platformGetWindowSizeRaw(windowId: number, outWidth: any, outHeight: any): void;
+  /** Attaches a platform window to the Multiverse context for surface rendering. */
+  multiverseAttachWindow(windowId: number): void | Promise<void>;
+  /** Registers a new Target in the Multiverse using a TargetDesc descriptor. */
+  multiverseCreateTarget(targetId: number, desc: TargetDesc | string): void;
+  /** Destroys a Target in the Multiverse. */
+  multiverseDestroyTarget(targetId: number): void;
+  /** Registers a solid color test Realm in the Multiverse. */
+  multiverseRegisterColorRealm(realmId: number, r: number, g: number, b: number, a: number): void;
+  /** Unregisters a Realm from the Multiverse. */
+  multiverseUnregisterRealm(realmId: number): void;
+  /** Registers a custom WGSL post-processing shader with an ID. */
+  multiverseRegisterShader(shaderId: number, source: string): void;
+  /** Creates an Invocation in the Multiverse linking a Realm to a Target. */
+  multiverseCreateInvocation(invocationId: number, desc: InvocationDesc | string): void;
+  /** Destroys an Invocation in the Multiverse. */
+  multiverseDestroyInvocation(invocationId: number): void;
+  /** Enables or disables an Invocation in the Multiverse. */
+  multiverseSetInvocationEnabled(invocationId: number, enabled: boolean): void;
+  /** Updates the presentation order of an Invocation. */
+  multiverseSetInvocationZIndex(invocationId: number, zIndex: number): void;
+  /** Updates the viewport rectangle of an existing Invocation. */
+  multiverseSetInvocationViewport(invocationId: number, viewport: ViewportRect | string): void;
+  /** Updates the post-process filter chain for an Invocation. */
+  multiverseSetInvocationFilters(invocationId: number, filters: InvocationFilter[] | string): void;
+  /** Updates the clear color of an Invocation. */
+  multiverseSetInvocationClearColor(invocationId: number, r: number, g: number, b: number, a: number, hasClear: boolean): void;
+  /** Updates the camera slot bound to an existing Invocation. */
+  multiverseSetInvocationCameraSlot(invocationId: number, cameraSlot: number, hasSlot: boolean): void;
+  /** Binds a Target output texture to a Realm input slot. */
+  multiverseBindTargetTexture(binding: TargetTextureBinding | string): void;
+  /** Unbinds a Target texture from a Realm input slot. */
+  multiverseUnbindTargetTexture(realmId: number, slot: string): void;
+  /** Updates the size of a window Target (e.g. on window resize). */
+  multiverseUpdateWindowSize(windowId: number, width: number, height: number): void;
+  /** Resolves and returns the Multiverse execution schedule as structured data. */
+  multiverseResolve(): MultiverseSchedule;
+  /** Dispatches the Multiverse schedule for a frame. */
+  multiverseDispatch(frameId: number, deltaTime: number): void;
+  /** Clears all entities, materials, and scene resources in a Realm without unregistering it. */
+  realmClear(realmId: number): void;
+  /** Destroys a Realm, frees all internal GPU resources, and unregisters it from the Multiverse. */
+  realmDestroy(realmId: number): void;
+  /** Reads the resolved size (width, height) of a Multiverse Target into two uint32 out pointers. */
+  multiverseGetTargetSizeRaw(targetId: number, outWidth: any, outHeight: any): void;
+  /** Sets the global Anti-Aliasing mode for the Multiverse. */
+  multiverseSetAntiAliasing(mode: string): void;
+  /** Gets the current global Anti-Aliasing mode of the Multiverse. */
+  multiverseGetAntiAliasing(): string;
+  /** Allocates and initializes a shared GPU texture under a host logical ID with raw pixel bytes. */
+  resourceCreateTexture(textureId: number, desc: GpuTextureDesc | string, data: any, dataLen: number): void;
+  /** Updates a sub-rectangle of an existing logical texture with raw pixel bytes. */
+  resourceUpdateTexture(textureId: number, rect: TextureUpdateDesc | string, data: any, dataLen: number): void;
+  /** Disposes a shared logical texture from GPU memory. */
+  resourceDisposeTexture(textureId: number): void;
+  /** Allocates and initializes a shared GPU buffer under a host logical ID with raw byte contents. */
+  resourceCreateBuffer(bufferId: number, desc: BufferDesc | string, data: any, dataLen: number): void;
+  /** Updates byte contents of an existing logical buffer at a given offset with raw byte contents. */
+  resourceUpdateBuffer(bufferId: number, offset: number, data: any, dataLen: number): void;
+  /** Disposes a shared logical buffer from GPU memory. */
+  resourceDisposeBuffer(bufferId: number): void;
+  /** Creates and registers a new 3D Realm in the Multiverse. */
+  realm3dCreate(realmId: number): void;
+  /** Destroys and unregisters a 3D Realm from the Multiverse. */
+  realm3dDestroy(realmId: number): void;
+  /** Registers or updates a 3D Camera with its spatial Transform in the 3D Realm. */
+  realm3dCreateCamera(realmId: number, cameraId: number, camera: Camera3DDesc | string, transform: Transform3DDesc | string): void;
+  /** Updates the transform of an existing Camera in the 3D Realm. */
+  realm3dSetCameraTransform(realmId: number, cameraId: number, transform: Transform3D): void;
+  /** Sets the optional world-space look-at point and up direction of an existing 3D Camera. */
+  realm3dSetCameraLookAt(realmId: number, cameraId: number, lookAt: CameraLookAt3D): void;
+  /** Gets the current optional look-at configuration of an existing 3D Camera. */
+  realm3dGetCameraLookAt(realmId: number, cameraId: number): CameraLookAt3DStateDesc;
+  /** Clears the optional look-at configuration of an existing 3D Camera. */
+  realm3dClearCameraLookAt(realmId: number, cameraId: number): void;
+  /** Registers or updates 3D geometry from canonical binary vertex and index buffers. */
+  realm3dCreateGeometry(realmId: number, geometryId: number, topology: number, vertexData: Uint8Array, vertexDataLen: number, indices: Uint32Array, indexCount: number): void;
+  /** Uploads target-major packed MorphVertex3D records (48 bytes each) for an existing geometry. */
+  realm3dSetGeometryMorphTargets(realmId: number, geometryId: number, targetData: Uint8Array, targetDataLen: number, targetCount: number): void;
+  /** Creates a cube primitive centered at the origin. */
+  realm3dCreateCube(realmId: number, geometryId: number, size: number): void;
+  /** Creates a horizontal plane primitive centered at the origin. */
+  realm3dCreatePlane(realmId: number, geometryId: number, width: number, depth: number): void;
+  /** Creates a vertical quad primitive centered at the origin and facing +Z. */
+  realm3dCreateQuad(realmId: number, geometryId: number, width: number, height: number): void;
+  /** Creates a UV sphere primitive centered at the origin. */
+  realm3dCreateSphere(realmId: number, geometryId: number, radius: number, rings: number, sectors: number): void;
+  /** Creates a cylinder primitive centered at the origin along the Y axis. */
+  realm3dCreateCylinder(realmId: number, geometryId: number, radius: number, height: number, sectors: number): void;
+  /** Creates a capsule primitive centered at the origin along the Y axis. */
+  realm3dCreateCapsule(realmId: number, geometryId: number, radius: number, cylinderHeight: number, rings: number, sectors: number): void;
+  /** Creates a pyramid primitive centered at the origin with its apex on +Y. */
+  realm3dCreatePyramid(realmId: number, geometryId: number, width: number, depth: number, height: number): void;
+  /** Creates a torus primitive centered at the origin in the XZ plane. */
+  realm3dCreateTorus(realmId: number, geometryId: number, majorRadius: number, minorRadius: number, majorSegments: number, minorSegments: number): void;
+  /** Registers or updates a 3D Material in the 3D Realm. */
+  realm3dCreateMaterial(realmId: number, materialId: number, material: Material3DDesc | string): void;
+  /** Registers or updates a 3D Model instance in the 3D Realm. */
+  realm3dCreateModel(realmId: number, modelId: number, model: Model3DDesc | string, transform: Transform3DDesc | string): void;
+  /** Updates the transform of an existing Model instance in the 3D Realm. */
+  realm3dSetModelTransform(realmId: number, modelId: number, transform: Transform3D): void;
+  /** Registers or updates an Instanced 3D Model in the 3D Realm. */
+  realm3dCreateInstancedModel(realmId: number, instancedModelId: number, model: InstancedModel3DDesc | string): void;
+  /** Uploads packed instance data: 32 f32 values per instance. */
+  realm3dSetInstancedModelData(realmId: number, instancedModelId: number, data: Float32Array, floatCount: number): void;
+  /** Uploads the current f32 blend weights for an existing model. */
+  realm3dSetModelMorphWeights(realmId: number, modelId: number, weights: Float32Array, weightCount: number): void;
+  /** Uploads the f32 blend weights shared by every instance in an instanced model batch. */
+  realm3dSetInstancedModelMorphWeights(realmId: number, instancedModelId: number, weights: Float32Array, weightCount: number): void;
+  /** Registers or updates a 3D Light in the 3D Realm. */
+  realm3dCreateLight(realmId: number, lightId: number, light: Light3DDesc | string, transform: Transform3DDesc | string): void;
+  /** Updates the transform of an existing Light in the 3D Realm. */
+  realm3dSetLightTransform(realmId: number, lightId: number, transform: Transform3D): void;
+  /** Sets global atmospheric environment properties for the 3D Realm. */
+  realm3dSetEnvironment(realmId: number, environment: EnvironmentRealm3DDesc | string): void;
+  /** Uploads packed 4x4 bone matrices for a model in the 3D Realm. */
+  realm3dUpdateBones(realmId: number, modelId: number, data: Float32Array, floatCount: number): void;
+  /** Queues a 3D debug line segment between start and end with an RGBA color. */
+  realm3dDrawLine(realmId: number, x0: number, y0: number, z0: number, x1: number, y1: number, z1: number, r: number, g: number, b: number, a: number): void;
+  /** Queues a 3D debug Axis-Aligned Bounding Box (AABB) wireframe. */
+  realm3dDrawAabb(realmId: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, r: number, g: number, b: number, a: number): void;
+  /** Clears any queued debug gizmos in the 3D Realm. */
+  realm3dClearGizmos(realmId: number): void;
+  /** Creates or updates a 3D particle emitter entity with an initial transform. */
+  realm3dCreateParticleEmitter(realmId: number, emitterId: number, emitter: ParticleEmitter3DDesc | string, transform: Transform3DDesc | string): void;
+  /** Updates the spatial transform of an existing 3D particle emitter. */
+  realm3dSetParticleEmitterTransform(realmId: number, emitterId: number, transform: Transform3D): void;
+  /** Triggers an immediate burst of particles from an existing 3D emitter. */
+  realm3dParticleEmitterBurst(realmId: number, emitterId: number, count: number): void;
+  /** Destroys an existing 3D particle emitter entity. */
+  realm3dDestroyParticleEmitter(realmId: number, emitterId: number): void;
+  /** Registers or updates a 3D optical portal or planar mirror. */
+  realm3dCreatePortal(realmId: number, portalId: number, portal: Portal3DDesc | string): void;
+  /** Sets whether an existing 3D portal or mirror is active. */
+  realm3dSetPortalActive(realmId: number, portalId: number, active: boolean): void;
+  /** Destroys an existing 3D portal or mirror. */
+  realm3dDestroyPortal(realmId: number, portalId: number): void;
+  /** Destroys an existing 3D camera entity. */
+  realm3dDestroyCamera(realmId: number, cameraId: number): void;
+  /** Destroys an existing 3D material entity. */
+  realm3dDestroyMaterial(realmId: number, materialId: number): void;
+  /** Destroys an existing 3D geometry entity. */
+  realm3dDestroyGeometry(realmId: number, geometryId: number): void;
+  /** Destroys an existing 3D model entity. */
+  realm3dDestroyModel(realmId: number, modelId: number): void;
+  /** Destroys an existing 3D instanced model entity. */
+  realm3dDestroyInstancedModel(realmId: number, instancedModelId: number): void;
+  /** Destroys an existing 3D light entity. */
+  realm3dDestroyLight(realmId: number, lightId: number): void;
+  /** Reads the transform of an existing Model instance. */
+  realm3dGetModelTransform(realmId: number, modelId: number): Transform3D;
+  /** Reads the transform of an existing Camera instance. */
+  realm3dGetCameraTransform(realmId: number, cameraId: number): Transform3D;
+  /** Reads the world-space bounding box (min, max) of a 3D model into two 3-float out buffers. */
+  realm3dGetModelAabbRaw(realmId: number, modelId: number, outMin: any, outMax: any): void;
+  /** Creates and registers a new 2D Realm in the Multiverse. */
+  realm2dCreate(realmId: number): void;
+  /** Destroys and unregisters a 2D Realm from the Multiverse. */
+  realm2dDestroy(realmId: number): void;
+  /** Creates or updates a 2D camera with an initial transform. */
+  realm2dCreateCamera(realmId: number, cameraId: number, camera: Camera2DDesc | string, transform: Transform2DDesc | string): void;
+  /** Updates the spatial transform of an existing 2D camera. */
+  realm2dSetCameraTransform(realmId: number, cameraId: number, transform: Transform2D): void;
+  /** Creates or updates a 2D material definition. */
+  realm2dCreateMaterial(realmId: number, materialId: number, material: Material2DDesc | string): void;
+  /** Creates or updates a 2D instanced sprite with an initial transform. */
+  realm2dCreateSprite(realmId: number, spriteId: number, sprite: Sprite2DDesc | string, transform: Transform2DDesc | string): void;
+  /** Updates the spatial transform of an existing 2D sprite. */
+  realm2dSetSpriteTransform(realmId: number, spriteId: number, transform: Transform2D): void;
+  /** Creates or updates a 2D vector shape (Rectangle, Circle, Polygon) with an initial transform. */
+  realm2dCreateShape(realmId: number, shapeId: number, shape: Shape2DDesc | string, transform: Transform2DDesc | string): void;
+  /** Updates the spatial transform of an existing 2D shape. */
+  realm2dSetShapeTransform(realmId: number, shapeId: number, transform: Transform2D): void;
+  /** Creates or updates a 2D point light with an initial transform. */
+  realm2dCreateLight(realmId: number, lightId: number, light: Light2DDesc | string, transform: Transform2DDesc | string): void;
+  /** Updates the spatial transform of an existing 2D light. */
+  realm2dSetLightTransform(realmId: number, lightId: number, transform: Transform2D): void;
+  /** Updates global 2D polar shadow parameters. */
+  realm2dSetShadowConfig(realmId: number, config: Shadow2DConfigDesc | string): void;
+  /** Creates or updates a 2D particle emitter entity with an initial transform. */
+  realm2dCreateParticleEmitter(realmId: number, emitterId: number, emitter: ParticleEmitter2DDesc | string, transform: Transform2DDesc | string): void;
+  /** Updates the spatial transform of an existing 2D particle emitter. */
+  realm2dSetParticleEmitterTransform(realmId: number, emitterId: number, transform: Transform2D): void;
+  /** Triggers an immediate burst of particles from an existing 2D emitter. */
+  realm2dParticleEmitterBurst(realmId: number, emitterId: number, count: number): void;
+  /** Destroys an existing 2D particle emitter entity. */
+  realm2dDestroyParticleEmitter(realmId: number, emitterId: number): void;
+  /** Destroys an existing 2D camera entity. */
+  realm2dDestroyCamera(realmId: number, cameraId: number): void;
+  /** Destroys an existing 2D material entity. */
+  realm2dDestroyMaterial(realmId: number, materialId: number): void;
+  /** Destroys an existing 2D sprite entity. */
+  realm2dDestroySprite(realmId: number, spriteId: number): void;
+  /** Destroys an existing 2D shape entity. */
+  realm2dDestroyShape(realmId: number, shapeId: number): void;
+  /** Destroys an existing 2D light entity. */
+  realm2dDestroyLight(realmId: number, lightId: number): void;
+  /** Reads the transform of an existing Sprite instance. */
+  realm2dGetSpriteTransform(realmId: number, spriteId: number): Transform2D;
+  /** Reads the transform of an existing Camera instance. */
+  realm2dGetCameraTransform(realmId: number, cameraId: number): Transform2D;
+  /** Creates or updates a 2D SVG vector entity with an initial transform. */
+  realm2dCreateSvg(realmId: number, svgId: number, svg: Svg2DDesc | string, transform: Transform2DDesc | string): void;
+  /** Reads the geometric bounds of an SVG element. */
+  realm2dGetSvgElementRect(realmId: number, svgId: number, elementId: string): SvgElementRectResult;
+  /** Reads the shaped text clusters of an SVG text element. */
+  realm2dGetSvgTextLayout(realmId: number, svgId: number, elementId: string): SvgTextLayoutResult;
+  /** Replaces the complete source XML markup string of an existing SVG entity. */
+  realm2dSetSvgSource(realmId: number, svgId: number, source: string): void;
+  /** Sets or overwrites an XML attribute on the matching element ID in the SVG. */
+  realm2dSetSvgAttribute(realmId: number, svgId: number, elementId: string, name: string, value: string): void;
+  /** Removes an XML attribute from the matching element ID in the SVG. */
+  realm2dRemoveSvgAttribute(realmId: number, svgId: number, elementId: string, name: string): void;
+  /** Updates the inner text content of the matching element ID in the SVG. */
+  realm2dSetSvgText(realmId: number, svgId: number, elementId: string, text: string): void;
+  /** Updates the spatial transform of an existing SVG entity. */
+  realm2dSetSvgTransform(realmId: number, svgId: number, transform: Transform2D): void;
+  /** Reads the transform of an existing SVG entity. */
+  realm2dGetSvgTransform(realmId: number, svgId: number): Transform2D;
+  /** Destroys an existing 2D SVG entity. */
+  realm2dDestroySvg(realmId: number, svgId: number): void;
+  /** Registers raw TTF/OTF font binary data from memory (zero filesystem access). Returns the detected font family name. */
+  realm2dLoadFontData(realmId: number, data: any, dataLen: number): string;
+  /** Creates a new property transition with an initial value and timing configuration. */
+  animationCreateTransition(transitionId: number, initialValue: AnimValue | string, config: TransitionConfig | string): void;
+  /** Binds an existing transition to a realm entity or multiverse property target. */
+  animationBindTarget(transitionId: number, target: AnimationTarget | string): void;
+  /** Unbinds a target from a transition and releases its property lock. */
+  animationUnbindTarget(transitionId: number): void;
+  /** Triggers a smooth transition from the live value towards a new target value. */
+  animationTransitionTo(transitionId: number, targetValue: AnimValue | string, config: TransitionConfig | string): void;
+  /** Fast-path helper creating a scalar transition. */
+  animationCreateScalarTransition(transitionId: number, initialScalar: number, duration: number, delay: number, easingId: number): void;
+  /** Fast-path helper smoothly transitioning a scalar property. */
+  animationTransitionToScalar(transitionId: number, targetScalar: number, duration: number, delay: number, easingId: number): void;
+  /** Fast-path transitioning a 3D Transform from 10 raw floats (pos, quat, scale). */
+  animationTransitionToTransform3d(transitionId: number, floats: any, duration: number, delay: number, easingId: number): void;
+  /** Fast-path transitioning a 2D Transform from 6 raw floats (pos, rot, scale, z_layer). */
+  animationTransitionToTransform2d(transitionId: number, floats: any, duration: number, delay: number, easingId: number): void;
+  /** Queries the current playback status and progress of a transition. */
+  animationGetState(transitionId: number): TransitionState;
+  /** Queries the current evaluated value of a transition. */
+  animationGetValue(transitionId: number): AnimValue;
+  /** Destroys an animation transition by ID. */
+  animationDestroyTransition(transitionId: number): void;
+  /** Advances all active animation transitions by dt seconds and applies updates to Multiverse. */
+  animationStep(dt: number): void;
+  /** Drains and returns all queued animation lifecycle events. */
+  animationPumpEvents(): AnimationEvent[];
+  /** Writes directly to a custom animation channel. */
+  animationSetCustomChannel(channelId: number, value: AnimValue | string): void;
+  /** Reads directly from a custom animation channel. */
+  animationGetCustomChannel(channelId: number): AnimValue;
+  /** Creates a new path follower traversing a declarative SVG-like path. */
+  animationCreatePathFollow(pathId: number, commands: PathCommand[] | string, config: PathFollowConfig | string): void;
+  /** Binds a path follower to an entity property target with conflict locking. */
+  animationBindPathFollowTarget(pathId: number, target: AnimationTarget | string): void;
+  /** Unbinds a target from a path follower and releases its property lock. */
+  animationUnbindPathFollowTarget(pathId: number): void;
+  /** Destroys a path follower by ID. */
+  animationDestroyPathFollow(pathId: number): void;
+  /** Queries the current playback status and progress of a path follower. */
+  animationGetPathFollowState(pathId: number): PathFollowState;
+  /** Reads the resolved physical size [width, height] of a Multiverse Target. */
+  multiverseGetTargetSize?(targetId: number): [number, number];
+  /** Reads the inner physical size [width, height] of a Platform window. */
+  platformGetWindowSize?(windowId: number): [number, number];
+  /** Reads the world-space bounding box { min: [x,y,z], max: [x,y,z] } of a 3D model. */
+  realm3dGetModelAabb?(realmId: number, modelId: number): { min: [number, number, number]; max: [number, number, number] };
+}