lecodes-cli 0.1.5 → 0.1.7

package/runtime/sdk/math/vec.ts

@@ -0,0 +1,255 @@
+// Fluent 2D / 3D vectors — the SDK's user-facing vector math (no gl-matrix, no out-params, no imports).
+//
+// Design (see PLAN.md): a vector is a *mutable little struct* — `v.x = 3`, `v.set(x, y, z)` mutate in
+// place — but every *method* is PURE: `a.add(b)` returns a NEW vector and never touches `a`. So chains
+// (`dir.normalize().scale(s)`) can't clobber their source, and the immutable-method style is the most
+// amenable to a future escape-analysis / scalar-replacement compiler pass. Backing is plain number
+// fields (not a Float32Array), which the optimizer can trivially scalar-replace.
+//
+// "Never wrap away the metal": vectors expose `.x/.y/.z`, are iterable (`const [x, y] = v`, `[...v]`),
+// and every method / constructor accepts a raw tuple just as well as a wrapper. Reads off a `*Like`
+// input go through the `cx/cy/cz` helpers below, which work uniformly on a wrapper (`.x`) or an
+// array-like (`[0]`), so callers can always pass `[0, 1, 0]` where a vector is expected.
+
+export type Vec2Like = Vec2 | readonly [number, number] | number[] | Float32Array
+export type Vec3Like = Vec3 | readonly [number, number, number] | number[] | Float32Array
+
+/** Read the x / first component of any vector-like (wrapper, tuple, or typed array). `?? ` is safe on
+ *  0 and NaN — it only falls through on `undefined` (i.e. a non-wrapper that has no `.x`). */
+export const cx = (v: { x?: number } | ArrayLike<number>): number => (v as { x?: number }).x ?? (v as ArrayLike<number>)[0]
+export const cy = (v: { y?: number } | ArrayLike<number>): number => (v as { y?: number }).y ?? (v as ArrayLike<number>)[1]
+export const cz = (v: { z?: number } | ArrayLike<number>): number => (v as { z?: number }).z ?? (v as ArrayLike<number>)[2]
+
+/** Relative-epsilon compare (matches gl-matrix's `equals`), so the oracle tests agree to the bit. */
+const approx = (a: number, b: number, eps: number): boolean => Math.abs(a - b) <= eps * Math.max(1, Math.abs(a), Math.abs(b))
+
+// ---------------------------------------------------------------------------------------------------
+// Vec2
+// ---------------------------------------------------------------------------------------------------
+
+export class Vec2 {
+  x: number
+  y: number
+
+  constructor(x: number | Vec2Like = 0, y = 0) {
+    if (typeof x === "number") { this.x = x; this.y = y }
+    else { this.x = cx(x); this.y = cy(x) }
+  }
+
+  // --- mutation (the only methods that change `this`) ---
+  /** Mutate the components in place. Returns `this`. */
+  set(x: number, y: number): this { this.x = x; this.y = y; return this }
+  /** Copy another vector's components into this one. Returns `this`. */
+  copy(v: Vec2Like): this { this.x = cx(v); this.y = cy(v); return this }
+
+  // --- pure arithmetic (each returns a NEW Vec2) ---
+  add(v: Vec2Like): Vec2 { return new Vec2(this.x + cx(v), this.y + cy(v)) }
+  sub(v: Vec2Like): Vec2 { return new Vec2(this.x - cx(v), this.y - cy(v)) }
+  mul(v: Vec2Like): Vec2 { return new Vec2(this.x * cx(v), this.y * cy(v)) }
+  div(v: Vec2Like): Vec2 { return new Vec2(this.x / cx(v), this.y / cy(v)) }
+  scale(s: number): Vec2 { return new Vec2(this.x * s, this.y * s) }
+  /** `this + v * s` (fused multiply-add). */
+  scaleAndAdd(v: Vec2Like, s: number): Vec2 { return new Vec2(this.x + cx(v) * s, this.y + cy(v) * s) }
+  negate(): Vec2 { return new Vec2(-this.x, -this.y) }
+
+  // --- products / measures ---
+  dot(v: Vec2Like): number { return this.x * cx(v) + this.y * cy(v) }
+  /** 2D cross product → the scalar z of the 3D cross (signed parallelogram area). */
+  cross(v: Vec2Like): number { return this.x * cy(v) - this.y * cx(v) }
+  length(): number { return Math.hypot(this.x, this.y) }
+  lengthSq(): number { return this.x * this.x + this.y * this.y }
+  distanceTo(v: Vec2Like): number { return Math.hypot(this.x - cx(v), this.y - cy(v)) }
+  distanceSqTo(v: Vec2Like): number { const dx = this.x - cx(v), dy = this.y - cy(v); return dx * dx + dy * dy }
+
+  normalize(): Vec2 {
+    const l = Math.hypot(this.x, this.y)
+    return l === 0 ? new Vec2(0, 0) : new Vec2(this.x / l, this.y / l)
+  }
+  lerp(v: Vec2Like, t: number): Vec2 { return new Vec2(this.x + (cx(v) - this.x) * t, this.y + (cy(v) - this.y) * t) }
+  clamp(min: Vec2Like, max: Vec2Like): Vec2 {
+    return new Vec2(clampN(this.x, cx(min), cx(max)), clampN(this.y, cy(min), cy(max)))
+  }
+  min(v: Vec2Like): Vec2 { return new Vec2(Math.min(this.x, cx(v)), Math.min(this.y, cy(v))) }
+  max(v: Vec2Like): Vec2 { return new Vec2(Math.max(this.x, cx(v)), Math.max(this.y, cy(v))) }
+  /** Left-hand perpendicular: (-y, x), a 90° CCW turn. */
+  perp(): Vec2 { return new Vec2(-this.y, this.x) }
+  /** Rotate by `rad` (CCW) around `origin` (default 0). */
+  rotate(rad: number, origin: Vec2Like = ZERO2): Vec2 {
+    const ox = cx(origin), oy = cy(origin)
+    const c = Math.cos(rad), s = Math.sin(rad)
+    const dx = this.x - ox, dy = this.y - oy
+    return new Vec2(ox + dx * c - dy * s, oy + dx * s + dy * c)
+  }
+  /** The vector's heading in radians: `atan2(y, x)`. */
+  heading(): number { return Math.atan2(this.y, this.x) }
+  /** Angle (radians) between this and `v`. */
+  angle(v: Vec2Like): number {
+    const mag = Math.sqrt(this.lengthSq() * (cx(v) * cx(v) + cy(v) * cy(v)))
+    return mag === 0 ? 0 : Math.acos(clampN(this.dot(v) / mag, -1, 1))
+  }
+
+  withX(x: number): Vec2 { return new Vec2(x, this.y) }
+  withY(y: number): Vec2 { return new Vec2(this.x, y) }
+
+  // --- interop ---
+  equals(v: Vec2Like, eps = 1e-6): boolean { return approx(this.x, cx(v), eps) && approx(this.y, cy(v), eps) }
+  clone(): Vec2 { return new Vec2(this.x, this.y) }
+  toArray(): [number, number] { return [ this.x, this.y ] }
+  *[Symbol.iterator](): Iterator<number> { yield this.x; yield this.y }
+
+  static from(v: Vec2Like): Vec2 { return new Vec2(cx(v), cy(v)) }
+  static get zero(): Vec2 { return new Vec2(0, 0) }
+  static get one(): Vec2 { return new Vec2(1, 1) }
+  static get up(): Vec2 { return new Vec2(0, 1) }
+  static get down(): Vec2 { return new Vec2(0, -1) }
+  static get left(): Vec2 { return new Vec2(-1, 0) }
+  static get right(): Vec2 { return new Vec2(1, 0) }
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Vec3
+// ---------------------------------------------------------------------------------------------------
+
+export class Vec3 {
+  x: number
+  y: number
+  z: number
+
+  constructor(x: number | Vec3Like = 0, y = 0, z = 0) {
+    if (typeof x === "number") { this.x = x; this.y = y; this.z = z }
+    else { this.x = cx(x); this.y = cy(x); this.z = cz(x) }
+  }
+
+  // --- mutation ---
+  set(x: number, y: number, z: number): this { this.x = x; this.y = y; this.z = z; return this }
+  copy(v: Vec3Like): this { this.x = cx(v); this.y = cy(v); this.z = cz(v); return this }
+
+  // --- pure arithmetic ---
+  add(v: Vec3Like): Vec3 { return new Vec3(this.x + cx(v), this.y + cy(v), this.z + cz(v)) }
+  sub(v: Vec3Like): Vec3 { return new Vec3(this.x - cx(v), this.y - cy(v), this.z - cz(v)) }
+  mul(v: Vec3Like): Vec3 { return new Vec3(this.x * cx(v), this.y * cy(v), this.z * cz(v)) }
+  div(v: Vec3Like): Vec3 { return new Vec3(this.x / cx(v), this.y / cy(v), this.z / cz(v)) }
+  scale(s: number): Vec3 { return new Vec3(this.x * s, this.y * s, this.z * s) }
+  /** `this + v * s` (fused multiply-add). */
+  scaleAndAdd(v: Vec3Like, s: number): Vec3 { return new Vec3(this.x + cx(v) * s, this.y + cy(v) * s, this.z + cz(v) * s) }
+  negate(): Vec3 { return new Vec3(-this.x, -this.y, -this.z) }
+
+  // --- products / measures ---
+  dot(v: Vec3Like): number { return this.x * cx(v) + this.y * cy(v) + this.z * cz(v) }
+  cross(v: Vec3Like): Vec3 {
+    const bx = cx(v), by = cy(v), bz = cz(v)
+    return new Vec3(this.y * bz - this.z * by, this.z * bx - this.x * bz, this.x * by - this.y * bx)
+  }
+  length(): number { return Math.hypot(this.x, this.y, this.z) }
+  lengthSq(): number { return this.x * this.x + this.y * this.y + this.z * this.z }
+  distanceTo(v: Vec3Like): number { return Math.hypot(this.x - cx(v), this.y - cy(v), this.z - cz(v)) }
+  distanceSqTo(v: Vec3Like): number {
+    const dx = this.x - cx(v), dy = this.y - cy(v), dz = this.z - cz(v)
+    return dx * dx + dy * dy + dz * dz
+  }
+
+  normalize(): Vec3 {
+    const l = Math.hypot(this.x, this.y, this.z)
+    return l === 0 ? new Vec3(0, 0, 0) : new Vec3(this.x / l, this.y / l, this.z / l)
+  }
+  lerp(v: Vec3Like, t: number): Vec3 {
+    return new Vec3(this.x + (cx(v) - this.x) * t, this.y + (cy(v) - this.y) * t, this.z + (cz(v) - this.z) * t)
+  }
+  clamp(min: Vec3Like, max: Vec3Like): Vec3 {
+    return new Vec3(clampN(this.x, cx(min), cx(max)), clampN(this.y, cy(min), cy(max)), clampN(this.z, cz(min), cz(max)))
+  }
+  min(v: Vec3Like): Vec3 { return new Vec3(Math.min(this.x, cx(v)), Math.min(this.y, cy(v)), Math.min(this.z, cz(v))) }
+  max(v: Vec3Like): Vec3 { return new Vec3(Math.max(this.x, cx(v)), Math.max(this.y, cy(v)), Math.max(this.z, cz(v))) }
+  /** Reflect this vector about a (unit) `normal`: `v - 2·(v·n)·n`. */
+  reflect(normal: Vec3Like): Vec3 {
+    const d = 2 * this.dot(normal)
+    return new Vec3(this.x - d * cx(normal), this.y - d * cy(normal), this.z - d * cz(normal))
+  }
+  /** Vector projection of this onto `onto`. */
+  project(onto: Vec3Like): Vec3 {
+    const ox = cx(onto), oy = cy(onto), oz = cz(onto)
+    const denom = ox * ox + oy * oy + oz * oz
+    if (denom === 0) return new Vec3(0, 0, 0)
+    const k = this.dot(onto) / denom
+    return new Vec3(ox * k, oy * k, oz * k)
+  }
+  /** Angle (radians) between this and `v`. */
+  angle(v: Vec3Like): number {
+    const bx = cx(v), by = cy(v), bz = cz(v)
+    const mag = Math.sqrt(this.lengthSq() * (bx * bx + by * by + bz * bz))
+    return mag === 0 ? 0 : Math.acos(clampN(this.dot(v) / mag, -1, 1))
+  }
+
+  // --- rotation ---
+  /** Rotate this point around the X axis through `origin` (default 0) by `rad`. */
+  rotateX(rad: number, origin: Vec3Like = ZERO3): Vec3 {
+    const ox = cx(origin), oy = cy(origin), oz = cz(origin)
+    const py = this.y - oy, pz = this.z - oz, c = Math.cos(rad), s = Math.sin(rad)
+    return new Vec3(this.x, oy + py * c - pz * s, oz + py * s + pz * c)
+  }
+  rotateY(rad: number, origin: Vec3Like = ZERO3): Vec3 {
+    const ox = cx(origin), oy = cy(origin), oz = cz(origin)
+    const px = this.x - ox, pz = this.z - oz, c = Math.cos(rad), s = Math.sin(rad)
+    return new Vec3(ox + pz * s + px * c, this.y, oz + pz * c - px * s)
+  }
+  rotateZ(rad: number, origin: Vec3Like = ZERO3): Vec3 {
+    const ox = cx(origin), oy = cy(origin), oz = cz(origin)
+    const px = this.x - ox, py = this.y - oy, c = Math.cos(rad), s = Math.sin(rad)
+    return new Vec3(ox + px * c - py * s, oy + px * s + py * c, this.z)
+  }
+  /** Rotate this vector by a quaternion (x, y, z, w). Accepts a `Quat` or a raw `[x,y,z,w]`. */
+  rotate(q: ArrayLike<number> | { x: number, y: number, z: number, w: number }): Vec3 {
+    const qx = cx(q as Vec3Like), qy = cy(q as Vec3Like), qz = cz(q as Vec3Like)
+    const qw = (q as { w?: number }).w ?? (q as ArrayLike<number>)[3]
+    const vx = this.x, vy = this.y, vz = this.z
+    // t = 2 * (q.xyz × v)
+    let tx = qy * vz - qz * vy, ty = qz * vx - qx * vz, tz = qx * vy - qy * vx
+    tx += tx; ty += ty; tz += tz
+    // v + w·t + q.xyz × t
+    return new Vec3(
+      vx + qw * tx + qy * tz - qz * ty,
+      vy + qw * ty + qz * tx - qx * tz,
+      vz + qw * tz + qx * ty - qy * tx,
+    )
+  }
+  /** Transform this point by a column-major mat4 (a `Mat4`, its `.m`, or a raw length-16 array),
+   *  applying translation and the perspective divide. */
+  transform(m: ArrayLike<number> | { m: ArrayLike<number> }): Vec3 {
+    const a = (m as { m?: ArrayLike<number> }).m ?? (m as ArrayLike<number>)
+    const x = this.x, y = this.y, z = this.z
+    let w = a[3] * x + a[7] * y + a[11] * z + a[15]
+    w = w || 1
+    return new Vec3(
+      (a[0] * x + a[4] * y + a[8] * z + a[12]) / w,
+      (a[1] * x + a[5] * y + a[9] * z + a[13]) / w,
+      (a[2] * x + a[6] * y + a[10] * z + a[14]) / w,
+    )
+  }
+
+  withX(x: number): Vec3 { return new Vec3(x, this.y, this.z) }
+  withY(y: number): Vec3 { return new Vec3(this.x, y, this.z) }
+  withZ(z: number): Vec3 { return new Vec3(this.x, this.y, z) }
+
+  // --- interop ---
+  equals(v: Vec3Like, eps = 1e-6): boolean {
+    return approx(this.x, cx(v), eps) && approx(this.y, cy(v), eps) && approx(this.z, cz(v), eps)
+  }
+  clone(): Vec3 { return new Vec3(this.x, this.y, this.z) }
+  toArray(): [number, number, number] { return [ this.x, this.y, this.z ] }
+  *[Symbol.iterator](): Iterator<number> { yield this.x; yield this.y; yield this.z }
+
+  static from(v: Vec3Like): Vec3 { return new Vec3(cx(v), cy(v), cz(v)) }
+  static get zero(): Vec3 { return new Vec3(0, 0, 0) }
+  static get one(): Vec3 { return new Vec3(1, 1, 1) }
+  static get up(): Vec3 { return new Vec3(0, 1, 0) }
+  static get down(): Vec3 { return new Vec3(0, -1, 0) }
+  static get left(): Vec3 { return new Vec3(-1, 0, 0) }
+  static get right(): Vec3 { return new Vec3(1, 0, 0) }
+  /** Forward is −Z (the engine's cameras look down −Z; `node.forward` is −Z at identity). */
+  static get forward(): Vec3 { return new Vec3(0, 0, -1) }
+  static get back(): Vec3 { return new Vec3(0, 0, 1) }
+}
+
+const clampN = (v: number, lo: number, hi: number): number => (v < lo ? lo : v > hi ? hi : v)
+const ZERO2 = new Vec2(0, 0)
+const ZERO3 = new Vec3(0, 0, 0)

package/runtime/sdk/plugins/qr.ts

@@ -0,0 +1,36 @@
+// QRScanner — an OPTIONAL, host-provided capability. The native scanner is implemented by some hosts
+// (the le.codes app) and not others (the generic web viewer), so it's gated on host support and throws
+// a clear error where it's missing — the same approach as physics (`physicsHasSupport`) and AR
+// (`requestCamera`). Ported 1:1 from worker/src/utils/QRScanner.ts.
+//
+// It lives under `plugins/` rather than the core engine folders to mark it as host-optional. This is a
+// *convention*, not a plugin *system* — when there are several of these (NFC, Bluetooth, …) we can
+// extract a real mechanism; for one capability that would be premature.
+
+export class QRScanner {
+  private readonly _onData: (data: string | null) => void
+
+  /** `onData` fires for every value the scanner decodes (null = a frame with no readable code). */
+  constructor(onData: (data: string | null) => void) {
+    this._onData = onData
+  }
+
+  /** Whether this host provides a native QR scanner (the le.codes app does; many hosts don't). */
+  static get isSupported(): boolean {
+    return typeof _creatorUtils.openScanner === "function"
+  }
+
+  /** Ask for camera access, then open the native scanner. Rejects if the host can't scan or access is denied. */
+  async open(): Promise<void> {
+    if (!QRScanner.isSupported) {
+      throw new Error("QRScanner isn't available on this host — it needs the le.codes app's native scanner.")
+    }
+    await new Promise<void>((res, rej) => _creator.requestCamera(res, rej))
+    await new Promise<void>((res, rej) => _creatorUtils.openScanner(res, rej, this._onData))
+  }
+
+  /** Close the scanner and release the camera. */
+  close(): void {
+    _creatorUtils.closeScanner()
+  }
+}

package/runtime/sdk/runtime/device.ts

@@ -0,0 +1,33 @@
+// 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).
+
+type ResizeCallback = (width: number, height: number) => void
+
+const resizeListeners: ResizeCallback[] = []
+let resizeRegistered = false
+
+const onResize = (width: number, height: number): void => {
+  for (const cb of resizeListeners.slice()) cb(width, height)
+}
+
+export const device = {
+  get platform(): "web" | "android" | "ios" | string {
+    return _creatorUtils.platform
+  },
+  get language(): string {
+    return _creatorUtils.language
+  },
+  addEventListener(channel: "resize", callback: ResizeCallback): void {
+    if (channel !== "resize") return
+    resizeListeners.push(callback)
+    if (!resizeRegistered) {
+      resizeRegistered = true
+      _creatorUI.registerResizeEvent(onResize)
+    }
+  },
+  removeEventListener(channel: "resize", callback: ResizeCallback): void {
+    if (channel !== "resize") return
+    const i = resizeListeners.indexOf(callback)
+    if (i >= 0) resizeListeners.splice(i, 1)
+  },
+}

package/runtime/sdk/runtime/fetch.ts

@@ -0,0 +1,71 @@
+// 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 {
+  readonly id: number
+  readonly name: string
+  readonly size: number
+  constructor(id: number, name: string, size: number) {
+    this.id = id
+    this.name = name
+    this.size = size
+  }
+}
+
+type FormDataValue = string | number | boolean | File | FetchResponse
+
+export class FormData {
+  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/runtime/sdk/runtime/files.ts

@@ -0,0 +1,23 @@
+// Native file picker. Ported from worker/src/utils/openFilePicker.ts; resolves to File handle(s)
+// (see runtime/fetch.ts) that can be appended to a FormData and uploaded.
+
+import { File } 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)
+  })
+}

