lecodes-sdk 1.2.0 → 2.0.0

package/src/runtime/media.ts

@@ -1,13 +1,15 @@
-// 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/.
+// Audio / video playback over the host's `_creatorMedia` bridge (absent on hosts without media
+// players — the players are inert there). The listener boilerplate is folded into the shared Emitter.
 //
-// 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.
+// Ownership (owned handles, docs/plans/hosts-unification-plan.md phase 10): a player is an owned resource
+// — `_h` is the handle the runtime returned; the runtime counts a PLAYING player as natively owned.
+// So `new AudioPlayer(src).play()` in a handler, reference dropped, plays to its end and is released
+// then; a paused player you stop referencing is released at once. There is nothing to dispose. The
+// end-of-playback report comes by id through ONE emitter per world; a playing player is pinned so
+// the report finds it.
 
 import { Emitter } from "../core/events"
+import { Pins } from "../core/pins"
 import { Texture } from "../gl/Texture"
 
 type MediaEvents = {
@@ -17,83 +19,84 @@ type MediaEvents = {
   completed: () => void
 }
 
+/** The players native owns right now (playing), by id — what an end-of-playback report resolves to. */
+const players = new Pins<MediaPlayer>()
+/** The host's media table, or undefined on a host without one (`@optional`: the global is absent). */
+const media = (): typeof _creatorMedia | undefined => (typeof _creatorMedia !== "undefined" ? _creatorMedia : undefined)
+let emitterInstalled = false
+const ensureEmitter = (): void => {
+  const m = media()
+  if (emitterInstalled || !m || typeof m.setEmitter !== "function") return
+  emitterInstalled = true
+  m.setEmitter((id) => { players.get(id)?._finished() })
+}
+
 abstract class MediaPlayer extends Emitter<MediaEvents> {
-  protected _id = -1
+  /** @internal The player's owned handle (`_h.id` = the host player id; -1 = no host player). */
+  _h: Handle = { 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 }
+  /** Pause and rewind to the start. */
+  stop(): void {
+    this.playing = false
+    media()?.setTime?.(this._h.id, 0)
+  }
 
   get playing(): boolean { return this._playing }
   set playing(value: boolean) {
-    this._assertAlive()
     this._playing = value
-    _creatorUtils.updateMediaPlayerPlaying(this._id, value)
+    media()?.setPlaying(this._h.id, value)
+    if (value) players.pin(this)          // playing: native owns it, the end report must find it
+    else players.unpin(this._h.id)
   }
 
   get volume(): number { return this._volume }
   set volume(value: number) {
-    this._assertAlive()
     this._volume = value
-    _creatorUtils.updateMediaPlayerVolume(this._id, value)
+    media()?.setVolume(this._h.id, value)
   }
 
   get loop(): boolean { return this._loop }
   set loop(value: boolean) {
-    this._assertAlive()
     this._loop = value
-    _creatorUtils.updateMediaPlayerLoop(this._id, value)
+    media()?.setLoop(this._h.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) }
+  get time(): number { return media()?.time?.(this._h.id) ?? 0 }
+  set time(value: number) { media()?.setTime?.(this._h.id, value) }
 
   /** Total media length in seconds (0 until metadata has loaded). */
-  get duration(): number { this._assertAlive(); return _creatorUtils.getMediaPlayerDuration(this._id) }
+  get duration(): number { return media()?.duration?.(this._h.id) ?? 0 }
 
-  /** 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
+  /** @internal — the runtime reports a play-through end. */
+  _finished(): void {
     if (this._loop) {
       this.dispatch("loopReached")
     } else {
       this._playing = false
+      players.unpin(this._h.id)
       this.dispatch("completed")
     }
   }
+
+  /** @deprecated There is nothing to dispose — a player the app stops referencing is released by
+   *  the runtime (a playing one at its end). Kept as `stop()` so old code still silences the player;
+   *  call `stop()` / `pause()` instead. */
+  dispose(): void { this.stop() }
 }
 
 export class AudioPlayer extends MediaPlayer {
   constructor(src?: string) {
     super()
     this._src = src ?? ""
-    this._id = _creatorUtils.createAudioPlayer(this._src, () => this._finished())
+    ensureEmitter()
+    this._h = media()?.createAudio(this._src) ?? { id: -1 }
   }
 }
 
@@ -101,11 +104,12 @@ export class VideoPlayer extends MediaPlayer {
   constructor(src?: string) {
     super()
     this._src = src ?? ""
-    this._id = _creatorUtils.createVideoPlayer(this._src, () => this._finished())
+    ensureEmitter()
+    this._h = media()?.createVideo(this._src) ?? { id: -1 }
   }
 
-  /** A 3D Texture that samples this video (e.g. for a Material.video()). */
+  /** A 3D Texture that samples this video (e.g. for a Material.video()). Owned by the player. */
   get texture(): Texture {
-    return new Texture(0, 0, _creator.createMediaPlayerTexture(this._id))
+    return new Texture(0, 0, _creator.createMediaPlayerTexture(this._h.id))
   }
 }

package/src/runtime/misc.ts

@@ -1,15 +1,19 @@
 // Small platform globals that are real (not engine-specific). Grown in Phase 1.
 
+import type { ColorInput } from "../core/color"
+
 /** Show a transient toast notification. */
-export const toast = (msg: string): void => _creatorUI.toast(msg)
+export const toast = (msg: string): void => _creatorTree.toast(msg, 2000)
 
 /** 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 const openURL = (url: string): void => _creatorApp.openUrl?.(url)
 
 export type SvgSourceValue = {
   readonly svg: string
-  tintColor: string | null
+  /** The source-level tint (a mask recolor under the `tintColor` style, which wins): any color, or
+   *  a theme `var(--…)`. */
+  tintColor: ColorInput | null
 }
 
 /** Wrap raw SVG XML so it can be used as an image source. */

