lecodes-sdk 0.19.0

package/src/runtime/device.ts

@@ -0,0 +1,293 @@
+// Platform info + the host resize event. The resize listener registers with the host lazily on the
+// first subscription (no top-level side effect, so tree-shaking can drop this entirely if unused).
+
+import { Quat } from "../math/quat"
+import { Vec3 } from "../math/vec"
+import { appEventsOn, appEventsOff } from "./appEvents"
+
+type ResizeCallback = (width: number, height: number) => void
+
+type HdrChangeCallback = (headroom: number) => void
+
+type DeviceEventMap = {
+  resize: ResizeCallback
+  /** Connectivity came back (best-effort, navigator.onLine semantics). */
+  online: () => void
+  /** Connectivity was lost. */
+  offline: () => void
+  /** The headroom the 3D engine renders to moved (`device.hdr.headroom`): the display ramped up to
+   *  its peak after launch, brightness changed, the window went to another screen. */
+  hdrchange: HdrChangeCallback
+}
+
+const resizeListeners: ResizeCallback[] = []
+let resizeRegistered = false
+
+const onResize = (width: number, height: number): void => {
+  for (const cb of resizeListeners.slice()) cb(width, height)
+}
+
+// --- device.hdr state ---
+// The 3D bridge is a free global that a 2D-only bundle never defines — reach it defensively. Hosts
+// without the methods are SDR by definition; the look setters are remembered so the getters read
+// back what the app asked for.
+const gl = (): typeof _creator | undefined => (typeof _creator !== "undefined" ? _creator : undefined)
+let hdrStrengthLocal = 0.35
+let hdrPaperWhiteLocal = 1
+// `hdrchange` is a poll: the engine quantises the headroom to half-stops, so a change is rare and
+// a 4 Hz timer (only while someone listens) is cheaper than a per-frame bridge call.
+const hdrListeners: HdrChangeCallback[] = []
+let hdrPollTimer: ReturnType<typeof setInterval> | undefined
+let hdrLastHeadroom = 1
+const pollHdr = (): void => {
+  const h = device.hdr.headroom
+  if (h === hdrLastHeadroom) return
+  hdrLastHeadroom = h
+  for (const cb of hdrListeners.slice()) cb(h)
+}
+
+/** Semantic haptic styles for `device.vibrate`. Impact styles (`light`/`medium`/`heavy`/`soft`/
+ *  `rigid`) are a physical "tap" of varying weight; notification styles (`success`/`warning`/`error`)
+ *  cue an outcome; `selection` is a light tick for a value change. Chosen to map 1:1 onto iOS
+ *  `UIFeedbackGenerator` and, on Android, `HapticFeedbackConstants` / `VibrationEffect` — so the same
+ *  call feels native everywhere, rather than a duration that only web/Android can honor. */
+export type HapticStyle =
+  | "light" | "medium" | "heavy" | "soft" | "rigid"
+  | "success" | "warning" | "error"
+  | "selection"
+
+/** Options for `device.motion.start`. */
+export interface MotionOptions {
+  /** Sensor update interval in seconds (default 1/60). The sensor fuses at ≥ this rate in the
+   *  background; you poll the freshest sample each frame, so this is a floor, not a sync. */
+  interval?: number
+  /** Frame the readables are delivered in. "world" (default): engine Y-up, screen-oriented — drops
+   *  straight into `camera.quaternion` / any node. "device": the raw sensor frame, no conversion. */
+  frame?: "world" | "device"
+}
+
+// --- device.motion state (pull-per-frame model) ---
+let motionEnabled = false
+let motionFrame: "world" | "device" = "world"
+let motionYawOffset = 0   // radians about world up, captured by recenter()
+
+// Calibration constants — VERIFY ON A PHYSICAL DEVICE (the simulator reports no motion).
+//  • CM_TO_WORLD: Core Motion's reference frame is Z-up; the engine world is Y-up. If a level horizon
+//    reads tilted ~90°, this is the term to check.
+//  • ORIENTATION_ROLL: roll about the view axis so camera-up tracks screen-up, indexed by the native
+//    interface-orientation code [portrait, landscapeLeft, landscapeRight, upsideDown]. If landscape is
+//    upside-down or rolled the wrong way, flip the ±π/2 signs.
+// If the whole panorama turns the wrong way (look right → view goes left), conjugate `raw` below.
+const CM_TO_WORLD = Quat.fromAxisAngle([1, 0, 0], -Math.PI / 2)
+const ORIENTATION_ROLL = [0, Math.PI / 2, -Math.PI / 2, Math.PI]
+
+// Device attitude → engine world frame, with the interface-orientation roll folded in (yaw NOT yet
+// recentered). Shared by `attitude` (which adds the recenter) and `gravity` (which is yaw-invariant).
+const orientedAttitude = (s: ArrayLike<number>): Quat => {
+  const raw = new Quat(s[0], s[1], s[2], s[3])
+  const roll = Quat.fromAxisAngle([0, 0, 1], ORIENTATION_ROLL[s[7]] ?? 0)
+  return CM_TO_WORLD.mul(raw).mul(roll)
+}
+
+export const device = {
+  /** Which INPUT MODEL the app is running under — the thing to branch on when a build needs
+   *  mouse-look instead of on-screen sticks. It is not the OS name: a Mac reports `"desktop"`,
+   *  like Windows and Linux do (the OS/version detail is host-side, not here). */
+  get platform(): "web" | "android" | "ios" | "desktop" | string {
+    return _creatorUtils.platform
+  },
+  get language(): string {
+    return _creatorUtils.language
+  },
+  /** Display device-pixel ratio (physical px per logical/CSS px): 1 on standard displays, 2–3 on
+   *  retina / iOS. Bake a Canvas at this ratio for crisp output without hardcoding, e.g.
+   *  `new Canvas(w, h, { pixelRatio: device.pixelRatio })`. NOTE: the web 2D/GL surface currently
+   *  renders at logical resolution, so on web this only helps UI canvases / is forward-looking for
+   *  2D; on iOS (physical surface) it makes 2D canvases crisp. Falls back to 1 if the host omits it. */
+  get pixelRatio(): number {
+    return _creatorUtils.pixelRatio || 1
+  },
+  /** Current display width in logical px — the same value the "resize" event delivers, but readable at
+   *  any time (not only inside the listener). 0 until the host has reported a size. */
+  get width(): number {
+    return _creatorUI.getDisplaySize?.()?.[0] ?? 0
+  },
+  /** Current display height in logical px — the same value the "resize" event delivers, readable at any
+   *  time. 0 until the host has reported a size. */
+  get height(): number {
+    return _creatorUI.getDisplaySize?.()?.[1] ?? 0
+  },
+  /** Opt into the precise-touch system where the platform supports it. OFF by default. When on, fast
+   *  strokes are sampled at the touch digitizer's full rate (iOS coalesced touches, ≈120–240 Hz) instead
+   *  of once per display frame (~60 Hz), so a pointer-heavy app (drawing, handwriting, dragging) gets more
+   *  points and smoother lines. Leave it off for tap/button UIs. No-op on hosts without a coalesced-input
+   *  concept (web already coalesces pointermove; headless). */
+  setPreciseTouch(enabled: boolean): void {
+    _creatorUtils.setPreciseTouch?.(enabled)
+  },
+  /** Fire a one-shot haptic of the given semantic `style` (default `"medium"`) — a physical tap on
+   *  supported hardware (iOS Taptic Engine, Android vibrator). Chosen by meaning, not duration, so it
+   *  feels native on each platform; see {@link HapticStyle}. Host-gated: a silent no-op where there's
+   *  no haptic hardware (iPad, older iPhones, web, headless). */
+  vibrate(style: HapticStyle = "medium"): void {
+    _creatorUtils.vibrate?.(style)
+  },
+  /** Device-orientation sensor (gyro + accelerometer, fused) for tilt/steering and magic-window /
+   *  360° panoramas. Poll `attitude` / `gravity` inside setLoop; they return the freshest fused
+   *  sample, so the sensor rate need not match your frame rate. Host-gated: a no-op with no sensor. */
+  motion: {
+    /** Whether this device has the motion sensors at all (no gyro → false; iPad/older, web, headless). */
+    get available(): boolean {
+      return _creatorUtils.motionAvailable?.() ?? false
+    },
+    /** Whether updates are currently running (start succeeded and stop hasn't been called). */
+    get enabled(): boolean {
+      return motionEnabled
+    },
+    /** Begin sensor updates. Resolves to whether it actually started (false = no sensor / denied).
+     *  Async so a web host can await its permission prompt; native resolves immediately. */
+    async start(options: MotionOptions = {}): Promise<boolean> {
+      motionFrame = options.frame ?? "world"
+      motionEnabled = !!(await (_creatorUtils.motionStart?.(options.interval ?? 1 / 60) ?? false))
+      return motionEnabled
+    },
+    /** Stop sensor updates and release the sensor (battery). */
+    stop(): void {
+      _creatorUtils.motionStop?.()
+      motionEnabled = false
+    },
+    /** Capture the current heading as "forward" — a yaw-only recenter (pitch/roll stay gravity-
+     *  referenced, so the horizon stays level). No-op in the "device" frame. */
+    recenter(): void {
+      const s = _creatorUtils.getMotionSample?.()
+      if (!s || motionFrame === "device") { motionYawOffset = 0; return }
+      const f = orientedAttitude(s).rotateVec3([0, 0, -1])   // world-space camera forward
+      motionYawOffset = Math.atan2(-f.x, -f.z)               // heading about world up
+    },
+    /** The device's current orientation as a `Quat`. In the "world" frame (default) it's engine Y-up
+     *  and screen-oriented, so `camera.quaternion = device.motion.attitude` is a complete magic-window
+     *  / panorama camera. `Quat.identity` until the first sample arrives / when not running. */
+    get attitude(): Quat {
+      const s = _creatorUtils.getMotionSample?.()
+      if (!s) return Quat.identity
+      if (motionFrame === "device") return new Quat(s[0], s[1], s[2], s[3])
+      const q = orientedAttitude(s)
+      return Quat.fromAxisAngle([0, 1, 0], -motionYawOffset).mul(q)   // yaw recenter (world-frame)
+    },
+    /** Gravity direction for tilt controls. In the "world" frame it's SCREEN space (x → right, y →
+     *  down, matching clientX/clientY), orientation-aware — a 2D game reads `gravity.x / gravity.y`.
+     *  `(0,0,0)` when not running. */
+    get gravity(): Vec3 {
+      const s = _creatorUtils.getMotionSample?.()
+      if (!s) return new Vec3(0, 0, 0)
+      if (motionFrame === "device") return new Vec3(s[4], s[5], s[6])
+      // Re-express the raw device-frame gravity in screen space: undo the interface roll (about the
+      // screen normal), then flip Y to screen-down. Uses the unambiguous CMDeviceMotion.gravity, so
+      // it stays correct regardless of the attitude-quaternion convention above.
+      const unroll = Quat.fromAxisAngle([0, 0, 1], -(ORIENTATION_ROLL[s[7]] ?? 0))
+      const g = new Vec3(s[4], s[5], s[6]).rotate(unroll)
+      return new Vec3(g.x, -g.y, g.z)
+    },
+  },
+  /** The display's extended dynamic range — HDR. On a screen with headroom above SDR white (Apple's
+   *  XDR panels; the macOS host today) the 3D surface is float and the engine renders past 1.0:
+   *  1.0 is the white of the UI and of a diffuse white surface, and the sun, emissives and speculars
+   *  climb up to `headroom` times that. Everywhere else it is SDR: `available` false, `headroom` 1,
+   *  the look setters remembered but invisible.
+   *
+   *  Branch content on `available`, not on `headroom` — the live value ramps up from 1 over the
+   *  first seconds after launch and follows the brightness keys. Particle `emissive` is the thing
+   *  to raise: it is in post-exposure units (1 = white on screen) and everything above that clips on
+   *  SDR, so an HDR display is the only place a fireball peaking at 8 reads as one. */
+  hdr: {
+    /** Whether the surface can show anything above SDR white at all (`maxHeadroom > 1`). */
+    get available(): boolean {
+      return device.hdr.maxHeadroom > 1
+    },
+    /** The peak the display can reach, as a multiple of SDR white (a 1600-nit XDR panel reports up
+     *  to 16). Constant for the surface; 1 on SDR. */
+    get maxHeadroom(): number {
+      const v = gl()?.getDisplayMaxHeadroom?.() ?? 1
+      return v > 1 ? v : 1
+    },
+    /** The headroom the engine renders to right now — the screen's current peak as a multiple of SDR
+     *  white, quantised to half-stops. Moves with brightness and the screen under the window
+     *  (`hdrchange` event); never below 1. */
+    get headroom(): number {
+      const v = gl()?.getDisplayHeadroom?.() ?? 1
+      return v > 1 ? v : 1
+    },
+    /** How much of the picture reaches for the headroom, 0..1 (default 0.35). 0 touches only what
+     *  SDR clipped — faithful to the SDR grade, but a mostly-mid-tone frame then looks flat next to
+     *  the one bright spot; 1 lifts nearly everything above black toward the peak. A sunlit exterior
+     *  takes 1, a dim interior wants less. A host may pin it (`LECODES_HDR_STRENGTH`). */
+    get strength(): number {
+      return gl()?.getHdrStrength?.() ?? hdrStrengthLocal
+    },
+    set strength(v: number) {
+      const s = Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 0.35
+      hdrStrengthLocal = s
+      gl()?.setHdrStrength?.(s)
+    },
+    /** Where white lands, as a multiple of SDR white, 1..8 (default 1) — the "HDR brightness" of a
+     *  console game's calibration screen, where paper white sits at ~200 nits against SDR's ~100.
+     *  It scales the WHOLE picture: at 1 a white wall is as bright as the UI's white, at 2 it is
+     *  twice that, and highlights still climb above it (the engine keeps `headroom / paperWhite` for
+     *  them, clamped at the peak). `strength` decides how much of the picture reaches for the
+     *  peak; this decides where the picture starts. 1.5–2 is the console norm; a game that wants to
+     *  read as "HDR on" rather than "SDR with a brighter sun" wants this over `strength`. A host may
+     *  pin it (`LECODES_HDR_PAPER_WHITE`). */
+    get paperWhite(): number {
+      return gl()?.getHdrPaperWhite?.() ?? hdrPaperWhiteLocal
+    },
+    set paperWhite(v: number) {
+      const p = Number.isFinite(v) ? Math.min(8, Math.max(1, v)) : 1
+      hdrPaperWhiteLocal = p
+      gl()?.setHdrPaperWhite?.(p)
+    },
+  },
+  /** Current connectivity — best-effort navigator.onLine semantics: `false` only when the platform
+   *  is sure there's no network. `true` on hosts that don't track it. Change events: `"online"` /
+   *  `"offline"`. */
+  get online(): boolean {
+    return _creatorUtils.isOnline?.() ?? true
+  },
+  addEventListener<E extends keyof DeviceEventMap>(channel: E, callback: DeviceEventMap[E]): void {
+    if (channel === "online" || channel === "offline") {
+      appEventsOn(channel, callback as () => void)
+      return
+    }
+    if (channel === "hdrchange") {
+      hdrListeners.push(callback as HdrChangeCallback)
+      if (hdrPollTimer === undefined) {
+        hdrLastHeadroom = device.hdr.headroom
+        hdrPollTimer = setInterval(pollHdr, 250)
+      }
+      return
+    }
+    if (channel !== "resize") return
+    resizeListeners.push(callback as ResizeCallback)
+    if (!resizeRegistered) {
+      resizeRegistered = true
+      _creatorUI.registerResizeEvent(onResize)
+    }
+  },
+  removeEventListener<E extends keyof DeviceEventMap>(channel: E, callback: DeviceEventMap[E]): void {
+    if (channel === "online" || channel === "offline") {
+      appEventsOff(channel, callback as () => void)
+      return
+    }
+    if (channel === "hdrchange") {
+      const i = hdrListeners.indexOf(callback as HdrChangeCallback)
+      if (i >= 0) hdrListeners.splice(i, 1)
+      if (hdrListeners.length === 0 && hdrPollTimer !== undefined) {
+        clearInterval(hdrPollTimer)
+        hdrPollTimer = undefined
+      }
+      return
+    }
+    if (channel !== "resize") return
+    const i = resizeListeners.indexOf(callback as ResizeCallback)
+    if (i >= 0) resizeListeners.splice(i, 1)
+  },
+}

