lecodes-sdk 0.19.0

package/src/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/src/runtime/misc.ts

@@ -0,0 +1,16 @@
+// 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)
+
+/** Open `url` in the system browser / external handler (fire-and-forget, like `share`). Silent
+ *  no-op on hosts without one (headless). */
+export const openURL = (url: string): void => _creatorUtils.openUrl?.(url)
+
+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/src/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/src/runtime/rpc.ts

@@ -0,0 +1,218 @@
+/**
+ * Client transport for the app backend (docs/backend-plan.md §3.2 / §3.3). The compiler replaces
+ * every `*.server.ts` module in the client bundle with a stub whose exports are built by the three
+ * globals below — user code never calls them; it imports the server function and calls it.
+ *
+ *   export const listNotes = __rpc("<serverUrl>", "notes.server.ts#listNotes")
+ *   export const chat      = __channel("<serverUrl>", "chat.server.ts#chat")
+ *   export const db        = __serverOnly("schema.server.ts#db")
+ *
+ * Wire (implemented by the runner):
+ *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known
+ *   → 200 {"ok":true,"result":…,"session"?:"…"} | {"ok":false,"status":n,"message":"…","session"?:"…"}
+ *   WS   <serverUrl>/ws  frames: → {t:"hello",session} {t:"sub",id,ch,topic} {t:"unsub",id}
+ *                                ← {t:"session",session} {t:"ok",id} {t:"err",id,status,message} {t:"ev",ch,topic,event,data}
+ *   (`ev` is addressed by channel + topic, not by subscription id, so the server can fan one publish out
+ *   to every socket of a topic natively; the client delivers it to each matching subscription.)
+ *
+ * The session token is transport-owned (cookie-like): stored under `lecodes.session:<serverUrl>` in
+ * localStorage, sent on every call and on the socket, replaced whenever a response carries `session`.
+ * User code never sees it — "am I logged in" is an endpoint (`me()`), see the plan.
+ */
+
+import { fetch } from "./fetch"
+import { localStorage } from "./storage"
+import { WebSocket } from "./net"
+
+/** Rejection value of a failed endpoint call: `status` mirrors the server's `ApiError`
+ *  (0 = the request itself failed: no network / no server). */
+export class RpcError extends Error {
+  readonly status: number
+  constructor(status: number, message: string) {
+    super(message)
+    this.name = "RpcError"
+    this.status = status
+  }
+}
+
+// ───────────────────────────── session token ─────────────────────────────
+
+const sessionKey = (serverUrl: string) => `lecodes.session:${serverUrl}`
+const getSession = (serverUrl: string): string | null => {
+  try { return localStorage.getItem(sessionKey(serverUrl)) } catch { return null }
+}
+const setSession = (serverUrl: string, token: string | null) => {
+  try {
+    if (token) localStorage.setItem(sessionKey(serverUrl), token)
+    else localStorage.removeItem(sessionKey(serverUrl))
+  } catch { /* storage-less host: the session lives for this run only */ }
+  sockets.get(serverUrl)?.onSessionChanged(token)
+}
+
+// ───────────────────────────── endpoints ─────────────────────────────
+
+const noServer = (id: string) => new RpcError(0, `Endpoint ${id}: the project has no deployed server (compile with serverUrl)`)
+
+/** Build the client proxy of endpoint `id`. Positional args travel as a JSON array. */
+export const __rpc = (serverUrl: string, id: string) => {
+  const call = async (...args: unknown[]): Promise<any> => {
+    if (!serverUrl) throw noServer(id)
+    const headers: Record<string, string> = { "content-type": "application/json" }
+    const session = getSession(serverUrl)
+    if (session) headers.authorization = `Bearer ${session}`
+    let res
+    try {
+      res = await fetch(`${serverUrl}/api/${encodeURIComponent(id)}`, { method: "POST", headers, body: JSON.stringify({ args }) })
+    } catch (e) {
+      throw new RpcError(0, `Endpoint ${id}: request failed (${(e as Error)?.message ?? e})`)
+    }
+    let body: any
+    try { body = res.json() } catch { body = null }
+    res.dispose()
+    if (body && typeof body === "object" && "session" in body) setSession(serverUrl, body.session ?? null)
+    if (body && body.ok === true) return body.result
+    if (body && body.ok === false) throw new RpcError(body.status ?? res.status, body.message ?? "")
+    throw new RpcError(res.status, `Endpoint ${id}: unexpected response (HTTP ${res.status})`)
+  }
+  return call
+}
+
+/** A server-only export (db, models, helpers) referenced from client code: any use throws. */
+export const __serverOnly = (id: string): any =>
+  new Proxy(function () {} as any, {
+    get: (_t, prop) => { if (prop === "then") return undefined; throw new RpcError(0, `${id} is server-only — it can't be used in client code`) },
+    apply: () => { throw new RpcError(0, `${id} is server-only — it can't be used in client code`) },
+  })
+
+// ───────────────────────────── channels ─────────────────────────────
+
+type Handlers = Record<string, ((payload: any) => void) | undefined> & {
+  /** The socket dropped and came back: subscriptions were re-sent, but events in between are lost — refetch. */
+  reconnect?: () => void
+  /** The subscription was refused (`onJoin` threw) or the socket can't connect. */
+  error?: (e: RpcError) => void
+}
+type Sub = { id: number, ch: string, topic: string, handlers: Handlers, ready: boolean }
+
+const BACKOFF_MS = [1000, 2000, 5000, 10000, 30000]
+
+/** One multiplexed socket per server URL, shared by every channel of the app. */
+class ChannelSocket {
+  private ws: WebSocket | null = null
+  private open = false
+  private subs = new Map<number, Sub>()
+  private nextId = 1
+  private attempts = 0
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private closedByUs = false
+  private everOpened = false
+  private serverUrl: string
+
+  constructor(serverUrl: string) { this.serverUrl = serverUrl }
+
+  subscribe(ch: string, topic: string, handlers: Handlers): { close(): void } {
+    const sub: Sub = { id: this.nextId++, ch, topic, handlers, ready: false }
+    this.subs.set(sub.id, sub)
+    if (this.open) this.send({ t: "sub", id: sub.id, ch, topic })
+    else this.connect()
+    return {
+      close: () => {
+        if (!this.subs.delete(sub.id)) return
+        if (this.open) this.send({ t: "unsub", id: sub.id })
+        if (this.subs.size === 0) this.shutdown()
+      },
+    }
+  }
+
+  onSessionChanged(token: string | null) {
+    if (this.open) this.send({ t: "hello", session: token })
+  }
+
+  private connect() {
+    if (this.ws || this.timer !== null) return
+    this.closedByUs = false
+    const url = this.serverUrl.replace(/^http/, "ws") + "/ws"
+    const session = getSession(this.serverUrl)
+    const ws = new WebSocket(url, session ? { authorization: `Bearer ${session}` } : undefined)
+    this.ws = ws
+    ws.addEventListener("open", () => {
+      this.open = true
+      this.attempts = 0
+      this.send({ t: "hello", session: getSession(this.serverUrl) })
+      const reconnected = this.everOpened
+      this.everOpened = true
+      for (const sub of this.subs.values()) {
+        sub.ready = false
+        this.send({ t: "sub", id: sub.id, ch: sub.ch, topic: sub.topic })
+        if (reconnected) sub.handlers.reconnect?.()
+      }
+    })
+    ws.addEventListener("message", (data) => {
+      if (typeof data !== "string") return
+      let msg: any
+      try { msg = JSON.parse(data) } catch { return }
+      this.onFrame(msg)
+    })
+    const onDown = () => {
+      if (this.ws !== ws) return
+      this.ws = null
+      this.open = false
+      if (this.closedByUs || this.subs.size === 0) return
+      const delay = BACKOFF_MS[Math.min(this.attempts++, BACKOFF_MS.length - 1)]
+      this.timer = setTimeout(() => { this.timer = null; this.connect() }, delay)
+    }
+    ws.addEventListener("close", onDown)
+    ws.addEventListener("error", onDown)
+  }
+
+  private onFrame(msg: any) {
+    switch (msg?.t) {
+      case "session": setSession(this.serverUrl, msg.session ?? null); break
+      case "ok": { const s = this.subs.get(msg.id); if (s) s.ready = true; break }
+      case "err": {
+        const s = this.subs.get(msg.id)
+        if (!s) break
+        this.subs.delete(msg.id)
+        s.handlers.error?.(new RpcError(msg.status ?? 0, msg.message ?? "subscription refused"))
+        break
+      }
+      case "ev": {
+        for (const s of this.subs.values()) {
+          if (s.ch === msg.ch && s.topic === msg.topic) s.handlers[msg.event]?.(msg.data)
+        }
+        break
+      }
+    }
+  }
+
+  private send(frame: unknown) { this.ws?.send(JSON.stringify(frame)) }
+
+  private shutdown() {
+    this.closedByUs = true
+    if (this.timer !== null) { clearTimeout(this.timer); this.timer = null }
+    this.ws?.close()
+    this.ws = null
+    this.open = false
+    sockets.delete(this.serverUrl)
+  }
+}
+
+const sockets = new Map<string, ChannelSocket>()
+const socketFor = (serverUrl: string) => {
+  let s = sockets.get(serverUrl)
+  if (!s) { s = new ChannelSocket(serverUrl); sockets.set(serverUrl, s) }
+  return s
+}
+
+export interface ClientChannel<E extends Record<string, unknown> = Record<string, unknown>> {
+  /** Subscribe to `topic`; handlers are keyed by event name (+ `reconnect`/`error`). Returns `{ close }`. */
+  subscribe(topic: string, handlers: { [K in keyof E]?: (payload: E[K]) => void } & { reconnect?: () => void, error?: (e: RpcError) => void }): { close(): void }
+}
+
+/** Build the client proxy of channel `id`. */
+export const __channel = (serverUrl: string, id: string): ClientChannel<any> => ({
+  subscribe(topic, handlers) {
+    if (!serverUrl) throw noServer(id)
+    return socketFor(serverUrl).subscribe(id, topic, handlers as Handlers)
+  },
+})