package/runtime/sdk/runtime/input.ts

@@ -0,0 +1,12 @@
+// Keyboard/pointer input. Replaces worker's bare `inputKey(code)` global with a small `Input`
+// namespace so the surface reads better and has room to grow (pointer, gamepad) without new globals.
+
+export const Input = {
+  /**
+   * Is a key currently held? `code` is a KeyboardEvent.code-style string, e.g. 'ArrowRight',
+   * 'KeyW', 'Space'. Poll this inside setLoop for frame-independent movement.
+   */
+  key(code: string): boolean {
+    return _creatorUtils.inputKey(code)
+  },
+}

package/runtime/sdk/runtime/media.ts

@@ -0,0 +1,111 @@
+// Audio / video playback over the host. Ported from worker/src/MediaPlayer.ts, with the listener
+// boilerplate folded into the shared Emitter. VideoPlayer.texture (a 3D Texture) is wired in Phase 4
+// when the Texture type exists — see gl/.
+//
+// The host no longer routes end-of-playback events back by id through a Registry: each player hands
+// the host a `_finished` callback at creation time. The host holds the JS closure directly — valid
+// on every backend (web JS, Android quickjs, iOS JavaScriptCore) — and invokes it when a play-through
+// completes, so there is no id table to keep in sync.
+
+import { Emitter } from "../core/events"
+import { Texture } from "../gl/Texture"
+
+type MediaEvents = {
+  /** Fired at each loop boundary while `loop` is true. */
+  loopReached: () => void
+  /** Fired once when playback reaches the end while `loop` is false. */
+  completed: () => void
+}
+
+abstract class MediaPlayer extends Emitter<MediaEvents> {
+  protected _id = -1
+  protected _src = ""
+  private _playing = false
+  private _loop = false
+  private _volume = 1
+  private _disposed = false
+
+  // Every host-touching operation runs through this so a disposed player can never address a freed
+  // (and possibly reused) host slot.
+  private _assertAlive(): void {
+    if (this._disposed) throw new Error("MediaPlayer has been disposed")
+  }
+
+  play(): void { this.playing = true }
+  pause(): void { this.playing = false }
+
+  get playing(): boolean { return this._playing }
+  set playing(value: boolean) {
+    this._assertAlive()
+    this._playing = value
+    _creatorUtils.updateMediaPlayerPlaying(this._id, value)
+  }
+
+  get volume(): number { return this._volume }
+  set volume(value: number) {
+    this._assertAlive()
+    this._volume = value
+    _creatorUtils.updateMediaPlayerVolume(this._id, value)
+  }
+
+  get loop(): boolean { return this._loop }
+  set loop(value: boolean) {
+    this._assertAlive()
+    this._loop = value
+    _creatorUtils.updateMediaPlayerLoop(this._id, value)
+  }
+
+  /** Current playback position, in seconds. Settable to seek. */
+  get time(): number { this._assertAlive(); return _creatorUtils.getMediaPlayerTime(this._id) }
+  set time(value: number) { this._assertAlive(); _creatorUtils.setMediaPlayerTime(this._id, value) }
+
+  /** Total media length in seconds (0 until metadata has loaded). */
+  get duration(): number { this._assertAlive(); return _creatorUtils.getMediaPlayerDuration(this._id) }
+
+  /** True once {@link dispose} has been called; the player is unusable afterwards. */
+  get disposed(): boolean { return this._disposed }
+
+  /**
+   * Release the underlying host media resource (decoder, network, buffers) immediately and detach
+   * all listeners. Idempotent. Any further use of the player throws.
+   */
+  dispose(): void {
+    if (this._disposed) return
+    this._disposed = true
+    this._playing = false
+    this.clearListeners()
+    _creatorUtils.removeMediaPlayer(this._id)
+  }
+
+  /** @internal — the host calls this when a play-through finishes. */
+  protected _finished(): void {
+    if (this._disposed) return
+    if (this._loop) {
+      this.dispatch("loopReached")
+    } else {
+      this._playing = false
+      this.dispatch("completed")
+    }
+  }
+}
+
+export class AudioPlayer extends MediaPlayer {
+  constructor(src?: string) {
+    super()
+    this._src = src ?? ""
+    this._id = _creatorUtils.createAudioPlayer(this._src, () => this._finished())
+  }
+}
+
+export class VideoPlayer extends MediaPlayer {
+  constructor(src?: string) {
+    super()
+    this._src = src ?? ""
+    this._id = _creatorUtils.createVideoPlayer(this._src, () => this._finished())
+  }
+
+  /** A 3D Texture that samples this video (e.g. for a Material.video()). */
+  get texture(): Texture {
+    return new Texture(0, 0, _creator.createMediaPlayerTexture(this._id))
+  }
+}