package/src/runtime/net.ts

@@ -1,5 +1,5 @@
-// 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.
+// WebSocket over the host's `_creatorSocket` bridge. Same event surface as the browser's
+// (open/message/close/error) via the shared Emitter.
 
 import { Emitter } from "../core/events"
 
@@ -13,18 +13,19 @@ type SocketEvents = {
 export class WebSocket extends Emitter<SocketEvents> {
   private _id: number | null = null
 
-  constructor(url: string, headers?: Record<string, string>) {
+  constructor(url: string) {
     super()
-    this._id = _creatorUtils.websocketOpen(url, (channel, data) => this._onMessage(channel, data), headers)
+    this._id = _creatorSocket.open(url, (channel, data) => this._onMessage(channel, data))
   }
 
-  send(message: string | ArrayBuffer): void {
-    if (this._id !== null) _creatorUtils.websocketSend(this._id, message)
+  /** Send a text frame. */
+  send(message: string): void {
+    if (this._id !== null) _creatorSocket.send(this._id, message)
   }
 
   close(): void {
     if (this._id !== null) {
-      _creatorUtils.websocketClose(this._id)
+      _creatorSocket.close(this._id)
       this._id = null
     }
   }

package/src/runtime/rpc.ts

@@ -68,7 +68,6 @@ export const __rpc = (serverUrl: string, id: string) => {
     }
     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 ?? "")
@@ -132,8 +131,7 @@ class ChannelSocket {
     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)
+    const ws = new WebSocket(url)
     this.ws = ws
     ws.addEventListener("open", () => {
       this.open = true

package/src/runtime/service.ts

@@ -1,7 +1,7 @@
 // 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*`.
+// shared call / event protocol (runtime/channel.ts) via `_creatorService`.
 //
 // 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
@@ -26,18 +26,22 @@ export class ServiceClient {
 
   /** 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)
+    return typeof _creatorService !== "undefined" && _creatorService.supported(name)
+  }
+
+  /** The contract version of the host's service `name`: 0 when it has none, 1 for one written by hand. */
+  static version(name: string): number {
+    return typeof _creatorService !== "undefined" ? _creatorService.version(name) : 0
   }
 
   /** @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)`)
+    if (typeof _creatorService === "undefined") {
+      throw new Error(`Service("${this.serviceName}") is not supported on this host (no service channel)`)
     }
-    const id = _creatorUtils.serviceOpen(this.serviceName, JSON.stringify(this.params ?? {}),
-      (event: string, dataJson?: string) => _channelEmit(this._listeners, event, dataJson))
+    const id = _creatorService.open(this.serviceName, JSON.stringify(this.params ?? {}),
+      (event: string, data?: unknown) => _channelEmit(this._listeners, event, data))
     if (id < 0) {
       throw new Error(`Service("${this.serviceName}") is not registered on this host`)
     }
@@ -46,8 +50,11 @@ export class ServiceClient {
   }
 
   /** 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> {
+   *  plain data (and Uint8Array). Rejects if the host has no such service/method. */
+  call(method: string, ...args: any[]): Promise<any> { return this._channelSend(method, args) }
+
+  /** @internal One call over the channel (runtime/channel.ts). */
+  _channelSend(method: string, args: any[]): Promise<any> {
     let id: number
     try {
       id = this._ensureOpen()
@@ -55,8 +62,8 @@ export class ServiceClient {
       return Promise.reject(e)
     }
     return _channelCall(
-      typeof _creatorUtils !== "undefined" ? _creatorUtils : undefined, "serviceCall",
-      `Service("${this.serviceName}") is not supported on this host (requires _creatorUtils.serviceCall)`,
+      typeof _creatorService !== "undefined" ? _creatorService : undefined, "call",
+      `Service("${this.serviceName}") is not supported on this host (no service channel)`,
       id, method, args)
   }
 
@@ -76,8 +83,6 @@ export class ServiceClient {
     if (this._serviceId === null) return
     const id = this._serviceId
     this._serviceId = null
-    if (typeof _creatorUtils !== "undefined" && typeof _creatorUtils.serviceClose === "function") {
-      _creatorUtils.serviceClose(id)
-    }
+    if (typeof _creatorService !== "undefined") _creatorService.close(id)
   }
 }

package/src/runtime/share.ts

@@ -1,9 +1,10 @@
-// Share a media File (image/video) via the OS share sheet. Wraps `_creatorUtils.shareMedia`, which
+// Share a media File (image/video) via the OS share sheet. Wraps `_creatorDevice.share`, 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.
+// on web it saves (downloads) the file. `text` is an optional caption/message. A silent no-op on
+// hosts without a share slot (headless).
 
 import type { File, FetchResponse } from "./fetch"
 
 export function share(media: File | FetchResponse, text?: string): void {
-  _creatorUtils.shareMedia((media as any)._id, text)
+  _creatorDevice.share?.((media as any)._h.id, text)
 }

package/src/runtime/storage.ts

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

package/src/runtime/touch.ts

@@ -74,3 +74,35 @@ export class LongPressEvent<T = any> {
     this._trackHandler = handler
   }
 }
+
+/** What a hover `track()` takes: the cursor's moves inside the element (only delivered when
+ *  `onMove` is present — otherwise the host never crosses into JS for them), `onEnd` when it
+ *  leaves (with the last position), `onCancel` when the element went away underneath it. No
+ *  `claim`: a hover competes with nothing. */
+export interface HoverTrackHandler {
+  onMove?(pos: { clientX: number, clientY: number, deltaX: number, deltaY: number }): void
+  onEnd?(pos: { clientX: number, clientY: number, deltaX: number, deltaY: number }): void
+  onCancel?(): void
+}
+
+/** Delivered to a `UIButton` `onMouseEnter` handler when a mouse cursor (no button) enters the
+ *  button. There is no separate leave event: `ev.track({ onEnd })` follows this hover to its end,
+ *  `onMove` follows the cursor inside — the visual state itself is the reserved `$hovered` class.
+ *  Touch never produces one. */
+export class MouseEnterEvent<T = any> {
+  readonly type = "mouseenter"
+  readonly clientX: number
+  readonly clientY: number
+  target!: T
+  /** @internal — read by the dispatch system after the handler runs. */
+  _trackHandler?: HoverTrackHandler
+  constructor(clientX: number, clientY: number) {
+    this.clientX = clientX
+    this.clientY = clientY
+  }
+
+  /** Follow this hover: moves inside the element, its end (the cursor left), its cancel. */
+  track(handler: HoverTrackHandler): void {
+    this._trackHandler = handler
+  }
+}