lecodes-sdk 1.2.0 → 2.0.1

package/src/compile/__tests__/serverSplit.test.ts

@@ -1,27 +0,0 @@
-import { test, expect } from "bun:test"
-import { compileServerBundle } from "../serverSplit"
-
-// The server bundle's file map is the whole project (a server module may import shared code), and
-// the bundler checks every `asset()` in that map. Seen live 2026-09-17: a Figma-exported design next
-// to app.server.ts failed the SERVER build with "asset not found: ../assets/figma/…" because the
-// map had the screens but not the binaries. Binaries are stubbed, design/ stays out.
-
-const text = (path: string, t: string) => ({ path, type: "text" as const, text: t })
-const res = (path: string) => ({ path, type: "resource" as const, fileSrc: "/uploads/x.bin" })
-
-test("a client screen's asset() does not break the server bundle", async () => {
-  const out = await compileServerBundle({
-    validate: false,
-    entries: [
-      text("/app.server.ts", "export const ping = async () => 1\n"),
-      text("/main.ts", "import { ping } from './app.server'\nconst hero = asset('./hero.png')\nping()\n"),
-      res("/hero.png"),
-      text("/design/screens/a4-40.ts", "export default UIScreen([ UIImage(asset('../assets/figma/a4-40/rectangle.png')), UIImage(asset('../assets/figma/a4-40/logo.svg')) ])\n"),
-      res("/design/assets/figma/a4-40/rectangle.png"),
-      text("/design/assets/figma/a4-40/logo.svg", "<svg/>"),
-    ],
-  })
-  expect(out).not.toBeNull()
-  expect(out!.code).toContain("ping")
-  expect(Object.keys(out!.manifest.modules)).toEqual(["app.server.ts"])
-})

package/src/core/__tests__/stateMachine.test.ts

