lecodes-cli 0.19.0 → 0.20.0

package/runtime/sdk/plugins/camera.ts

@@ -1,81 +0,0 @@
-// CameraView — the device camera (live preview + still capture) as a Presentable. A typed wrapper
-// over the `NativeView("camera")` capability (docs/navigation-presentable-plan.md): open it
-// fullscreen (`await camera.open()`), push it (`Router.push(camera)`), or embed it among a
-// screen's children as a live preview node. `takePhoto()` returns a `File` (a host buffer
-// handle) — use it as a texture (`Texture2D.load(file)`), upload it (`FormData`), or `share` it.
-//
-// Host-OPTIONAL: it exists where the host registers a "camera" view (Android; web can via
-// `_creatorUI._registerView`) — gate on `CameraView.isSupported`. Opening prepares first (camera
-// permission) while the current destination stays visible — the same contract as ARScene/QRScanner.
-//
-// The pre-Presentable `_creatorUtils.camera*` bridges are gone from the ABI (2026-07-15): hosts
-// keep their implementations only to serve previously compiled bundles.
-
-import { File } from "../runtime/fetch"
-import { _navEpoch, type PresentOptions } from "../ui/presentable"
-import { NativeView, NativeViewElement } from "../ui/NativeView"
-import { _requestCameraPermission } from "./permission"
-
-export type CameraFacing = "front" | "back"
-
-export interface CameraView extends NativeView {
-  /** Request camera permission, then present the preview. The current destination stays visible
-   *  until the camera is ready; rejects if permission is denied, the host has no camera, or
-   *  another navigation superseded this one. */
-  open(options?: PresentOptions): Promise<void>
-  /** Capture a still frame as an image `File` (host-encoded). */
-  takePhoto(): Promise<File>
-  /** Switch between the front and back camera while the preview is live. */
-  setFacingMode(facingMode: CameraFacing): Promise<void>
-}
-
-class CameraViewElement extends NativeViewElement {
-  constructor(options: { facingMode?: CameraFacing } = {}) {
-    super("camera", { facingMode: options.facingMode ?? "back" })
-  }
-
-  /** @internal prepare-then-present: permission before the swap (see Presentable._prepare). */
-  async _prepare(): Promise<void> {
-    const epoch = _navEpoch()
-    await _requestCameraPermission()
-    if (_navEpoch() !== epoch) {
-      throw new Error("CameraView.open() superseded: another destination was opened while preparing")
-    }
-  }
-
-  override async open(options?: PresentOptions): Promise<void> {
-    // Fail before prompting for the camera — see QRScanner.
-    if (!NativeView.isSupported("camera")) {
-      throw new Error("CameraView isn't available on this host — it needs a registered \"camera\" view.")
-    }
-    await this._prepare()
-    super.open(options)
-  }
-
-  async takePhoto(): Promise<File> {
-    const photo = await this.call("takePhoto")
-    return new File(photo.systemId, photo.name, photo.size)
-  }
-
-  async setFacingMode(facingMode: CameraFacing): Promise<void> {
-    await this.call("setFacingMode", facingMode)
-  }
-}
-
-/**
- * Create a camera view (default: the back camera). `CameraView.isSupported` reports whether this
- * host has a camera capability — check it before offering the feature.
- */
-// PURE IIFE so an app that never uses the camera tree-shakes the whole plugin away (see NativeView).
-export const CameraView: {
-  (options?: { facingMode?: CameraFacing }): CameraView
-  /** Whether this host registered a "camera" view. */
-  readonly isSupported: boolean
-} = /*#__PURE__*/ (() => {
-  const factory = (options?: { facingMode?: CameraFacing }): CameraView =>
-    new CameraViewElement(options) as unknown as CameraView
-  Object.defineProperty(factory, "isSupported", {
-    get: (): boolean => NativeView.isSupported("camera"),
-  })
-  return factory as any
-})()

package/runtime/sdk/plugins/geolocation.ts

