lecodes-sdk 1.2.0 → 2.0.1

package/src/bridges/2d.d.ts

@@ -0,0 +1,317 @@
+// The 2D engine bridge (`_creator2d`): engines/2d (sokol + Box2D).
+// Part of the host contract: every runtime implements this global (runtime/native in C++, the web
+// runtimes in TS). Types are the PRECISE ones the native side reads (see ./types.d.ts); the SDK
+// only sees numbers. The ABI checker (scripts/check-pkg-bridges.mjs) reads this folder.
+import type { bytes, f32, f64, i32, u32 } from "./types"
+
+declare global {
+  // ---- 2D engine (sokol / creator-2d) ----------------------------------------------------------
+  // A 2D-only project loads ONLY creator2d.wasm — never Filament.
+  /** @engine 2d */
+  var _creator2d: {
+    backend: string
+    /** @c creator2dVersion */
+    version(): i32
+    /** @c c2dRender */
+    render(nowMs: f32): void
+    /** @custom */
+    onUpdate(cb: (dt: number) => void): void
+    /** @custom */
+    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).
+    /** @custom */
+    setEarlyUpdate(cb: (dt: number) => void): void
+    /** @custom */
+    setLateUpdate(cb: (dt: number) => void): void
+    /** Clock multiplier for the 2D physics step + sprite animations (see `_creator.setTimeScale`). @c c2dSetTimeScale */
+    setTimeScale?(scale: f64): void
+    /** @custom */
+    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.
+    /** @custom */
+    setOnPointer(cb: (phase: number, pointerId: number, x: number, y: number) => void): void
+    /** @c c2dSetClearColor */
+    setClearColor(r: f32, g: f32, b: f32, a: f32): void
+
+    /** @c c2dCreateScene @custom web */
+    createScene(): i32
+    /** @c c2dDestroyScene @custom web */
+    destroyScene(sceneId: i32): void
+    /** @c c2dOpenScene @custom */
+    openScene(sceneId: i32): void
+    /** @c c2dCloseScene @custom */
+    closeScene(): void
+    /** @c c2dSceneSetClearColor */
+    sceneSetClearColor(sceneId: i32, r: f32, g: f32, b: f32, a: f32): void
+    /** @c c2dAddEntityToScene */
+    addEntityToScene(sceneId: i32, entityId: i32): void
+    /** @c c2dRemoveEntityFromScene */
+    removeEntityFromScene(sceneId: i32, entityId: i32): void
+    /** @c c2dSetLayerYSort */
+    setLayerYSort(sceneId: i32, layer: i32, enabled: boolean): void
+
+    /** @c c2dCameraSetPosition */
+    cameraSetPosition(sceneId: i32, x: f32, y: f32): void
+    /** @c c2dCameraSetZoom @custom web */
+    cameraSetZoom(sceneId: i32, zoom: f32): void
+    /** @c c2dCameraSetRotation */
+    cameraSetRotation(sceneId: i32, deg: f32): void
+    /** @c c2dCameraScreenToWorld @out 2 @custom web */
+    cameraScreenToWorld(sceneId: i32, sx: f32, sy: f32): Float32Array
+    /** @c c2dCameraWorldToScreen @out 2 @custom web */
+    cameraWorldToScreen(sceneId: i32, wx: f32, wy: f32): Float32Array
+
+    /** An OWNED root (owned.h): loose and dropped → its whole subtree goes. @c c2dCreateEntity @owned Entity2d */
+    createEntity(): Handle
+    /** The subtree, its records, and the SDK hears the ids (the freed channel). @custom */
+    destroyEntity(entityId: i32): void
+    /** True while the engine holds the entity (a parent, a scene). @c c2dEntityIsOwned */
+    entityIsOwned(entityId: i32): boolean
+    /** @c c2dSetPosition */
+    setPosition(entityId: i32, x: f32, y: f32): void
+    /** @c c2dSetRotation */
+    setRotation(entityId: i32, deg: f32): void
+    /** @c c2dSetScale */
+    setScale(entityId: i32, sx: f32, sy: f32): void
+    /** @c c2dSetLayer */
+    setLayer(entityId: i32, layer: i32): void
+    /** @c c2dSetZ */
+    setZ(entityId: i32, z: f32): void
+    /** @c c2dSetVisible */
+    setVisible(entityId: i32, visible: boolean): void
+    /** @c c2dGetPosition @out 2 */
+    getPosition(entityId: i32): Float32Array
+
+    /** @c c2dSetParent */
+    setParent(childId: i32, parentId: i32, keepWorld: boolean): void
+    /** @c c2dGetParent */
+    getParent(entityId: i32): i32
+    /** @c c2dGetChildCount */
+    getChildCount(entityId: i32): i32
+    /** @c c2dGetChild */
+    getChild(entityId: i32, index: i32): i32
+    /** @c c2dGetWorldPosition @out 2 */
+    getWorldPosition(entityId: i32): Float32Array
+    /** @c c2dGetWorldMatrix @out 6 */
+    getWorldMatrix(entityId: i32): Float32Array
+    /** @c c2dWorldToLocal @out 2 */
+    worldToLocal(entityId: i32, wx: f32, wy: f32): Float32Array
+    /** @c c2dLocalToWorld @out 2 */
+    localToWorld(entityId: i32, lx: f32, ly: f32): Float32Array
+    /** @c c2dGetLocalTransform @out 5 */
+    getLocalTransform(entityId: i32): Float32Array
+
+    /** @c c2dSetSprite */
+    setSprite(entityId: i32, textureId: i32): void
+    /** @c c2dSetSpriteFrame */
+    setSpriteFrame(entityId: i32, u0: f32, v0: f32, u1: f32, v1: f32): void
+    /** @c c2dSetSpriteFramePx */
+    setSpriteFramePx(entityId: i32, px: f32, py: f32, pw: f32, ph: f32): void
+    /** @c c2dSetSpriteSize */
+    setSpriteSize(entityId: i32, w: f32, h: f32): void
+    /** @c c2dSetSpriteAnchor */
+    setSpriteAnchor(entityId: i32, ax: f32, ay: f32): void
+    /** @c c2dSetSpriteColor */
+    setSpriteColor(entityId: i32, r: f32, g: f32, b: f32): void
+    /** @c c2dSetSpriteOpacity */
+    setSpriteOpacity(entityId: i32, a: f32): void
+    /** @c c2dSetSpriteFlip */
+    setSpriteFlip(entityId: i32, flipX: boolean, flipY: boolean): void
+
+    /** @custom */
+    createTexture(systemId: bytes, onComplete: (texId: number, w: number, h: number) => void, onReject: (e: any) => void): void
+    /** @c c2dGetTextureWidth */
+    getTextureWidth(texId: i32): i32
+    /** @c c2dGetTextureHeight */
+    getTextureHeight(texId: i32): i32
+    /** @c c2dDestroyTexture */
+    destroyTexture(texId: i32): void
+    /** @c c2dSetDefaultFilter */
+    setDefaultFilter(linear: boolean): void
+
+    // Textures from a _creatorCanvas surface (RGBA8, already rasterized — no decode, so synchronous).
+    // See ./canvas.d.ts.
+    /** @custom */
+    createTextureFromCanvas(surfaceId: i32): i32
+    /** @custom */
+    updateTextureFromCanvas(texId: i32, surfaceId: i32): void
+
+    /** @c c2dDefineAnimation @count frameCount=frames/4 */
+    defineAnimation(entityId: i32, frames: Float32Array, fps: f32, loop: boolean): i32
+    /** @c c2dPlayAnimation */
+    playAnimation(entityId: i32, clipId: i32): void
+    /** @c c2dStopAnimation */
+    stopAnimation(entityId: i32): void
+    /** @c c2dSetAnimationSpeed */
+    setAnimationSpeed(entityId: i32, speed: f32): void
+    /** @c c2dGetAnimationFrame */
+    getAnimationFrame(entityId: i32): i32
+
+    /** @c c2dCreateTilemap */
+    createTilemap(textureId: i32, cols: i32, rows: i32, tileW: f32, tileH: f32, atlasCols: i32, atlasRows: i32, data: Int32Array): i32
+    /** @c c2dSetTile */
+    setTile(tilemapId: i32, x: i32, y: i32, index: i32): void
+
+    /** @c c2dBulkSetPositions */
+    bulkSetPositions(ids: Uint32Array, xy: Float32Array, count: i32): 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.
+    /** @c c2dPhysicsHasSupport */
+    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). @c c2dPhysicsConfigure */
+    physicsConfigure(gx: f32, gy: f32, pixelsPerMeter: f32, subStepCount: i32): void
+    /** @c c2dSetInterpolation */
+    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.) @custom */
+    setOnPhysicsEvent(cb: (entityA: number, entityB: number, type: number, px: number, py: number, nx: number, ny: number, speed: number) => void): void
+    /** @c c2dPhysicsCreateBody */
+    physicsCreateBody(entityId: i32, motionType: i32): i32
+    /** @c c2dPhysicsRemoveBody */
+    physicsRemoveBody(bodyHandle: i32): 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".
+    /** @c c2dPhysicsAddBox */
+    physicsAddBox(bodyHandle: i32, hw: f32, hh: f32, ox: f32, oy: f32, friction: f32, bounce: f32, isSensor: boolean, category: u32, mask: u32): void
+    /** @c c2dPhysicsAddCircle */
+    physicsAddCircle(bodyHandle: i32, radius: f32, ox: f32, oy: f32, friction: f32, bounce: f32, isSensor: boolean, category: u32, mask: u32): void
+    /** @c c2dPhysicsAddCapsule */
+    physicsAddCapsule(bodyHandle: i32, x1: f32, y1: f32, x2: f32, y2: f32, radius: f32, friction: f32, bounce: f32, isSensor: boolean, category: u32, mask: u32): void
+    /** @c c2dPhysicsAddSegment */
+    physicsAddSegment(bodyHandle: i32, x1: f32, y1: f32, x2: f32, y2: f32, friction: f32, bounce: f32, category: u32, mask: u32): void
+    /** @c c2dPhysicsAddPolygon */
+    physicsAddPolygon(bodyHandle: i32, pts: Float32Array, count: i32, friction: f32, bounce: f32, isSensor: boolean, category: u32, mask: u32): 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. @c c2dPhysicsAddChain */
+    physicsAddChain(bodyHandle: i32, pts: Float32Array, count: i32, isLoop: boolean, friction: f32, bounce: f32, category: u32, mask: u32): void
+    /** Destroy every shape on a body, keeping the body (id, transform, velocity) — the first half of a
+     *  live collider rebuild. @c c2dPhysicsClearShapes */
+    physicsClearShapes(bodyHandle: i32): 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. @c c2dPhysicsSetContactEvents */
+    physicsSetContactEvents(bodyHandle: i32, enabled: boolean): void
+    /** @c c2dPhysicsSetLinearVelocity */
+    physicsSetLinearVelocity(bodyHandle: i32, x: f32, y: f32): void
+    /** @c c2dPhysicsGetLinearVelocity @out 2 */
+    physicsGetLinearVelocity(bodyHandle: i32): Float32Array
+    /** @c c2dPhysicsSetAngularVelocity */
+    physicsSetAngularVelocity(bodyHandle: i32, degPerSec: f32): void
+    /** @c c2dPhysicsGetAngularVelocity */
+    physicsGetAngularVelocity(bodyHandle: i32): f64
+    /** @c c2dPhysicsApplyLinearImpulse */
+    physicsApplyLinearImpulse(bodyHandle: i32, x: f32, y: f32): void
+    /** Impulse at a WORLD point — the lever arm becomes angular impulse (a central impulse never
+     *  spins a body). Mirrors 3D physicsApplyImpulseAt. @c c2dPhysicsApplyImpulseAt */
+    physicsApplyImpulseAt(bodyHandle: i32, x: f32, y: f32, px: f32, py: f32): void
+    /** @c c2dPhysicsApplyForce */
+    physicsApplyForce(bodyHandle: i32, x: f32, y: f32): 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. @c c2dPhysicsSetFromEntity */
+    physicsSetFromEntity(bodyHandle: i32): void
+    /** @c c2dPhysicsSetFixedRotation */
+    physicsSetFixedRotation(bodyHandle: i32, enabled: boolean): void
+    /** @c c2dPhysicsSetGravityScale */
+    physicsSetGravityScale(bodyHandle: i32, scale: f32): void
+    /** @c c2dPhysicsSetLinearDamping */
+    physicsSetLinearDamping(bodyHandle: i32, damping: f32): void
+    /** @c c2dPhysicsSetAngularDamping */
+    physicsSetAngularDamping(bodyHandle: i32, damping: f32): void
+    /** @c c2dPhysicsSetBullet */
+    physicsSetBullet(bodyHandle: i32, enabled: boolean): void
+    /** @c c2dPhysicsSetEnabled */
+    physicsSetEnabled(bodyHandle: i32, enabled: boolean): void
+    /** @c c2dPhysicsSetAwake */
+    physicsSetAwake(bodyHandle: i32, awake: boolean): void
+    /** Scales the shape-derived mass data, so the rotational inertia keeps its ratio. <= 0 restores
+     *  the area-derived default. @c c2dPhysicsSetMass */
+    physicsSetMass(bodyHandle: i32, mass: f32): void
+    /** @c c2dPhysicsGetMass */
+    physicsGetMass(bodyHandle: i32): f64
+    /** @c c2dPhysicsSetMotionType */
+    physicsSetMotionType(bodyHandle: i32, motionType: i32): void
+    /** @c c2dPhysicsSetFriction */
+    physicsSetFriction(bodyHandle: i32, friction: f32): void
+    /** @c c2dPhysicsSetBounce */
+    physicsSetBounce(bodyHandle: i32, bounce: f32): void
+    /** @c c2dPhysicsSetFilter */
+    physicsSetFilter(bodyHandle: i32, category: u32, mask: u32): 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.
+    /** @c c2dPhysicsRaycastClosest @out 7 */
+    physicsRaycastClosest(x0: f32, y0: f32, x1: f32, y1: f32, mask: u32, ignore: Float32Array, ignoreCount: i32): Float32Array
+    /** All hits along the segment, nearest first: maxHits records of [entityId, px, py, nx, ny, fraction]. @c c2dPhysicsRaycastAll @out maxHits*6 */
+    physicsRaycastAll(x0: f32, y0: f32, x1: f32, y1: f32, mask: u32, ignore: Float32Array, ignoreCount: i32, maxHits: i32): 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. @c c2dPhysicsOverlap @out maxHits*1 */
+    physicsOverlap(pts: Float32Array, count: i32, radius: f32, mask: u32, ignore: Float32Array, ignoreCount: i32, maxHits: i32): Float32Array
+    /** Topmost by DRAW order (layer, then z) — not whatever the broadphase hands back first. @c c2dPhysicsOverlapPoint */
+    physicsOverlapPoint(x: f32, y: f32, mask: u32, ignore: Float32Array, ignoreCount: i32): i32
+    // 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.
+    /** @c c2dCharacterCreate */
+    characterCreate(entityId: i32, x1: f32, y1: f32, x2: f32, y2: f32, radius: f32, maxSlopeDeg: f32, category: u32, mask: u32): i32
+    /** @c c2dCharacterDestroy */
+    characterDestroy(charId: i32): void
+    /** The HORIZONTAL command, world units/s — a per-frame command that EXPIRES once a step consumes it. @c c2dCharacterMove */
+    characterMove(charId: i32, x: f32): void
+    /** Free mode (gravityScale 0): both axes as one expiring command. @c c2dCharacterMoveFree */
+    characterMoveFree(charId: i32, x: f32, y: f32): void
+    /** @c c2dCharacterSetVerticalVelocity */
+    characterSetVerticalVelocity(charId: i32, vy: f32): void
+    /** LATCH the whole velocity — it persists until a characterMove takes the axis back. @c c2dCharacterSetVelocity */
+    characterSetVelocity(charId: i32, x: f32, y: f32): void
+    /** @c c2dCharacterSetGravityScale */
+    characterSetGravityScale(charId: i32, scale: f32): void
+    /** @c c2dCharacterSetMaxSlope */
+    characterSetMaxSlope(charId: i32, maxSlopeDeg: f32): void
+    /** @c c2dCharacterSetFilter */
+    characterSetFilter(charId: i32, category: u32, mask: u32): void
+    /** Ignore this entity's one-way surfaces (0 = none) — dropping through a semisolid platform. @c c2dCharacterSetDropThrough */
+    characterSetDropThrough(charId: i32, entityId: i32): 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. @c c2dCharacterSetCapsule */
+    characterSetCapsule(charId: i32, x1: f32, y1: f32, x2: f32, y2: f32, radius: f32): boolean
+    /** Teleport to the entity's world transform (how node.position reaches a character). Drops fall speed. @c c2dCharacterSetFromEntity */
+    characterSetFromEntity(charId: i32): void
+    /** out8 = [velX, velY, groundState (0 ground / 1 slope / 2 air), normalX, normalY, groundEntity,
+     *  collisionCount, 0]. The velocity is MEASURED, not commanded. @c c2dCharacterGetState */
+    characterGetState(charId: i32, out: Float32Array): void
+    /** maxN records of [entityId, normalX, normalY] — what the mover pushed out of this step. @c c2dCharacterGetCollisions @out maxN*3 */
+    characterGetCollisions(charId: i32, maxN: i32): 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. @c c2dPhysicsSetOneWay */
+    physicsSetOneWay(bodyHandle: i32, nx: f32, ny: f32, arcDeg: f32, enabled: boolean): void
+    /** @c c2dPickSprite */
+    pickSprite(sceneId: i32, wx: f32, wy: f32): i32
+  }
+}
+
+/** The 2D HOST's side of the contract (`HostScene2d` of creator-pkg/host.gen.h): the engine renders
+ *  through a GL context / device the HOST owns and composites, so the host learns when a 2D scene
+ *  opens and closes (bring up / tear down its render target, start / stop compositing) and may take
+ *  over the engine's GPU setup. OPTIONAL as a whole; every slot optional.
+ *  @host scene2d HostScene2d @optional */
+export interface HostScene2d {
+  /** scene.open(): create the 2D render target lazily, start compositing. */
+  open2DScene?(sceneId: i32): void
+  close2DScene?(): void
+  /** The engine's GPU setup (sg_setup) instead of the default c2dInit(): a host with device handles to
+   *  pass (the desktop Vulkan host, c2dInitVulkan) does it here and leaves the engine initialised. */
+  init2D?(): void
+}
+
+export {}