package/src/runtime/fetch.ts

@@ -0,0 +1,77 @@
+// HTTP via the host. `fetch` is async (host streams the body), `fetchLocal` reads a preloaded asset
+// synchronously. Ported from worker/src/fetch.ts over the same _creatorUtils bridge.
+
+export type FetchOptions = {
+  body?: any
+  method?: string
+  headers?: Record<string, string>
+  useOnce?: boolean
+  onProgress?: (progress: { loaded: number, total?: number }) => void
+}
+
+export interface FetchResponse {
+  readonly status: number
+  json<T = any>(): T
+  text(): string
+  dispose(): void
+}
+
+class FetchResponseImpl implements FetchResponse {
+  readonly status: number
+  private readonly _id: number
+  constructor(id: number, status: number) {
+    this._id = id
+    this.status = status
+  }
+  json<T = any>(): T {
+    return _creatorUtils.fetchToJson(this._id)
+  }
+  text(): string {
+    return _creatorUtils.fetchToText(this._id)
+  }
+  dispose(): void {
+    _creatorUtils.disposeFetch(this._id)
+  }
+}
+
+export const fetch = (url: string, options: FetchOptions = {}): Promise<FetchResponse> =>
+  new Promise<FetchResponse>((resolve, reject) => {
+    _creatorUtils.fetch(url, options, (systemId, statusCode) => {
+      resolve(new FetchResponseImpl(systemId, statusCode))
+    }, reject)
+  })
+
+export const fetchLocal = (path: string): FetchResponse =>
+  new FetchResponseImpl(_creatorUtils.fetchLocal(path), 200)
+
+/** A handle to a picked / fetched file (see openFilePicker). */
+export class File {
+  /** @internal host buffer handle. `_`-prefixed because hosts read it off the raw object —
+   *  same key `FetchResponse` carries, so both are accepted anywhere a buffer is expected
+   *  (FormData entries, `UIImage` src, `Texture.load`, `share`). */
+  readonly _id: number
+  readonly name: string
+  readonly size: number
+  constructor(systemId: number, name: string, size: number) {
+    this._id = systemId
+    this.name = name
+    this.size = size
+  }
+}
+
+type FormDataValue = string | number | boolean | File | FetchResponse
+
+export class FormData {
+  // Host-facing: hosts walk `_entries` and treat any object value carrying `_id` as binary
+  // (the buffer id), everything else as a text field. See viewer-lite utils/fetch.ts,
+  // creator-pkg creatorUtilsHandler.cpp, iOS Fetch.swift buildMultipartBody.
+  private _entries: [string, FormDataValue, filename?: string][] = []
+
+  append(name: string, value: FormDataValue, filename?: string): void {
+    this._entries.push([ name, value, filename ?? (typeof value === "object" ? (value as any).name : undefined) ])
+  }
+  delete(name: string): void {
+    const index = this._entries.findIndex((i) => i[0] === name)
+    if (index >= 0) this._entries.splice(index, 1)
+  }
+}

