lecodes-sdk 0.19.0

package/src/bridges.d.ts

@@ -0,0 +1,1345 @@
+// The host ABI. These four objects are injected onto the global scope by the runtime host
+// (web viewer, desktop, iOS) before any user/SDK code runs. The SDK is a thin, typed re-skin over
+// them — it never bundles them; it only references them as free globals. Faithfully tracks the
+// surface in packages/worker/src/global.d.ts (the proven contract).
+
+declare global {
+
+  // ---- 3D engine (Filament / creator-gl) -------------------------------------------------------
+  var _creator: {
+    backend: string
+
+    createScene(): number
+    createOverlayScene(sceneId: number): number
+    createGLView(): void
+    openScene(sceneId: number): void
+    closeScene(): void
+    launchAR(sceneId: number, onComplete: () => void, onReject: () => void): void
+    stopAR(): void
+    launchVR(sceneId: number, onComplete: () => void, onReject: (err?: unknown) => void): void
+    stopVR(): void
+    addEntityToScene(sceneId: number, entityId: number): void
+    removeEntityFromScene(sceneId: number, entityId: number): void
+    getSceneMaterial(sceneId: number): number
+    warmRender(sceneId: number, onComplete: () => void): void
+
+    createEntity(): number
+    cloneEntity(entityId: number): number
+    destroyEntity(entityId: number): void
+
+    setMatrix(entityId: number, mat: Float32Array): void
+    setWorldMatrix(entityId: number, mat: Float32Array): void
+    getChildren(entityId: number): number[]
+    getChildCount(entityId: number): number
+    getChild(entityId: number, index: number): number
+
+    setPosition(entityId: number, x: number, y: number, z: number): void
+    setQuaternion(entityId: number, x: number, y: number, z: number, w: number): void
+    setEulerAngles(entityId: number, x: number, y: number, z: number, order: number): void
+    setScale(entityId: number, x: number, y: number, z: number): void
+
+    addChildren(parentEntityId: number, entityIds: number[]): void
+    setParent(entityId: number, parentEntityId: number, worldPositionStays: boolean): void
+    setParentNull(entityId: number, worldPositionStays: boolean): void
+    getParent(entityId: number): number
+    traverse(entityId: number, callback: (entityId: number) => void): void
+    /** Descendant of `entityId` by name, with the Animator's binding rule: exact name first, then the
+     *  short name (after the last `:` / `|` — Mixamo `mixamorig:Hips`); a skin joint beats a plain node
+     *  of the same name (merged GLBs carrying a leftover skeleton copy), otherwise first in tree order.
+     *  0 when absent. Optional: hosts that predate it fall back to the SDK's traverse walk (node.bone). */
+    findNode?(entityId: number, name: string): number
+
+    createSunLight(entityId: number, x: number, y: number, z: number, intensity: number, color: number, shadowsQuality: number, shadowDistance: number): void
+    /** Punctual light. `intensity` is luminous POWER in lumens; `falloff` is the metres of
+     *  influence (filament's own default is 1 m, i.e. invisible, so it is always passed). */
+    createPointLight?(entityId: number, intensity: number, color: number, falloff: number, castShadows: boolean): void
+    /** Live intensity for any light (sun: lux, point: lumens) — a flash animates instead of rebuilding. */
+    setLightIntensity?(entityId: number, intensity: number): void
+    setLightColor?(entityId: number, color: number): void
+    /** `iblFetchId` (optional, -1 = none) names the scene's own probe; without it the host looks for a project-wide `ibl.ktx`. */
+    setDefaultIbl(sceneId: number, intensity: number, iblFetchId?: number): void
+    setBloomOptions(sceneId: number, enabled: boolean, strength: number, quality: number): void
+    setToneMapping?(sceneId: number, mode: number): void
+    /** Exposure of the scene's camera — filament's physical model: `aperture` f-stops,
+     *  `shutterSpeed` seconds, `sensitivity` ISO (default f/16, 1/125 s, ISO 100 = EV100 15, bright
+     *  sunlight). ISO ×2 = one stop brighter. Scene-referred light follows it; particle emission is
+     *  post-exposure and does not. Optional: hosts that predate it keep the fixed default. */
+    setCameraExposure?(sceneId: number, aperture: number, shutterSpeed: number, sensitivity: number): void
+    /** Display output range (macOS/iOS EDR, `device.hdr`). `getDisplayHeadroom` is what the engine
+     *  renders to right now: the screen's peak as a multiple of SDR white, quantised to half-stops;
+     *  0 or 1 = SDR. Live — it ramps up from 1 over the first seconds, follows brightness and the
+     *  screen under the window. `getDisplayMaxHeadroom` is the peak the surface can reach at all
+     *  (1 = SDR), constant once the surface exists: the value to branch content on. Optional: hosts
+     *  that predate it, or render 8-bit, are SDR. */
+    getDisplayHeadroom?(): number
+    getDisplayMaxHeadroom?(): number
+    /** HDR look, engine-wide (creator.h `setHdrStrength` / `setHdrPaperWhite`): `strength` 0..1 =
+     *  how much of the picture reaches for the headroom (0 only what SDR clipped, 1 nearly
+     *  everything), `paperWhite` 1..8 = where the operator's white lands as a multiple of SDR white
+     *  (the "HDR brightness" of a console calibration screen; clamped to the headroom). A host may
+     *  pin either from its environment — the getters report what is in force. Optional. */
+    setHdrStrength?(strength: number): void
+    getHdrStrength?(): number
+    setHdrPaperWhite?(paperWhite: number): void
+    getHdrPaperWhite?(): number
+    /** Screen-space ambient occlusion: the contact darkening in creases and where objects meet the
+     *  ground. `radius` is world-space metres, `power` the falloff contrast, `quality` 0 LOW … 3
+     *  ULTRA (sample count — not the buffer resolution, which stays half-res).
+     *  Optional: hosts that predate it render without AO and the SDK skips the call. */
+    setAmbientOcclusionOptions?(sceneId: number, enabled: boolean, intensity: number, radius: number, power: number, quality: number): void
+    /** Distance fog / aerial perspective. `color` is packed 0xRRGGBB used as a TINT on the
+     *  in-scattered ambient — the engine multiplies it by the environment luminance, so white means
+     *  "as bright as the ambient" and it is NOT the absolute-radiance convention `setSkybox` uses.
+     *  `density` = extinction per metre at `height`, `heightFalloff` 1/m (0 = uniform),
+     *  `cutOff` <= 0 = apply at every distance (the skybox included — that is what blends the
+     *  horizon), `fromIbl` = take the colour from the environment in the view direction and tint
+     *  it by `color`.
+     *  Optional: hosts that predate it render without fog and the SDK skips the call. */
+    setFogOptions?(sceneId: number, enabled: boolean, color: number, distance: number, density: number, height: number, heightFalloff: number, maxOpacity: number, cutOff: number, fromIbl: boolean): void
+    setSkybox(sceneId: number, color: number): void
+    /** Draw the scene's IBL environment as the sky instead of a flat colour. No-op until the IBL
+     *  exists (setDefaultIbl runs first). Optional: hosts that predate it keep the flat skybox. */
+    setSkyboxFromEnvironment?(sceneId: number): void
+    /** The sky from its own KTX1 cubemap. `fetchId` is a local-resource id (`_creatorUtils.fetchLocal`
+     *  / an `asset()` handle), pointing at cmgen's `<name>_skybox.ktx` — the sharp single-mip file,
+     *  not the roughness-prefiltered `_ibl.ktx` beside it. Optional: hosts that predate it keep the
+     *  flat skybox. */
+    setSkyboxTexture?(sceneId: number, fetchId: number): void
+    setSceneMultiSampleAntiAliasing(sceneId: number, enabled: boolean, scale: number): void
+    /** Render resolution: `renderScale` (0.25–1) = fixed 3D-buffer scale vs the viewport (the UI is
+     *  untouched; a host that owns the 3D texture resizes it, one rendering into the swapchain may
+     *  ignore it), `dynamicResolution` = engine-adaptive scaling under that down to `minScale`.
+     *  Optional: older hosts predate it and the SDK skips the call. */
+    setSceneRenderOptions?(sceneId: number, renderScale: number, dynamicResolution: boolean, minScale: number): void
+    /** Anisotropic filtering for every texture bound FROM HERE ON (1 = off, 2 = the engine default,
+     *  16 = max; clamped). Engine-wide rather than per scene, because a sampler is baked when its
+     *  texture is bound — a glTF binds during `Model.load`, and two scenes cannot disagree about a
+     *  texture they share. Call it before loading the assets it should apply to; `SceneOptions.
+     *  anisotropy` does that automatically (a scene's env runs before its nodes build). Optional:
+     *  hosts that predate it keep isotropic filtering and the SDK skips the call. */
+    setTextureAnisotropy?(level: number): void
+    setMaterialGlobalParameter(sceneId: number, i: number, x: number, y: number, z: number, w: number): void
+    getCameraFov(sceneId: number, fovType: number): number
+    /** The scene camera's projection: VERTICAL fov in degrees + near/far clip distances (defaults
+     *  60 / 0.01 / 1000). Aspect stays host-owned — the host STORES these per scene and re-applies
+     *  them whenever the viewport changes, so one call outlives every resize. Optional: hosts that
+     *  predate it keep the fixed defaults and the SDK feature-detects (Camera.setProjection). */
+    setCameraProjection?(sceneId: number, fov: number, near: number, far: number): void
+
+    getMatrix(entityId: number, mat: Float32Array): boolean
+    getWorldMatrix(entityId: number, mat: Float32Array): void
+    getWorldPosition(entityId: number, mat: Float32Array): void
+    getWorldDirection(entityId: number, mode: number, mat: Float32Array): void
+
+    getWorldMatrixInverse(entityId: number, mat: Float32Array): void
+    getCameraViewDirection(sceneId: number, screenX: number, screenY: number, mat: Float32Array): void
+
+    /** `uv1` (optional, 2 floats per vertex) is the lightmap UV set (Geometry.uv1); absent → the
+     *  host duplicates `uv` into UV1. Hosts that predate the argument ignore it. */
+    setMesh(entityId: number, materialId: number, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, meshType: number, uv1?: Float32Array): void
+    // Terrain (gl/Terrain.ts ↔ creator-gl/src/terrain.cpp, docs/terrain-plan.md §1.4): a heightmap grid of
+    // sizeX × sizeZ samples `cellSize` apart (+X across columns, +Z across rows, height on +Y, sample 0 at
+    // the node origin), drawn as one renderable per `chunk`×`chunk` cells on internal children of the
+    // entity (u16 indices → chunk ≤ 255). `holes` = one byte per sample, 1 = hole (a triangle exists only
+    // when its three samples are valid — the same rule as the Jolt height field), null = none. UV0 = local
+    // XZ in metres, UV1 = the terrain's unit square. Returns the chunk count (0 = refused). terrainUpdate
+    // re-reads the FULL arrays and rebuilds the chunks the sample rectangle touches. All optional: a host
+    // without them gets the SDK's own chunk meshes through setMesh (gl/terrainMesh.ts).
+    terrainCreate?(entityId: number, materialId: number, heights: Float32Array, sizeX: number, sizeZ: number, cellSize: number, chunk: number, holes: Uint8Array | null): number
+    terrainUpdate?(entityId: number, heights: Float32Array, holes: Uint8Array | null, x0: number, z0: number, w: number, h: number): void
+    terrainSetMaterial?(entityId: number, materialId: number): void
+    terrainSetShadows?(entityId: number, cast: boolean, receive: boolean): void
+    // Instanced mesh (gl/InstancedMesh.ts ↔ creator-gl/src/instanced.cpp): `count` transforms,
+    // column-major 4×4 local to the node, all-zero = hidden. setInstanceTransforms writes
+    // matrices.length / 16 of them starting at `first` (a subarray view is fine — consumed synchronously).
+    createInstancedMesh(entityId: number, materialId: number, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, count: number): void
+    setInstanceTransforms(entityId: number, matrices: Float32Array, first: number): void
+    setInstancedMeshMaterial(entityId: number, materialId: number): void
+    setInstancedMeshShadows(entityId: number, cast: boolean, receive: boolean): void
+    setCulling(entityId: number, culling: boolean): void
+    setCastShadows(entityId: number, culling: boolean): void
+    setReceiveShadows(entityId: number, culling: boolean): void
+
+    createTexture(systemId: number, onComplete: (id: number, width: number, height: number) => void, onReject: () => void): void
+    // Texture from a baked _creatorCanvas surface (RGBA8, already rasterized — synchronous, no decode).
+    createTextureFromCanvas(surfaceId: number): number
+    updateTextureFromCanvas(texId: number, surfaceId: number): void
+    /** A texture from raw UBYTE pixels — `channels` 1–4, row-major, `width*height*channels` bytes, no
+     *  mips; `srgb` selects the sRGB internal format for 3/4 channels (colour) vs linear (data — a
+     *  terrain's control map). The bytes are copied. Returns 0xFFFFFFFF on failure. `updateTexturePixels`
+     *  re-uploads a sub-rectangle with the creation channel count. Optional (Texture.fromPixels throws). */
+    createTexturePixels?(width: number, height: number, channels: number, data: Uint8Array, srgb: boolean): number
+    updateTexturePixels?(textureId: number, x: number, y: number, width: number, height: number, data: Uint8Array): void
+
+    createMaterial(systemId: number): number
+    createMaterialS(name: string): number
+    setMaterial(entityId: number, materialId: number, index: number): void
+    getMaterial(entityId: number, index: number): number
+
+    setUniformRgb(materialId: number, uniform: string, color: number): void
+    setUniformRgba(materialId: number, uniform: string, color: number): void
+    setUniformFloat(materialId: number, uniform: string, value: number): void
+    setUniformBoolean(materialId: number, uniform: string, value: boolean): void
+    setUniformTexture(materialId: number, uniform: string, systemId: number, wrapS: number, wrapT: number): void
+    setUniformArray(materialId: number, uniform: string, value: Float32Array): void
+    setUniformNull(materialId: number, uniform: string): void
+
+    attachCameraToAR(sceneId: number, cameraEntityId: number, onProjectionChange: (mat: Float32Array, fov: number) => void): void
+    getDisplaySize(): Float32Array
+
+    setVisible(entityId: number, visible: boolean): void
+    isVisible(entityId: number): boolean
+
+    createGlb(systemId: number, onComplete: (buff: number) => void, onReject: () => void): void
+    setGlbCulling(entityId: number, culling: boolean): void
+    /** Optional. True when the host refits a skinned model's frustum-culling bounds to its joints every
+     *  frame (creator-gl animation/skinning.cpp), i.e. culling is safe for animated GLBs. Model.load
+     *  defaults culling ON only where this returns true; absent / false = the always-draw default. */
+    skinnedCullingSupported?(): boolean
+    /** Optional. Level-of-detail override for a GLB instance (docs/lod-plan.md): `mesh` / `anim` are -1 for
+     *  automatic (the engine picks by screen size and visibility) or a forced level 0..3. Backs Model.lod
+     *  and Animator.lod; a host without it (no LOD pass) leaves everything at full detail. */
+    setLod?(entityId: number, mesh: number, anim: number): void
+
+    // Render-synced aspect update(dt) dispatch, called from inside render(). Early = before the physics
+    // step; late = after animations/particles, just before draw. Single-slot per phase (the SDK's Aspect
+    // dispatcher registers one callback per phase that iterates its ordered updater list).
+    setEarlyUpdate(cb: (dt: number) => void): void
+    setLateUpdate(cb: (dt: number) => void): void
+    /** FIXED phase - the SDK's `updateFixed`: once per physics substep with dt = 1/60 exactly, BEFORE
+     *  that substep's Jolt step (move commands / velocities written here feed the same step). Under
+     *  `setTimeScale` the NUMBER of substeps changes, never the dt; at most 4 per frame. `null` clears it -
+     *  registered lazily, only once an aspect declares the phase (one flag check per substep otherwise).
+     *  Optional: a host without it gets the SDK's own 1/60 accumulator inside the early phase. */
+    setFixedUpdate?(cb: ((dt: number) => void) | null): void
+    /** The engine's clock multiplier for physics / animators / particles (1 normal, 0 frozen) — the
+     *  SDK's `Time.scale` / `Time.paused` pushed down so the sims stay in step with game code. The
+     *  two aspect phases still receive the RAW wall-clock dt (the SDK scales it itself). Optional:
+     *  a host without it keeps its sims at wall-clock speed. */
+    setTimeScale?(scale: number): void
+    // Physics contact/sensor events (drained after each step): a/b = entity ids, type 0 enter / 1 exit.
+    setOnPhysicsEvent(cb: (a: number, b: number, type: number) => void): void
+
+    // ---- Animation system (docs/animation-v2-plan.md): AnimationClip + Animator — THE skeletal animation
+    // path, evaluated by creator-anim on every host. A clip set is parsed straight from GLB bytes (tracks
+    // target bone NAMES, no entities); a model's embedded clips are registered by createGlb (getGlbClipSet,
+    // 0 = none). An Animator binds clips to one node hierarchy by name; the native evaluator runs the WHOLE
+    // per-frame loop (sources, transitions, blend spaces, one-shot hand-over, root motion) — the SDK only
+    // issues play/stop/blend calls and has no tick. Skinning is flushed AFTER the late phase so IK /
+    // procedural joint writes land in the skin.
+    // TRANSITIONS ARE INERTIAL, NOT CROSSFADES: a layer evaluates exactly ONE source (its one-shot, its
+    // loop, or nothing); a switch records the difference between the pose the layer SHOWED and the pose the
+    // new source shows and decays it away over `fade` seconds (halflife = 0.4 × fade). A replaced source is
+    // silent from that moment — it costs nothing, its weight is 0 at once, and it may be replaced again
+    // mid-transition (the offset is re-recorded from the displayed pose). `fade` 0 = cut.
+    loadClips(systemId: number, onComplete: (clipSetId: number) => void, onReject: (err: unknown) => void): void
+    // names = newline-joined track targets; data = [trackCount, duration (<=0 → max key time), (path 0 T/1 R/2 S,
+    // interp 0 linear/1 step/2 cubic, comps, keyCount, times…, values…)*]. Returns a one-clip set id (0 = bad).
+    createClipFromTracks(names: string, data: Float32Array): number
+    getClipSetInfo(clipSetId: number): { name: string, duration: number, trackCount: number }[]
+    // A sub-range [start, end] seconds of one clip as a NEW single-clip set (index 0), re-timed to 0;
+    // interior keys copied, boundary values interpolated in at the cut points; events re-timed. 0 = bad id/range.
+    sliceClip(clipSetId: number, clip: number, start: number, end: number): number
+    // Clip events on the CLIP: normalized times (sorted ascending). Every slot bound to the clip, in every
+    // animator, fires slot event type 4 + i on crossing event i. Empty = clear.
+    setClipEvents(clipSetId: number, clip: number, times: Float32Array): void
+    getGlbClipSet(entityId: number): number
+    destroyClipSet(clipSetId: number): void
+    animatorCreate(entityId: number): number                     // 0 = not a transform node
+    animatorDestroy(animatorId: number): void                    // leaves the skeleton in rest pose
+    // One (clip, layer) slot, silent until played / made a blend member. slot index or -1.
+    animatorBind(animatorId: number, clipSetId: number, clipIndex: number, layer: number): number
+    animatorBoundTracks(animatorId: number, slot: number): number
+    // The layer's LOOP: member slots + positions (dims 1: x per member, 2: x,y; one member = a plain looping
+    // clip). The members share ONE cycle clock (aligned by their foot contacts, not by normalized time) and
+    // animatorSetBlendValue picks the mix (1D linear between neighbours / 2D gradient band). Setting it
+    // takes the layer over from whatever it shows — the previous loop and any one-shot on it go silent — with
+    // a transition of `fade`. Empty = no loop. speed = the members' rate.
+    animatorSetBlend(animatorId: number, layer: number, dims: 1 | 2, slots: Uint16Array, positions: Float32Array, fade: number, speed: number): void
+    animatorSetBlendValue(animatorId: number, layer: number, x: number, y: number): void
+    // Play a slot as the layer's one-shot, transitioned in over fadeIn (0 = cut) from whatever the layer
+    // showed (playing a blend MEMBER brings the whole blend back instead). A non-looping one-shot hands the
+    // layer back to the loop at the end, the hand-over firing fadeOut seconds BEFORE the end and the return
+    // transition taking fadeOut; fadeOut < 0 = not given (cut back; on a loopless layer hold the last frame).
+    // restart = rewind even if already playing (a restart is a new source: it transitions from the pose shown).
+    animatorPlay(animatorId: number, slot: number, loop: boolean, speed: number, fadeIn: number, fadeOut: number, restart: boolean): void
+    // TURN WARP for the slot's current play (right after animatorPlay): the node's turn from the clip's baked heading is
+    // scaled to `radians` total; the pose keeps its own turn, the extra pivots about the planted foot. enabled false =
+    // the clip's own turn. Optional: older hosts lack it.
+    animatorSlotSetTurn?(animatorId: number, slot: number, radians: number, enabled: boolean): void
+    // Release over `fade` (a transition toward what is left — the loop, or the rest pose): one slot; a
+    // layer's one-shot + loop (slot -1); everything (layer -1).
+    animatorStop(animatorId: number, layer: number, slot: number, fade: number): void
+    animatorSeek(animatorId: number, slot: number, time: number): void   // seeking a blend member moves the blend
+    animatorGetSlotTime(animatorId: number, slot: number): number
+    animatorGetSlotWeight(animatorId: number, slot: number): number     // 1 = the layer's source, a loop member = its share, else 0
+    // Layer config: weight 0–1; additive = each slot's DELTA vs its clip's first frame on top of the layers
+    // below; maskRoot = bone name(s, '\n'-separated) whose subtrees the layer drives ("" = all).
+    animatorSetLayer(animatorId: number, layer: number, weight: number, additive: boolean, maskRoot: string): void
+    // ANTICIPATION for the layer's next source change: the transition starts with -amount x the new source's
+    // joint velocity (a wind-up against the coming motion), consumed by that switch. Optional: older hosts lack it.
+    animatorSetLayerAnticipation?(animatorId: number, layer: number, amount: number): void
+    animatorSetGlobal(animatorId: number, speed: number, paused: boolean): void
+    // Root motion: "" off, "*" auto (the shallowest joint a base-layer clip translates), else a bone name. The
+    // root's horizontal travel (animator-node frame) is stripped from the pose and, per apply: 0 accumulated
+    // only (animatorGetRootMotion copies + clears out[3]), 1 added to the node's transform, 2 fed to the
+    // CharacterController on the node or an ancestor as a world velocity (falls back to 1 without one).
+    /** `apply` bits 0–1: 0 accumulate only / 1 move the node / 2 feed the CharacterController; bit 2 (+4): the
+     *  root joint's yaw about the node's up is root motion too (off the pose, onto the node the travel lands on). */
+    animatorSetRootMotion(animatorId: number, bone: string, apply: number): void
+    animatorGetRootMotion(animatorId: number, out: Float32Array): void
+    // Slot events: 0 completed (non-loop end) / 1 loop wrapped / 2 settled (no longer a source, after a stop
+    // or a replacement) / 3 HAND-OVER (a one-shot's return starts — for the SDK the clip is over; what the app
+    // starts in response takes the layer over instead) / 4+i clip event i. Single-slot (routed by animatorId).
+    setOnAnimatorEvent(callback: (animatorId: number, slot: number, type: number) => void): void
+    // ---- contacts, phase, root curves (docs/animation-v2-plan.md §2.5–2.6) ----
+    // Every clip bound to a skeleton is baked once against it: when each foot is planted, the gait phase
+    // φ(t) (0 at a left-foot-down, 0.5 at a right-foot-down, unwrapped over the clip; absent for a clip
+    // with no gait cycle) and the root's cumulative travel / yaw / speed. A controller asks these instead
+    // of shipping measured tables of its own.
+    // The feet: '\n'-joined bone names per side (foot[, toe/ball]); both "" = classify by name. Re-bakes.
+    animatorSetFeet(animatorId: number, left: string, right: string): void
+    // One curve of a slot's clip at `time` seconds (< 0 = the slot's clock now): which 0 φ (-1 = no gait)
+    // / 1 travel (m) / 2 yaw (rad, + = left) / 3 speed (m/s) / 4-5 unit travel direction x / z
+    // (model space, held through stills — integrate dir × d(travel) for the root's 2D path).
+    animatorSlotCurveAt(animatorId: number, slot: number, which: 0 | 1 | 2 | 3 | 4 | 5, time: number): number
+    // out ← [curve sample dt, total travel (m), mean speed (m/s), in-place flag]. False = unbound slot.
+    animatorSlotCurveInfo(animatorId: number, slot: number, out: Float32Array): boolean
+    animatorSlotTurn(animatorId: number, slot: number): number          // the clip's total root yaw, rad
+    // The first time the clip has turned `yaw` radians — where a turn is entered by a body already
+    // that far into the same turn, so the two read as one move.
+    animatorSlotTimeAtTurn(animatorId: number, slot: number, yaw: number): number
+    // What the LAYER shows, as a cycle phase in [0, 1) — its loop's clock, or its one-shot's φ; -1 = none.
+    animatorLayerPhase(animatorId: number, layer: number): number
+    // Seek the slot to the first time whose φ ≡ phase (mod 1); a blend member moves its whole group.
+    animatorSeekPhase(animatorId: number, slot: number, phase: number): void
+    // How far the slot's pose is from `target`'s at the same cycle phase, metres (joint distance +
+    // the velocity difference over 0.1 s, the planted foot weighted most) — what handing over to that
+    // clip would hand the inertializer. Fills `out` at the curve rate, returns the sample count.
+    // align: 0 = compare at the same cycle phase, 1 = at the same time (two clips that both begin
+    // from standing have no shared cycle to line up on).
+    animatorSlotFit(animatorId: number, slot: number, target: number, align: 0 | 1, out: Float32Array): number
+    // The earliest time in the slot where that hand-over costs no more than `tolerance` metres;
+    // atContact snaps to the next foot-down at or after it. -1 = never that close.
+    animatorSlotExit(animatorId: number, slot: number, target: number, tolerance: number, atContact: boolean, align: 0 | 1): number
+    // Contact spans as (side 0 left / 1 right, from, to, atX, atY, atZ) sextuplets (seconds, model space);
+    // returns the span count, filling `out` up to its capacity.
+    animatorSlotContacts(animatorId: number, slot: number, out: Float32Array): number
+    // A CLIMBING clip's tread levels (model-space plant heights, sorted ascending): out[0] = the
+    // riser (median level spacing), out[1..] = the levels, filled up to out's capacity. Returns the
+    // level count — 0 for a flat clip.
+    animatorSlotTreads(animatorId: number, slot: number, out: Float32Array): number
+    // The clip's baked physics at `time` seconds (< 0 = the slot's current time), unit body mass,
+    // model space: out11 = COM position xyz, COM velocity xyz (= linear momentum per kg), angular
+    // momentum about the COM xyz, then per-foot support left/right (contact-gated, seesaw split,
+    // scaled by the vertical force proxy — > 1 on a landing, 0 in flight). 0 = no body segments
+    // classified on this skeleton.
+    animatorSlotPhysics(animatorId: number, slot: number, time: number, out: Float32Array): number
+    // The clip's MATCHING FEATURE ROW at `time` (37 floats, the clip's heading frame at that time —
+    // x lateral (+ left), y up, z forward): 0–5 feet positions (relative to the pelvis' ground
+    // point), 6–11 feet velocities, 12–14 pelvis velocity, 15 pelvis height, 16–18 COM velocity,
+    // 19–20 support L/R, 21–22 contact phase L/R, 23 yaw angular momentum, 24–31 the clip's own
+    // path 0.3/0.6/1.0/1.5 s ahead as (lateral, forward) pairs, 32–35 facing change at those
+    // horizons (rad, + = left), 36 cyclic flag. Returns 37, or 0 without a leg chain.
+    animatorSlotFeatures(animatorId: number, slot: number, time: number, out: Float32Array): number
+    // The calibrated knee HINGE AXIS of a side (0 left / 1 right): a unit vector in the thigh's local
+    // frame — a skeleton property, measured over every bound clip's knee rotation track. out8 = axis
+    // xyz, spread mean (rad), spread max (rad), measurement count, 0, 0. 0 = no leg / no knee motion.
+    animatorKneeAxis(animatorId: number, side: number, out: Float32Array): number
+    // The knee's bend plane of a slot's clip at `time` seconds (< 0 = the slot's current time),
+    // predicted from the hinge axis + the clip's own thigh rotation — continuous even where the leg
+    // is straight. out6 = pole xyz (unit, model space, toward the knee — a two-bone solver's bend
+    // direction), then the plane normal xyz. 0 = uncalibrated / no leg.
+    animatorSlotKneePole(animatorId: number, slot: number, side: number, time: number, out: Float32Array): number
+    // Step warp v2: stride scales the feet's travel-direction offsets from the hips (uniform through
+    // stance and swing), lift = metres ADDED to their height (swing-gated by the contact marks;
+    // 0 = neutral, negative = a shuffle; half of what it adds raises the pelvis, capped by the
+    // planted legs' remaining extension), pitchDeg rotates each foot about its lateral axis
+    // (+ = toes up), slopeDeg the invisible staircase (+ = ascending: foot heights follow the
+    // incline + the feet auto-pitch; the HOST climbs the body at tan(slope) × the stride-scaled
+    // travel, which holds each planted foot's world height constant on its tread). Solved in the
+    // calibrated knee hinge plane with a soft reach; the pelvis lowers by any leg's overreach
+    // (marks-weighted, spring-followed, zero when nothing overreaches). 1/0/0/0 = identity;
+    // on false = off.
+    animatorSetStepWarp(animatorId: number, on: boolean, stride: number, lift: number, pitchDeg: number, slopeDeg: number): void
+    // Footsteps: a contact that BEGAN this evaluation on what the base layer shows — side 0 left / 1 right,
+    // x/y/z = the foot's WORLD position at the plant. Fired after the frame's transform commit.
+    setOnAnimatorStep(callback: (animatorId: number, side: number, x: number, y: number, z: number) => void): void
+
+    // ---- drives + warping ----
+    // The character's world velocity this frame: the speed the stride warp fits the stride to and the
+    // direction the orientation warp turns the lower body toward.
+    animatorSetMotion(animatorId: number, vx: number, vy: number, vz: number): void
+    // Cumulative capsule travel (m) and yaw (rad, + = left) — what a slot's distance / angle drive reads.
+    animatorSetDriveInput(animatorId: number, distance: number, angle: number): void
+    // Drive a slot's clock by a quantity instead of time: 0 time / 1 distance / 2 angle. `entry` is the
+    // curve value that corresponds to NOW (a start 0; a stop with D metres left: total travel − D), so
+    // the clip is entered where it already agrees with the body. Stalls fall back to time.
+    animatorSetSlotDrive(animatorId: number, slot: number, mode: 0 | 1 | 2, entry: number): void
+    // [stride on, stride min, stride max, orient on, orient max°, orient time, min speed, pelvis drop]
+    animatorSetWarpParams(animatorId: number, params: Float32Array): void
+
+    // ---- feet: foot lock + ground IK (docs/animation-v2-plan.md §2.9) ----
+    // The feet stage runs in WORLD space inside the evaluation, after the clips are composited: a foot
+    // the shown clip calls planted is pinned where it landed and the leg re-solved to keep it there
+    // while the body moves on (the lock), and each foot is put on the ground the ENGINE probed under it,
+    // the pelvis lowered so the leg reaches (ground IK). The engine casts the probe rays itself against
+    // what a character can stand on (static + moving solids; never the character's own bodies, debris
+    // or sensors) and reads the CharacterController's ground state — nothing per frame from the SDK.
+    // [ik on, lock on, pelvis drop m, unlock distance m, lock-in s, lock-out s, pelvis spring s,
+    //  align to ground normal 0..1, probe half-length m, detector max speed m/s, detector max height m]
+    // Optional: a host without it has no feet stage (the legs stay as animated).
+    animatorSetFeetParams?(animatorId: number, params: Float32Array): void
+    // One foot after this frame's evaluation, side 0 left / 1 right: out ← [locked, lock weight,
+    // anchor xyz, target xyz] (world) — a debug overlay's beam under the foot. False = no such foot.
+    animatorFootState?(animatorId: number, side: number, out: Float32Array): boolean
+
+    // ---- locomotion: the movement model + the clip selector, both engine-side ----
+    // The intent (`locoSetInput`) becomes a desired velocity; the simulated velocity springs toward it
+    // one fixed substep at a time (`locoStep`, given the capsule's place), and `locoUpdate` — called
+    // before the animators are evaluated — picks and drives what the base layer shows. The host moves
+    // the character with the velocity and facing it reads back: in displacement `code` the animation
+    // never moves the body, so "how fast am I" is an input to the animation, not an output of it.
+    locoCreate(animatorId: number): number
+    locoDestroy(loco: number): void
+    // [halflife walk, halflife run, halflife facing, speed walk, speed run, speed sprint, deadzone,
+    //  turn min°, turn big°, blend, stop blend, start tap, resume, predict, displacement (0 code /
+    //  1 data / 2 hybrid), mode (0 rules / 1 matching), match interval, match blend, spin min°, turn
+    //  rate cap (deg/s, 0 = uncapped), halflife braking, hybrid adjustment clamp (m/s)]
+    locoSetParams(loco: number, params: Float32Array): void
+    locoDefaults(out: Float32Array): void
+    // Register a bound slot: kind 0 idle / 1 gait / 2 start / 3 stop / 4 turn / 5 match / 6 spin
+    // (a turn on the spot); `angle` degrees (+ = left) for the starts / turns / spins, `speed` m/s for
+    // a gait (0 = the clip's own measured speed), `gait` the gait a transition belongs to (0 walk /
+    // 1 run / 2 sprint, -1 = any) — a walking body plays the walking starts, stops and turns.
+    locoSetEntry(loco: number, slot: number, kind: number, angle: number, speed: number, gait: number): void
+    locoClearSet(loco: number): void
+    // [dir x, dir z, magnitude 0–1, face x, face z, gait 0 walk / 1 run / 2 sprint] — the facing is
+    // independent of the movement: a released key with a heading still owed turns the body on the spot.
+    locoSetInput(loco: number, input: Float32Array): void
+    // One simulation step at the capsule's world place — from the fixed substep loop.
+    locoStep(loco: number, dt: number, px: number, py: number, pz: number): void
+    // Run the selector for this frame — before the animators are evaluated.
+    locoUpdate(loco: number, dt: number): void
+    // out ← [state (0 idle / 1 start / 2 move / 3 turn / 4 stop / 5 spin), speed, vel x/y/z, yaw (rad,
+    // 0 = +Z, + = toward +X), yaw rate, phase, state sequence, then 3 × (x, z, dir x, dir z) predicted
+    // at +0.2 / +0.4 / +0.7 s].
+    locoRead(loco: number, out: Float32Array): void
+    // Why the last STOP was the one played: one row of 9 floats per candidate weighed — [slot, entry
+    // time, metres it still travels, metres the body needs, seconds to its next foot-down, foot-downs
+    // left, flags (1 = its phase matched, 2 = at/after its first foot-down, 4 = played, 8 = entered
+    // ahead of that foot-down by its pose), score, pose distance from what showed (m, -1 = not
+    // measured)]. Returns the rows written. A debug read; absent on hosts predating it.
+    locoStopReport?(loco: number, out: Float32Array): number
+    // Build the motion-matching database over the registered set (selector mode 1); returns frames.
+    locoBuildDatabase(loco: number): number
+
+    /** Subtree AABB in the entity's OWN local space (its own transform excluded) as
+     *  [minX,minY,minZ, maxX,maxY,maxZ] — zeros for an empty / not-yet-loaded subtree. What
+     *  `Shape.fit()` measures. Optional: absent on hosts predating the binding. */
+    computeBoundingBox?(entityId: number): Float32Array
+    setColliderFromMesh(entityId: number, meshEntityId: number, form: number): void
+    setColliderBox(entityId: number, centerX: number, centerY: number, centerZ: number, sizeX: number, sizeY: number, sizeZ: number): void
+    setColliderSphere(entityId: number, centerX: number, centerY: number, centerZ: number, radius: number): void
+
+    // JoltPhysics. motionType: 0 static / 1 kinematic / 2 dynamic.
+    physicsHasSupport(): boolean
+    /** Lightmap bake (docs/lightmap-plan.md) — a dev-time tool compiled into the desktop host only;
+     *  `lightmapBake` exists only where `lightmapHasSupport()` is true. Writes the raster (lightmap.png, an intermediate the CLI turns into lightmap.ktx2)
+     *  — one per atlas PAGE (`lightmap_<n>.png`, up to `maxPages` of `size` before the texel coarsens) —, the point lights' baked
+     *  irradiance (`lightmap-light[_<n>].png`, sRGB(E / lightScale), `lightRays` shadow rays toward a `lightRadius`-metre disc) when the
+     *  scene holds point lights, lightmap.bake (rects, pages, the baked lights) and lightmap.volume (`volumeCell` > 0)
+     *  into outDir (R = sun visibility, G = ambient occlusion) for the given static instances (GLB roots /
+     *  Mesh entities; `keysJoined` = one key per id, '
+'-joined). Synchronous; progress on stdout. */
+    lightmapHasSupport?(): boolean
+    /** Lightmap consumption (docs/lightmap-plan.md §3): the next createGlb takes lightmap.filamat (the material
+     *  behind that instance id) instead of the ubershader and keeps TEXCOORD_1; UINT32_MAX clears. */
+    setNextGlbLightmapped?(materialInstanceId: number): void
+    /** The level-wide knobs every lightmap-material instance shares (applied to the ones that exist and to every one
+     *  created afterwards): the sun-mask shadow math (ambientScale, sunStrength), how much baked AO applies (aoStrength,
+     *  1 = all) and the light atlas' / volume's physical irradiance per encoded 1.0 (lightScale; 0 = no baked lights).
+     *  volumeLightScale = the light VOLUME's own scale (movers); omitted or < 0 = same as lightScale. lightGamma = the light
+     *  store's curve, texel = sRGB(pow(E / lightScale, 1 / lightGamma)) — 1 (default) for the linear v2 store, 2 for the
+     *  square-root store bakes write since 2026-08-31 (the .bake's `lightGamma`). */
+    lightmapSetOptions?(ambientScale: number, sunStrength: number, aoStrength: number, lightScale: number, volumeLightScale?: number, lightGamma?: number): void
+    /** Bind the atlas page + this instance's rect (uv1 * [sx, sy] + [ox, oy]) and, unless 0xFFFFFFFF, the matching page of
+     *  the light atlas; the sun / IBL terms come from filament's per-frame uniforms inside the shader. Returns how many
+     *  material instances took it (0 = not loaded lightmapped). */
+    lightmapApply?(entityId: number, textureId: number, sx: number, sy: number, ox: number, oy: number, lightTextureId: number): number
+    /** Shadow flags on every renderable of a GLB instance (Mesh has setCastShadows/setReceiveShadows). */
+    setGlbShadows?(entityId: number, cast: boolean, receive: boolean): void
+    lightmapBake?(outDir: string, entityIds: Uint32Array, keysJoined: string, size: number, texel: number, sunRays: number, aoRays: number, aoDistance: number, bias: number, sunAngleDeg: number, volumeCell: number, maxPages: number, lightRays: number, lightRadius: number, bounceAlbedo?: number, bounceDistance?: number, bounceRays?: number, coplanarSkip?: number, denoise?: number): boolean
+    /** Light VOLUME for dynamic objects (docs/lightmap-plan.md §9). `lightmapVolumeLoad` turns a fetched
+     *  lightmap.volume (`fetchSystemId` from `_creatorUtils.fetch`) into RGBA8 3D textures and returns its
+     *  header as JSON — `{"texture":id,"dims":[nx,ny,nz],"min":[x,y,z],"cell":m,"light"?:id,"faces"?:n}` (`light` = the
+     *  point lights' block: a version-3 volume's six ambient-cube faces (+X −X +Y −Y +Z −Z, `faces` 6), a version-2
+     *  volume's one directionless value (`faces` 1) — uploaded either way as six face slabs stacked along z, so the
+     *  light texture's depth is nz × 6) — or "" on failure. */
+    lightmapVolumeLoad?(fetchSystemId: number): string
+    /** Make those textures THE volume (`textureId` 0xFFFFFFFF clears; `lightTextureId` 0xFFFFFFFF = no baked lights):
+     *  every lightmap-material instance without an atlas rect — loaded already or later — samples it at the pixel's
+     *  world position (+ half a `cell` along the normal). `size` = dims × cell. Returns how many instances switched. */
+    lightmapVolumeSet?(textureId: number, lightTextureId: number, minX: number, minY: number, minZ: number, sizeX: number, sizeY: number, sizeZ: number, cell: number): number
+    physicsConfigure(gx: number, gy: number, gz: number, maxBodies: number): void
+    setInterpolation(enabled: boolean): void
+    // Shape/Physics/Trigger aspects: build a shape once, create bodies from it.
+    physicsBuildBox(hx: number, hy: number, hz: number): number
+    physicsBuildSphere(radius: number): number
+    physicsBuildCylinder(halfHeight: number, radius: number): number
+    physicsBuildCapsule(halfHeight: number, radius: number): number
+    /** Mesh shape from node-local triangles. convex=false → triangle mesh (static/kinematic/pick/character
+     *  only; physicsCreateBody returns 0 for a dynamic one), convex=true → convex hull (any motion).
+     *  (sx,sy,sz) = world scale, applied natively. Returns 0 if the shape can't be built. */
+    physicsBuildMesh(vertices: Float32Array, indices: Uint32Array, convex: boolean, sx: number, sy: number, sz: number): number
+    /** Same from a loaded GLB root (non-skinned primitives, bind pose, baked sub-node transforms; cached per asset). */
+    physicsBuildMeshFromEntity(entityId: number, convex: boolean, sx: number, sy: number, sz: number): number
+    /** Terrain collider (Shape { heightfield: true }, docs/terrain-plan.md §1.4): a Jolt HeightFieldShape over
+     *  the grid `terrainCreate` draws (same arrays, same hole rule). Static / kinematic / pick / character
+     *  ground only. (sx,sy,sz) = world scale. `physicsUpdateHeightField` rewrites a sample rectangle in
+     *  place from the FULL arrays (live bodies keep the shape); heights beyond the range chosen at build
+     *  time (25 % headroom) clamp — the SDK rebuilds the shape when an edit leaves that range. Optional. */
+    physicsBuildHeightField?(heights: Float32Array, sizeX: number, sizeZ: number, cellSize: number, holes: Uint8Array | null, sx: number, sy: number, sz: number): number
+    physicsUpdateHeightField?(shapeId: number, heights: Float32Array, sizeX: number, sizeZ: number, x0: number, z0: number, w: number, h: number, holes: Uint8Array | null): void
+    /** A loaded GLB root's triangle soup — the one `physicsBuildMeshFromEntity` collides — as 9 floats per
+     *  triangle in the asset root's space (empty when the entity is not a GLB). `Terrain.conform` stamps a
+     *  road model into the ground with it. Optional. */
+    glbTriangles?(entityId: number): Float32Array
+    /** Offset a built shape's centre from the node's origin (Shape `origin`) — world units in the
+     *  body's rotated, UNSCALED frame, sitting outside a mesh shape's scale wrapper. Sets rather
+     *  than accumulates; (0,0,0) clears it. Optional: an older host just centres on the node. */
+    physicsSetShapeOrigin?(shapeId: number, x: number, y: number, z: number): void
+    /** Swap a live body's shape, keeping its id, velocity and transform (Shape.fit / a re-attach).
+     *  updateMass recomputes the inertia tensor. Refuses a triangle mesh on a dynamic body. */
+    physicsSetBodyShape?(bodyId: number, shapeId: number, updateMass: boolean): void
+    physicsDestroyShape(shapeId: number): void
+    /** sensor = trigger (overlap events, no response); pickOnly = raycast-only, non-colliding body. */
+    physicsCreateBody(entityId: number, shapeId: number, motion: number, mass: number, sensor: boolean, pickOnly: boolean): number
+    physicsSetPickable(bodyId: number, pickable: boolean): void
+    /** Surface friction of one body (0 = ice, ~1 = grippy asphalt). Values COMBINE as sqrt(a * b), so
+     *  a low value on either side dominates. New bodies start at 0.6 — a neutral solid surface.
+     *  The vehicle wheel cast reads the GROUND body's value — this is what caps a car's cornering. */
+    physicsSetFriction(bodyId: number, friction: number): void
+    physicsGetFriction(bodyId: number): number
+    /** Ray vs pickable bodies → hit entity id (0 = miss); fills `out` = [px,py,pz,nx,ny,nz,fraction]. */
+    physicsRaycast(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDist: number, out?: Float32Array): number
+    /** Dev-time dump of the static collision geometry (docs/navmesh-plan.md §4) — the input of
+     *  `lecodes navmesh bake`: every STATIC solid body's triangles in world space, as an NGEO file at
+     *  `outPath`. `entityIds`/`areas` are per-entity overrides (area 0..15, 255 unwalkable, 254 skip).
+     *  Returns the triangle count (-1 = failed). Desktop hosts with physics only. */
+    physicsStaticGeometry?(outPath: string, entityIds: Uint32Array, areas: Uint8Array): number
+    // CharacterController (Jolt CharacterVirtual). The character steps on the engine's FIXED clock like
+    // every body (frame-rate independent) and is render-interpolated; the engine owns its gravity, so
+    // the SDK never ticks it. Both velocity halves are LATCHED STATE, never one-shot events — JS runs
+    // once per frame while the sim runs 0..4 sub-steps, so a one-shot would double-apply or vanish.
+    // groundState: 0 OnGround / 1 OnSteepGround / 2 NotSupported / 3 InAir.
+    characterCreate(entityId: number, shapeId: number, maxSlopeDeg: number): number
+    characterDestroy(charId: number): void
+    /** This frame's HORIZONTAL command (world units/s), cleared once a step consumes it — no command
+     *  means standing still, not coasting. Held across the frame's sub-steps, and it takes the axis
+     *  back from a latched velocity: the last writer owns X/Z. */
+    characterMove(charId: number, x: number, z: number): void
+    /** The same command including the vertical — free mode (gravityScale 0): swimming / flying. */
+    characterMoveFree(charId: number, x: number, y: number, z: number): void
+    /** Seed the LATCHED ballistic vertical (jump / dash). No ground check. */
+    characterSetVerticalVelocity(charId: number, vy: number): void
+    /** Latch the whole velocity — it persists until a characterMove takes the axis back (knockback,
+     *  wall jump, launch pad, weightless flight). Gravity still acts on the vertical. */
+    characterSetVelocity(charId: number, x: number, y: number, z: number): void
+    /** Multiplier over the world gravity; 0 = free mode, which ALSO disables stick-to-floor + stairs. */
+    characterSetGravityScale(charId: number, scale: number): void
+    characterSetMaxSlope(charId: number, maxSlopeDeg: number): void
+    /** Swap the collider live (crouch / stand up), keeping the FEET planted. Returns false when the new
+     *  shape doesn't fit where the character stands — nothing changed, so the caller retries later and
+     *  that retry is an exact headroom test. Optional: a host without it can't resize a character. */
+    characterSetShape?(charId: number, shapeId: number): boolean
+    /** The velocity the solver ENDED UP with after the last step (post-collision), not the command. */
+    characterGetVelocity(charId: number, out: Float32Array): void
+    characterGetGroundState(charId: number): number
+    /** Discontinuous move (spawn / respawn / teleport) — also resets the interpolation pair. */
+    characterSetPosition(charId: number, x: number, y: number, z: number): void
+    // Vehicle (Jolt VehicleConstraint + WheeledVehicleController). One settings BLOB, so tuning knobs
+    // never grow this ABI — layout (floats):
+    //   header[21]: version(5), mass, comAuto, comY,
+    //               engTorque, engMaxRpm, engIdleRpm, engInertia, engBraking, clutchStrength,
+    //               diffRatio (<= 0 = a fully OPEN differential),
+    //               antiRoll (the bar's stiffness as a FRACTION of the wheel spring; 0 = no bars),
+    //               maxTiltDeg,
+    //               steerLockDeg, steerAtSpeedDeg, steerSpeedMs, steerRateDeg (speed-sensitive
+    //                 steering: the lock falls to steerAtSpeedDeg by steerSpeedMs and the wheels turn
+    //                 no faster than steerRateDeg per second; 0/0/0 = the raw lock, instantly),
+    //               aeroDownforce, aeroDrag (each a fraction of the car's own WEIGHT at 30 m/s, scaled
+    //                 by v² from there; 0/0 = no aero, Jolt's own behaviour),
+    //               wheelCount, curveCount
+    //   + curveCount * 2: the engine's normalized torque curve (x = rpm/maxRpm, y = torque/maxTorque);
+    //                     0 points keeps Jolt's default
+    //   + wheelCount * 15: px, py, pz, radius, width, maxSteerDeg, drive, brakeTorque, handBrakeTorque,
+    //                      axle, travel, stiffness, damping, grip, tireCurve (0 = road, 1 = arcade)
+    // NO gear list and no wheel node ids: the gearbox is the SDK's (see vehicleSetTransmission) and the
+    // SDK poses the wheel nodes itself. Chassis space is forward -Z / up +Y (matching node.forward);
+    // wheel positions are suspension attachment points in unscaled chassis space; `axle` pairs wheels
+    // for the differentials + anti-roll bars.
+    vehicleCreate(entityId: number, shapeId: number, settings: Float32Array): number
+    vehicleDestroy(vehicleId: number): void
+    /** forward/right in [-1,1], brake/handBrake in [0,1]. Sticky; any non-zero input wakes the car. */
+    vehicleSetInput(vehicleId: number, forward: number, right: number, brake: number, handBrake: number): void
+    /** The SDK's gearbox, latched and applied once per fixed step: `ratio` is the ONE ratio the car is
+     *  running (0 = neutral, negative = reverse — the engine never sees a gear list) and `clutch` is
+     *  the 0..1 shift envelope scaling the clutch in the coupled engine/wheel solve. */
+    vehicleSetTransmission(vehicleId: number, ratio: number, clutch: number): void
+    /** Re-apply the TUNABLE half of the blob (same layout) to a live car — differential, per-wheel grip,
+     *  engine torque/RPM/curve, clutch strength, steering lock/taper/rate, brake torques, tilt limit.
+     *  Structural values (mass, centre of mass, wheel geometry, driven wheels, suspension, anti-roll)
+     *  are ignored: those need a re-create. */
+    vehicleSetTuning?(vehicleId: number, settings: Float32Array): void
+    /** out = [speed, rpm, wheelsInContact, vx, vy, vz] + per wheel
+     *  [contact, slipLong, slipAngleDeg, suspensionLength, steerDeg, spin]. The last three per wheel are
+     *  its VISUAL POSE — the SDK's Wheel aspect builds the node transform from them. */
+    vehicleGetState(vehicleId: number, out: Float32Array): void
+    /** Teleport upright and clear all motion (velocities, engine RPM, gear, wheel spin). */
+    vehicleReset(vehicleId: number, x: number, y: number, z: number, qx: number, qy: number, qz: number, qw: number): void
+    /** The chassis rigid body, for the plain body calls (physicsApplyImpulse, …). 0 if unknown. */
+    vehicleBodyId(vehicleId: number): number
+    // Ragdoll (Jolt Ragdoll): a Model's skeleton handed to physics — one dynamic body per listed bone
+    // (a capsule from the bone's origin to the next joint) joined to its parent part by a swing-twist
+    // constraint. Built ONCE from the pose the bones are in (that pose is the joints' neutral for the
+    // limits) and kept out of the world until ragdollActivate, which takes the bones' CURRENT pose,
+    // adds the bodies and gives every body one velocity; from then on the engine writes the bodies'
+    // poses onto the bone entities every frame AFTER the animator (bones not listed keep their
+    // animated local pose under the ragdolled parents — fingers, toes, a spine bone between two
+    // parts), until ragdollDeactivate. Every body carries its bone entity as user data, so
+    // physicsRaycast / contact events name the bone. Optional: a host without it has no ragdolls.
+    //   bones[partCount * 2]: bone entity, `to` entity (0 = a leaf: `length` along the parent's line;
+    //                         a leaf ROOT points along the model's up)
+    //   settings — header[12]: version(2), partCount, stride(12), friction, linearDamping,
+    //              angularDamping (0 = Jolt's own), collide (0 = everything, 1 = the STATIC world and
+    //              other such ragdolls only: dynamic bodies, character controllers and vehicles pass
+    //              through — Jolt's DEBRIS object/broadphase layer), freeze (1 = once every part is
+    //              asleep the bodies turn STATIC where they lie: the last pose keeps being written
+    //              onto the bones, raycasts still hit, nothing wakes them, the solver skips them;
+    //              ragdollActive reads false, ragdollDeactivate / ragdollActivate still work —
+    //              activate makes the parts dynamic again), freezeAfter (seconds in the world after which the freeze happens
+    //              regardless; 0 = no cap), reserved x3. A version-1 blob (header[8], stops after
+    //              angularDamping) is still accepted = collide everything, never freeze.
+    //   + partCount * 12: parentIndex (-1 = the root; always < the part's own index), radius, length
+    //              (0 = up to the `to` bone), mass (kg; 0 = from the volume), swingDeg (cone
+    //              half-angle), twistDeg (half-angle), hinge (0/1), hingeAxisX/Y/Z (in the MODEL
+    //              node's space), hingeMinDeg, hingeMaxDeg — a hinge is a swing-twist whose cone is
+    //              flat (2°) across the axis and [min, max] about it (a knee, an elbow)
+    ragdollCreate?(rootEntityId: number, bones: Uint32Array, settings: Float32Array): number
+    ragdollDestroy?(ragdollId: number): void
+    /** Pose the bodies from the bones' current transforms, add them to the world, set every body's
+     *  linear velocity. Already active = re-wake + velocity. false = unknown id / no world. */
+    ragdollActivate?(ragdollId: number, vx: number, vy: number, vz: number): boolean
+    /** Take the bodies out of the world; the animator owns the bones again from the next frame. */
+    ragdollDeactivate?(ragdollId: number): void
+    /** In the world AND at least one body still awake (a settled ragdoll reads false). */
+    ragdollActive?(ragdollId: number): boolean
+    /** The rigid body of part `index` (for physicsApplyImpulseAt / velocities). 0 if unknown. */
+    ragdollBodyId?(ragdollId: number, index: number): number
+    // Legacy coupled shape+body (still used by the worker RigidBody).
+    physicsCreateBox(entityId: number, hx: number, hy: number, hz: number, motionType: number, mass: number): number
+    physicsCreateSphere(entityId: number, radius: number, motionType: number, mass: number): number
+    physicsCreateCylinder(entityId: number, halfHeight: number, radius: number, motionType: number, mass: number): number
+    physicsSetLinearVelocity(bodyId: number, x: number, y: number, z: number): void
+    physicsGetLinearVelocity(bodyId: number, out: Float32Array): void
+    /** Angular velocity about each world axis, RADIANS/second — Jolt's unit; the SDK exposes degrees.
+     *  The only way to stop a spin: a position write leaves both velocities untouched. */
+    physicsSetAngularVelocity?(bodyId: number, x: number, y: number, z: number): void
+    physicsGetAngularVelocity?(bodyId: number, out: Float32Array): void
+    physicsApplyImpulse(bodyId: number, x: number, y: number, z: number): void
+    physicsApplyImpulseAt?(bodyId: number, x: number, y: number, z: number, px: number, py: number, pz: number): void
+    physicsSetBodyPosition(bodyId: number, x: number, y: number, z: number): void
+    /** The rotation twin (normalized host-side). Both snap the body's render-interpolation pair, so a
+     *  discontinuous move is drawn as one rather than as a one-frame slide/spin across the gap. */
+    physicsSetBodyRotation?(bodyId: number, qx: number, qy: number, qz: number, qw: number): void
+    physicsRemoveBody(bodyId: number): void
+
+    createMediaPlayerTexture(id: number): number
+
+    getName(entityId: number): string
+    setName(entityId: number, name: string): void
+
+    hasMesh(entityId: number): boolean
+
+    createARController(sceneId: number, cameraId: number, mode: string, onTrack: (entityId: number, track: boolean) => void): void
+    createRootAnchor(sceneId: number): number
+    createAnchor(sceneId: number, physicalWidth: number, systemId: number): number
+
+    // Particles. All emitter/curve config crosses as ONE Float32Array of [tag, payloadLen,
+    // ...payload] records, parsed once in creator-gl (PsTag in creator-gl/src/particles.h; the
+    // SDK mirror is in gl/Particles.ts, guarded by sdk/tests/particles-tags.test.ts). Unknown
+    // tags skip by length. maxParticles 0 = default (1000).
+    createParticleSystem(entityId: number, materialInstanceId: number, maxParticles: number): void
+    spawnParticles(entityId: number, count: number): void
+    setParticleSystemConfig(entityId: number, data: Float32Array): void
+
+    createNoise(): number
+    setNoiseFrequency(noiseId: number, frequency: number): void
+    setNoiseOctaves(noiseId: number, octaves: number): void
+    setNoiseFractalLunacrity(noiseId: number, lunacrity: number): void
+    setNoiseFractalGain(noiseId: number, fractalGain: number): void
+    getNoise2D(noiseId: number, x: number, y: number): number
+    getNoise3D(noiseId: number, x: number, y: number, z: number): number
+
+    captureImage(sceneId: number, onComplete: (bufferId: number, name: string, size: number) => void, onReject: () => void): void
+  }
+
+  // ---- 2D engine (sokol / creator-2d) ----------------------------------------------------------
+  // A 2D-only project loads ONLY creator2d.wasm — never Filament.
+  var _creator2d: {
+    backend: string
+    version(): number
+    render(nowMs: number): void
+    onUpdate(cb: (dt: number) => void): void
+    offUpdate(cb: (dt: number) => void): void
+    // Render-synced aspect update(dt) dispatch, called from inside c2dRender. Early = before the
+    // physics step; late = after animations, just before draw. Single-slot per phase (the SDK's
+    // Aspect dispatcher registers one callback that iterates its ordered updater list).
+    setEarlyUpdate(cb: (dt: number) => void): void
+    setLateUpdate(cb: (dt: number) => void): void
+    /** Clock multiplier for the 2D physics step + sprite animations (see `_creator.setTimeScale`). */
+    setTimeScale?(scale: number): void
+    setOnAnimEvent(cb: (ev: { entityId: number, clipId: number, type: number }) => void): void
+    // Raw scene pointer events from the host (canvas / iOS view). phase: 0 down, 1 move, 2 up, 3 cancel;
+    // x,y in logical (CSS px / iOS point) coords relative to the surface. The SDK hit-tests + tracks.
+    setOnPointer(cb: (phase: number, pointerId: number, x: number, y: number) => void): void
+    setClearColor(r: number, g: number, b: number, a: number): void
+
+    createScene(): number
+    destroyScene(sceneId: number): void
+    openScene(sceneId: number): void
+    closeScene(): void
+    sceneSetClearColor(sceneId: number, r: number, g: number, b: number, a: number): void
+    addEntityToScene(sceneId: number, entityId: number): void
+    removeEntityFromScene(sceneId: number, entityId: number): void
+    setLayerYSort(sceneId: number, layer: number, enabled: boolean): void
+
+    cameraSetPosition(sceneId: number, x: number, y: number): void
+    cameraSetZoom(sceneId: number, zoom: number): void
+    cameraSetRotation(sceneId: number, deg: number): void
+    cameraScreenToWorld(sceneId: number, sx: number, sy: number): Float32Array
+    cameraWorldToScreen(sceneId: number, wx: number, wy: number): Float32Array
+
+    createEntity(): number
+    destroyEntity(entityId: number): void
+    setPosition(entityId: number, x: number, y: number): void
+    setRotation(entityId: number, deg: number): void
+    setScale(entityId: number, sx: number, sy: number): void
+    setLayer(entityId: number, layer: number): void
+    setZ(entityId: number, z: number): void
+    setVisible(entityId: number, visible: boolean): void
+    getPosition(entityId: number): Float32Array
+
+    setParent(childId: number, parentId: number, keepWorld: boolean): void
+    getParent(entityId: number): number
+    getChildCount(entityId: number): number
+    getChild(entityId: number, index: number): number
+    getWorldPosition(entityId: number): Float32Array
+    getWorldMatrix(entityId: number): Float32Array
+    worldToLocal(entityId: number, wx: number, wy: number): Float32Array
+    localToWorld(entityId: number, lx: number, ly: number): Float32Array
+    getLocalTransform(entityId: number): Float32Array
+
+    setSprite(entityId: number, textureId: number): void
+    setSpriteFrame(entityId: number, u0: number, v0: number, u1: number, v1: number): void
+    setSpriteFramePx(entityId: number, px: number, py: number, pw: number, ph: number): void
+    setSpriteSize(entityId: number, w: number, h: number): void
+    setSpriteAnchor(entityId: number, ax: number, ay: number): void
+    setSpriteColor(entityId: number, r: number, g: number, b: number): void
+    setSpriteOpacity(entityId: number, a: number): void
+    setSpriteFlip(entityId: number, flipX: boolean, flipY: boolean): void
+
+    createTexture(systemId: number, onComplete: (texId: number, w: number, h: number) => void, onReject: (e: any) => void): void
+    getTextureWidth(texId: number): number
+    getTextureHeight(texId: number): number
+    destroyTexture(texId: number): void
+    setDefaultFilter(linear: boolean): void
+
+    // Textures from a _creatorCanvas surface (RGBA8, already rasterized — no decode, so synchronous).
+    // See docs/canvas-contract.md.
+    createTextureFromCanvas(surfaceId: number): number
+    updateTextureFromCanvas(texId: number, surfaceId: number): void
+
+    defineAnimation(entityId: number, frames: Float32Array, fps: number, loop: boolean): number
+    playAnimation(entityId: number, clipId: number): void
+    stopAnimation(entityId: number): void
+    setAnimationSpeed(entityId: number, speed: number): void
+    getAnimationFrame(entityId: number): number
+
+    createTilemap(textureId: number, cols: number, rows: number, tileW: number, tileH: number, atlasCols: number, atlasRows: number, data: Int32Array): number
+    setTile(tilemapId: number, x: number, y: number, index: number): void
+
+    bulkSetPositions(ids: Uint32Array, xy: Float32Array, count: number): void
+
+    // physics (Box2D v3; present only in CREATOR_2D_PHYSICS builds — physicsHasSupport() reports it).
+    // See docs/2d-physics-plan.md. physicsHasSupport() reports the BUILD, not the world: the world is
+    // created lazily by the first physicsCreateBody, so configure() is optional.
+    physicsHasSupport(): boolean
+    /** Live and non-destructive: an existing world keeps its bodies and takes the new gravity.
+     *  pixelsPerMeter only applies to a world that doesn't exist yet (global Box2D tolerance). */
+    physicsConfigure(gx: number, gy: number, pixelsPerMeter: number, subStepCount: number): void
+    setInterpolation(enabled: boolean): void
+    /** type 0 contactBegin / 1 contactEnd / 2 sensorBegin / 3 sensorEnd. A contact BEGIN carries the
+     *  manifold — world point, normal pointing A→B, and the approach speed at impact; the other three
+     *  carry zeros. (The begin manifold is pre-solve, so its impulses are all zero — `speed` is the
+     *  pre-solve relative normal velocity, which is the number an impact actually wants.) */
+    setOnPhysicsEvent(cb: (entityA: number, entityB: number, type: number, px: number, py: number, nx: number, ny: number, speed: number) => void): void
+    physicsCreateBody(entityId: number, motionType: number): number
+    physicsRemoveBody(bodyHandle: number): void
+    // Shapes carry no `density` (built at density 1, so mass == area — physicsSetMass overrides) and
+    // do carry the collision filter. category/mask are 32-bit; 0 means "everything".
+    physicsAddBox(bodyHandle: number, hw: number, hh: number, ox: number, oy: number, friction: number, bounce: number, isSensor: boolean, category: number, mask: number): void
+    physicsAddCircle(bodyHandle: number, radius: number, ox: number, oy: number, friction: number, bounce: number, isSensor: boolean, category: number, mask: number): void
+    physicsAddCapsule(bodyHandle: number, x1: number, y1: number, x2: number, y2: number, radius: number, friction: number, bounce: number, isSensor: boolean, category: number, mask: number): void
+    physicsAddSegment(bodyHandle: number, x1: number, y1: number, x2: number, y2: number, friction: number, bounce: number, category: number, mask: number): void
+    physicsAddPolygon(bodyHandle: number, pts: Float32Array, count: number, friction: number, bounce: number, isSensor: boolean, category: number, mask: number): void
+    /** A polyline of connected segments — long CONCAVE surfaces in one seam-free piece. STATIC bodies
+     *  only, >= 4 points; the SDK synthesises the tangent points an open chain needs, because Box2D's
+     *  first and last edges do not collide. One-sided: solid on the right of the point order. */
+    physicsAddChain(bodyHandle: number, pts: Float32Array, count: number, isLoop: boolean, friction: number, bounce: number, category: number, mask: number): void
+    /** Destroy every shape on a body, keeping the body (id, transform, velocity) — the first half of a
+     *  live collider rebuild. */
+    physicsClearShapes(bodyHandle: number): void
+    /** Contact events are OFF per body until this turns them on — otherwise every crate-on-crate pair
+     *  crosses the bridge every frame. The SDK enables it on the first 'enter'/'exit' listener. */
+    physicsSetContactEvents(bodyHandle: number, enabled: boolean): void
+    physicsSetLinearVelocity(bodyHandle: number, x: number, y: number): void
+    physicsGetLinearVelocity(bodyHandle: number): Float32Array
+    physicsSetAngularVelocity(bodyHandle: number, degPerSec: number): void
+    physicsGetAngularVelocity(bodyHandle: number): number
+    physicsApplyLinearImpulse(bodyHandle: number, x: number, y: number): void
+    /** Impulse at a WORLD point — the lever arm becomes angular impulse (a central impulse never
+     *  spins a body). Mirrors 3D physicsApplyImpulseAt. */
+    physicsApplyImpulseAt(bodyHandle: number, x: number, y: number, px: number, py: number): void
+    physicsApplyForce(bodyHandle: number, x: number, y: number): void
+    /** Teleport the body to its ENTITY's current world transform — how node.position / .rotation reach
+     *  it. The parent-chain math stays native instead of being re-derived in TS. Snaps prev/cur so the
+     *  renderer doesn't interpolate across the jump; the body KEEPS its velocity. */
+    physicsSetFromEntity(bodyHandle: number): void
+    physicsSetFixedRotation(bodyHandle: number, enabled: boolean): void
+    physicsSetGravityScale(bodyHandle: number, scale: number): void
+    physicsSetLinearDamping(bodyHandle: number, damping: number): void
+    physicsSetAngularDamping(bodyHandle: number, damping: number): void
+    physicsSetBullet(bodyHandle: number, enabled: boolean): void
+    physicsSetEnabled(bodyHandle: number, enabled: boolean): void
+    physicsSetAwake(bodyHandle: number, awake: boolean): void
+    /** Scales the shape-derived mass data, so the rotational inertia keeps its ratio. <= 0 restores
+     *  the area-derived default. */
+    physicsSetMass(bodyHandle: number, mass: number): void
+    physicsGetMass(bodyHandle: number): number
+    physicsSetMotionType(bodyHandle: number, motionType: number): void
+    physicsSetFriction(bodyHandle: number, friction: number): void
+    physicsSetBounce(bodyHandle: number, bounce: number): void
+    physicsSetFilter(bodyHandle: number, category: number, mask: number): void
+    // Queries. `mask` = the union of group categories the query may hit (0 = everything); `ignore` is
+    // a list of ENTITY ids to skip, passed as floats because ids are small ints and that reuses the
+    // one buffer helper. Box2D's closest-ray API has no exclusion, hence the explicit list.
+    physicsRaycastClosest(x0: number, y0: number, x1: number, y1: number, mask: number, ignore: Float32Array, ignoreCount: number): Float32Array
+    /** All hits along the segment, nearest first: maxHits records of [entityId, px, py, nx, ny, fraction]. */
+    physicsRaycastAll(x0: number, y0: number, x1: number, y1: number, mask: number, ignore: Float32Array, ignoreCount: number, maxHits: number): Float32Array
+    /** Overlap an arbitrary convex shape given as a point cloud + radius (Box2D's b2ShapeProxy form),
+     *  so one call covers circle / capsule / box / polygon — and the swept test for a moving circle.
+     *  Returns up to maxHits entity ids. */
+    physicsOverlap(pts: Float32Array, count: number, radius: number, mask: number, ignore: Float32Array, ignoreCount: number, maxHits: number): Float32Array
+    /** Topmost by DRAW order (layer, then z) — not whatever the broadphase hands back first. */
+    physicsOverlapPoint(x: number, y: number, mask: number, ignore: Float32Array, ignoreCount: number): number
+    // CharacterController2D (Box2D's kinematic mover). The character steps on the engine's FIXED clock
+    // inside the same loop as the bodies, so the SDK does no per-frame work. Capsule ends are in the
+    // character's own frame. It also owns a hidden kinematic "shadow" body so raycasts, overlaps and
+    // sensors see it — solid shapes strip the reserved character bit from their mask, sensors add it.
+    characterCreate(entityId: number, x1: number, y1: number, x2: number, y2: number, radius: number, maxSlopeDeg: number, category: number, mask: number): number
+    characterDestroy(charId: number): void
+    /** The HORIZONTAL command, world units/s — a per-frame command that EXPIRES once a step consumes it. */
+    characterMove(charId: number, x: number): void
+    /** Free mode (gravityScale 0): both axes as one expiring command. */
+    characterMoveFree(charId: number, x: number, y: number): void
+    characterSetVerticalVelocity(charId: number, vy: number): void
+    /** LATCH the whole velocity — it persists until a characterMove takes the axis back. */
+    characterSetVelocity(charId: number, x: number, y: number): void
+    characterSetGravityScale(charId: number, scale: number): void
+    characterSetMaxSlope(charId: number, maxSlopeDeg: number): void
+    characterSetFilter(charId: number, category: number, mask: number): void
+    /** Ignore this entity's one-way surfaces (0 = none) — dropping through a semisolid platform. */
+    characterSetDropThrough(charId: number, entityId: number): void
+    /** Resize keeping the FEET planted; false = it didn't fit and NOTHING changed, so the caller
+     *  retries later and that retry is an exact headroom test. */
+    characterSetCapsule(charId: number, x1: number, y1: number, x2: number, y2: number, radius: number): boolean
+    /** Teleport to the entity's world transform (how node.position reaches a character). Drops fall speed. */
+    characterSetFromEntity(charId: number): void
+    /** out8 = [velX, velY, groundState (0 ground / 1 slope / 2 air), normalX, normalY, groundEntity,
+     *  collisionCount, 0]. The velocity is MEASURED, not commanded. */
+    characterGetState(charId: number, out: Float32Array): void
+    /** maxN records of [entityId, normalX, normalY] — what the mover pushed out of this step. */
+    characterGetCollisions(charId: number, maxN: number): Float32Array
+    /** Mark a body's surfaces one-way: solid only from the side (nx, ny) points to, within arcDeg.
+     *  Honoured by the mover and, via a native pre-solve callback, by ordinary rigid bodies. */
+    physicsSetOneWay(bodyHandle: number, nx: number, ny: number, arcDeg: number, enabled: boolean): void
+    pickSprite(sceneId: number, wx: number, wy: number): number
+  }
+
+  // ---- multiplayer transport (creator-net / yojimbo) -------------------------------------------
+  // A byte pipe pumped on the JS thread (docs/multiplayer-plan.md). Present only on hosts built
+  // with CREATOR_PKG_NET (desktop, the 3d/full Android variants, iOS); the SDK feature-detects it.
+  // One endpoint per process: `listen` (server / host) or `connect` (client), never both.
+  var _creatorNet: {
+    /** What the exe was launched as (`--server --port N` / `--connect ADDR`), or null. */
+    launch(): { role: string, address: string, port: number, maxClients: number } | null
+    /** Serve on every interface at `port` (wildcard public address). */
+    listen(port: number, maxClients: number): boolean
+    /** Insecure (dev / LAN) connect to "ip:port"; the outcome arrives as a poll record. */
+    connect(address: string): boolean
+    disconnect(): void
+    kick(client: number): void
+    /** Queue a payload: channel 0 reliable-ordered, 1 unreliable; `client` ignored on a client.
+     *  A string travels as UTF-8 text and arrives as a string; bytes arrive as an ArrayBuffer. */
+    send(client: number, channel: number, data: string | ArrayBuffer | Uint8Array): boolean
+    /** Pump once and return every record since the last call as a flat array of 4-tuples
+     *  [kind, client, arg, payload] — kind 1 connected · 2 disconnected · 3 message · 4 connectFailed;
+     *  arg = channel (message) or reason code; payload = string | ArrayBuffer | null. */
+    poll(): any[] | null
+    /** 0 idle · 1 client · 2 server */
+    mode(): number
+    /** Client: 0 disconnected · 1 connecting · 2 connected · 3 failed. A listening server: 2. */
+    state(): number
+    /** [connected, rttMs, lossPct, sentKbps, receivedKbps] for a slot (server) / the link (client). */
+    clientInfo(client: number): Float32Array
+    /** yojimbo network simulator on this side of the wire. */
+    simulate(latencyMs: number, jitterMs: number, lossPercent: number): void
+    reasonString(reason: number, serverSide: boolean): string
+  }
+
+  // ---- navigation meshes (creator-nav / Recast+Detour) -----------------------------------------
+  // Runtime only (docs/navmesh-plan.md §5): load a baked `.navmesh` (LNAV) from a fetch system id,
+  // query it, run a DetourCrowd of agents one fixed step at a time. Present on hosts built with
+  // CREATOR_PKG_NAV (desktop, the 3d/full Android variants, iOS) and on every web host through the
+  // wasm build; the SDK feature-detects it. Parameter blocks are fixed-order Float32Arrays
+  // (creator-nav.h CNAV_AGENT_* / CNAV_READ_*). Handles (meshId / crowdId, from 1) die with the world.
+  var _creatorNav: {
+    /** Web hosts only: loads the wasm lazily. Absent on native hosts — call it when present. */
+    ready?(): Promise<void>
+    lastError(): string
+    /** LNAV bytes already fetched (the createGlb pattern) → meshId, 0 on failure. */
+    load(systemId: number): number
+    unload(meshId: number): void
+    /** The file's JSON header: agent size, cell, bounds, stats, `meta` (the CLI's provenance). */
+    header(meshId: number): string
+    polyCount(meshId: number): number
+    setAreaCost(meshId: number, area: number, cost: number): void
+    /** Straight path from → to into `out` (xyz per corner); returns the corner count, NEGATIVE when
+     *  the path is partial (the target is unreachable — it ends at the closest polygon). `ex <= 0`
+     *  = default search extents. */
+    findPath(meshId: number, fx: number, fy: number, fz: number, tx: number, ty: number, tz: number, ex: number, ey: number, ez: number, include: number, exclude: number, maxCorners: number, out: Float32Array): number
+    nearest(meshId: number, x: number, y: number, z: number, ex: number, ey: number, ez: number, include: number, exclude: number, out: Float32Array): boolean
+    /** Walkability ray along the surface; true = BLOCKED, out = [hit xyz, wall normal xyz]. */
+    raycast(meshId: number, fx: number, fy: number, fz: number, tx: number, ty: number, tz: number, include: number, exclude: number, out: Float32Array): boolean
+    /** `radius <= 0` = anywhere on the mesh; deterministic per seed. */
+    randomPoint(meshId: number, cx: number, cy: number, cz: number, radius: number, seed: number, include: number, exclude: number, out: Float32Array): boolean
+    /** The polygon mesh as a triangle soup (xyz per vertex) for debug drawing. */
+    debugTriangles(meshId: number): Float32Array
+    crowdCreate(meshId: number, maxAgents: number, maxRadius: number): number
+    crowdDestroy(crowdId: number): void
+    /** → the agent's slot (0..maxAgents-1), -1 when full / off the mesh. */
+    crowdAdd(crowdId: number, x: number, y: number, z: number, params: Float32Array): number
+    crowdRemove(crowdId: number, agent: number): void
+    crowdSetParams(crowdId: number, agent: number, params: Float32Array): void
+    crowdSetTarget(crowdId: number, agent: number, x: number, y: number, z: number): boolean
+    crowdSetVelocity(crowdId: number, agent: number, vx: number, vy: number, vz: number): void
+    crowdResetTarget(crowdId: number, agent: number): void
+    crowdWarp(crowdId: number, agent: number, x: number, y: number, z: number): boolean
+    /** Once per fixed step. */
+    crowdUpdate(crowdId: number, dt: number): void
+    /** Every slot into `out` (CNAV_AGENT_READ_STRIDE floats each); returns maxAgents. */
+    crowdRead(crowdId: number, out: Float32Array): number
+  }
+
+  // ---- UI engine (creator-ui) ------------------------------------------------------------------
+  var _creatorUI: {
+    // Global back-press fallback (app.onBackPressed): a PROPERTY the SDK writes, not a call —
+    // the engine reads it off this world's _creatorUI object at the END of its back chain
+    // (widget → destination → pager → router → this), so it dies with the world's context.
+    // Old hosts never read it and the handler is silently inert there.
+    _backButtonCallback?: () => void
+    openScreen(screen: object): void
+    closeScreen(): void
+    updateStyle(nodeId: number, prop: string, value: any): void
+    mergeStyle(nodeId: number, style: object): void
+    // Toggle a user style class (a `$`-block declared in .style()) on a node. `name` arrives
+    // WITHOUT the leading `$`. Class state CASCADES down the node tree: a class set on a node is
+    // active on all its descendants within the same root (screens/widgets are separate roots) —
+    // implemented ONCE in creator-ui's setNodeClass (docs/style-class-cascade-plan.md); hosts must
+    // NOT layer their own inheritance on top. `$pressed`/`$focused` are reserved cascading classes
+    // hosts toggle alongside the built-in onPressed/onFocused (creator-ui setNodePressed/Focused).
+    setClass(nodeId: number, name: string, enabled: boolean): void
+
+    // Theme variables (docs/ui-theme-plan.md). MERGES `values` into the app theme table and
+    // re-resolves live styles: keys are var names (`var(--name)` in style values reads them;
+    // the four `comfort-*` keys are the comfort knobs), null removes a key, numbers are lengths
+    // (px). Env names (safe-*, vw/vh/vmin/vmax) are reserved — hosts ignore writes to them.
+    // Optional during rollout: the SDK feature-detects.
+    setTheme?(values: Record<string, string | number | null>): void
+
+    // Content-property push. Props: "value" (input/textarea text), "focus" (boolean — focus/blur
+    // the input, opening/dismissing the keyboard; rides this channel so programmatic focus needs
+    // no new ABI method), plus element-specific ones ("src", "text", …).
+    updateNode(nodeId: number, prop: string, value: any): void
+    setSourceRect(nodeId: number, x: number, y: number, w: number, h: number): void
+
+    // Canvas.update() → live-refresh every UIImage(canvas) node currently showing this baked surface:
+    // the host re-reads the re-rasterized pixels into the image view WITHOUT a relayout (the surface
+    // keeps its id and size across an update; a resize goes through a full `src` re-assign). Optional
+    // during rollout — the SDK feature-detects and falls back to re-assigning `src`.
+    refreshCanvasSurface?(surfaceId: number): void
+
+    // Font registration is fire-and-forget in practice: hosts load the face, then re-measure /
+    // re-layout when it lands (docs/font-system-plan.md — swap is the fallback; boot faces are
+    // prefetched via the bundle's `// fonts:` header). The callbacks stay on the wire for old
+    // bundles that gate on them — hosts must keep invoking onComplete. Repeated registration of
+    // the same (family, weight, style) is a cheap no-op — hosts dedupe.
+    registerFont(fontFamily: string, url: string, options: any, onComplete: () => void, onReject: () => void): void
+    // Preferred container format for CDN-served faces: "woff2" on browser hosts, absent (= "ttf")
+    // on native/headless. The font() macro's generated registration code reads it to pick the
+    // file extension; the `// fonts:` header carries a `{fmt}` placeholder for the same choice.
+    fontFormat?: "woff2" | "ttf"
+
+    isButtonPressed(nodeId: number): boolean
+
+    registerTouchStartEvent(callback: (...args: any) => void): void
+    registerTouchEndEvent(callback: (...args: any) => void): void
+    registerResizeEvent(callback: (...args: any) => void): void
+    // Current display size [width, height] in logical px — the same values the resize event delivers.
+    // Surfaced as device.width / device.height. Optional: hosts that don't track it (headless) omit it,
+    // and the getters fall back to 0.
+    getDisplaySize?(): [number, number]
+
+    getTextValue(nodeId: number): string
+
+    // Absolute device-space rect [left, top, width, height] of a laid-out node, in logical px —
+    // the same space UIWidget top/left position in — INCLUDING scroll offsets: computed live at
+    // call time, never cached from layout events. null (or undefined) when the node isn't
+    // mounted/laid out. Backs el.getBoundingClientRect(), the widget-anchoring primitive
+    // (dropdowns, popovers, tooltips — docs/ui-components-plan.md §3.2). Optional: the SDK
+    // feature-detects and returns null on hosts without it.
+    getBoundingClientRect?(nodeId: number): [number, number, number, number] | null
+
+    insertNode(index: number, nodeId: number, childNode: any): void
+    removeNode(nodeId: number, childNode: any): void
+    setContent(nodeId: number, oldChildren: any[], children: any[]): void
+
+    animateTo(nodeId: number, style: any): void
+    animateFrom(nodeId: number, style: any): void
+    toast(msg: string): void
+
+    // Router over destinations. On hosts that implement openView (below), `screen`/`view` is any
+    // view descriptor (not just a screen object) and the extra `transition` args apply; legacy
+    // hosts receive screen objects only and ignore the extras.
+    routerOpen(view: any, onChange: (view: any) => void, showBackButton: boolean): void
+    routerPush(view: any, transition?: string | object): void
+    routerReplace(view: any, transition: string | object): void
+    routerPop(index: number, transition?: string | object): void
+    routerHide(): void
+    routerRestore(): void
+
+    // ---- Presentable navigation (docs/navigation-presentable-plan.md) --------------------------
+    // One visible destination at a time. `view` is either a screen node object (type "screen")
+    // or a descriptor:
+    //   { type: "scene3d", sceneId }  { type: "scene2d", sceneId }
+    //   { type: "native", viewName, params, viewId }  { type: "videoView", node }
+    // Descriptors carry `_p` (the SDK Presentable instance): hand the SAME object back through
+    // router onChange, and fire its `ol`/`cl` arrays on present/dismiss (screens carry ol/cl
+    // themselves). Presenting a scene descriptor includes activating the engine (the openScene
+    // equivalent); while covered, scene rendering pauses. `transition` is a TransitionName string
+    // or a TransitionSpec object (see sdk/src/ui/presentable.ts).
+    // Optional during the migration: the SDK feature-detects openView and falls back to
+    // openScreen/openScene; hosts implementing openView should keep openScreen/routerPush(screen)
+    // as thin aliases into it for previously compiled bundles.
+    openView?(view: object, transition: string | object): void
+    closeView?(): void
+
+    // NativeView plugin channel (host `registerView(name, factory)` capabilities). `args`, the
+    // result, and event payloads are JSON strings. Events are delivered by invoking the arrays in
+    // the element's `nvl[event]` or via its `_emitViewEvent(event, json)`.
+    isViewSupported?(name: string): boolean
+    viewCall?(viewId: number, method: string, args: string, onComplete: (result?: string) => void, onError: (err: string) => void): void
+
+    // `owner` (a view descriptor) binds the widget to a destination: it mounts inside the owner's
+    // page — shows/hides with it and rides its transition. Omitted = global overlay (legacy
+    // behavior; legacy hosts ignore the arg).
+    showWidget(widget: object, owner?: object): void
+    hideWidget(widget: object): void
+
+    vlistMount(jsNode: any, key: string, subtree: any): void
+    vlistSetKeys(jsNode: any, keys: string[], estimates: number[]): void
+    vlistInsertKeys(jsNode: any, index: number, keys: string[], estimates: number[]): void
+    vlistInvalidate(jsNode: any, k: string): void
+    vlistRemoveKeys(jsNode: any, keys: string[]): void
+    command(jsNode: any, command: string, ...args: any): void
+  }
+
+  // ---- Platform utilities ----------------------------------------------------------------------
+  var _creatorUtils: {
+    // `fetchOptions.body` is either a string or a FormData: an object carrying `_entries`, an array
+    // of [key, value, filename?]. A `value` object carrying a numeric `_id` is binary (that's the
+    // host buffer id — SDK `File` and `FetchResponse` both expose it under that key); anything else
+    // is a text field. Same `_id` convention as an image `src` object (see _creatorUI.updateNode).
+    fetch(url: string, fetchOptions: any, onComplete: (systemId: number, statusCode: number) => void, onReject: () => void): void
+    fetchLocal(path: string): number
+    fetchToJson(systemId: number): any
+    fetchSlice(systemId: number, start: number, end: number): any
+    fetchToText(systemId: number): string
+    /** The fetched bytes as a Uint8Array copy (a `.terrain` file, any binary the SDK parses itself).
+     *  Optional: an older host has only the text/JSON readers (Terrain.load throws there). */
+    fetchToBytes?(systemId: number): Uint8Array
+    disposeFetch(systemId: number): void
+    // ---- Local filesystem (the SDK `files` global) ----------------------------------------------
+    // The read/write/delete half of `fetchLocal`, for hosts where the app OWNS a filesystem
+    // (desktop). All five are OPTIONAL and stand or fall together: a sandboxed host (web, mobile)
+    // implements none of them and `files.supported` is false there.
+    //
+    // ASYNC, like `fetch`: file IO must not block the frame, so each takes an onComplete/onReject
+    // pair (the SDK turns them into a promise) and the host does the work off the JS thread. Hosts
+    // must keep the ops ORDERED — two appends to one file settle in call order — so a queue, not a
+    // thread per call. Exactly one handle is ever settled.
+    //
+    // PATH POLICY, identical for all five and owned by the host: an ABSOLUTE path is used verbatim;
+    // a RELATIVE one is resolved against the app's OWN folder — never the process cwd — which for a
+    // packaged desktop app is the exe's directory, one of the directories `fetchLocal` searches by
+    // name. So `writeLocal("save.json", …)` and `fetchLocal("save.json")` are a pair.
+    /** Write a file, creating the parent folders. `append` adds to the end instead of replacing.
+     *  `data` is text (written as UTF-8), raw bytes (Uint8Array / ArrayBuffer), or a host buffer
+     *  object carrying `_id` (an SDK `File` / `FetchResponse` — so a picked or generated file is
+     *  saved as it is); the bytes are only valid for the duration of the call, so a host that
+     *  defers the write copies them first. The core drops the path's cached `fetchLocal` id, so
+     *  the next read sees the new bytes. */
+    writeLocal?(path: string, data: string | Uint8Array | ArrayBuffer | { _id: number }, append: boolean, onComplete: () => void, onReject: (err: Error) => void): void
+    /** The whole file as bytes, or null when there is no such file. Unlike `fetchLocal` this
+     *  re-reads every call and holds nothing — no buffer id to dispose. Only a real failure
+     *  (an unreadable file) rejects; "not there" is a null result. */
+    readLocalBytes?(path: string, onComplete: (bytes: Uint8Array | null) => void, onReject: (err: Error) => void): void
+    /** The whole file decoded as UTF-8 text, or null when there is no such file. */
+    readLocalText?(path: string, onComplete: (text: string | null) => void, onReject: (err: Error) => void): void
+    /** Delete a file, or an EMPTY directory; `recursive` also deletes a directory's contents.
+     *  Deleting something that is already gone SUCCEEDS — the post-condition is what matters. */
+    deleteLocal?(path: string, recursive: boolean, onComplete: () => void, onReject: (err: Error) => void): void
+    /** Create a directory and any missing parents. An existing directory is success. */
+    mkdirLocal?(path: string, onComplete: () => void, onReject: (err: Error) => void): void
+    openFilePicker(onComplete: (res: any) => void, onReject: () => void, multiple: boolean, accept?: string): void
+    // Present the OS media share sheet for a host buffer (`systemId` — a File/response id), with an
+    // optional caption. iOS: the share sheet also offers "Save to Files"/Photos. Web: saves (downloads)
+    // the file. Backs the SDK `share(media, text?)`.
+    shareMedia(systemId: number, text?: string): void
+
+    /** Prompt for camera permission (resolve = granted, reject = denied). Shared by everything that
+     *  needs the camera — ARScene.prepare, QRScanner, CameraView — hence a platform utility rather
+     *  than a 3D-engine call (it moved off `_creator` 2026-07-15). Optional: hosts whose view
+     *  factory prompts on its own (web getUserMedia) don't implement it and the SDK resolves
+     *  immediately, so callers go through `_requestCameraPermission()`. */
+    requestCamera?(onComplete: () => void, onReject: () => void): void
+
+    // (openScanner/closeScanner removed 2026-07-15 — QRScanner rides the registered "qrScanner"
+    // NativeView; hosts keep the old handlers only for previously compiled bundles.)
+    // ---- Input (docs/input-plan.md — keyboard / mouse / gamepad behind the SDK `Input` global) ----
+    // Design: a BUTTON is anything that goes down and up — keyboard keys, mouse buttons, gamepad
+    // buttons — and they share ONE code vocabulary (KeyboardEvent.code + "MouseLeft|Right|Middle|
+    // Back|Forward" + the W3C standard-gamepad "GamepadSouth|East|West|North|L1|R1|L2|R2|Select|
+    // Start|L3|R3|Up|Down|Left|Right"), one held-poll and one event pair. Continuous signals (mouse
+    // motion, sticks, triggers) are numbered channels behind one poll. Bindings/axes/edge detection
+    // are SDK-side; hosts only report physical state.
+    /** Is this button held right now? `gamepad` (0..3) scopes a Gamepad* code to one pad; omitted =
+     *  any connected pad. Keyboard/mouse codes ignore it. */
+    inputKey: (code: string, gamepad?: number) => boolean
+    /** Continuous input poll by channel id (SDK `InputChannel`): 0 MouseX, 1 MouseY (logical px,
+     *  last known cursor position inside the viewport), 2 MouseDX, 3 MouseDY (motion accumulated
+     *  during the PREVIOUS frame — unaccelerated/raw where the OS offers it, counts while locked),
+     *  4 WheelX, 5 WheelY (wheel notches, previous frame), 6 PointerLocked (0/1), 7 GamepadCount;
+     *  gamepad p at 16 + 16·p: +0 Connected, +1 LeftX, +2 LeftY, +3 RightX, +4 RightY (−1..1,
+     *  +Y = down like the web), +5 LeftTrigger, +6 RightTrigger (0..1). Unknown channel → 0.
+     *  "Previous frame" = the host's own frame boundary (the event pump / rAF / fixed step), so
+     *  every read within one frame agrees. Optional: a host without it has no pointer/gamepad. */
+    inputRead?(channel: number): number
+    /** Request (true) / release (false) pointer lock: hide + confine the cursor, keep MouseDX/DY
+     *  flowing (FPS look). Returns whether the request was accepted now (web needs a user gesture);
+     *  the eventual state is channel 6. Hosts release on focus loss and re-acquire on focus. */
+    inputSetPointerLock?(on: boolean): boolean
+    /** Register THE input-event listener (single slot per JS world, like registerAppEvent — the SDK
+     *  fans out). kind: 0 keydown, 1 keyup, 2 gamepadconnected, 3 gamepaddisconnected. `code` is the
+     *  button code above ("" for connect events); `gamepad` the pad index for Gamepad* codes /
+     *  connect events, −1 otherwise; `repeat` 1 for an OS auto-repeat keydown. Delivered on the JS
+     *  thread no later than the end of the frame it arrived in — i.e. always before the NEXT
+     *  setLoop tick (creator-pkg drains its dispatch queue after the frame's timers, so a poll can
+     *  see the new state one tick before the event; web/headless deliver synchronously). */
+    registerInputEvent?(callback: (kind: number, code: string, gamepad: number, repeat: number) => void): void
+    // ---- World control (run/restart/quit — the platform's `location` analog) --------------------
+    // Worlds carry two host-tracked bits: an IDENTITY (project uuid) and a TRUST flag. The host's
+    // own boot world (the bundled launcher) is trusted; a world created by `run` is trusted only
+    // when its declared uuid is on the host's trusted-launcher allowlist AND the caller was
+    // trusted itself. Push registration attribution reads the identity (docs/push-plan.md).
+    /** Swap in a new project world. `projectUuid` declares the new world's identity — honored
+     *  ONLY when the calling world is trusted (launchers); silently dropped otherwise. `url`
+     *  (any caller — the caller already controls the code it runs) is the new world's
+     *  launchUrl: a string sets it, null clears it, omitted leaves it unchanged. */
+    run(systemId: number, onReject: () => void, projectUuid?: string, url?: string | null): void
+    /** Re-run the CURRENT world's bundle in a fresh world — `location.reload()`. Identity and
+     *  trust are inherited (the host re-evaluates bytes it already holds, so nothing is
+     *  spoofable). `url`: string sets the new launchUrl, null clears it, omitted keeps the
+     *  current one (a plain reload). If the re-run throws, the current world stays live. */
+    restart?(url?: string | null): void
+    /** Leave the current app. A world launched by `run` returns to the caller's boot bundle
+     *  (launch URL cleared, boot identity/trust restored). The boot world itself has no caller —
+     *  the host's app-exit hook fires instead (Android backgrounds the task; hosts that can't
+     *  exit programmatically, iOS/desktop, register nothing and the call is a no-op). */
+    quit?(): void
+
+    animate(callback: (val: number) => void, duration: number): number
+    stopAnimation(id: number): void
+    pauseAnimation(id: number): void
+    resumeAnimation(id: number): void
+
+    localStorageGetValue(key: string): string | null
+    localStorageSetValue(key: string, value: string): void
+    localStorageRemoveValue(key: string): void
+
+    websocketOpen(url: string, onWebsocketMessage: (channel: string, data: any) => void, headers?: any): number
+    websocketSend(id: number, message: string | ArrayBuffer): void
+    websocketClose(id: number): void
+
+    // ---- Service channel (headless registerService capabilities) --------------------------------
+    // The UI-less sibling of the NativeView channel (docs/service-channel-plan.md): the host
+    // registers named service factories (`registerService("geolocation", factory)`) and the SDK
+    // talks to them over the same JSON call/event protocol as viewCall. All four are optional —
+    // feature-detect with typeof; hosts that didn't opt in simply don't have them. Sessions must
+    // open cheaply (no permission prompt, no I/O) — prompts belong in the first call that needs
+    // them, so a rejected call is the failure surface, never a hung open.
+    isServiceSupported?(name: string): boolean
+    /** Open a session against the registered factory. `params` is a JSON string. Returns the
+     *  host-allocated session id, or -1 when no factory is registered under `name`. `onEvent`
+     *  delivers service events (payload as a JSON string, or omitted) until serviceClose. */
+    serviceOpen?(name: string, params: string, onEvent: (event: string, dataJson?: string) => void): number
+    /** Invoke a method on a live session — args/result JSON-encoded, exactly like viewCall. */
+    serviceCall?(serviceId: number, method: string, args: string,
+                 onComplete: (result?: string) => void, onError: (err: string) => void): void
+    serviceClose?(serviceId: number): void
+
+    // ---- App lifecycle & environment (docs/app-lifecycle-plan.md) --------------------------------
+    // One push channel + synchronous pulls. All optional — typeof feature-detect; the SDK wrappers
+    // fall back cleanly (state "active", launchUrl null, online true) on hosts that lack them.
+    /** Register THE app-event listener (single slot per JS world — the SDK fans out; the host/core
+     *  scopes the stored callback to the world and frees it on teardown). Events: "pause" / "resume"
+     *  (app left / returned to the foreground), "url" (a link arrived while running; data = the URL),
+     *  "online" / "offline" (connectivity changed). "pause" is delivered BEFORE the host halts the
+     *  frame loop (the dispatch queue must still drain). */
+    registerAppEvent?(callback: (event: string, data?: string) => void): void
+    /** Current lifecycle state: "active" | "background". Surfaced as app.state. */
+    appState?(): string
+    /** The URL the app was (most recently) opened with, or null — the cold-start deep link. A warm
+     *  link updates this value first, then fires the "url" event. Surfaced as app.launchUrl. */
+    getLaunchUrl?(): string | null
+    /** Current connectivity (navigator.onLine semantics — best-effort: false only when the platform
+     *  is sure there is no network). Surfaced as device.online. */
+    isOnline?(): boolean
+    /** Open a URL in the system browser / external handler (fire-and-forget). Backs openURL(). */
+    openUrl?(url: string): void
+    /** Lock the interface orientation: "landscape" (either landscape direction — sensor
+     *  landscape, what a horizontal game wants), "portrait" (upright only) or "auto" (release —
+     *  the device's rotation rules apply again). Fire-and-forget; the rotation itself is
+     *  animated by the platform and lands as an ordinary resize. PER WORLD: the host resets the
+     *  lock to "auto" on every world swap BEFORE the new bundle evaluates, so a game may lock at
+     *  synchronous top level and the launcher always comes back unlocked. Optional — hosts
+     *  without a rotatable screen (desktop, headless, macOS) omit it. Backs app.setOrientation. */
+    setOrientation?(mode: string): void
+    /** Write text to the system clipboard (fire-and-forget). Backs clipboard.write. */
+    clipboardWrite?(text: string): void
+    /** Read text from the system clipboard — async because web needs a permission prompt; native
+     *  hosts may complete synchronously. Reject = no access / nothing readable. Backs clipboard.read. */
+    clipboardRead?(onComplete: (text: string) => void, onReject: (err: string) => void): void
+
+    // ---- Keyboard inset (docs/input-upgrades-plan.md §7) ------------------------------------------
+    /** On-screen keyboard height in logical px currently overlapping the app viewport, 0 when
+     *  hidden. The RAW overlap, independent of the focused input's keyboardShrink policy (with
+     *  shrink the layout already avoids it; the main consumer is overlay mode). Surfaced as
+     *  app.keyboardHeight. Optional — hosts without an on-screen keyboard omit it. */
+    keyboardHeight?(): number
+    /** Register THE keyboard listener (single slot per JS world, like registerAppEvent — the SDK
+     *  fans out; a separate channel because the string one can't carry two numbers). Fires on every
+     *  keyboard frame change with (height — as above, duration — the platform's animation duration
+     *  in ms, 0 where none). Surfaced as the app "keyboard" event. */
+    registerKeyboardEvent?(callback: (height: number, duration: number) => void): void
+
+    // (camera* removed 2026-07-15 — CameraView rides the registered "camera" NativeView; hosts
+    // keep the old handlers only for previously compiled bundles.)
+
+    createAudioPlayer(src: string, onFinished: () => void): number
+    createVideoPlayer(src: string, onFinished: () => void): number
+    updateMediaPlayerVolume(id: number, volume: number): void
+    updateMediaPlayerLoop(id: number, loop: boolean): void
+    updateMediaPlayerPlaying(id: number, play: boolean): void
+    getMediaPlayerTime(id: number): number
+    setMediaPlayerTime(id: number, time: number): void
+    getMediaPlayerDuration(id: number): number
+    removeMediaPlayer(id: number): void
+
+    /** The host bucket surfaced as `device.platform`. Apps BRANCH on it (mouse-look vs on-screen
+     *  sticks, hover affordances, key hints), so it names the INPUT MODEL, not the OS — one of
+     *  "web" | "ios" | "android" | "desktop". macOS reports "desktop", not "macos": a project
+     *  testing `device.platform === "desktop"` must get the same answer on every desktop host.
+     *  OS/version detail belongs in the host's own systemInfo callback, never here. Every host
+     *  must define it — where it was missing (Android before 2026-07-30, iOS before 2026-08-25)
+     *  the SDK read undefined and no platform branch in any app could ever match. */
+    platform: string
+    language: string
+    /** Display device-pixel ratio (physical px per CSS/logical px): 1 on standard displays, 2–3 on
+     *  retina / iOS. Host-provided (web: window.devicePixelRatio; iOS: UIScreen.scale). Surfaced as
+     *  device.pixelRatio — for baking a Canvas at the right resolution without hardcoding it. */
+    pixelRatio: number
+    /** Opt into the precise-touch system (full-rate coalesced sampling) where the host supports it — iOS
+     *  coalesced touches. Surfaced as device.setPreciseTouch. Optional: hosts without a coalesced-input
+     *  concept (web, headless) simply don't implement it, so callers guard with `?.`. */
+    setPreciseTouch?(enabled: boolean): void
+    /** Fire a one-shot semantic haptic (device.vibrate). `style` is a HapticStyle string. Optional:
+     *  hosts without haptic hardware (web, headless, iPad / older iPhones) simply don't implement it,
+     *  so callers guard with `?.`. */
+    vibrate?(style: string): void
+
+    // ---- device.motion (orientation sensor; pull-per-frame model) --------------------------------
+    /** Does this device have the motion sensors (gyro)? Surfaced as device.motion.available. */
+    motionAvailable?(): boolean
+    /** Start fused device-motion updates at `interval` seconds; returns whether it started (false =
+     *  no sensor / permission denied). May return a Promise on hosts with an async permission prompt
+     *  (web). Surfaced as device.motion.start. */
+    motionStart?(interval: number): boolean | Promise<boolean>
+    /** Stop updates and release the sensor. Surfaced as device.motion.stop. */
+    motionStop?(): void
+    /** The freshest raw sample in the DEVICE frame: `[qx,qy,qz,qw, gx,gy,gz, interfaceOrientation]`
+     *  (orientation code: 0 portrait, 1 landscapeLeft, 2 landscapeRight, 3 upsideDown), or null until
+     *  the first sample / when not running. The SDK converts it to world/screen space. */
+    getMotionSample?(): number[] | null
+  }
+
+  // ---- 2D canvas (core; native-per-platform — see docs/canvas-contract.md) ---------------------
+  // Immediate-mode 2D drawing that bakes to a texture, shared by 2D/3D/UI. The SDK Canvas records a
+  // command buffer and flushes it here once per bake (opcodes documented in the contract).
+  var _creatorCanvas: {
+    // Rasterize `cmd` (cmdLen floats) into surface `surfaceId` (0 = create), sized w×h logical @
+    // `scale` device px. Clears then replays the whole buffer. Returns the surface id.
+    rasterize(surfaceId: number, w: number, h: number, scale: number,
+              cmd: Float32Array, cmdLen: number, refs: string[]): number
+    // [width, ascent, descent] in logical px for `text` in `font`, measured on this platform.
+    measureText(text: string, font: string): Float32Array
+    // Copy surface `surfaceId`'s pixels into a NEW standalone surface; returns the new id. Backs
+    // Canvas.toBitmap() — an immutable snapshot the source canvas can no longer touch.
+    snapshot(surfaceId: number): number
+    // Decode an image source into a NEW standalone surface (device px) — backs Canvas.loadImage() for
+    // Canvas.drawImage(). `bufferId < 0` → rasterize the SVG markup in `svg`; otherwise decode the
+    // encoded image bytes in host buffer `bufferId` (an already-fetched FetchResponse). Async, because
+    // turning SVG / encoded bytes into pixels needs a decode on web (createImageBitmap / <img>). Returns
+    // (surfaceId, width, height) in device px via onComplete, or onReject on failure.
+    loadImage(svg: string, bufferId: number,
+              onComplete: (surfaceId: number, width: number, height: number) => void, onReject: () => void): void
+    // Encode surface `surfaceId` to an image ('image/png' | 'image/jpeg'), register the bytes as a host
+    // buffer, and return (bufferId, size) — the SDK wraps it in a File. Backs Canvas/Bitmap.toFile().
+    toFile(surfaceId: number, type: string, onComplete: (bufferId: number, size: number) => void, onReject: () => void): void
+    destroySurface(surfaceId: number): void
+  }
+}
+
+export {}