@@ -1,132 +0,0 @@
-import { describe, expect, test } from "bun:test"
-import { StateMachine, defineStates } from "../StateMachine"
-
-type Bot = { hp: number; target: boolean; visible: boolean; dist: number; lost: number; fire: boolean; log: string[] }
-const makeBot = (): Bot => ({ hp: 100, target: false, visible: false, dist: 99, lost: 0, fire: false, log: [] })
-
-const Guard = defineStates<Bot>({
-  initial: "patrol",
-  on: { hit: "flinch" },
-  to: { dead: (b) => b.hp <= 0 },
-  states: {
-    patrol: { enter: (b) => b.log.push("enter patrol"), exit: (b) => b.log.push("exit patrol"), to: { combat: (b) => b.target } },
-    combat: {
-      initial: "engage",
-      enter: (b) => b.log.push("enter combat"),
-      exit: (b) => b.log.push("exit combat"),
-      to: { search: (b) => b.lost > 4 },
-      states: {
-        engage: { enter: (b) => b.log.push("enter engage"), exit: (b) => b.log.push("exit engage"), to: { shoot: (b) => b.visible && b.dist < 12 } },
-        shoot: {
-          enter: (b) => { b.fire = true; b.log.push("enter shoot") },
-          exit: (b) => { b.fire = false; b.log.push("exit shoot") },
-          to: { engage: (b) => !b.visible },
-          on: { hit: (b) => (b.hp < 30 ? "combat.engage" : undefined) },
-        },
-      },
-    },
-    search: { after: [6, "patrol"], enter: (b) => b.log.push("enter search") },
-    flinch: { after: [0.2, "$back"], enter: (b) => b.log.push("enter flinch"), exit: (b) => b.log.push("exit flinch") },
-    dead: { enter: (b) => b.log.push("enter dead") },
-  },
-})
-
-const DT = 1 / 60
-
-describe("StateMachine", () => {
-  test("enters the initial state and follows guards into nested states", () => {
-    const bot = makeBot()
-    const fsm = new StateMachine(Guard, bot)
-    expect(fsm.state).toBe("patrol")
-    expect(bot.log).toEqual(["enter patrol"])
-    fsm.step(DT)
-    expect(fsm.state).toBe("patrol")
-    bot.target = true
-    fsm.step(DT)
-    expect(fsm.state).toBe("combat.engage")
-    expect(bot.log.slice(-3)).toEqual(["exit patrol", "enter combat", "enter engage"])
-    expect(fsm.is("combat")).toBe(true)
-    expect(fsm.is("engage")).toBe(true)
-    expect(fsm.is("patrol")).toBe(false)
-  })
-
-  test("a sibling transition exits and enters only the leaves", () => {
-    const bot = makeBot()
-    const fsm = new StateMachine(Guard, bot)
-    bot.target = true
-    fsm.step(DT)
-    bot.visible = true
-    bot.dist = 5
-    fsm.step(DT)
-    expect(fsm.state).toBe("combat.shoot")
-    expect(bot.fire).toBe(true)
-    expect(bot.log.slice(-2)).toEqual(["exit engage", "enter shoot"])
-  })
-
-  test("events: innermost handler wins, the root's `on` is the fallback, $back restores the previous leaf", () => {
-    const bot = makeBot()
-    const fsm = new StateMachine(Guard, bot)
-    bot.target = true; fsm.step(DT)
-    bot.visible = true; bot.dist = 5; fsm.step(DT)
-    // handled by shoot (returns undefined → stays), the root's handler is NOT consulted
-    expect(fsm.send("hit")).toBe(true)
-    expect(fsm.state).toBe("combat.shoot")
-    bot.hp = 20
-    expect(fsm.send("hit")).toBe(true)
-    expect(fsm.state).toBe("combat.engage")
-    // engage has no handler → root → flinch, leaving combat
-    bot.visible = false
-    fsm.send("hit")
-    expect(fsm.state).toBe("flinch")
-    expect(bot.log.slice(-3)).toEqual(["exit engage", "exit combat", "enter flinch"])
-    for (let i = 0; i < 13; i++) fsm.step(DT)
-    expect(fsm.state).toBe("combat.engage")
-    expect(bot.log.slice(-3)).toEqual(["exit flinch", "enter combat", "enter engage"])
-    expect(fsm.previous).toBe("flinch")
-  })
-
-  test("compound guards, timed transitions, clocks", () => {
-    const bot = makeBot()
-    const fsm = new StateMachine(Guard, bot)
-    bot.target = true; fsm.step(DT)
-    bot.lost = 5
-    fsm.step(DT)
-    expect(fsm.state).toBe("search")
-    bot.target = false; bot.lost = 0
-    for (let i = 0; i < 361; i++) fsm.step(DT)
-    expect(fsm.state).toBe("patrol")
-    expect(fsm.time).toBeLessThan(0.05)
-  })
-
-  test("go() re-enters the current state; guards never re-enter an active state", () => {
-    const bot = makeBot()
-    const fsm = new StateMachine(Guard, bot)
-    bot.log.length = 0
-    fsm.go("patrol")
-    expect(bot.log).toEqual(["exit patrol", "enter patrol"])
-    bot.hp = 0
-    bot.target = true
-    const changes: string[] = []
-    fsm.on("change", (to, from) => changes.push(`${from}>${to}`))
-    fsm.step(DT)   // the any-state `dead` guard beats patrol→combat
-    expect(fsm.state).toBe("dead")
-    fsm.step(DT); fsm.step(DT)
-    expect(changes).toEqual(["patrol>dead"])   // no dead>dead re-entries while the guard stays true
-  })
-
-  test("unknown targets throw when the machine is built", () => {
-    expect(() => new StateMachine(defineStates<{}>({ initial: "a", states: { a: { to: { nowhere: () => true } } } }), {})).toThrow(/unknown state 'nowhere'/)
-    expect(() => new StateMachine(defineStates<{}>({ initial: "zzz", states: { a: {} } }), {})).toThrow()
-  })
-
-  test("pass-through states chain within one step; update may return a target", () => {
-    const chain = new StateMachine(defineStates<{}>({ initial: "a", states: { a: { to: { b: () => true } }, b: { to: { c: () => true } }, c: {} } }), {})
-    chain.step(0)
-    expect(chain.state).toBe("c")
-    const upd = new StateMachine(defineStates<{ n: number }>({ initial: "a", states: { a: { update: (c) => (++c.n >= 3 ? "b" : undefined) }, b: {} } }), { n: 0 })
-    upd.step(0); upd.step(0)
-    expect(upd.state).toBe("a")
-    upd.step(0)
-    expect(upd.state).toBe("b")
-  })
-})

package/src/core/registry.ts

@@ -1,23 +0,0 @@
-// Maps a native handle (the integer id the engine returns) back to its JS wrapper, so callbacks
-// the host fires by id (animation events, touch hits, media events) can be routed to the owning
-// object. Each engine/domain keeps its own Registry instance.
-
-export class Registry<T> {
-  private map = new Map<number, T>()
-
-  set(id: number, value: T): void {
-    this.map.set(id, value)
-  }
-
-  get(id: number): T | undefined {
-    return this.map.get(id)
-  }
-
-  delete(id: number): void {
-    this.map.delete(id)
-  }
-
-  has(id: number): boolean {
-    return this.map.has(id)
-  }
-}

package/src/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/src/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/src/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
-})()