package/src/runtime/service.ts

@@ -0,0 +1,83 @@
+// A host-registered headless service (geolocation, bluetooth, contacts, …) — the UI-less sibling
+// of NativeView (docs/service-channel-plan.md). The host registers a *capability*
+// (`registerService("geolocation") { params, channel -> ... }`); the SDK talks to it over the
+// shared JSON call/event protocol (runtime/channel.ts) via `_creatorUtils.service*`.
+//
+// Not a public global itself: apps meet services through typed plugin wrappers (Geolocation —
+// src/plugins/) or the raw `Service(name)` global (src/plugins/service.ts), both thin layers
+// over this exactly like QRScanner wraps NativeViewElement.
+
+import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "./channel"
+
+/** @internal Base for typed service plugins. The host session opens lazily on the first `call()`
+ *  (`on()` only records listeners), and `close()` releases it — a later `call()` reopens a fresh
+ *  session. Session ids are host-allocated (websocket model): the `onEvent` callback is handed
+ *  over at open, so no SDK-side ref registry is needed. */
+export class ServiceClient {
+  readonly serviceName: string
+  readonly params: any
+  private _serviceId: number | null = null
+  private readonly _listeners: ChannelListeners = {}
+
+  constructor(serviceName: string, params: any = {}) {
+    this.serviceName = serviceName
+    this.params = params
+  }
+
+  /** Whether this host registered a `registerService` factory under `name`. */
+  static isSupported(name: string): boolean {
+    return typeof _creatorUtils !== "undefined" && typeof _creatorUtils.isServiceSupported === "function"
+      && _creatorUtils.isServiceSupported(name)
+  }
+
+  /** @internal open (or reuse) the host session; throws when the host has no channel/factory. */
+  private _ensureOpen(): number {
+    if (this._serviceId !== null) return this._serviceId
+    if (typeof _creatorUtils === "undefined" || typeof _creatorUtils.serviceOpen !== "function") {
+      throw new Error(`Service("${this.serviceName}") is not supported on this host (requires _creatorUtils.serviceOpen)`)
+    }
+    const id = _creatorUtils.serviceOpen(this.serviceName, JSON.stringify(this.params ?? {}),
+      (event: string, dataJson?: string) => _channelEmit(this._listeners, event, dataJson))
+    if (id < 0) {
+      throw new Error(`Service("${this.serviceName}") is not registered on this host`)
+    }
+    this._serviceId = id
+    return id
+  }
+
+  /** Invoke a method on the service (`geo.call("getCurrent", options)`). Args and the result are
+   *  JSON-serialized. Rejects if the host has no such service/method. */
+  call(method: string, ...args: any[]): Promise<any> {
+    let id: number
+    try {
+      id = this._ensureOpen()
+    } catch (e) {
+      return Promise.reject(e)
+    }
+    return _channelCall(
+      typeof _creatorUtils !== "undefined" ? _creatorUtils : undefined, "serviceCall",
+      `Service("${this.serviceName}") is not supported on this host (requires _creatorUtils.serviceCall)`,
+      id, method, args)
+  }
+
+  /** Subscribe to an event the service emits (`geo.on("position", cb)`). */
+  on(event: string, callback: (data?: any) => void): this {
+    _channelOn(this._listeners, event, callback)
+    return this
+  }
+  off(event: string, callback: (data?: any) => void): this {
+    _channelOff(this._listeners, event, callback)
+    return this
+  }
+
+  /** Close the host session (stops whatever the service was doing). Listeners stay registered —
+   *  a later `call()` opens a fresh session that delivers to them again. */
+  close(): void {
+    if (this._serviceId === null) return
+    const id = this._serviceId
+    this._serviceId = null
+    if (typeof _creatorUtils !== "undefined" && typeof _creatorUtils.serviceClose === "function") {
+      _creatorUtils.serviceClose(id)
+    }
+  }
+}