package/src/bridges/app.d.ts

@@ -0,0 +1,91 @@
+// The app bridge (`_creatorApp`): the app's own world (run / restart / quit) and its lifecycle.
+// Part of the host contract: every runtime implements this global (runtime/native in C++, the web
+// runtimes in TS). Types are the PRECISE ones the native side reads (see ./types.d.ts); the SDK
+// only sees numbers. The ABI checker (scripts/check-pkg-bridges.mjs) reads this folder.
+//
+// A HOST bridge (`@host`): unlike an engine bridge, whose C functions live in an engine header, the
+// native side of these methods is a table of functions the HOST fills in — `HostApp` in
+// runtime/native/include/creator-pkg/host.gen.h, generated from this file by scripts/gen-bridges.ts.
+// A method without a tag is a slot of that table (the JS wrapper is generated); `@custom` methods are
+// the runtime's own (world control, the listener slot) and live in runtime/native/src/host/app.cpp.
+// `?` on a method = an optional slot: a host that leaves it null gets no such JS method, so the SDK's
+// `typeof` feature-detects stay honest. The `HostApp` interface below adds the slots the runtime
+// calls that JS never sees (notifications to the host).
+import type { bytes } from "./types"
+
+declare global {
+  // ---- 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).
+  /** @host app */
+  var _creatorApp: {
+    /** 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. @custom */
+    run(systemId: bytes, onReject: (err: string) => 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. @custom */
+    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 `exit` slot fires instead (Android backgrounds the task; hosts that can't
+     *  exit programmatically, iOS/desktop, leave it null and the call is a no-op). @custom */
+    quit?(): void
+    /** 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.
+     *  Runtime-owned: the host seeds it with `setLaunchUrl` and run/restart carry it. @custom */
+    launchUrl?(): string | null
+
+    // ---- 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 runtime
+     *  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). The host pushes with `emitAppEvent`. @custom */
+    registerEvent?(callback: (event: string, data?: string) => void): void
+    /** The freed channel (owned handles, docs/plans/hosts-unification-plan.md phase 10): ONE function per
+     *  world that hears `(kind, ids)` — OWNED_KIND_* of ui/tree.ts — when a subtree free took
+     *  resources under other wrappers (a 3D / 2D root destroyed or dropped: its descendants). The
+     *  SDK's core/pins.ts unpins them and marks the wrappers dead. @custom */
+    setFreedEmitter(callback: (kind: number, ids: number[]) => void): void
+    /** Collect garbage, drain the release queue and report the live owned records per kind
+     *  (`{"live":{"tree":n,…},"pending":n}`) — the read behind checks/owned. @custom */
+    ownedStats(): string
+    /** Current lifecycle state: "active" | "background". Surfaced as app.state. */
+    state?(): string
+    /** 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
+  }
+}
+
+/** The slots of `HostApp` the runtime calls and JS never sees. */
+export interface HostApp {
+  /** Fired whenever the current world's (identity, trust) changes: BEFORE the new bundle evaluates,
+   *  and again with the restored values if the evaluation throws — so a host cache consulted from a
+   *  synchronous host call (a push registration during the world's top-level code) is always
+   *  current. `projectUuid` is null for an unattributed world. JS thread. */
+  worldChange?(projectUuid: string | null, trusted: boolean): void
+  /** `quit()` called from the boot world — no caller world to return to, so the host decides what
+   *  "leave the app" means (the Android SDK backgrounds the task). JS thread. */
+  exit?(): void
+}
+
+export {}

package/src/bridges/audio.d.ts

@@ -0,0 +1,97 @@
+// The audio bridge (`_creatorAudio`): engines/audio (miniaudio).
+// Part of the host contract: every runtime implements this global (runtime/native in C++, the web
+// runtimes in TS). Types are the PRECISE ones the native side reads (see ./types.d.ts); the SDK
+// only sees numbers. The ABI checker (scripts/check-pkg-bridges.mjs) reads this folder.
+import type { bytes, f32, f64, i32, u32 } from "./types"
+
+declare global {
+  // ---- 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).
+  /** @engine audio */
+  var _creatorAudio: {
+    /** @guard audioEnsureEngine @c caudHasSupport */
+    hasSupport(): boolean
+    /** Decode the bytes behind a fetch system id (WAV / MP3 / OGG Vorbis) on the engine's
+     *  loader thread; mono unless `stereo`. onDone(clipId, durationSeconds, channels). @custom */
+    loadClip(systemId: bytes, stereo: boolean, onDone: (clipId: number, duration: number, channels: number) => void, onReject: (message: string) => void): void
+    /** @c caudClipRelease */
+    releaseClip(clipId: u32): void
+    /** Bus id by name (-1 unknown); 0 master, 1 sfx, 2 music, 3 ui, 4 voice. @c caudBusId */
+    busId(name: string): i32
+    /** Creates (or finds) an app-defined bus under master. -1 when the 16 slots are full. @c caudBusCreate */
+    createBus(name: string): i32
+    /** @c caudBusSetVolume */
+    setBusVolume(bus: i32, volume: f32): void
+    /** @c caudBusSetMuted */
+    setBusMuted(bus: i32, 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. @c caudBusSetEffect */
+    setBusEffect(bus: i32, kind: i32, params: Float32Array): void
+    /** @c caudBusStopAll */
+    stopBus(bus: i32, fade: f32): void
+    /** A 3D emitter. `attachSource` binds it to an entity the engine follows every frame;
+     *  `setSourcePosition` places an unbound one (playAt). @guard audioEnsureEngine @c caudSourceCreate */
+    createSource(): u32
+    /** @c gl:audioAttachSource */
+    attachSource(sourceId: u32, entityId: u32): void
+    /** [minDistance, maxDistance, rolloff (0 none 1 inverse 2 linear 3 exp), coneInnerDeg,
+     *  coneOuterDeg, coneOuterGain, doppler, spread, occlusion (0/1), bus]. @c caudSourceSetParams */
+    setSourceParams(sourceId: u32, params: Float32Array): void
+    /** @c caudSourceSetPose @pack x 3 @rest nullptr */
+    setSourcePosition(sourceId: u32, x: f32, y: f32, z: f32): void
+    /** @c caudSourceStopAll */
+    stopSource(sourceId: u32, fade: f32): void
+    /** @c caudSourceVoices */
+    sourceVoices(sourceId: u32): i32
+    /** @c gl:audioDetachSource, caudSourceDestroy */
+    destroySource(sourceId: u32): void
+    /** The listener entity; 0 = the active scene camera (the default). @c gl:audioSetListener */
+    setListener(entityId: u32): void
+    /** @c caudListenerSetDoppler */
+    setListenerOptions(dopplerFactor: f32): void
+    /** HRTF binaural rendering for the `maxVoices` nearest spatial voices (headphones); the rest keep panning. @guard audioEnsureEngine @c caudSetHrtf */
+    setHrtf(enabled: boolean, maxVoices: i32): void
+    /** Whether the engine's time scale (Time.scale) also pitches the sfx bus. Default false (pause = mute only). @guard audioEnsureEngine @c caudSetTimeScalePitch */
+    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. @c caudPlay @pack bus CaudPlay */
+    play(clipId: u32, sourceId: u32, bus: i32, volume: f32, pitch: f32, loop: boolean, priority: i32, fadeIn: f32, startAt: f32, pan: f32): u32
+    /** @c caudVoiceSetVolume */
+    setVoiceVolume(token: u32, volume: f32): void
+    /** @c caudVoiceSetPitch */
+    setVoicePitch(token: u32, pitch: f32): void
+    /** @c caudVoiceSetPan */
+    setVoicePan(token: u32, pan: f32): void
+    /** @c caudVoiceStop */
+    stopVoice(token: u32, fade: f32): void
+    /** @c caudVoicePlaying */
+    voicePlaying(token: u32): boolean
+    /** @c caudVoiceTime */
+    voiceTime(token: u32): f64
+    /** 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. @custom */
+    setOnEnded(callback: ((tokens: Float32Array) => void) | null): void
+    /** @c caudStopAll */
+    stopAll(fade: f32): 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`. @guard audioEnsureEngine @c caudZoneCreate */
+    createZone(): u32
+    /** @c gl:audioAttachZone */
+    attachZone(zoneId: u32, entityId: u32): void
+    /** @c caudZoneSet */
+    setZone(zoneId: u32, shape: i32, dims: Float32Array, blend: f32, bus: i32, reverb: Float32Array): void
+    /** @c gl:audioDetachZone, caudZoneDestroy */
+    destroyZone(zoneId: u32): void
+    /** [voicesPlaying, voicesMono, voicesStereo, stolen, clips, clipBytes, peak, sampleRate, listenerZone, zoneBlend, hrtfVoices]. @custom */
+    stats(): Float32Array
+  }
+}
+
+export {}

package/src/bridges/canvas.d.ts

@@ -0,0 +1,79 @@
+// The canvas bridge (`_creatorCanvas`): the 2D canvas surfaces a host paints.
+// Part of the host contract: every runtime implements this global (runtime/native in C++, the web
+// runtimes in TS). Types are the PRECISE ones the native side reads (see ./types.d.ts). A surface is an
+// OWNED resource (docs/owned.md, OwnedKind::Canvas): the creators hand the SDK a Handle, a surface id on
+// the wire is `_h.id`, and the runtime frees the surface once the app dropped the wrapper AND no UI image
+// shows it. The ABI checker (scripts/check-pkg-bridges.mjs) reads this folder.
+//
+// Since phase 12 (docs/canvas.md) the runtime does NOT interpret the opcode stream
+// itself: it links the AnyCanvas core (engines/canvas), which turns the SDK Canvas' opcode stream
+// (spec/ops.h of the pinned submodule — the SDK's consts are generated from it) and SVG markup into
+// ONE resolved draw list (spec/draw.h), and a host PAINTS that list (HostCanvas below). The runtime
+// keeps the surface registry (ids, sizes); the host keeps the pixels.
+import type { bytes, f32, i32, i32out, f32out } from "./types"
+
+declare global {
+  // ---- 2D canvas (core; the AnyCanvas core + a painter per platform) --------------------------
+  // Immediate-mode 2D drawing that bakes to a texture, shared by 2D/3D/UI. The SDK Canvas records a
+  // command buffer (the AnyCanvas opcode stream) and flushes it here once per bake.
+  var _creatorCanvas: {
+    /** Rasterize `cmd` (cmdLen floats) into surface `surfaceId` (0 = create), sized w×h logical @
+     *  `scale` device px. Clears then replays the whole buffer. A Handle when the surface is made now
+     *  (0 in, or an id the registry no longer knows); the same id as a number for a re-bake.
+     *  @owned Canvas */
+    rasterize(surfaceId: i32, w: f32, h: f32, scale: f32,
+              cmd: Float32Array, cmdLen: i32, refs: string[]): Handle | i32
+    // [width, ascent, descent] in logical px for `text` in the CSS `font`, measured on this platform.
+    measureText(text: string, font: string): Float32Array
+    /** Copy surface `surfaceId`'s pixels into a NEW standalone surface; its Handle, or null without a
+     *  painter (or for an unknown source). Backs Canvas.toBitmap() — an immutable snapshot the source
+     *  canvas can no longer touch. @owned Canvas */
+    snapshot(surfaceId: i32): Handle | null
+    /** 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` (the core draws it, the
+     *  host paints it); otherwise decode the encoded image bytes in host buffer `bufferId` (an SVG file
+     *  is detected and drawn the same way). Delivers (surface, width, height) in device px to
+     *  onComplete, or calls onReject on failure. @owned Canvas (the surface) */
+    loadImage(svg: string, bufferId: bytes,
+              onComplete: (surface: Handle, 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: i32, type: string, onComplete: (bufferId: number, size: number) => void, onReject: () => void): void
+    // Free a surface NOW (Canvas / Bitmap destroy(): the explicit early free), even while an image shows it.
+    destroySurface(surfaceId: i32): void
+    // The deterministic JSON of the draw list a surface was last painted with (the AnyCanvas dump:
+    // checks/canvas hashes it, debugging reads it); "" for an unknown surface.
+    debugDrawList(surfaceId: i32): string
+  }
+}
+
+/** The PAINTER's side of the contract — the table the runtime's `_creatorCanvas` bridge calls after the
+ *  AnyCanvas core produced a draw list (`HostCanvas` of creator-pkg/host.gen.h). Every call is synchronous
+ *  on the JS thread. OPTIONAL as a whole: a host without a backend (the windowless server, a UI-only
+ *  build) leaves the pointer null — every op is then a no-op and a baked texture is 0. Desktop / Quest:
+ *  the tgfx painter (engines/canvas/painters/tgfx); Android: the Kotlin painter (painters/android);
+ *  web / headless: painters/web. Surface ids come from the runtime's registry; a host creates the
+ *  pixels on the first `paint` / `decodeImage` of an id and frees them on `releaseSurface`.
+ *  @host canvas HostCanvas @optional */
+export interface HostCanvas {
+  /** Paint the draw list `words` + `strings` (engines/canvas/spec/draw.h; already in device px) into
+   *  surface `surfaceId`, which is pw×ph device px at `scale` device px per logical unit: create or
+   *  resize the surface as needed, clear it, replay the list. */
+  paint(surfaceId: i32, pw: i32, ph: i32, scale: f32, words: Float32Array, strings: string[]): void
+  /** Metrics of `text` in the resolved font (family, px size, weight 100..900, italic) on THIS platform
+   *  → out[3] = width, ascent, descent (logical px, both positive). The same font resolution the
+   *  painter uses for a text command. @outSize out 3 */
+  measureText(text: string, family: string, size: f32, weight: i32, italic: boolean, out: f32out): void
+  /** Decode the encoded image bytes of host buffer `bufferId` into the NEW surface `surfaceId` (an id
+   *  the runtime reserved); its pixel size to size[2] = w, h. False when the bytes do not decode.
+   *  @outSize size 2 */
+  decodeImage(bufferId: i32, surfaceId: i32, size: i32out): boolean
+  /** A surface's straight-RGBA8 pixels, top row first, w×h device px in size[2] — malloc'd, the
+   *  runtime frees them (the engines' createTextureFromCanvas, `toFile`, `snapshot`). Null for an
+   *  unknown surface. @outSize size 2 */
+  readPixels(surfaceId: i32, size: i32out): Uint8Array | null
+  /** Free a surface's pixels (the runtime dropped the id). */
+  releaseSurface(surfaceId: i32): void
+}
+
+export {}