lecodes-sdk 1.1.0 → 2.0.0

package/src/runtime/fetch.ts

@@ -1,5 +1,13 @@
 // 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.
+// synchronously. Over the `_creatorFetch` bridge (sdk/src/bridges/fetch.d.ts).
+//
+// Ownership (owned handles, docs/plans/hosts-unification-plan.md phase 10): a fetched body lives as long as
+// the app holds the response — `_h` is the owned handle the runtime returned with the completion,
+// its collection frees the host buffer. There is nothing to dispose. A LOCAL asset's buffer is the
+// host's (cached by name, shared by every `fetchLocal` of that name), so its wrapper only carries
+// the id. The same goes for a `File` (picker / camera / canvas export): a host buffer the wrapper
+// names but does not own.
+
 
 export type FetchOptions = {
   body?: any
@@ -13,47 +21,50 @@ export interface FetchResponse {
   readonly status: number
   json<T = any>(): T
   text(): string
+  /** @deprecated A no-op: the body is freed with the response's handle (owned handles). Apps written
+   *  against the pre-owned SDK still call it after `text()` / `json()`; remove the call. */
   dispose(): void
 }
 
 class FetchResponseImpl implements FetchResponse {
   readonly status: number
-  private readonly _id: number
-  constructor(id: number, status: number) {
-    this._id = id
+  /** @internal The buffer handle (`_h.id` = the host buffer id). Hosts and the runtime read a buffer
+   *  off any object carrying `_h` — a File / FetchResponse alike (FormData entries, `UIImage` src,
+   *  `Texture.load`, `share`, `files.write`). */
+  readonly _h: Handle
+  constructor(h: Handle, status: number) {
+    this._h = h
     this.status = status
   }
   json<T = any>(): T {
-    return _creatorUtils.fetchToJson(this._id)
+    return _creatorFetch.toJson(this._h.id)
   }
   text(): string {
-    return _creatorUtils.fetchToText(this._id)
-  }
-  dispose(): void {
-    _creatorUtils.disposeFetch(this._id)
+    return _creatorFetch.toText(this._h.id)
   }
+  /** @deprecated see the interface */
+  dispose(): void {}
 }
 
 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))
+    _creatorFetch.fetch(url, options, (h, statusCode) => {
+      resolve(new FetchResponseImpl(h, statusCode))
     }, reject)
   })
 
 export const fetchLocal = (path: string): FetchResponse =>
-  new FetchResponseImpl(_creatorUtils.fetchLocal(path), 200)
+  new FetchResponseImpl({ id: _creatorFetch.local(path) }, 200)   // the host's buffer: not owned
 
 /** 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
+  /** @internal The host buffer (not owned — see the header). Same key `FetchResponse` carries, so
+   *  both are accepted anywhere a buffer is expected. */
+  readonly _h: Handle
   readonly name: string
   readonly size: number
   constructor(systemId: number, name: string, size: number) {
-    this._id = systemId
+    this._h = { id: systemId }
     this.name = name
     this.size = size
   }