@@ -1,123 +0,0 @@
-// Geolocation — the device position as a typed service plugin (docs/service-channel-plan.md).
-// A wrapper over the host-registered "geolocation" service, exactly like QRScanner wraps the
-// "qrScanner" NativeView — except services have no UI surface, so there is nothing to present:
-// just `getCurrent()` and `watch()`.
-//
-// Host-OPTIONAL, like every plugin: it exists where the host registered a "geolocation" service
-// (web hosts do out of the box; Android via MainActivity) — gate on `Geolocation.isSupported`.
-// The OS permission prompt happens on the first call that needs it (host-side); denial is a
-// rejection. Both methods reject immediately on unsupported hosts, BEFORE any permission path.
-//
-// Service contract ("geolocation"): calls `getCurrent(options) → GeoPosition`,
-// `startWatch(options)` (resolves once watching), `stopWatch()`; event `position` → GeoPosition.
-
-import { ServiceClient } from "../runtime/service"
-
-export interface GeoPosition {
-  latitude: number
-  longitude: number
-  /** Horizontal accuracy radius, meters. */
-  accuracy: number
-  /** Meters above sea level, or null when the provider doesn't know. */
-  altitude: number | null
-  /** Direction of travel in degrees clockwise from north, or null when stationary/unknown. */
-  heading: number | null
-  /** Ground speed in m/s, or null when unknown. */
-  speed: number | null
-  /** When this fix was taken, ms epoch. */
-  timestamp: number
-}
-
-export interface GeoOptions {
-  /** Prefer the precise (GPS) provider — slower first fix, more battery. Default false. */
-  highAccuracy?: boolean
-  /** getCurrent only: reject with "timeout" if no fix arrives in this many ms. */
-  timeout?: number
-}
-
-/** A live `Geolocation.watch()` subscription — `stop()` it when the screen goes away. */
-export interface GeoWatch {
-  stop(): void
-}
-
-/**
- * The device position. `Geolocation.isSupported` reports whether this host registered the
- * service — check it before offering location features.
- */
-// PURE IIFE so an app that never uses location tree-shakes the whole plugin away (see NativeView).
-export const Geolocation: {
-  /** Whether this host registered a "geolocation" service. */
-  readonly isSupported: boolean
-  /** One position fix. Prompts for permission on first use; rejects on denial ("denied"), no
-   *  provider ("unavailable"), or `options.timeout` elapsing ("timeout"). */
-  getCurrent(options?: GeoOptions): Promise<GeoPosition>
-  /** Continuous updates. Resolves once watching (permission granted + provider started) — so a
-   *  denial is a rejection, never a silently dead callback. One host watch serves every
-   *  subscriber; the options of the watch that starts it win. Always `stop()` when done. */
-  watch(callback: (position: GeoPosition) => void, options?: GeoOptions): Promise<GeoWatch>
-} = /*#__PURE__*/ (() => {
-  let client: ServiceClient | null = null
-  const service = (): ServiceClient => client ??= new ServiceClient("geolocation")
-
-  // Watch state: one host watch fans out to N subscribers (SDK-side), the last stop() releases it.
-  const watchers: ((position: GeoPosition) => void)[] = []
-  let positionHooked = false
-  let startPromise: Promise<void> | null = null
-
-  const assertSupported = (): void => {
-    // Fail before the host is touched — a permission dialog for a feature that can't exist
-    // would be worse than the error (same ordering rule as QRScanner.open).
-    if (!ServiceClient.isSupported("geolocation")) {
-      throw new Error('Geolocation isn\'t available on this host — it needs a registered "geolocation" service.')
-    }
-  }
-
-  const removeWatcher = (callback: (position: GeoPosition) => void): void => {
-    const i = watchers.indexOf(callback)
-    if (i >= 0) watchers.splice(i, 1)
-    if (watchers.length === 0 && startPromise !== null) {
-      startPromise = null
-      service().call("stopWatch").catch(() => {})
-    }
-  }
-
-  const geolocation = {
-    async getCurrent(options?: GeoOptions): Promise<GeoPosition> {
-      assertSupported()
-      return await service().call("getCurrent", options ?? {})
-    },
-
-    async watch(callback: (position: GeoPosition) => void, options?: GeoOptions): Promise<GeoWatch> {
-      assertSupported()
-      if (!positionHooked) {
-        positionHooked = true
-        service().on("position", (position?: GeoPosition) => {
-          if (position) for (const cb of [...watchers]) cb(position)
-        })
-      }
-      watchers.push(callback)
-      startPromise ??= service().call("startWatch", options ?? {})
-      try {
-        await startPromise
-      } catch (e) {
-        // The watch never started — unwind without the stopWatch a live watch would need.
-        const i = watchers.indexOf(callback)
-        if (i >= 0) watchers.splice(i, 1)
-        if (watchers.length === 0) startPromise = null
-        throw e
-      }
-      let stopped = false
-      return {
-        stop(): void {
-          if (stopped) return
-          stopped = true
-          removeWatcher(callback)
-        },
-      }
-    },
-  }
-  Object.defineProperty(geolocation, "isSupported", {
-    get: (): boolean => ServiceClient.isSupported("geolocation"),
-  })
-  return geolocation as any
-})()