package/src/runtime/share.ts

@@ -0,0 +1,9 @@
+// Share a media File (image/video) via the OS share sheet. Wraps `_creatorUtils.shareMedia`, which
+// takes the host buffer id behind the File. On iOS the sheet also lets the user save to Files/Photos;
+// on web it saves (downloads) the file. `text` is an optional caption/message.
+
+import type { File, FetchResponse } from "./fetch"
+
+export function share(media: File | FetchResponse, text?: string): void {
+  _creatorUtils.shareMedia((media as any)._id, text)
+}

package/src/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/src/runtime/touch.ts

@@ -0,0 +1,76 @@
+// 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
+  /** World-space hit position (2D scenes only; undefined in 3D). */
+  worldX?: number
+  worldY?: 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
+  /** World-space hit position (2D scenes only; undefined in 3D). */
+  worldX?: number
+  worldY?: 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
+  }
+}
+
+/** Delivered to a `UIButton` `onLongPress` handler when a finger is held on the button past the
+ *  host's long-press threshold. Like `TouchStartEvent` it can `track(...)` the rest of the gesture —
+ *  so the common "press-and-hold, then drag to move" flow is one handler: start the drag from here. */
+export class LongPressEvent<T = any> {
+  readonly type = "longpress"
+  readonly pointerId: number
+  readonly clientX: number
+  readonly clientY: number
+  /** World-space hit position (2D scenes only; undefined in 3D). */
+  worldX?: number
+  worldY?: 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 the element after the hold. */
+  track(handler: TrackHandler): void {
+    this._trackHandler = handler
+  }
+}