package/src/runtime/files.ts

@@ -0,0 +1,108 @@
+// Native file picker + local file writing. openFilePicker is ported from
+// worker/src/utils/openFilePicker.ts; it resolves to File handle(s) (see runtime/fetch.ts) that can
+// be appended to a FormData and uploaded.
+
+import { File, type FetchResponse } from "./fetch"
+
+type OpenFilePickerOptions = { accept?: string }
+
+export function openFilePicker(options?: OpenFilePickerOptions & { multiple?: false }): Promise<File | null>
+export function openFilePicker(options: OpenFilePickerOptions & { multiple: true }): Promise<File[]>
+export function openFilePicker(
+  options: OpenFilePickerOptions & { multiple?: boolean } = {},
+): Promise<File | File[] | null> {
+  return new Promise((resolve, reject) => {
+    _creatorUtils.openFilePicker((resp) => {
+      if (!resp || resp.length === 0) {
+        resolve(options.multiple ? [] : null)
+        return
+      }
+      if (options.multiple) resolve(resp.map((i: any) => new File(i[0], i[1], i[2])))
+      else resolve(new File(resp[0][0], resp[0][1], resp[0][2]))
+    }, reject, !!options.multiple, options.accept)
+  })
+}
+
+// ---- Local filesystem -------------------------------------------------------------------------
+// `files` is the read/write/delete half of `fetchLocal`, for platforms where the app owns a
+// filesystem — desktop today. A RELATIVE path is resolved against the app's OWN folder (for a
+// packaged desktop app: the directory the exe sits in), never the process cwd, so a save written by
+// a shortcut and one written from a terminal land in the same place; an ABSOLUTE path goes wherever
+// it points. That folder is also one `fetchLocal` searches, so the two are a pair:
+//
+//     await files.write("saves/slot1.json", JSON.stringify(state))
+//     const state = JSON.parse((await files.readText("saves/slot1.json")) ?? "{}")
+//
+// Every call is a promise: the host does the IO off the JS thread, so a big write never costs a
+// frame. Calls stay ORDERED — two appends to one file land in call order — so a log written in a
+// loop comes out in the order it was written, without awaiting each line.
+//
+// Writing into a folder that doesn't exist yet is not a failure (the folders are created), and
+// deleting something already gone is not either — what's promised is the end state. The readers
+// resolve to null for a file that isn't there; a real failure rejects with an Error carrying the
+// host's reason. On a sandboxed platform (web, mobile) every call rejects — check `files.supported`
+// if the same bundle runs there too.
+
+/** Anything writable as-is: text, raw bytes, or a buffer the host already holds
+ *  (a picked `File`, a `FetchResponse`, a `Canvas.toFile()` snapshot). */
+export type FileData = string | Uint8Array | ArrayBuffer | File | FetchResponse
+
+const supported = () =>
+  typeof _creatorUtils !== "undefined" && typeof _creatorUtils.writeLocal === "function"
+
+// The host is asked for the work only when it can do it; otherwise the promise rejects with the
+// same message the native bridge uses, so a project sees one error either way.
+const run = <T>(op: string, path: string, call: (resolve: (v: T) => void, reject: (e: Error) => void) => void) =>
+  new Promise<T>((resolve, reject) => {
+    if (!supported()) throw new Error(`files.${op}("${path}"): this platform has no local filesystem`)
+    call(resolve, reject)
+  })
+
+// A File / FetchResponse crosses as the bare host buffer handle — the same `_id` convention
+// FormData entries and image `src` objects use, so the bytes never travel through JS.
+const payload = (data: FileData) =>
+  (typeof data === "object" && "_id" in (data as any) ? { _id: (data as any)._id } : data) as any
+
+export const files = {
+  /** Is there a filesystem here (desktop)? False on web/mobile, where every other call rejects. */
+  get supported(): boolean {
+    return supported()
+  },
+
+  /** Replace the file's contents, creating the parent folders on the way. */
+  write(path: string, data: FileData): Promise<void> {
+    return run<void>("write", path, (resolve, reject) =>
+      _creatorUtils.writeLocal!(path, payload(data), false, () => resolve(), reject))
+  },
+
+  /** Add to the end of the file, creating it (and the parent folders) when it isn't there yet. */
+  append(path: string, data: FileData): Promise<void> {
+    return run<void>("append", path, (resolve, reject) =>
+      _creatorUtils.writeLocal!(path, payload(data), true, () => resolve(), reject))
+  },
+
+  /** The whole file as UTF-8 text — null when there is no such file. */
+  readText(path: string): Promise<string | null> {
+    return run<string | null>("readText", path, (resolve, reject) =>
+      _creatorUtils.readLocalText!(path, resolve, reject))
+  },
+
+  /** The whole file as bytes — null when there is no such file. */
+  readBytes(path: string): Promise<Uint8Array | null> {
+    return run<Uint8Array | null>("readBytes", path, (resolve, reject) =>
+      _creatorUtils.readLocalBytes!(path, resolve, reject))
+  },
+
+  /** Delete a file, or a directory (empty, or any directory with `{ recursive: true }`). Deleting
+   *  something already gone is success — what's promised is that the path is free afterwards. */
+  delete(path: string, options: { recursive?: boolean } = {}): Promise<void> {
+    return run<void>("delete", path, (resolve, reject) =>
+      _creatorUtils.deleteLocal!(path, !!options.recursive, () => resolve(), reject))
+  },
+
+  /** Create a directory and any missing parents. An existing directory is fine. */
+  mkdir(path: string): Promise<void> {
+    return run<void>("mkdir", path, (resolve, reject) =>
+      _creatorUtils.mkdirLocal!(path, () => resolve(), reject))
+  },
+}