package/runtime/sdk/plugins/oauth.ts

@@ -1,61 +0,0 @@
-// OAuth — native provider sign-in as a typed service plugin (docs/backend-plan.md §3.4). The
-// browser broker (`auth.oauth.url()` on the server + `openURL` in the app) works everywhere; on
-// hosts that ship a provider SDK (Yandex LoginSDK, VK ID, Sign in with Apple, Google Sign-In) the
-// user shouldn't leave the app — the host registers an "oauth" service that runs the native sheet
-// and hands back the provider's CREDENTIAL. The app then calls its own endpoint, which does
-// `auth.oauth.signIn(provider, credential)`: the server verifies the credential with the provider
-// (audience = the platform's app ids) and binds the device session. No token is ever trusted
-// client-side; the credential is opaque to the app.
-//
-// Host-OPTIONAL — gate on `OAuth.isSupported(provider)`; fall back to the browser broker otherwise.
-//
-// Service contract ("oauth"): call `signIn(provider) → OAuthCredential` (rejects "cancelled" /
-// "unavailable"), call `providers() → string[]` (which providers this host has SDKs for).
-
-import { ServiceClient } from "../runtime/service"
-
-export type OAuthProviderName = "google" | "apple" | "yandex" | "vk"
-
-/** What a native provider SDK yields — pass it verbatim to your endpoint / `auth.oauth.signIn`. */
-export type OAuthCredential = {
-  provider: OAuthProviderName
-  /** OAuth access token (Yandex, VK ID). */
-  accessToken?: string
-  /** OpenID identity token (Google, Apple). */
-  idToken?: string
-  /** Apple only sends the name once, on the first sign-in — forward it so the server can store it. */
-  name?: string
-  email?: string
-}
-
-/**
- * Native provider sign-in. `OAuth.isSupported` reports whether this host registered the service;
- * `OAuth.providers()` which providers it has SDKs for. Otherwise open `auth.oauth.url(provider)` (server)
- * with `openURL` — the browser broker.
- */
-// PURE IIFE so an app that never uses it tree-shakes the plugin away (see Geolocation).
-export const OAuth: {
-  /** Whether this host registered an "oauth" service. */
-  readonly isSupported: boolean
-  /** The providers this host can sign in with natively. */
-  providers(): Promise<OAuthProviderName[]>
-  /** Run the provider's native sheet; resolves with the credential for `auth.oauth.signIn`. Rejects "cancelled" / "unavailable". */
-  signIn(provider: OAuthProviderName): Promise<OAuthCredential>
-} = /*#__PURE__*/ (() => {
-  let client: ServiceClient | null = null
-  const service = (): ServiceClient => client ??= new ServiceClient("oauth")
-  const assertSupported = (): void => {
-    if (!ServiceClient.isSupported("oauth")) {
-      throw new Error("OAuth isn't available on this host — it needs a registered \"oauth\" service; open auth.oauth.url(provider) in the browser instead.")
-    }
-  }
-  return {
-    get isSupported() { return ServiceClient.isSupported("oauth") },
-    providers: async () => { assertSupported(); const p = await service().call("providers"); return Array.isArray(p) ? p : [] },
-    signIn: async (provider) => {
-      assertSupported()
-      const r = await service().call("signIn", provider)
-      return { provider, ...(r ?? {}) }
-    },
-  }
-})()

