lecodes-cli 0.18.2 → 0.19.2

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

package/runtime/sdk/runtime/appEvents.ts

@@ -1,54 +0,0 @@
-// The shared app-event dispatcher. The host exposes ONE registerAppEvent 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[]> = {}
-let registered = false
-
-const dispatch = (event: string, data?: string): void => {
-  const arr = listeners[event]
-  if (arr) for (const cb of arr.slice()) cb(data)
-}
-
-export const appEventsOn = (event: string, cb: AppEventCallback): void => {
-  ;(listeners[event] ??= []).push(cb)
-  if (!registered) {
-    registered = true
-    _creatorUtils.registerAppEvent?.(dispatch)
-  }
-}
-
-export const appEventsOff = (event: string, cb: AppEventCallback): void => {
-  const arr = listeners[event]
-  if (!arr) return
-  const i = arr.indexOf(cb)
-  if (i >= 0) arr.splice(i, 1)
-}
-
-// The keyboard channel is a separate host slot (registerKeyboardEvent) — the registerAppEvent
-// string channel can't carry the (height, duration) number pair. Same lazy single-slot pattern.
-
-type KeyboardCallback = (height: number, duration: number) => void
-
-const keyboardListeners: KeyboardCallback[] = []
-let keyboardRegistered = false
-
-const dispatchKeyboard = (height: number, duration: number): void => {
-  for (const cb of keyboardListeners.slice()) cb(height, duration)
-}
-
-export const keyboardEventsOn = (cb: KeyboardCallback): void => {
-  keyboardListeners.push(cb)
-  if (!keyboardRegistered) {
-    keyboardRegistered = true
-    _creatorUtils.registerKeyboardEvent?.(dispatchKeyboard)
-  }
-}
-
-export const keyboardEventsOff = (cb: KeyboardCallback): void => {
-  const i = keyboardListeners.indexOf(cb)
-  if (i >= 0) keyboardListeners.splice(i, 1)
-}

package/runtime/sdk/runtime/channel.ts

@@ -1,61 +0,0 @@
-// 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/.
-
-/** @internal event-name → listeners. NativeView exposes it as `nvl` (host contract). */
-export type ChannelListeners = Record<string, ((data?: any) => void)[]>
-
-/** @internal */
-export const _channelOn = (listeners: ChannelListeners, event: string, callback: (data?: any) => void): void => {
-  (listeners[event] ??= []).push(callback)
-}
-
-/** @internal */
-export const _channelOff = (listeners: ChannelListeners, event: string, callback: (data?: any) => void): void => {
-  const list = listeners[event]
-  if (!list) return
-  const i = list.indexOf(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 => {
-  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,
-) => void
-
-/** @internal one JSON call over a channel bridge.
- *
- *  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
- *  binds those to their native receiver: invoking a detached `handler.viewCall(…)` with no `this`
- *  fails at runtime with "self type check failed for Objective-C instance method". QuickJS and web
- *  hosts are plain functions that ignore `this`, so a detached call works there and the breakage
- *  looks iOS/macOS-only. Calling through `owner` keeps the receiver attached on every host.
- *
- *  `bridgeName` may be absent from the host object (optional ABI member) — that's the
- *  unsupported-host path, not an error. */
-export const _channelCall = (
-  owner: Record<string, any> | undefined, bridgeName: string, unsupportedError: string,
-  id: number, method: string, args: any[],
-): Promise<any> =>
-  new Promise((res, rej) => {
-    const bridge = owner?.[bridgeName] as ChannelCallBridge | undefined
-    if (typeof bridge !== "function") {
-      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)))
-  })

package/runtime/sdk/runtime/clipboard.ts

@@ -1,20 +0,0 @@
-// 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)
-  },
-  /** 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") {
-        reject(new Error("Clipboard is not supported on this platform"))
-        return
-      }
-      _creatorUtils.clipboardRead(resolve, (err: string) => reject(new Error(err)))
-    })
-  },
-}