package/runtime/sdk/runtime/misc.ts

@@ -0,0 +1,12 @@
+// Small platform globals that are real (not engine-specific). Grown in Phase 1.
+
+/** Show a transient toast notification. */
+export const toast = (msg: string): void => _creatorUI.toast(msg)
+
+export type SvgSourceValue = {
+  readonly svg: string
+  tintColor: string | null
+}
+
+/** Wrap raw SVG XML so it can be used as an image source. */
+export const SvgSource = (svg: string): SvgSourceValue => ({ svg, tintColor: null })

package/runtime/sdk/runtime/net.ts

@@ -0,0 +1,36 @@
+// WebSocket over the host bridge. Same event surface as the browser's (open/message/close/error)
+// via the shared Emitter. Ported from worker/src/WebSocket.ts.
+
+import { Emitter } from "../core/events"
+
+type SocketEvents = {
+  open: () => void
+  message: (data: any) => void
+  close: (code?: number) => void
+  error: () => void
+}
+
+export class WebSocket extends Emitter<SocketEvents> {
+  private _id: number | null = null
+
+  constructor(url: string, headers?: Record<string, string>) {
+    super()
+    this._id = _creatorUtils.websocketOpen(url, (channel, data) => this._onMessage(channel, data), headers)
+  }
+
+  send(message: string | ArrayBuffer): void {
+    if (this._id !== null) _creatorUtils.websocketSend(this._id, message)
+  }
+
+  close(): void {
+    if (this._id !== null) {
+      _creatorUtils.websocketClose(this._id)
+      this._id = null
+    }
+  }
+
+  private _onMessage(channel: string, data: any): void {
+    if (data !== undefined && data !== null) this.dispatch(channel as keyof SocketEvents, data)
+    else this.dispatch(channel as keyof SocketEvents)
+  }
+}