package/runtime/sdk/plugins/permission.ts

@@ -1,7 +0,0 @@
-// Camera permission, host-gated: hosts expose it as `_creatorUtils.requestCamera`. Hosts without
-// that bridge resolve immediately — their view factory prompts on its own (e.g. getUserMedia on
-// the web). Shared by ARScene.prepare, QRScanner and CameraView.
-export const _requestCameraPermission = (): Promise<void> =>
-  typeof _creatorUtils.requestCamera === "function"
-    ? new Promise<void>((res, rej) => _creatorUtils.requestCamera!(res, rej))
-    : Promise.resolve()

package/runtime/sdk/plugins/push.ts

@@ -1,132 +0,0 @@
-// Push — remote notifications as a typed service plugin (docs/push-plan.md). A wrapper over
-// the host-registered "push" service, the Geolocation recipe applied to notifications: the
-// host owns the OS token, the permission prompt, and the platform registration with the
-// le.codes backend; the app only ever sees the opaque project-scoped ADDRESS (never the raw
-// APNs/FCM token) plus payloads.
-//
-// Host-OPTIONAL, like every plugin — gate on `Push.isSupported`. The OS permission prompt
-// happens inside `register()` (the first call that needs it, host-side); `getStatus()` and
-// `getLaunch()` never prompt. On hosts without the service every method rejects immediately,
-// BEFORE any permission path.
-//
-// The app is not running when a push arrives — display is host/OS work. The JS world sees
-// exactly three delivery paths:
-//   - event "message": arrived while this app was foregrounded (the host suppresses the banner)
-//   - event "tap":     tapped while the world was alive (warm)
-//   - getLaunch():     the notification that cold-started this world (stable pull, or null)
-// A payload's `url` additionally rides the app-lifecycle deep-link path (`app.launchUrl` /
-// the "url" event), so apps that already route links get notification routing for free.
-//
-// Service contract ("push"): calls `getStatus() → PushStatus`, `register({user?}) → {address}`
-// (rejects "denied"/"unavailable"), `unregister()`, `getLaunch() → PushPayload|null`;
-// events `message`/`tap` → PushPayload. An OPEN SESSION is the host's delivery pipe for the
-// events — addEventListener opens one eagerly (cheap by the channel contract: no prompt, no I/O).
-
-import { ServiceClient } from "../runtime/service"
-
-/** A delivered notification, as the app sees it. */
-export interface PushPayload {
-  title: string
-  body?: string
-  /** Deep link — also delivered through `app.launchUrl` / the app "url" event. */
-  url?: string
-  /** The developer's own JSON, ≤ 2 KB serialized. */
-  data?: Record<string, any>
-  badge?: number
-}
-
-export interface PushStatus {
-  /** OS notification permission for the host app. "prompt" = not asked yet. */
-  permission: "granted" | "denied" | "prompt"
-  /** Whether this device already holds a registration (an address) for this app. */
-  registered: boolean
-}
-
-export interface PushRegisterOptions {
-  /** Your app's OWN user id ("external user id"): lets your server send to `users: ["u42"]`
-   *  instead of storing addresses, fanning out to all the user's devices. CLIENT-ASSERTED and
-   *  unverified — never target sensitive content by user. The registration reflects the latest
-   *  `register()` call, so registering without `user` clears it (logout). */
-  user?: string
-}
-
-export type PushEvent = "message" | "tap"
-
-/**
- * Remote push notifications. `Push.isSupported` reports whether this host registered the
- * service — check it before offering notification features.
- */
-// PURE IIFE so an app that never uses push tree-shakes the whole plugin away (see Geolocation).
-export const Push: {
-  /** Whether this host registered a "push" service. */
-  readonly isSupported: boolean
-  /** Permission + registration state. Never prompts. */
-  getStatus(): Promise<PushStatus>
-  /** Ask for permission (first time) and register this device → the opaque address your server
-   *  targets. Idempotent — safe to call every launch; rejects "denied" / "unavailable". */
-  register(options?: PushRegisterOptions): Promise<{ address: string }>
-  /** Remove this device's registration (the address stops receiving). */
-  unregister(): Promise<void>
-  /** The notification that cold-started this app run, or null. Stable across calls. */
-  getLaunch(): Promise<PushPayload | null>
-  /** "message" = received while the app is open; "tap" = the user tapped one while it ran. */
-  addEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void
-  removeEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void
-} = /*#__PURE__*/ (() => {
-  let client: ServiceClient | null = null
-  const service = (): ServiceClient => client ??= new ServiceClient("push")
-
-  const assertSupported = (): void => {
-    // Fail before the host is touched — a permission dialog for a feature that can't exist
-    // would be worse than the error (same ordering rule as QRScanner/Geolocation).
-    if (!ServiceClient.isSupported("push")) {
-      throw new Error('Push isn\'t available on this host — it needs a registered "push" service.')
-    }
-  }
-
-  // ServiceClient.on only records listeners; events need a live session to arrive on. Poke the
-  // host with the prompt-free getStatus once so a listener-only app (already registered on a
-  // previous run) still hears warm taps.
-  let pipeOpened = false
-  const ensurePipe = (): void => {
-    if (pipeOpened || !ServiceClient.isSupported("push")) return
-    pipeOpened = true
-    service().call("getStatus").catch(() => { pipeOpened = false })
-  }
-
-  const push = {
-    async getStatus(): Promise<PushStatus> {
-      assertSupported()
-      return await service().call("getStatus")
-    },
-
-    async register(options?: PushRegisterOptions): Promise<{ address: string }> {
-      assertSupported()
-      return await service().call("register", options ?? {})
-    },
-
-    async unregister(): Promise<void> {
-      assertSupported()
-      await service().call("unregister")
-    },
-
-    async getLaunch(): Promise<PushPayload | null> {
-      assertSupported()
-      return (await service().call("getLaunch")) ?? null
-    },
-
-    addEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void {
-      // Recording on an unsupported host is a silent no-op (the events just never fire),
-      // like app/device listeners — only the promise-returning methods reject loudly.
-      service().on(event, callback as (data?: any) => void)
-      ensurePipe()
-    },
-    removeEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void {
-      service().off(event, callback as (data?: any) => void)
-    },
-  }
-  Object.defineProperty(push, "isSupported", {
-    get: (): boolean => ServiceClient.isSupported("push"),
-  })
-  return push as any
-})()

