lecodes-sdk 1.2.0 → 2.0.0

package/src/runtime/app.ts

@@ -2,7 +2,9 @@
 // "pause"/"resume", never Activity/Scene vocabulary — and the current values are synchronous pulls
 // so render-loop code can read them without subscribing.
 
+import { setAppBackHandler } from "../ui/tree"
 import { appEventsOn, appEventsOff, keyboardEventsOn, keyboardEventsOff } from "./appEvents"
+import { SDK_VERSION } from "../version"
 
 export type AppState = "active" | "background"
 
@@ -26,15 +28,19 @@ type AppEventMap = {
 }
 
 export const app = {
+  /** The SDK this app was compiled with (semver, e.g. `"2.0.0"`). Its major is the bundle ↔ runtime
+   *  contract: a host runs only bundles of its own major, and the launchers send it as `?sdk=` when
+   *  they fetch a published bundle — the platform keeps one bundle per major. */
+  sdkVersion: SDK_VERSION,
   /** Current lifecycle state. `"background"` while the app is not the foreground app / the tab is
    *  hidden. `"active"` on hosts that don't track it. */
   get state(): AppState {
-    return _creatorUtils.appState?.() === "background" ? "background" : "active"
+    return _creatorApp.state?.() === "background" ? "background" : "active"
   },
   /** The URL the app was (most recently) opened with — the deep link — or `null` for a plain
    *  launch. Warm links update it and fire the `"url"` event. */
   get launchUrl(): string | null {
-    return _creatorUtils.getLaunchUrl?.() ?? null
+    return _creatorApp.launchUrl?.() ?? null
   },
   /** On-screen keyboard height in logical px currently overlapping the app viewport, `0` when
    *  hidden. This is the RAW overlap, independent of the focused input's `keyboardShrink` policy —
@@ -42,7 +48,7 @@ export const app = {
    *  mode (`keyboardShrink: false`), e.g. a chat composer's `pb`. `0` on hosts without an
    *  on-screen keyboard. */
   get keyboardHeight(): number {
-    return _creatorUtils.keyboardHeight?.() ?? 0
+    return (typeof _creatorInput !== "undefined" ? _creatorInput.keyboardHeight?.() : undefined) ?? 0
   },
   /** Lock the screen orientation — `"landscape"` for a horizontal game (the device rotates to
    *  landscape right away and stays there whichever way it is held), `"portrait"` for upright
@@ -51,29 +57,29 @@ export const app = {
    *  ordinary resize — layouts reflow, a scene's viewport follows. Silent no-op on hosts
    *  without a rotatable screen (desktop, headless, web). */
   setOrientation(mode: OrientationLock): void {
-    _creatorUtils.setOrientation?.(mode)
+    _creatorApp.setOrientation?.(mode)
   },
   /** Re-run this app's bundle in a fresh world — the platform's `location.reload()`. Pass `url`
    *  to reboot with different launch arguments (the new run reads them via `app.launchUrl`),
    *  `null` to reboot with a cleared one, or omit it to replay the current one. No-op on hosts
    *  without world control (headless). */
   restart(url?: string | null): void {
-    _creatorUtils.restart?.(url)
+    _creatorApp.restart?.(url)
   },
   /** Leave this app. Inside the LeCodes viewer that returns to the launcher (the LeCodes home
    *  screen); a standalone-built app leaves to the platform instead — Android backgrounds it,
    *  iOS ignores the call (the platform forbids programmatic exit). */
   quit(): void {
-    _creatorUtils.quit?.()
+    _creatorApp.quit?.()
   },
   /** Global back-press fallback (Android back button/gesture — iOS has no system back). Fires
    *  only when nothing else consumed the press: no open widget/modal claimed it, the current
-   *  screen has no `onBackPressed`, every pager is at its tab root and the router is at its
+   *  screen has no `onBack`, every pager is at its tab root and the router is at its
    *  stack root. The place for app-wide policy — e.g. double-press-to-quit:
    *
    *  ```ts
    *  let armedAt = 0
-   *  app.onBackPressed(() => {
+   *  app.onBack(() => {
    *    if (Date.now() - armedAt < 2000) { app.quit(); return }
    *    armedAt = Date.now()
    *    toast("Press back again to exit")
@@ -81,8 +87,13 @@ export const app = {
    *  ```
    *
    *  Replaces the previous handler; pass `null` to remove. */
+  onBack(callback: (() => void) | null): void {
+    setAppBackHandler(callback ?? null)
+  },
+  /** @deprecated Renamed `onBack` (2026-09-26). An alias for the projects compiled before the
+   *  rename; removed with the release that recompiles them. */
   onBackPressed(callback: (() => void) | null): void {
-    _creatorUI._backButtonCallback = callback ?? undefined
+    setAppBackHandler(callback ?? null)
   },
   addEventListener<E extends keyof AppEventMap>(event: E, callback: AppEventMap[E]): void {
     if (event === "keyboard") {

package/src/runtime/appEvents.ts

@@ -1,8 +1,9 @@
-// The shared app-event dispatcher. The host exposes ONE registerAppEvent slot per JS world
+// The shared app-event dispatcher. The host exposes ONE `_creatorApp.registerEvent` slot per JS world
 // (docs/app-lifecycle-plan.md), so every SDK consumer (the `app` global's pause/resume/url, the
 // `device` global's online/offline) subscribes here and this module registers with the host once,
 // lazily on the first subscription — no top-level side effect, tree-shaking drops it when unused.
 
+
 type AppEventCallback = (data?: string) => void
 
 const listeners: Record<string, AppEventCallback[]> = {}
@@ -17,7 +18,7 @@ export const appEventsOn = (event: string, cb: AppEventCallback): void => {
   ;(listeners[event] ??= []).push(cb)
   if (!registered) {
     registered = true
-    _creatorUtils.registerAppEvent?.(dispatch)
+    _creatorApp.registerEvent?.(dispatch)
   }
 }
 
@@ -28,7 +29,7 @@ export const appEventsOff = (event: string, cb: AppEventCallback): void => {
   if (i >= 0) arr.splice(i, 1)
 }
 
-// The keyboard channel is a separate host slot (registerKeyboardEvent) — the registerAppEvent
+// The keyboard channel is a separate host slot (`_creatorInput.registerKeyboardEvent`) — the app-event
 // string channel can't carry the (height, duration) number pair. Same lazy single-slot pattern.
 
 type KeyboardCallback = (height: number, duration: number) => void
@@ -44,7 +45,7 @@ export const keyboardEventsOn = (cb: KeyboardCallback): void => {
   keyboardListeners.push(cb)
   if (!keyboardRegistered) {
     keyboardRegistered = true
-    _creatorUtils.registerKeyboardEvent?.(dispatchKeyboard)
+    if (typeof _creatorInput !== "undefined") _creatorInput.registerKeyboardEvent?.(dispatchKeyboard)
   }
 }
 

package/src/runtime/channel.ts

@@ -1,9 +1,11 @@
-// The JSON wire protocol shared by the two host plugin channels — NativeView
-// (`_creatorUI.viewCall`, see ui/NativeView.ts) and headless services
-// (`_creatorUtils.serviceCall`, see runtime/service.ts). One protocol, two transports:
-// `args`, results, and event payloads travel as JSON strings, and an absent/empty string
-// decodes to `undefined`. Typed plugins (QRScanner, CameraView, Geolocation) layer methods
-// over this — see src/plugins/.
+// The wire protocol shared by the two host plugin channels — NativeView
+// (`_creatorTree.viewCall`, see ui/NativeView.ts) and headless services
+// (`_creatorService.call`, see runtime/service.ts). One protocol, two transports: `args`, results
+// and event payloads travel as VALUES (`value` of bridges/types.d.ts — plain data and Uint8Array;
+// the runtime reads them once, the host gets its platform's own), and what a host leaves out
+// arrives as `undefined`. Only a view's / a service's PARAMS are JSON text: they are part of the
+// tree (a node's property, a destination). Typed plugins (QRScanner, CameraView, Geolocation)
+// layer methods over this — see src/plugins/.
 
 /** @internal event-name → listeners. NativeView exposes it as `nvl` (host contract). */
 export type ChannelListeners = Record<string, ((data?: any) => void)[]>
@@ -21,20 +23,21 @@ export const _channelOff = (listeners: ChannelListeners, event: string, callback
   if (i >= 0) list.splice(i, 1)
 }
 
-/** @internal deliver a host event: decode the JSON payload, fan out (copy-before-iterate). */
-export const _channelEmit = (listeners: ChannelListeners, event: string, dataJson?: string): void => {
+/** @internal deliver a host event: fan out (copy-before-iterate). */
+export const _channelEmit = (listeners: ChannelListeners, event: string, data?: unknown): void => {
   const list = listeners[event]
   if (!list || list.length === 0) return
-  const data = dataJson === undefined || dataJson === "" ? undefined : JSON.parse(dataJson)
   for (const cb of [...list]) cb(data)
 }
 
 type ChannelCallBridge = (
-  id: number, method: string, args: string,
-  onComplete: (result?: string) => void, onError: (err: string) => void,
+  id: number, method: string, args: unknown[],
+  onComplete: (result?: unknown) => void, onError: (err: string) => void,
 ) => void
 
-/** @internal one JSON call over a channel bridge.
+/** @internal one call over a channel bridge. An argument that cannot cross (a cycle, a typed array
+ *  that is not bytes) makes the bridge THROW: the promise rejects with it, the host never sees
+ *  the call.
  *
  *  Takes the HANDLER OBJECT plus the member name — never a plucked-off function reference. On
  *  Apple hosts the bridge members are JSExport-ed Objective-C/Swift methods, and JavaScriptCore
@@ -55,7 +58,7 @@ export const _channelCall = (
       rej(new Error(unsupportedError))
       return
     }
-    bridge.call(owner, id, method, JSON.stringify(args),
-      (result?: string) => res(result === undefined || result === "" ? undefined : JSON.parse(result)),
-      (err: string) => rej(new Error(err)))
+    // A host rejects with its message — as a string, or as the Error the runtime made of it (the
+    // Android host): the message is the same either way, never "Error: <message>".
+    bridge.call(owner, id, method, args, res, (err: unknown) => rej(typeof err === "string" ? new Error(err) : err))
   })

package/src/runtime/clipboard.ts

@@ -1,20 +1,21 @@
 // System clipboard (docs/app-lifecycle-plan.md). Write is fire-and-forget; read is async because
 // web gates it behind a permission prompt (native hosts complete synchronously).
 
+
 export const clipboard = {
   /** Put `text` on the system clipboard. Silent no-op on hosts without clipboard access. */
   write(text: string): void {
-    _creatorUtils.clipboardWrite?.(text)
+    _creatorDevice.clipboardWrite?.(text)
   },
   /** Read text from the system clipboard. Rejects when the platform has no clipboard access, the
    *  user denied it, or there is nothing readable. */
   read(): Promise<string> {
     return new Promise((resolve, reject) => {
-      if (typeof _creatorUtils.clipboardRead !== "function") {
+      if (typeof _creatorDevice.clipboardRead !== "function") {
         reject(new Error("Clipboard is not supported on this platform"))
         return
       }
-      _creatorUtils.clipboardRead(resolve, (err: string) => reject(new Error(err)))
+      _creatorDevice.clipboardRead(resolve, (err: string) => reject(new Error(err)))
     })
   },
 }

package/src/runtime/datetime.ts

@@ -15,6 +15,7 @@
 // Even before that pass lands, each method is a class method, so chisel's method-granular DCE drops
 // whichever ones a project doesn't use.
 
+
 export type Locale = "en" | "ru"
 export type DateInput = Date | number | string | DateValue
 export type Unit = "ms" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year"
@@ -58,7 +59,7 @@ const DATA: Record<Locale, LocaleData> = { en: EN, ru: RU }
 
 const resolveLocale = (locale?: Locale): Locale => {
   if (locale) return locale === "ru" ? "ru" : "en"
-  const lang = typeof _creatorUtils !== "undefined" ? _creatorUtils.language : ""
+  const lang = typeof _creatorDevice !== "undefined" ? _creatorDevice.language : ""
   return lang && lang.toLowerCase().indexOf("ru") === 0 ? "ru" : "en"
 }
 

package/src/runtime/device.ts

@@ -1,6 +1,7 @@
 // Platform info + the host resize event. The resize listener registers with the host lazily on the
 // first subscription (no top-level side effect, so tree-shaking can drop this entirely if unused).
 
+import { ensureEmitter, onTreeResize } from "../ui/tree"
 import { Quat } from "../math/quat"
 import { Vec3 } from "../math/vec"
 import { appEventsOn, appEventsOff } from "./appEvents"
@@ -94,10 +95,10 @@ export const device = {
    *  mouse-look instead of on-screen sticks. It is not the OS name: a Mac reports `"desktop"`,
    *  like Windows and Linux do (the OS/version detail is host-side, not here). */
   get platform(): "web" | "android" | "ios" | "desktop" | string {
-    return _creatorUtils.platform
+    return _creatorDevice.platform
   },
   get language(): string {
-    return _creatorUtils.language
+    return _creatorDevice.language
   },
   /** Display device-pixel ratio (physical px per logical/CSS px): 1 on standard displays, 2–3 on
    *  retina / iOS. Bake a Canvas at this ratio for crisp output without hardcoding, e.g.
@@ -105,17 +106,17 @@ export const device = {
    *  renders at logical resolution, so on web this only helps UI canvases / is forward-looking for
    *  2D; on iOS (physical surface) it makes 2D canvases crisp. Falls back to 1 if the host omits it. */
   get pixelRatio(): number {
-    return _creatorUtils.pixelRatio || 1
+    return _creatorDevice.pixelRatio || 1
   },
   /** Current display width in logical px — the same value the "resize" event delivers, but readable at
    *  any time (not only inside the listener). 0 until the host has reported a size. */
   get width(): number {
-    return _creatorUI.getDisplaySize?.()?.[0] ?? 0
+    return _creatorTree.getDisplaySize()[0] ?? 0
   },
   /** Current display height in logical px — the same value the "resize" event delivers, readable at any
    *  time. 0 until the host has reported a size. */
   get height(): number {
-    return _creatorUI.getDisplaySize?.()?.[1] ?? 0
+    return _creatorTree.getDisplaySize()[1] ?? 0
   },
   /** Opt into the precise-touch system where the platform supports it. OFF by default. When on, fast
    *  strokes are sampled at the touch digitizer's full rate (iOS coalesced touches, ≈120–240 Hz) instead
@@ -123,14 +124,14 @@ export const device = {
    *  points and smoother lines. Leave it off for tap/button UIs. No-op on hosts without a coalesced-input
    *  concept (web already coalesces pointermove; headless). */
   setPreciseTouch(enabled: boolean): void {
-    _creatorUtils.setPreciseTouch?.(enabled)
+    _creatorDevice.setPreciseTouch?.(enabled)
   },
   /** Fire a one-shot haptic of the given semantic `style` (default `"medium"`) — a physical tap on
    *  supported hardware (iOS Taptic Engine, Android vibrator). Chosen by meaning, not duration, so it
    *  feels native on each platform; see {@link HapticStyle}. Host-gated: a silent no-op where there's
    *  no haptic hardware (iPad, older iPhones, web, headless). */
   vibrate(style: HapticStyle = "medium"): void {
-    _creatorUtils.vibrate?.(style)
+    _creatorDevice.vibrate?.(style)
   },
   /** Device-orientation sensor (gyro + accelerometer, fused) for tilt/steering and magic-window /
    *  360° panoramas. Poll `attitude` / `gravity` inside setLoop; they return the freshest fused
@@ -138,7 +139,7 @@ export const device = {
   motion: {
     /** Whether this device has the motion sensors at all (no gyro → false; iPad/older, web, headless). */
     get available(): boolean {
-      return _creatorUtils.motionAvailable?.() ?? false
+      return _creatorDevice.motionAvailable?.() ?? false
     },
     /** Whether updates are currently running (start succeeded and stop hasn't been called). */
     get enabled(): boolean {
@@ -148,18 +149,18 @@ export const device = {
      *  Async so a web host can await its permission prompt; native resolves immediately. */
     async start(options: MotionOptions = {}): Promise<boolean> {
       motionFrame = options.frame ?? "world"
-      motionEnabled = !!(await (_creatorUtils.motionStart?.(options.interval ?? 1 / 60) ?? false))
+      motionEnabled = !!(await (_creatorDevice.motionStart?.(options.interval ?? 1 / 60) ?? false))
       return motionEnabled
     },
     /** Stop sensor updates and release the sensor (battery). */
     stop(): void {
-      _creatorUtils.motionStop?.()
+      _creatorDevice.motionStop?.()
       motionEnabled = false
     },
     /** Capture the current heading as "forward" — a yaw-only recenter (pitch/roll stay gravity-
      *  referenced, so the horizon stays level). No-op in the "device" frame. */
     recenter(): void {
-      const s = _creatorUtils.getMotionSample?.()
+      const s = _creatorDevice.motionSample?.()
       if (!s || motionFrame === "device") { motionYawOffset = 0; return }
       const f = orientedAttitude(s).rotateVec3([0, 0, -1])   // world-space camera forward
       motionYawOffset = Math.atan2(-f.x, -f.z)               // heading about world up
@@ -168,7 +169,7 @@ export const device = {
      *  and screen-oriented, so `camera.quaternion = device.motion.attitude` is a complete magic-window
      *  / panorama camera. `Quat.identity` until the first sample arrives / when not running. */
     get attitude(): Quat {
-      const s = _creatorUtils.getMotionSample?.()
+      const s = _creatorDevice.motionSample?.()
       if (!s) return Quat.identity
       if (motionFrame === "device") return new Quat(s[0], s[1], s[2], s[3])
       const q = orientedAttitude(s)
@@ -178,7 +179,7 @@ export const device = {
      *  down, matching clientX/clientY), orientation-aware — a 2D game reads `gravity.x / gravity.y`.
      *  `(0,0,0)` when not running. */
     get gravity(): Vec3 {
-      const s = _creatorUtils.getMotionSample?.()
+      const s = _creatorDevice.motionSample?.()
       if (!s) return new Vec3(0, 0, 0)
       if (motionFrame === "device") return new Vec3(s[4], s[5], s[6])
       // Re-express the raw device-frame gravity in screen space: undo the interface roll (about the
@@ -250,7 +251,7 @@ export const device = {
    *  is sure there's no network. `true` on hosts that don't track it. Change events: `"online"` /
    *  `"offline"`. */
   get online(): boolean {
-    return _creatorUtils.isOnline?.() ?? true
+    return _creatorApp.isOnline?.() ?? true
   },
   addEventListener<E extends keyof DeviceEventMap>(channel: E, callback: DeviceEventMap[E]): void {
     if (channel === "online" || channel === "offline") {
@@ -269,7 +270,8 @@ export const device = {
     resizeListeners.push(callback as ResizeCallback)
     if (!resizeRegistered) {
       resizeRegistered = true
-      _creatorUI.registerResizeEvent(onResize)
+      ensureEmitter()
+      onTreeResize(onResize)
     }
   },
   removeEventListener<E extends keyof DeviceEventMap>(channel: E, callback: DeviceEventMap[E]): void {

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"
@@ -138,11 +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 _creatorUtils.inputRumble?.(index, strong, weak, durationMs) ?? false
+        return input()?.rumble?.(index, strong, weak, durationMs) ?? false
       },
-      stopRumble() { _creatorUtils.inputRumble?.(index, 0, 0, 0) },
+      stopRumble() { input()?.rumble?.(index, 0, 0, 0) },
     }
   }
   return g
@@ -156,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,