@@ -62,9 +73,8 @@ export class File {
 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.
+  // Host-facing: the runtime walks `_entries` and treats any object value carrying `_h` as binary
+  // (the buffer id), everything else as a text field. See runtime/native src/host/fetch.cpp.
   private _entries: [string, FormDataValue, filename?: string][] = []
 
   append(name: string, value: FormDataValue, filename?: string): void {

package/src/runtime/files.ts

@@ -12,7 +12,9 @@ export function openFilePicker(
   options: OpenFilePickerOptions & { multiple?: boolean } = {},
 ): Promise<File | File[] | null> {
   return new Promise((resolve, reject) => {
-    _creatorUtils.openFilePicker((resp) => {
+    // No picker on this host (headless, a hidden render): nothing picked, like a cancelled dialog.
+    if (typeof _creatorDevice.openFilePicker !== "function") { resolve(options.multiple ? [] : null); return }
+    _creatorDevice.openFilePicker((resp) => {
       if (!resp || resp.length === 0) {
         resolve(options.multiple ? [] : null)
         return
@@ -24,7 +26,7 @@ export function openFilePicker(
 }
 
 // ---- Local filesystem -------------------------------------------------------------------------
-// `files` is the read/write/delete half of `fetchLocal`, for platforms where the app owns a
+// `files` (the `_creatorFiles` bridge, absent on sandboxed hosts) 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
@@ -61,8 +63,7 @@ export type FileEntry = {
   modified: number
 }
 
-const supported = () =>
-  typeof _creatorUtils !== "undefined" && typeof _creatorUtils.writeLocal === "function"
+const supported = () => typeof _creatorFiles !== "undefined"
 
 // 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.
@@ -72,10 +73,10 @@ const run = <T>(op: string, path: string, call: (resolve: (v: T) => void, reject
     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.
+// A File / FetchResponse crosses as its buffer handle — the same `_h` 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
+  (typeof data === "object" && "_h" in (data as any) ? { _h: (data as any)._h } : data) as any
 
 export const files = {
   /** Is there a filesystem here (desktop)? False on web/mobile, where every other call rejects. */
@@ -86,38 +87,38 @@ export const files = {
   /** 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))
+      _creatorFiles.write(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))
+      _creatorFiles.write(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))
+      _creatorFiles.readText(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))
+      _creatorFiles.readBytes(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. */
   rm(path: string, options: { recursive?: boolean } = {}): Promise<void> {
     return run<void>("rm", path, (resolve, reject) =>
-      _creatorUtils.deleteLocal!(path, !!options.recursive, () => resolve(), reject))
+      _creatorFiles.remove(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))
+      _creatorFiles.mkdir(path, () => resolve(), reject))
   },
 
   /** The entries of a directory, sorted by path — null when there is no such directory (an empty
@@ -126,13 +127,13 @@ export const files = {
    *  is a file, not a directory, rejects. Filter in JS — `entries.filter(e => e.name.endsWith(".json"))`. */
   ls(path: string, options: { recursive?: boolean } = {}): Promise<FileEntry[] | null> {
     return run<FileEntry[] | null>("ls", path, (resolve, reject) =>
-      _creatorUtils.listLocal!(path, !!options.recursive, resolve, reject))
+      _creatorFiles.list(path, !!options.recursive, resolve, reject))
   },
 
   /** What is at `path`: a file or a directory entry (`path` equal to `name`), or null when nothing
    *  is there — `(await files.stat(p)) !== null` is the exists check. */
   stat(path: string): Promise<FileEntry | null> {
     return run<FileEntry | null>("stat", path, (resolve, reject) =>
-      _creatorUtils.statLocal!(path, (e) => resolve(e ? { ...e, path: e.name } : null), reject))
+      _creatorFiles.stat(path, (e) => resolve(e ? { ...e, path: e.name } : null), reject))
   },
 }

package/src/runtime/input.ts

@@ -7,9 +7,9 @@
 //   - 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`).
+// Hosts report physical state only (`_creatorInput.key / read / registerEvent`).
 
-/** Continuous channel ids — the `_creatorUtils.inputRead` contract (bridges.d.ts). */
+/** Continuous channel ids — the `_creatorInput.read` contract (sdk/src/bridges/input.d.ts). */
 export const InputChannel = {
   MouseX: 0, MouseY: 1, MouseDX: 2, MouseDY: 3, WheelX: 4, WheelY: 5, PointerLocked: 6,
   GamepadCount: 7, PointerOnUI: 8,
@@ -77,10 +77,12 @@ const deliver = (kind: number, code: string, gamepad: number, repeat: number) =>
 const ensureHostListener = () => {
   if (hostListenerInstalled) return
   hostListenerInstalled = true
-  _creatorUtils.registerInputEvent?.(deliver)
+  input()?.registerEvent?.(deliver)
 }
 
-const read = (channel: number): number => _creatorUtils.inputRead?.(channel) ?? 0
+// The host's input bridge, or undefined on a host without one (every read then answers "nothing").
+const input = () => (typeof _creatorInput !== "undefined" ? _creatorInput : undefined)
+const read = (channel: number): number => input()?.read?.(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 —
@@ -99,8 +101,8 @@ export const mouse = {
    *  `if (!Input.mouse.onUI) look(Input.mouse.delta)` never turns a HUD drag into camera look.
    *  Always false while `locked`. A press that fell through to the scene reads false. */
   get onUI(): boolean { return read(InputChannel.PointerOnUI) !== 0 },
-  lock(): boolean { return _creatorUtils.inputSetPointerLock?.(true) ?? false },
-  unlock(): void { _creatorUtils.inputSetPointerLock?.(false) },
+  lock(): boolean { return input()?.setPointerLock?.(true) ?? false },
+  unlock(): void { input()?.setPointerLock?.(false) },
 }
 
 export type GamepadAxisName = "leftX" | "leftY" | "rightX" | "rightY" | "leftTrigger" | "rightTrigger"
@@ -117,6 +119,13 @@ export interface GamepadState {
   axis(name: GamepadAxisName, deadzone?: number): number
   /** Held? Same as `Input.key(code, index)`. */
   button(code: string): boolean
+  /** Rumble: `strong` = the heavy low-frequency motor, `weak` = the light high-frequency one, both
+   *  0..1, for `durationMs` (default 200, hosts cap at 5000). A new call replaces the running
+   *  effect. The host stops the motors by itself — after the duration, on focus loss and when the
+   *  project is swapped — so there is nothing to clean up. False when the pad or host has no motors. */
+  rumble(strong: number, weak?: number, durationMs?: number): boolean
+  /** Stop the running rumble now. */
+  stopRumble(): void
 }
 
 const padCache: GamepadState[] = []
@@ -131,7 +140,11 @@ const gamepadAt = (index: number): GamepadState => {
         const v = read(base + PAD_AXIS[name])
         return deadzone > 0 && Math.abs(v) < deadzone ? 0 : v
       },
-      button(code) { return _creatorUtils.inputKey(code, index) },
+      button(code) { return input()?.key?.(code, index) ?? false },
+      rumble(strong, weak = strong, durationMs = 200) {
+        return input()?.rumble?.(index, strong, weak, durationMs) ?? false
+      },
+      stopRumble() { input()?.rumble?.(index, 0, 0, 0) },
     }
   }
   return g
@@ -145,7 +158,7 @@ export const Input = {
    * 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)
+    return input()?.key?.(code, gamepad ?? -1) ?? false
   },
 
   /** Listen for a discrete input moment. `keydown`/`keyup` cover EVERY button — keyboard, mouse,

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)
   },
 }