package/runtime/sdk/plugins/qr.ts

@@ -1,73 +0,0 @@
-// QRScanner — the host's camera QR scanner as a Presentable. A typed wrapper over the
-// `NativeView("qrScanner")` capability (docs/navigation-presentable-plan.md): open it fullscreen
-// (`await scanner.open()`), push it (`Router.push(scanner)`), or embed it among a screen's
-// children as a live preview node — everything a NativeView can do, plus a typed `onScan`.
-//
-// Host-OPTIONAL, like every plugin: it exists where the host registers a "qrScanner" view
-// (Android; web can via `_creatorUI._registerView`) — gate on `QRScanner.isSupported`. Opening
-// prepares first (camera permission) while the current destination stays visible — the same
-// prepare-then-present contract as ARScene.
-//
-// The pre-Presentable `_creatorUtils.openScanner/closeScanner` bridges are gone from the ABI
-// (2026-07-15): hosts keep their implementations only to serve previously compiled bundles.
-
-import { _navEpoch, type PresentOptions } from "../ui/presentable"
-import { NativeView, NativeViewElement } from "../ui/NativeView"
-import { _requestCameraPermission } from "./permission"
-
-export interface QRScanner extends NativeView {
-  /** Fires per decoded camera frame: the decoded string, or `null` for a frame with no readable
-   *  code (expect those repeatedly while the user aims). The same code can be reported more than
-   *  once — `close()` or debounce once you have what you need. */
-  onScan(callback: (data: string | null) => void): this
-  /** Request camera permission, then present the scanner. The current destination (and its
-   *  loading state) stays visible until the scanner is ready; rejects if the camera is denied,
-   *  the host can't scan, or another navigation superseded this one. */
-  open(options?: PresentOptions): Promise<void>
-}
-
-class QRScannerElement extends NativeViewElement {
-  constructor() {
-    super("qrScanner", {})
-  }
-
-  onScan(callback: (data: string | null) => void): this {
-    return this.on("scan", (payload?: { data?: string | null }) => callback(payload?.data ?? null))
-  }
-
-  /** @internal prepare-then-present: permission before the swap (see Presentable._prepare). */
-  async _prepare(): Promise<void> {
-    const epoch = _navEpoch()
-    await _requestCameraPermission()
-    if (_navEpoch() !== epoch) {
-      throw new Error("QRScanner.open() superseded: another destination was opened while preparing")
-    }
-  }
-
-  override async open(options?: PresentOptions): Promise<void> {
-    // Fail before prompting for the camera — a permission dialog for a scanner that can't exist
-    // would be worse than the error.
-    if (!NativeView.isSupported("qrScanner")) {
-      throw new Error("QRScanner isn't available on this host — it needs a registered \"qrScanner\" view.")
-    }
-    await this._prepare()
-    super.open(options)
-  }
-}
-
-/**
- * Create a QR scanner view. `QRScanner.isSupported` reports whether this host can scan at all —
- * check it before offering the feature.
- */
-// PURE IIFE so an app that never scans tree-shakes the whole plugin away (see NativeView).
-export const QRScanner: {
-  (): QRScanner
-  /** Whether this host registered a "qrScanner" view. */
-  readonly isSupported: boolean
-} = /*#__PURE__*/ (() => {
-  const factory = (): QRScanner => new QRScannerElement() as unknown as QRScanner
-  Object.defineProperty(factory, "isSupported", {
-    get: (): boolean => NativeView.isSupported("qrScanner"),
-  })
-  return factory as any
-})()

