lecodes-sdk 0.20.2 → 1.0.0

package/src/bridges.d.ts

@@ -1,1481 +1,1599 @@
-// 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
-    /** Filament View::setStencilBufferEnabled (Scene.stencil). Optional. */
-    setSceneStencil?(sceneId: number, enabled: boolean): 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
-    /** Engine-wide cap on texture size (`Texture.maxSize` / `SceneOptions.maxTextureSize`): a
-     *  KTX2 wider or taller than `size` loses its top mip levels on load, a glTF PNG/JPEG is
-     *  downsampled; 0 = no cap. Reaches textures created AFTER the call — a loaded level keeps
-     *  its textures, so a settings menu applies it on the next level load. `createTexture` flag
-     *  2 (FULL_SIZE) exempts one texture (lightmap pages). Optional: hosts that predate it load
-     *  full-size textures and the SDK skips the call. */
-    setTextureMaxSize?(size: number): void
-    /** Depth-reading effects on / off (`scene.setDepthEffects`): soft particles (`depthFade`) and
-     *  projected decals read the scene depth, which costs a half-res depth pre-pass of every opaque
-     *  draw. Off = no pre-pass, hard-edged particles, decal sets draw nothing. Engine-wide, live.
-     *  Optional: hosts that predate it keep the effects and the SDK skips the call. */
-    setDepthEffects?(enabled: boolean): void
-    /** LOD distance (`scene.setLodBias`): the LOD pass' screen-size thresholds × `bias` — 2 = every
-     *  level switches at half the distance, 0.5 = full detail twice as far; 1 = the defaults
-     *  (0.30 / 0.12 / 0.05 of the viewport height). Engine-wide, live, clamped 0.25..8. Optional:
-     *  hosts without the LOD pass ignore it and the SDK skips the call. */
-    setLodBias?(bias: 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. */
-    /** `colors` (Geometry.colors) is 4 bytes RGBA per vertex for a `requires: [color]` material;
-     *  a host that predates it draws the mesh white. */
-    setMesh(entityId: number, materialId: number, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, meshType: number, uv1?: Float32Array, colors?: Uint8Array): 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
-    /** Filament RenderableManager::setPriority — the coarse draw order, 0..7 (Mesh.renderPriority).
-     *  Optional: an older host leaves everything at the default 4. */
-    setRenderPriority?(entityId: number, priority: number): void
-    /** Filament MaterialInstance::setDepthCulling / setDepthWrite — per-instance overrides of the
-     *  depth state baked into the shader package (Material.depthTest / depthWrite). Optional. */
-    setMaterialDepthTest?(materialInstanceId: number, enable: boolean): void
-    setMaterialDepthWrite?(materialInstanceId: number, enable: boolean): void
-    /** Filament MaterialInstance::setCullingMode: 0 none (double-sided), 1 front, 2 back. Optional. */
-    setMaterialCulling?(materialInstanceId: number, mode: number): void
-    /** Filament MaterialInstance stencil state in one call (Material.stencil): `test` 0 always, 1 never,
-     *  2 less, 3 lessEqual, 4 greater, 5 greaterEqual, 6 equal, 7 notEqual; the ops 0 keep, 1 zero,
-     *  2 replace, 3 increment, 4 decrement, 5 invert. Optional. */
-    setMaterialStencil?(materialInstanceId: number, write: boolean, test: number, ref: number, onPass: number, onFail: number, onDepthFail: number, readMask: number, writeMask: number): void
-    setCastShadows(entityId: number, culling: boolean): void
-    setReceiveShadows(entityId: number, culling: boolean): void
-
-    /** Decode a fetched image into a texture. `flags` (optional, Texture.load): bit 1 = LINEAR data
-     *  (a normal map — store RGBA8, not sRGB); unset / absent = colour, sRGB. A host that ignores
-     *  it loads colour correctly and normal maps wrongly. KTX2 decides by its own header. */
-    createTexture(systemId: number, onComplete: (id: number, width: number, height: number) => void, onReject: () => void, flags?: number): 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 clip DERIVED from one of the set as a NEW single-clip set (index 0) — AnimationClip.from(clip, { mirror,
-    // from, to }): the mirror (left ↔ right on the set's own rig, the GLB's node tree: contacts swapped, heading
-    // negated), then the [start, end] window re-timed to 0 (start < 0 = whole, end < 0 = the clip's end; boundary
-    // values interpolated in, events re-timed). 0 = bad id / range, or a mirror asked of a set without a rig.
-    deriveClip(clipSetId: number, clip: number, mirror: boolean, 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, each placed on it LINEARLY by `phases` — two floats per member,
-    // (offset, cycles): φ(t) = offset + cycles · t / duration, 0 at a left-foot-down (measured offline
-    // from the clip's foot marks). An empty array, or cycles <= 0 for a member = normalized time (0, 1) and no
-    // cycle to phase-match to — the clock never reads the clip's marks. 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, phases: Float32Array): 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 | 6, 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
-    // CYCLE ALIGNMENT by pose, no marks: given slot a's cycle (offA, cyclesA), the (offset, cycles) of slot b
-    // under which the two loops show the same pose at the same gait phase — b's cycle count searched over
-    // cyclesA × {1/3 … 3}, its offset on a fine grid. out = [offset, cycles, score (metres), margin (runner-up
-    // ≥ 0.2 cycle away minus the best; ~0 = ambiguous)]. Returns 1, or 0 when there is nothing to compare.
-    animatorSlotAlign(animatorId: number, a: number, b: number, offA: number, cyclesA: number, out: Float32Array): 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-particles (CPART_TAG_* in creator-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
-
-    // Projected decals (creator-gl src/decals.h; SDK gl/DecalSet.ts). A set on an entity = one
-    // renderable of `capacity` (0 = 256) unit boxes drawn with the material instance (decal.filamat)
-    // — each box projects its atlas cell onto the opaque scene behind it through the scene depth
-    // buffer. A record is 23 floats in the SET entity's space: X Y Z axes scaled by the box's
-    // width / height / depth (Z = out of the surface), centre, atlas rect u0 v0 u1 v1, tint rgba,
-    // life (s, 0 = forever), fadeIn (s), fadeOut (s). addDecal returns the slot (0xFFFFFFFF = no
-    // set; a full set recycles its oldest); updateDecal keeps the slot's birth time. Optional:
-    // a host without them draws no decals (the SDK warns once).
-    createDecalSet?(entityId: number, materialInstanceId: number, capacity: number): void
-    addDecal?(entityId: number, record: Float32Array): number
-    updateDecal?(entityId: number, slot: number, record: Float32Array): void
-    removeDecal?(entityId: number, slot: number): void
-    clearDecals?(entityId: number): void
-    decalCount?(entityId: number): number
-
-    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
-  }
-
-  // ---- Game audio (creator-audio) ----------------------------------------------------------------
-  // docs/audio-plan.md. Whole clips decoded up front, a fixed voice pool (play allocates nothing),
-  // 3D sources the engine follows per frame, mixer buses with insert effects, reverb zones,
-  // occlusion. OPTIONAL as a block: the SDK gates on `typeof _creatorAudio !== 'undefined' &&
-  // hasSupport()` and stays inert (silent Sound, inert Voice) without it. Present on hosts built with
-  // CREATOR_PKG_AUDIO (desktop first; Android / Apple pending — parity `audio-game`). The headless
-  // renderer provides a RECORDER (plays are logged, nothing is mixed). Every parameter block is a
-  // fixed-order Float32Array (creator-audio.h CAUD_SRC_* / the effect param orders).
-  var _creatorAudio: {
-    hasSupport(): boolean
-    /** Decode the bytes behind a fetch system id (WAV / MP3 / FLAC / OGG Vorbis) on the engine's
-     *  loader thread; mono unless `stereo`. onDone(clipId, durationSeconds, channels). */
-    loadClip(systemId: number, stereo: boolean, onDone: (clipId: number, duration: number, channels: number) => void, onReject: (message: string) => void): void
-    releaseClip(clipId: number): void
-    /** Bus id by name (-1 unknown); 0 master, 1 sfx, 2 music, 3 ui, 4 voice. */
-    busId(name: string): number
-    /** Creates (or finds) an app-defined bus under master. -1 when the 16 slots are full. */
-    createBus(name: string): number
-    setBusVolume(bus: number, volume: number): void
-    setBusMuted(bus: number, muted: boolean): void
-    /** kind 1 reverb [roomSize, damping, width, mix, preDelay] · 2 echo [delay, decay, mix] ·
-     *  3 lowpass [cutoffHz]; an empty array turns the effect off. Changes are smoothed. */
-    setBusEffect(bus: number, kind: number, params: Float32Array): void
-    stopBus(bus: number, fade: number): void
-    /** A 3D emitter. `attachSource` binds it to an entity the engine follows every frame;
-     *  `setSourcePosition` places an unbound one (playAt). */
-    createSource(): number
-    attachSource(sourceId: number, entityId: number): void
-    /** [minDistance, maxDistance, rolloff (0 none 1 inverse 2 linear 3 exp), coneInnerDeg,
-     *  coneOuterDeg, coneOuterGain, doppler, spread, occlusion (0/1), bus]. */
-    setSourceParams(sourceId: number, params: Float32Array): void
-    setSourcePosition(sourceId: number, x: number, y: number, z: number): void
-    stopSource(sourceId: number, fade: number): void
-    sourceVoices(sourceId: number): number
-    destroySource(sourceId: number): void
-    /** The listener entity; 0 = the active scene camera (the default). */
-    setListener(entityId: number): void
-    setListenerOptions(dopplerFactor: number): void
-    /** HRTF binaural rendering for the `maxVoices` nearest spatial voices (headphones); the rest keep panning. */
-    setHrtf(enabled: boolean, maxVoices: number): void
-    /** Whether the engine's time scale (Time.scale) also pitches the sfx bus. Default false (pause = mute only). */
-    setTimeScalePitch(enabled: boolean): void
-    /** → a voice token (0 = nothing played: the pool refused, the clip is not ready). bus -1 = the
-     *  source's bus (sfx for 2D). pan is 2D only. */
-    play(clipId: number, sourceId: number, bus: number, volume: number, pitch: number, loop: boolean, priority: number, fadeIn: number, startAt: number, pan: number): number
-    setVoiceVolume(token: number, volume: number): void
-    setVoicePitch(token: number, pitch: number): void
-    setVoicePan(token: number, pan: number): void
-    stopVoice(token: number, fade: number): void
-    voicePlaying(token: number): boolean
-    voiceTime(token: number): number
-    /** THE ended listener (single slot per JS world): called once per tick with the tokens of the
-     *  voices that ended since the previous tick — natural end, stop, steal. */
-    setOnEnded(callback: ((tokens: Float32Array) => void) | null): void
-    stopAll(fade: number): void
-    /** A reverb volume: shape 0 box (dims = full size) / 1 sphere (dims[0] = diameter), in the
-     *  entity's local units; `blend` metres of crossfade inside the border; reverb params as for
-     *  setBusEffect kind 1. The listener inside blends the zone's reverb onto `bus`. */
-    createZone(): number
-    attachZone(zoneId: number, entityId: number): void
-    setZone(zoneId: number, shape: number, dims: Float32Array, blend: number, bus: number, reverb: Float32Array): void
-    destroyZone(zoneId: number): void
-    /** [voicesPlaying, voicesMono, voicesStereo, stolen, clips, clipBytes, peak, sampleRate, listenerZone, zoneBlend, hrtfVoices]. */
-    stats(): Float32Array
-  }
-
-  // ---- 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", …).
-    // An image "src" (here and at creation) is a url string, { _id } (a host buffer), { svg },
-    // { canvasSurface } (a baked Canvas), or { scene2d: sceneId } — a LIVE 2D scene the host draws
-    // into the node's laid-out box every frame with the scene's own camera (native: c2dDrawSceneGL
-    // into a per-node framebuffer; no intrinsic size, the scene needs no openScene). The engine's
-    // simulation must still step each frame for it (native: c2dTick when nothing is presented).
-    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,
-     *  8 PointerOnUI (0/1: the primary pointer went DOWN on something the UI claimed — an
-     *  interactive node, a scrollable, an editable, a modal backdrop — and is still held; stays 1
-     *  wherever the cursor goes until the release, so a drag that started on a HUD control never
-     *  becomes camera look; always 0 while pointer-locked and for touch-only hosts without a UI claim);
-     *  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 {}
+// 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
+    /** Filament View::setStencilBufferEnabled (Scene.stencil). Optional. */
+    setSceneStencil?(sceneId: number, enabled: boolean): 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
+    /** Engine-wide cap on texture size (`Texture.maxSize` / `SceneOptions.maxTextureSize`): a
+     *  KTX2 wider or taller than `size` loses its top mip levels on load, a glTF PNG/JPEG is
+     *  downsampled; 0 = no cap. Reaches textures created AFTER the call — a loaded level keeps
+     *  its textures, so a settings menu applies it on the next level load. `createTexture` flag
+     *  2 (FULL_SIZE) exempts one texture (lightmap pages). Optional: hosts that predate it load
+     *  full-size textures and the SDK skips the call. */
+    setTextureMaxSize?(size: number): void
+    /** Depth-reading effects on / off (`scene.setDepthEffects`): soft particles (`depthFade`) and
+     *  projected decals read the scene depth, which costs a half-res depth pre-pass of every opaque
+     *  draw. Off = no pre-pass, hard-edged particles, decal sets draw nothing. Engine-wide, live.
+     *  Optional: hosts that predate it keep the effects and the SDK skips the call. */
+    setDepthEffects?(enabled: boolean): void
+    /** LOD distance (`scene.setLodBias`): the LOD pass' screen-size thresholds × `bias` — 2 = every
+     *  level switches at half the distance, 0.5 = full detail twice as far; 1 = the defaults
+     *  (0.30 / 0.12 / 0.05 of the viewport height). Engine-wide, live, clamped 0.25..8. Optional:
+     *  hosts without the LOD pass ignore it and the SDK skips the call. */
+    setLodBias?(bias: 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. */
+    /** `colors` (Geometry.colors) is 4 bytes RGBA per vertex for a `requires: [color]` material;
+     *  a host that predates it draws the mesh white. */
+    setMesh(entityId: number, materialId: number, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, meshType: number, uv1?: Float32Array, colors?: Uint8Array): 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
+    /** Filament RenderableManager::setPriority — the coarse draw order, 0..7 (Mesh.renderPriority).
+     *  Optional: an older host leaves everything at the default 4. */
+    setRenderPriority?(entityId: number, priority: number): void
+    /** Filament MaterialInstance::setDepthCulling / setDepthWrite — per-instance overrides of the
+     *  depth state baked into the shader package (Material.depthTest / depthWrite). Optional. */
+    setMaterialDepthTest?(materialInstanceId: number, enable: boolean): void
+    setMaterialDepthWrite?(materialInstanceId: number, enable: boolean): void
+    /** Filament MaterialInstance::setCullingMode: 0 none (double-sided), 1 front, 2 back. Optional. */
+    setMaterialCulling?(materialInstanceId: number, mode: number): void
+    /** Filament MaterialInstance stencil state in one call (Material.stencil): `test` 0 always, 1 never,
+     *  2 less, 3 lessEqual, 4 greater, 5 greaterEqual, 6 equal, 7 notEqual; the ops 0 keep, 1 zero,
+     *  2 replace, 3 increment, 4 decrement, 5 invert. Optional. */
+    setMaterialStencil?(materialInstanceId: number, write: boolean, test: number, ref: number, onPass: number, onFail: number, onDepthFail: number, readMask: number, writeMask: number): void
+    setCastShadows(entityId: number, culling: boolean): void
+    setReceiveShadows(entityId: number, culling: boolean): void
+
+    /** Decode a fetched image into a texture. `flags` (optional, Texture.load): bit 1 = LINEAR data
+     *  (a normal map — store RGBA8, not sRGB); unset / absent = colour, sRGB. A host that ignores
+     *  it loads colour correctly and normal maps wrongly. KTX2 decides by its own header. */
+    createTexture(systemId: number, onComplete: (id: number, width: number, height: number) => void, onReject: () => void, flags?: number): 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 clip DERIVED from one of the set as a NEW single-clip set (index 0) — AnimationClip.from(clip, { mirror,
+    // from, to }): the mirror (left ↔ right on the set's own rig, the GLB's node tree: contacts swapped, heading
+    // negated), then the [start, end] window re-timed to 0 (start < 0 = whole, end < 0 = the clip's end; boundary
+    // values interpolated in, events re-timed). 0 = bad id / range, or a mirror asked of a set without a rig.
+    deriveClip(clipSetId: number, clip: number, mirror: boolean, 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, each placed on it LINEARLY by `phases` — two floats per member,
+    // (offset, cycles): φ(t) = offset + cycles · t / duration, 0 at a left-foot-down (measured offline
+    // from the clip's foot marks). An empty array, or cycles <= 0 for a member = normalized time (0, 1) and no
+    // cycle to phase-match to — the clock never reads the clip's marks. 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, phases: Float32Array): 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 | 6, 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
+    // CYCLE ALIGNMENT by pose, no marks: given slot a's cycle (offA, cyclesA), the (offset, cycles) of slot b
+    // under which the two loops show the same pose at the same gait phase — b's cycle count searched over
+    // cyclesA × {1/3 … 3}, its offset on a fine grid. out = [offset, cycles, score (metres), margin (runner-up
+    // ≥ 0.2 cycle away minus the best; ~0 = ambiguous)]. Returns 1, or 0 when there is nothing to compare.
+    animatorSlotAlign(animatorId: number, a: number, b: number, offA: number, cyclesA: number, out: Float32Array): 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
+    /** DEBUG pick: the closest TRIANGLE under a screen point (logical px) among the loaded GLB instances —
+     *  entityId = one Model's root, 0 = every instance — CPU-skinned with the joints' CURRENT pose, both
+     *  faces. JSON string (`Model.pickTriangle` parses it: node, mesh, primitive, triangle, hit point,
+     *  the three vertices with their raw JOINTS_0/WEIGHTS_0 pairs), "" on a miss. One full CPU skin per
+     *  call — click-rate only. Optional: a debug tool, hosts may lack it. */
+    pickTriangle?(entityId: number, screenX: number, screenY: number): string
+    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. */
+    /** `maskedMaterialInstanceId` (2026-09-11): the tier's masked twin for the asset's alpha-MASK materials
+     *  (foliage cards); a host without it ignores the argument and keeps those on the ubershader. */
+    setNextGlbLightmapped?(materialInstanceId: number, maskedMaterialInstanceId?: 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[34]: version(15), mass, comAuto, comY,
+    //               engTorque, engMaxRpm, engIdleRpm (0 = no floor: the engine can stall, the game
+    //                 holds idle and cranks it), 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,
+    //               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),
+    //               steerMode (0 = `steer` is the wheel angle as a fraction of the lock; 1 = `steer`
+    //                 is where the driver's HANDS aim a steering column the engine integrates every
+    //                 sub-step: I·θ̈ = T_hand + T_align·(1 − assist) + T_stop − damping·θ̇ − friction,
+    //                 T_hand = clamp(handStiffness·(steer·lock − θ), ±handTorque·steerForce),
+    //                 steerForce = the input's per-frame hold — the game's policy on when the hands let go,
+    //                 T_align = the steered tires' lateral force × (pneumatic trail collapsing to
+    //                 trailFloor × trail at the curve's peak + caster) — heavy at speed, light past
+    //                 the peak, self-centring, counter-steering in a slide),
+    //               colInertia, colDamping, colFriction (the patch's dry friction, fades out by 1.5 m/s),
+    //               colCaster, colTrail, colTrailFloor (the aligning torque's arms — read in BOTH
+    //                 modes; steerTorque is reported either way, the force-feedback signal),
+    //               colHandTorque, colHandStiffness, colAssist (power steering),
+    //               colRateDeg (the HANDS' top turning speed, deg/s — they cannot push a wheel that
+    //                 outruns them, they can still hold it; the free column is uncapped; 0 = none),
+    //               colStopDeg, colStopTorque, colStopDamping (the end stop: over the last colStopDeg
+    //                 before the lock the rack pushes back colStopTorque × depth² N·m and damps by
+    //                 colStopDamping × depth N·m·s/rad — progressive, viscous rubber; 0 band = the
+    //                 hard clamp only),
+    //               colBearing (the column's own dry friction, N·m, at any speed — rack and bearings),
+    //               colHandRamp (seconds the hands' torque builds to colHandTorque over; 0 = instant),
+    //               clutchCapacity (N·m the clutch passes before it slips, × the clutch scalar; 0 = Jolt's
+    //                 viscous clutch alone),
+    //               wheelCount, curveCount
+    //   + curveCount * 2: the engine's normalized torque curve (x = rpm/maxRpm, y = torque/maxTorque);
+    //                     0 points keeps Jolt's default
+    //   + per wheel, VARIABLE length: 15 fixed floats — px, py, pz, radius, width, maxSteerDeg,
+    //                      driven (the wheel's SHARE of the engine's torque: an axle's share is the sum
+    //                      of its two, the left/right split their ratio; every wheel 0 = no drive at
+    //                      all), axle, travel, stiffness, damping,
+    //                      traction (the longitudinal impulse clamp as a multiple of friction × load;
+    //                      1 = the physical tire, Jolt's sample runs 10), circle (friction circle 0..1:
+    //                      the share of lateral capacity the longitudinal impulse in use takes away;
+    //                      0 = the two axes independent), sideCount, forwardCount — then
+    //                      sideCount × (slip angle °, friction) and forwardCount × (slip ratio,
+    //                      friction). Tire curves are POINTS the SDK sends (its presets are SDK-side);
+    //                      0 points keeps Jolt's own curve.
+    // In steerMode 0 the steering input is RAW: `steer` × each wheel's maxSteerDeg, per fixed step —
+    // any taper / rate limit is the game's. In mode 1 `steer` is where the hands aim the wheel.
+    // NO gear list, no pedals and no wheel node ids: the gearbox is the game's (a ratio + clutch in
+    // the input vector), the brakes are a torque per wheel in the same vector, and the game poses its
+    // wheel models itself from the state. 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
+    /** ONE input vector, latched and applied once per fixed step: [throttle 0..1, steer −1..1 (a
+     *  fraction of the wheels' maxSteerDeg, applied as is; with a column, where the hands aim),
+     *  steerForce 0..1 (with a column: how firmly the hands hold the wheel — the game's per-frame
+     *  policy on letting go; without one, ignored), ratio (the ONE gear ratio the car runs: 0 =
+     *  neutral, negative = reverse — the engine never sees a gear list), clutch 0..1 (scales the clutch
+     *  in the coupled engine/wheel solve), brake_0 … brake_n (N·m of brake torque per wheel, this
+     *  step)]. A shorter vector leaves the rest as it was. Sticky; a non-zero throttle, steer or brake
+     *  wakes a sleeping car. */
+    vehicleSetInput(vehicleId: number, input: Float32Array): void
+    /** Re-apply the TUNABLE half of the blob (same layout) to a live car — differential, per-wheel tire
+     *  curves / traction / circle, engine torque/RPM/curve, clutch strength + capacity, steer lock, the
+     *  column, anti-roll stiffness, tilt limit. Structural values (mass, centre of mass, wheel geometry,
+     *  the driven shares, suspension, whether an axle has a bar) are ignored: those need a re-create. */
+    vehicleSetTuning?(vehicleId: number, settings: Float32Array): void
+    /** out = [speed, rpm, wheelsInContact, vx, vy, vz, wx, wy, wz, steerDeg, steerTorque] (w = chassis
+     *  angular velocity, rad/s; steerDeg = where the road wheels are, right-positive; steerTorque = the
+     *  tires' self-aligning torque on the steering, N·m, + = pulls right — the force-feedback signal,
+     *  reported in both steering modes)
+     *  + per wheel [contact, slipLong, slipAngleDeg, suspensionLength, steerDeg, spin, fLat, fLong, vLat, vSlip, load]
+     *  (fLat/fLong = the tire's forces, N, + = to its right / pushing the car forward; vLat/vSlip = the
+     *  patch's sliding speeds, m/s, + = to the right / tread spinning up — force × speed is heat; load =
+     *  the suspension's force on the wheel, N). slipLong is SIGNED (+ spinning up, − locking) and so is
+     *  slipAngleDeg (+ the patch sliding to the tire's right). suspensionLength, steerDeg and spin are
+     *  what a wheel model's pose is built from — by the game, the SDK only exposes them. */
+    vehicleGetState(vehicleId: number, out: Float32Array): void
+    /** Teleport upright and clear all motion (velocities, engine RPM, wheel spin); the input vector is
+     *  zeroed — the SDK re-sends its own on the next early pass. */
+    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
+    // Dynamic bones (the SDK's DynamicBone; creator-anim canimDyn* behind creator-gl): secondary motion
+    // for tails, ears, hair and cloaks — a bone tree under one root simulated as Verlet particle chains
+    // (gravity, wind, drag, stiffness toward the animated shape, an angle cone, capsule / sphere
+    // colliders, a floor plane, bone length, neighbour links) in an engine stage AFTER the late phase
+    // and BEFORE the skin flush: the animator, an active ragdoll and late-phase JS bone writes are the
+    // input, the simulated local rotations the output. Bones the animator does not drive keep their
+    // bind pose as the target; driven ones follow their clip. Optional: a host without it shows the
+    // animation alone.
+    //   bones[boneCount]: entity ids — the root first, every other bone a child of an earlier one.
+    //   settings — header[28]: version(1), boneCount, boneStride(7), then the chain params: weight
+    //              (0..1 animation → simulation; 0 = off, re-arms on the animated pose), follow (0..1 of
+    //              the root's travel carried onto the particles; 0 = full whip), wind xyz (m/s², world),
+    //              link (0..1 neighbour-link strength), rate (substep Hz, ≤ 4 substeps per frame),
+    //              teleport (a root jump past this many metres resets the chain), floor (0/1), floor
+    //              point xyz, floor normal xyz (the floor slots are overridden by dynamicBoneSetFloor),
+    //              floorFriction (a Coulomb coefficient: a resting particle's slide loses up to friction · g · dt of
+    //              speed per substep), iterations
+    //              (constraint passes per substep, 1..8, default 4; a long rope may want 8), side (the
+    //              cloth's outside, one-sided colliders: 0 none, 1 away from the root bone's axis, 2 the
+    //              next xyz in the root bone's frame), side xyz, guideHold (0..1: guides re-applied after
+    //              every constraint pass with this fraction of their weight; 0 = once before the passes),
+    //              edges (1 = the bone segments and links collide with the capsules too, not only the particles),
+    //              spin (> 0: the chain in the parent bone's rotating frame + its centrifugal / Euler forces × spin;
+    //              0 = the translational frame, no turn forces), spinInertia (s: the cloth's own rotation follows the body's with this time constant — behind on a start, past the back on a stop; 0 = glued)
+    //   + boneCount × 7: radius (m), stiffness (0..1 per 1/60 s toward the animated shape), damping
+    //              (0..1 velocity lost per 1/60 s), gravity (m/s² along world −Y), angleLimit (degrees off
+    //              the animated direction, 0 = none), mass (relative, 0 = 1: a bone-length constraint
+    //              moves its two ends in inverse proportion; the root is kinematic; < 0 = PINNED, the bone
+    //              rides the animation), give (m, pinned bones: a soft pin — a collider may push the bone
+    //              this far off its animated place, its local translation is written back too; 0 = hard)
+    //   links: (a, b) bone index pairs held at their rest distance (a cloak's columns; two linked leaves
+    //          link their virtual tips too, so a hem stays a hem); optional.
+    dynamicBoneCreate?(modelRootId: number, bones: Uint32Array, settings: Float32Array, links?: Uint16Array): number
+    dynamicBoneDestroy?(id: number): void
+    /** Retune a live chain: the same blob as create (the bone rows too when the count matches). */
+    dynamicBoneSet?(id: number, settings: Float32Array): void
+    /** The floor the particles stay above: mode 0 none / 1 the plane (point, normal) / 2 probe — the
+     *  engine casts a ray from the chain root down every frame (the ground probe, the model root
+     *  excluded) and uses the hit; no hit / no physics world = no floor that frame. */
+    dynamicBoneSetFloor?(id: number, mode: 0 | 1 | 2, x: number, y: number, z: number, nx: number, ny: number, nz: number): void
+    /** The next frame snaps the chain onto the animated pose (a teleport, a cut). */
+    dynamicBoneReset?(id: number): void
+    /** The colliders this chain collides with (dynamicBoneColliderCreate ids); replaces the list. */
+    dynamicBoneSetColliders?(id: number, colliderIds: Uint32Array): void
+    /** The particles' world positions (bones first, then the leaves' virtual tips), 3 floats each into
+     *  `out`; returns the count written — a debug overlay. */
+    dynamicBoneParticles?(id: number, out: Float32Array): number
+    // guides: rows × 5 — bone index (in the chain's bone order), world x y z, weight — world points the
+    // bones' particles are drawn to before the constraints; null / empty clears; refreshed every frame
+    dynamicBoneTargets?(id: number, rows: Float32Array | null): void
+    /** A capsule a → b in the entity's local space (a == b = a sphere) that rides the entity — a bone
+     *  of the body the chains must not pass through. Returns a collider id (0 on failure). */
+    dynamicBoneColliderCreate?(entityId: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, radius: number): number
+    dynamicBoneColliderSet?(colliderId: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, radius: number): void
+    dynamicBoneColliderDestroy?(colliderId: number): void
+    // 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-particles (CPART_TAG_* in creator-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
+
+    // Projected decals (creator-gl src/decals.h; SDK gl/DecalSet.ts). A set on an entity = one
+    // renderable of `capacity` (0 = 256) unit boxes drawn with the material instance (decal.filamat)
+    // — each box projects its atlas cell onto the opaque scene behind it through the scene depth
+    // buffer. A record is 27 floats in the SET entity's space: X Y Z axes scaled by the box's
+    // width / height / depth (Z = out of the surface), centre, atlas rect u0 v0 u1 v1, tint rgba,
+    // life (s, 0 = forever), fadeIn (s), fadeOut (s), capStart, capEnd (tilt of the image's bottom /
+    // top edge in unit space — mitred trail joints, 0 = square), alphaStart, alphaEnd (opacity
+    // multipliers at the bottom / top edge — a gradient along the image). addDecal returns the slot (0xFFFFFFFF = no
+    // set; a full set recycles its oldest); updateDecal keeps the slot's birth time. Optional:
+    // a host without them draws no decals (the SDK warns once).
+    createDecalSet?(entityId: number, materialInstanceId: number, capacity: number): void
+    addDecal?(entityId: number, record: Float32Array): number
+    updateDecal?(entityId: number, slot: number, record: Float32Array): void
+    removeDecal?(entityId: number, slot: number): void
+    clearDecals?(entityId: number): void
+    decalCount?(entityId: number): number
+
+    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
+  }
+
+  // ---- Game audio (creator-audio) ----------------------------------------------------------------
+  // docs/audio-plan.md. Whole clips decoded up front, a fixed voice pool (play allocates nothing),
+  // 3D sources the engine follows per frame, mixer buses with insert effects, reverb zones,
+  // occlusion. OPTIONAL as a block: the SDK gates on `typeof _creatorAudio !== 'undefined' &&
+  // hasSupport()` and stays inert (silent Sound, inert Voice) without it. Present on hosts built with
+  // CREATOR_PKG_AUDIO (desktop first; Android / Apple pending — parity `audio-game`). The headless
+  // renderer provides a RECORDER (plays are logged, nothing is mixed). Every parameter block is a
+  // fixed-order Float32Array (creator-audio.h CAUD_SRC_* / the effect param orders).
+  var _creatorAudio: {
+    hasSupport(): boolean
+    /** Decode the bytes behind a fetch system id (WAV / MP3 / FLAC / OGG Vorbis) on the engine's
+     *  loader thread; mono unless `stereo`. onDone(clipId, durationSeconds, channels). */
+    loadClip(systemId: number, stereo: boolean, onDone: (clipId: number, duration: number, channels: number) => void, onReject: (message: string) => void): void
+    releaseClip(clipId: number): void
+    /** Bus id by name (-1 unknown); 0 master, 1 sfx, 2 music, 3 ui, 4 voice. */
+    busId(name: string): number
+    /** Creates (or finds) an app-defined bus under master. -1 when the 16 slots are full. */
+    createBus(name: string): number
+    setBusVolume(bus: number, volume: number): void
+    setBusMuted(bus: number, muted: boolean): void
+    /** kind 1 reverb [roomSize, damping, width, mix, preDelay] · 2 echo [delay, decay, mix] ·
+     *  3 lowpass [cutoffHz]; an empty array turns the effect off. Changes are smoothed. */
+    setBusEffect(bus: number, kind: number, params: Float32Array): void
+    stopBus(bus: number, fade: number): void
+    /** A 3D emitter. `attachSource` binds it to an entity the engine follows every frame;
+     *  `setSourcePosition` places an unbound one (playAt). */
+    createSource(): number
+    attachSource(sourceId: number, entityId: number): void
+    /** [minDistance, maxDistance, rolloff (0 none 1 inverse 2 linear 3 exp), coneInnerDeg,
+     *  coneOuterDeg, coneOuterGain, doppler, spread, occlusion (0/1), bus]. */
+    setSourceParams(sourceId: number, params: Float32Array): void
+    setSourcePosition(sourceId: number, x: number, y: number, z: number): void
+    stopSource(sourceId: number, fade: number): void
+    sourceVoices(sourceId: number): number
+    destroySource(sourceId: number): void
+    /** The listener entity; 0 = the active scene camera (the default). */
+    setListener(entityId: number): void
+    setListenerOptions(dopplerFactor: number): void
+    /** HRTF binaural rendering for the `maxVoices` nearest spatial voices (headphones); the rest keep panning. */
+    setHrtf(enabled: boolean, maxVoices: number): void
+    /** Whether the engine's time scale (Time.scale) also pitches the sfx bus. Default false (pause = mute only). */
+    setTimeScalePitch(enabled: boolean): void
+    /** → a voice token (0 = nothing played: the pool refused, the clip is not ready). bus -1 = the
+     *  source's bus (sfx for 2D). pan is 2D only. */
+    play(clipId: number, sourceId: number, bus: number, volume: number, pitch: number, loop: boolean, priority: number, fadeIn: number, startAt: number, pan: number): number
+    setVoiceVolume(token: number, volume: number): void
+    setVoicePitch(token: number, pitch: number): void
+    setVoicePan(token: number, pan: number): void
+    stopVoice(token: number, fade: number): void
+    voicePlaying(token: number): boolean
+    voiceTime(token: number): number
+    /** THE ended listener (single slot per JS world): called once per tick with the tokens of the
+     *  voices that ended since the previous tick — natural end, stop, steal. */
+    setOnEnded(callback: ((tokens: Float32Array) => void) | null): void
+    stopAll(fade: number): void
+    /** A reverb volume: shape 0 box (dims = full size) / 1 sphere (dims[0] = diameter), in the
+     *  entity's local units; `blend` metres of crossfade inside the border; reverb params as for
+     *  setBusEffect kind 1. The listener inside blends the zone's reverb onto `bus`. */
+    createZone(): number
+    attachZone(zoneId: number, entityId: number): void
+    setZone(zoneId: number, shape: number, dims: Float32Array, blend: number, bus: number, reverb: Float32Array): void
+    destroyZone(zoneId: number): void
+    /** [voicesPlaying, voicesMono, voicesStereo, stolen, clips, clipBytes, peak, sampleRate, listenerZone, zoneBlend, hrtfVoices]. */
+    stats(): Float32Array
+  }
+
+  // ---- 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", …).
+    // An image "src" (here and at creation) is a url string, { _id } (a host buffer), { svg },
+    // { canvasSurface } (a baked Canvas), or { scene2d: sceneId } — a LIVE 2D scene the host draws
+    // into the node's laid-out box every frame with the scene's own camera (native: c2dDrawSceneGL
+    // into a per-node framebuffer; no intrinsic size, the scene needs no openScene). The engine's
+    // simulation must still step each frame for it (native: c2dTick when nothing is presented).
+    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 seven 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
+    /** List a directory (added 2026-09-11, same optional set). Settles with an array of entries —
+     *  `name` = basename, `path` = relative to the listed directory with `/` separators (equals
+     *  `name` unless `recursive`), `kind`, `size` in bytes (0 for a directory), `modified` in ms
+     *  since the epoch — SORTED by `path`, so two runs and two hosts agree. Symlinks are followed
+     *  for `kind`; anything that is neither file nor directory is skipped. A MISSING directory is a
+     *  null result (like the readers); a path that is a file, or an unreadable directory, rejects. */
+    listLocal?(path: string, recursive: boolean, onComplete: (entries: { name: string; path: string; kind: "file" | "dir"; size: number; modified: number }[] | null) => void, onReject: (err: Error) => void): void
+    /** One entry's metadata (`name`, `kind`, `size`, `modified` — see `listLocal`) for a file or a
+     *  directory, or null when there is nothing at `path`. */
+    statLocal?(path: string, onComplete: (entry: { name: string; kind: "file" | "dir"; size: number; modified: number } | null) => 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,
+     *  8 PointerOnUI (0/1: the primary pointer went DOWN on something the UI claimed — an
+     *  interactive node, a scrollable, an editable, a modal backdrop — and is still held; stays 1
+     *  wherever the cursor goes until the release, so a drag that started on a HUD control never
+     *  becomes camera look; always 0 while pointer-locked and for touch-only hosts without a UI claim);
+     *  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 {}