package/runtime/sdk/runtime/storage.ts

@@ -0,0 +1,13 @@
+// Key/value persistence backed by the host. Same shape as the web localStorage subset projects use.
+
+export const localStorage = {
+  getItem(key: string): string | null {
+    return _creatorUtils.localStorageGetValue(key)
+  },
+  setItem(key: string, value: string): void {
+    _creatorUtils.localStorageSetValue(key, value)
+  },
+  removeItem(key: string): void {
+    _creatorUtils.localStorageRemoveValue(key)
+  },
+}

package/runtime/sdk/runtime/touch.ts

@@ -0,0 +1,44 @@
+// Pointer event objects delivered to 3D scene/node touch handlers. Ported from worker/src/TouchEvent.ts.
+// The dispatch wiring (reading the active scene, hit entity) is set up in Phase 4 with the 3D Scene;
+// these classes are the injected globals user code receives. `target` is the hit Node (typed loosely
+// here to avoid a forward dependency on gl/).
+
+export class ClickEvent<T = any> {
+  readonly type = "click"
+  readonly pointerId: number
+  readonly clientX: number
+  readonly clientY: number
+  target!: T
+  constructor(clientX: number, clientY: number, pointerId: number) {
+    this.clientX = clientX
+    this.clientY = clientY
+    this.pointerId = pointerId
+  }
+}
+
+export interface TrackHandler {
+  onMove?(pos: { clientX: number, clientY: number, deltaX: number, deltaY: number }): void
+  onEnd?(pos: { clientX: number, clientY: number, deltaX: number, deltaY: number }): void
+  onCancel?(): void
+  claim?: boolean | "pan-x" | "pan-y" | "pan-down" | "pan-up" | "pan-left" | "pan-right"
+}
+
+export class TouchStartEvent<T = any> {
+  readonly type = "touchstart"
+  readonly pointerId: number
+  readonly clientX: number
+  readonly clientY: number
+  target!: T
+  /** @internal — read by the dispatch system after the handler runs. */
+  _trackHandler?: TrackHandler
+  constructor(clientX: number, clientY: number, pointerId: number) {
+    this.clientX = clientX
+    this.clientY = clientY
+    this.pointerId = pointerId
+  }
+
+  /** Capture subsequent moves/end for this pointer (drag/pan gestures). */
+  track(handler: TrackHandler): void {
+    this._trackHandler = handler
+  }
+}

package/runtime/sdk/ui/UI.ts

@@ -0,0 +1,19 @@
+// Renderer-side contract + per-renderer status (DOM / canvas-ui / desktop) for every component
+// below is tracked in packages/canvas-ui/COMPONENTS.md.
+export { UIButton, type UIButtonStyle } from './UIButton'
+export { UIScreen, type UIScreenStyle } from './UIScreen'
+export { UISpacer, type UISpacerStyle } from './UISpacer'
+export { UIText, type UITextStyle } from './UIText'
+export { registerFont } from './fonts'
+export { UIImage, type UIImageStyle } from './UIImage'
+export { UIVideo, type UIVideoStyle } from './UIVideo'
+export { UIInput, UITextArea, type UIInputStyle } from './UIInput'
+
+export { UIWidget, type UIWidgetStyle } from './UIWidget'
+
+export { UIRow, UIColumn, UIBox, type UIContainerStyle } from './UIContainer'
+export { UIScrollable, type UIScrollableStyle } from './UIScrollable'
+
+export { UIVirtualizedList } from './UIVirtualizedList'
+
+export { Router } from './router'