package/runtime/sdk/plugins/service.ts

@@ -1,47 +0,0 @@
-// Raw access to host-registered headless services — the escape hatch for services that
-// have no typed wrapper (yet). First-party services ship wrapped (Geolocation); app-local
-// native code (an `engine.registerService` in the app shell) and third-party plugins are
-// reachable through this global immediately, wrapper or not. Thin sugar over the internal
-// ServiceClient (src/runtime/service.ts) — same JSON call/event channel, same lazy session.
-
-import { ServiceClient } from "../runtime/service"
-
-export interface Service {
-  /** Invoke a method on the service (`battery.call("level")`). Arguments and the result are
-   *  JSON-serialized; rejects when the host has no such service or the method reports an
-   *  error. The host session opens lazily on the first call. */
-  call(method: string, ...args: any[]): Promise<any>
-  /** Subscribe to an event the service emits while a session is open
-   *  (`battery.on("change", data => …)`). Payloads are JSON-decoded. */
-  on(event: string, callback: (data?: any) => void): this
-  /** Remove a previously added listener. */
-  off(event: string, callback: (data?: any) => void): 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
-}
-
-/**
- * A host-registered headless service — the UI-less sibling of `NativeView`. Use it for
- * services without a typed wrapper: native code registered in your app shell
- * (`engine.registerService("app.battery") { … }`) or a third-party plugin's channel.
- * **Host-optional** — gate on `Service.isSupported` (the web editor registers none of them).
- *
- * ```ts
- * if (Service.isSupported("app.battery")) {
- *   const battery = Service("app.battery")
- *   battery.on("change", data => { level.text = data.level + "%" })
- *   const { level } = await battery.call("level")
- * }
- * ```
- */
-// PURE IIFE so an app that never touches raw services tree-shakes this away.
-export const Service: {
-  (name: string, params?: any): Service
-  /** Whether this host registered a service under `name`. */
-  isSupported(name: string): boolean
-} = /*#__PURE__*/ (() => {
-  const factory = (name: string, params: any = {}): Service => new ServiceClient(name, params) as unknown as Service
-  factory.isSupported = (name: string): boolean => ServiceClient.isSupported(name)
-  return factory as any
-})()