package/src/runtime/input.ts

@@ -0,0 +1,175 @@
+// Keyboard / mouse / gamepad input behind one `Input` global (docs/input-plan.md).
+//
+// Two kinds of signal, two shapes of API:
+//   - BUTTONS — anything that goes down and up: keyboard keys, mouse buttons, gamepad buttons. One
+//     code vocabulary ('KeyW', 'MouseLeft', 'GamepadSouth'), one held-poll (`Input.key`) and one
+//     event pair (`Input.on('keydown' | 'keyup')`). A mouse button IS a key.
+//   - CONTINUOUS — mouse motion/wheel, sticks, triggers: polled every frame (`Input.mouse.delta`,
+//     `Input.gamepad(0).axis('leftX')`), never events.
+// Bindings ("jump = Space | GamepadSouth") are app code: compare `e.code`, OR a few `Input.key`s.
+// Hosts report physical state only (`_creatorUtils.inputKey/inputRead/registerInputEvent`).
+
+/** Continuous channel ids — the `_creatorUtils.inputRead` contract (bridges.d.ts). */
+export const InputChannel = {
+  MouseX: 0, MouseY: 1, MouseDX: 2, MouseDY: 3, WheelX: 4, WheelY: 5, PointerLocked: 6,
+  GamepadCount: 7,
+  GamepadBase: 16, GamepadStride: 16,
+  PadConnected: 0, PadLeftX: 1, PadLeftY: 2, PadRightX: 3, PadRightY: 4, PadLeftTrigger: 5, PadRightTrigger: 6,
+} as const
+
+export type InputEventName = "keydown" | "keyup" | "gamepadconnected" | "gamepaddisconnected"
+
+/** `keydown` / `keyup` payload. `code` is the same string `Input.key()` takes. */
+export interface InputKeyEvent {
+  readonly type: "keydown" | "keyup"
+  /** Button code: KeyboardEvent.code ('KeyW', 'Space'), 'MouseLeft|Right|Middle|Back|Forward', or
+   *  'GamepadSouth|East|West|North|L1|R1|L2|R2|Select|Start|L3|R3|Up|Down|Left|Right'. */
+  readonly code: string
+  /** Which device: 'keyboard' | 'mouse' | 'gamepad'. */
+  readonly source: "keyboard" | "mouse" | "gamepad"
+  /** Pad index (0..3) for gamepad buttons, undefined otherwise. */
+  readonly gamepad?: number
+  /** OS auto-repeat keydown (key still held) — ignore for one-shot actions. */
+  readonly repeat: boolean
+}
+
+export interface InputGamepadEvent {
+  readonly type: "gamepadconnected" | "gamepaddisconnected"
+  readonly gamepad: number
+}
+
+type Listener<E> = (e: E) => void
+type InputEventMap = {
+  keydown: InputKeyEvent
+  keyup: InputKeyEvent
+  gamepadconnected: InputGamepadEvent
+  gamepaddisconnected: InputGamepadEvent
+}
+
+const listeners: { [K in InputEventName]?: Listener<InputEventMap[K]>[] } = {}
+let hostListenerInstalled = false
+
+const sourceOf = (code: string): InputKeyEvent["source"] =>
+  code.startsWith("Mouse") ? "mouse" : code.startsWith("Gamepad") ? "gamepad" : "keyboard"
+
+const emit = <K extends InputEventName>(name: K, e: InputEventMap[K]) => {
+  const list = listeners[name]
+  if (!list || list.length === 0) return
+  for (const fn of [...list]) fn(e as any)
+}
+
+// One fan-out for the host channel and the test/host `_emit` seam.
+const deliver = (kind: number, code: string, gamepad: number, repeat: number) => {
+  if (kind === 0 || kind === 1) {
+    const src = sourceOf(code)
+    emit(kind === 0 ? "keydown" : "keyup", {
+      type: kind === 0 ? "keydown" : "keyup", code, source: src,
+      gamepad: src === "gamepad" && gamepad >= 0 ? gamepad : undefined, repeat: repeat !== 0,
+    })
+  } else if (kind === 2 || kind === 3) {
+    emit(kind === 2 ? "gamepadconnected" : "gamepaddisconnected",
+         { type: kind === 2 ? "gamepadconnected" : "gamepaddisconnected", gamepad })
+  }
+}
+
+// Lazily claim the host's single listener slot (never at module scope — chisel drops top-level
+// side effects, and a host without the channel simply never fires).
+const ensureHostListener = () => {
+  if (hostListenerInstalled) return
+  hostListenerInstalled = true
+  _creatorUtils.registerInputEvent?.(deliver)
+}
+
+const read = (channel: number): number => _creatorUtils.inputRead?.(channel) ?? 0
+
+/** Mouse state — polled. Position is the cursor inside the viewport in logical px; `delta` is the
+ *  motion during the previous frame (raw where the OS offers it) and keeps counting while locked —
+ *  that's FPS look. Hosts without a mouse report zeros. */
+export const mouse = {
+  get position(): { x: number, y: number } { return { x: read(InputChannel.MouseX), y: read(InputChannel.MouseY) } },
+  get delta(): { x: number, y: number } { return { x: read(InputChannel.MouseDX), y: read(InputChannel.MouseDY) } },
+  /** Wheel notches during the previous frame (+y = wheel toward you / scroll down). */
+  get wheel(): { x: number, y: number } { return { x: read(InputChannel.WheelX), y: read(InputChannel.WheelY) } },
+  /** Pointer lock: cursor hidden + confined, `delta` keeps flowing. Web grants it only from a user
+   *  gesture (call it in a 'keydown' handler for MouseLeft); hosts drop it on focus loss and
+   *  re-acquire on focus. Escape does NOT unlock by itself on native hosts — call `unlock()`. */
+  get locked(): boolean { return read(InputChannel.PointerLocked) !== 0 },
+  lock(): boolean { return _creatorUtils.inputSetPointerLock?.(true) ?? false },
+  unlock(): void { _creatorUtils.inputSetPointerLock?.(false) },
+}
+
+export type GamepadAxisName = "leftX" | "leftY" | "rightX" | "rightY" | "leftTrigger" | "rightTrigger"
+const PAD_AXIS: Record<GamepadAxisName, number> = {
+  leftX: InputChannel.PadLeftX, leftY: InputChannel.PadLeftY, rightX: InputChannel.PadRightX,
+  rightY: InputChannel.PadRightY, leftTrigger: InputChannel.PadLeftTrigger, rightTrigger: InputChannel.PadRightTrigger,
+}
+
+export interface GamepadState {
+  readonly index: number
+  readonly connected: boolean
+  /** Stick axes −1..1 (+Y = down, like the web Gamepad API), triggers 0..1. `deadzone` (default
+   *  0.15) zeroes small stick drift — pass 0 for the raw value. */
+  axis(name: GamepadAxisName, deadzone?: number): number
+  /** Held? Same as `Input.key(code, index)`. */
+  button(code: string): boolean
+}
+
+const padCache: GamepadState[] = []
+const gamepadAt = (index: number): GamepadState => {
+  let g = padCache[index]
+  if (!g) {
+    const base = InputChannel.GamepadBase + InputChannel.GamepadStride * index
+    g = padCache[index] = {
+      index,
+      get connected() { return read(base + InputChannel.PadConnected) !== 0 },
+      axis(name, deadzone = 0.15) {
+        const v = read(base + PAD_AXIS[name])
+        return deadzone > 0 && Math.abs(v) < deadzone ? 0 : v
+      },
+      button(code) { return _creatorUtils.inputKey(code, index) },
+    }
+  }
+  return g
+}
+
+export const Input = {
+  /**
+   * Is a button held? `code` is the physical key (`KeyboardEvent.code`: 'ArrowRight', 'KeyW',
+   * 'Space'), a mouse button ('MouseLeft', 'MouseRight', 'MouseMiddle') or a gamepad button
+   * ('GamepadSouth' = A/Cross, 'GamepadR2' = right trigger as a button …). Poll inside setLoop for
+   * frame-independent movement. `gamepad` scopes a Gamepad* code to one pad; omitted = any pad.
+   */
+  key(code: string, gamepad?: number): boolean {
+    return _creatorUtils.inputKey(code, gamepad)
+  },
+
+  /** Listen for a discrete input moment. `keydown`/`keyup` cover EVERY button — keyboard, mouse,
+   *  gamepad — filter on `e.code`. Use these for one-shot actions (jump, shoot, charge-release);
+   *  `Input.key` for continuous ones (walk). */
+  on<K extends InputEventName>(name: K, listener: Listener<InputEventMap[K]>): void {
+    ensureHostListener()
+    const list = (listeners[name] ??= []) as Listener<InputEventMap[K]>[]
+    if (!list.includes(listener)) list.push(listener)
+  },
+  off<K extends InputEventName>(name: K, listener: Listener<InputEventMap[K]>): void {
+    const list = listeners[name] as Listener<InputEventMap[K]>[] | undefined
+    if (!list) return
+    const i = list.indexOf(listener)
+    if (i >= 0) list.splice(i, 1)
+  },
+
+  mouse,
+
+  /** Gamepad `index` (0..3). Always returns an object — check `.connected`. */
+  gamepad(index = 0): GamepadState { return gamepadAt(index) },
+  /** Indices of the currently connected gamepads. */
+  gamepads(): number[] {
+    const out: number[] = []
+    const n = read(InputChannel.GamepadCount)
+    for (let i = 0; i < 4 && out.length < n; i++) if (gamepadAt(i).connected) out.push(i)
+    return out
+  },
+
+  /** @internal — hosts/tests: deliver an event exactly as the host listener would. */
+  _emit(kind: number, code: string, gamepad: number, repeat: number): void { deliver(kind, code, gamepad, repeat) },
+}