package/runtime/sdk/runtime/app.ts

@@ -1,101 +0,0 @@
-// The app's own lifecycle + how it was opened (docs/app-lifecycle-plan.md). Events are semantic —
-// "pause"/"resume", never Activity/Scene vocabulary — and the current values are synchronous pulls
-// so render-loop code can read them without subscribing.
-
-import { appEventsOn, appEventsOff, keyboardEventsOn, keyboardEventsOff } from "./appEvents"
-
-export type AppState = "active" | "background"
-
-/** `"landscape"` — either landscape direction (sensor landscape), `"portrait"` — upright only,
- *  `"auto"` — released: the device's own rotation rules apply. */
-export type OrientationLock = "auto" | "portrait" | "landscape"
-
-type AppEventMap = {
-  /** The app left the foreground (home button, tab hidden, another app on top). Delivered before
-   *  the host halts the frame loop — the last chance to persist state / pause work. */
-  pause: () => void
-  /** The app returned to the foreground; frames are running again. */
-  resume: () => void
-  /** A link arrived while the app was running (warm deep link). `app.launchUrl` is already
-   *  updated to the same value when this fires. */
-  url: (url: string) => void
-  /** The on-screen keyboard changed. `height` mirrors `app.keyboardHeight` (the raw overlap, see
-   *  there); `duration` is the platform's keyboard animation duration in ms (0 where none) — pass
-   *  it to `animateTo` to move a composer in sync with the keyboard. */
-  keyboard: (height: number, duration: number) => void
-}
-
-export const app = {
-  /** 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"
-  },
-  /** 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
-  },
-  /** 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 —
-   *  with the default shrink the layout already avoids the keyboard; the main consumer is overlay
-   *  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
-  },
-  /** 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
-   *  only, `"auto"` to release. Call it once at startup; the lock is per app run (it resets
-   *  when the app quits or restarts), so there is nothing to undo. The rotation arrives as an
-   *  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)
-  },
-  /** 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)
-  },
-  /** 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?.()
-  },
-  /** 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
-   *  stack root. The place for app-wide policy — e.g. double-press-to-quit:
-   *
-   *  ```ts
-   *  let armedAt = 0
-   *  app.onBackPressed(() => {
-   *    if (Date.now() - armedAt < 2000) { app.quit(); return }
-   *    armedAt = Date.now()
-   *    toast("Press back again to exit")
-   *  })
-   *  ```
-   *
-   *  Replaces the previous handler; pass `null` to remove. */
-  onBackPressed(callback: (() => void) | null): void {
-    _creatorUI._backButtonCallback = callback ?? undefined
-  },
-  addEventListener<E extends keyof AppEventMap>(event: E, callback: AppEventMap[E]): void {
-    if (event === "keyboard") {
-      keyboardEventsOn(callback as (height: number, duration: number) => void)
-      return
-    }
-    appEventsOn(event, callback as (data?: string) => void)
-  },
-  removeEventListener<E extends keyof AppEventMap>(event: E, callback: AppEventMap[E]): void {
-    if (event === "keyboard") {
-      keyboardEventsOff(callback as (height: number, duration: number) => void)
-      return
-    }
-    appEventsOff(event, callback as (data?: string) => void)
-  },
-}