lecodes-cli 0.19.0 → 0.20.0

package/runtime/sdk/runtime/misc.ts

@@ -1,16 +0,0 @@
-// Small platform globals that are real (not engine-specific). Grown in Phase 1.
-
-/** Show a transient toast notification. */
-export const toast = (msg: string): void => _creatorUI.toast(msg)
-
-/** Open `url` in the system browser / external handler (fire-and-forget, like `share`). Silent
- *  no-op on hosts without one (headless). */
-export const openURL = (url: string): void => _creatorUtils.openUrl?.(url)
-
-export type SvgSourceValue = {
-  readonly svg: string
-  tintColor: string | null
-}
-
-/** Wrap raw SVG XML so it can be used as an image source. */
-export const SvgSource = (svg: string): SvgSourceValue => ({ svg, tintColor: null })

package/runtime/sdk/runtime/net.ts

@@ -1,36 +0,0 @@
-// WebSocket over the host bridge. Same event surface as the browser's (open/message/close/error)
-// via the shared Emitter. Ported from worker/src/WebSocket.ts.
-
-import { Emitter } from "../core/events"
-
-type SocketEvents = {
-  open: () => void
-  message: (data: any) => void
-  close: (code?: number) => void
-  error: () => void
-}
-
-export class WebSocket extends Emitter<SocketEvents> {
-  private _id: number | null = null
-
-  constructor(url: string, headers?: Record<string, string>) {
-    super()
-    this._id = _creatorUtils.websocketOpen(url, (channel, data) => this._onMessage(channel, data), headers)
-  }
-
-  send(message: string | ArrayBuffer): void {
-    if (this._id !== null) _creatorUtils.websocketSend(this._id, message)
-  }
-
-  close(): void {
-    if (this._id !== null) {
-      _creatorUtils.websocketClose(this._id)
-      this._id = null
-    }
-  }
-
-  private _onMessage(channel: string, data: any): void {
-    if (data !== undefined && data !== null) this.dispatch(channel as keyof SocketEvents, data)
-    else this.dispatch(channel as keyof SocketEvents)
-  }
-}

package/runtime/sdk/runtime/rpc.ts

@@ -1,218 +0,0 @@
-/**
- * Client transport for the app backend (docs/backend-plan.md §3.2 / §3.3). The compiler replaces
- * every `*.server.ts` module in the client bundle with a stub whose exports are built by the three
- * globals below — user code never calls them; it imports the server function and calls it.
- *
- *   export const listNotes = __rpc("<serverUrl>", "notes.server.ts#listNotes")
- *   export const chat      = __channel("<serverUrl>", "chat.server.ts#chat")
- *   export const db        = __serverOnly("schema.server.ts#db")
- *
- * Wire (implemented by the runner):
- *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known
- *   → 200 {"ok":true,"result":…,"session"?:"…"} | {"ok":false,"status":n,"message":"…","session"?:"…"}
- *   WS   <serverUrl>/ws  frames: → {t:"hello",session} {t:"sub",id,ch,topic} {t:"unsub",id}
- *                                ← {t:"session",session} {t:"ok",id} {t:"err",id,status,message} {t:"ev",ch,topic,event,data}
- *   (`ev` is addressed by channel + topic, not by subscription id, so the server can fan one publish out
- *   to every socket of a topic natively; the client delivers it to each matching subscription.)
- *
- * The session token is transport-owned (cookie-like): stored under `lecodes.session:<serverUrl>` in
- * localStorage, sent on every call and on the socket, replaced whenever a response carries `session`.
- * User code never sees it — "am I logged in" is an endpoint (`me()`), see the plan.
- */
-
-import { fetch } from "./fetch"
-import { localStorage } from "./storage"
-import { WebSocket } from "./net"
-
-/** Rejection value of a failed endpoint call: `status` mirrors the server's `ApiError`
- *  (0 = the request itself failed: no network / no server). */
-export class RpcError extends Error {
-  readonly status: number
-  constructor(status: number, message: string) {
-    super(message)
-    this.name = "RpcError"
-    this.status = status
-  }
-}
-
-// ───────────────────────────── session token ─────────────────────────────
-
-const sessionKey = (serverUrl: string) => `lecodes.session:${serverUrl}`
-const getSession = (serverUrl: string): string | null => {
-  try { return localStorage.getItem(sessionKey(serverUrl)) } catch { return null }
-}
-const setSession = (serverUrl: string, token: string | null) => {
-  try {
-    if (token) localStorage.setItem(sessionKey(serverUrl), token)
-    else localStorage.removeItem(sessionKey(serverUrl))
-  } catch { /* storage-less host: the session lives for this run only */ }
-  sockets.get(serverUrl)?.onSessionChanged(token)
-}
-
-// ───────────────────────────── endpoints ─────────────────────────────
-
-const noServer = (id: string) => new RpcError(0, `Endpoint ${id}: the project has no deployed server (compile with serverUrl)`)
-
-/** Build the client proxy of endpoint `id`. Positional args travel as a JSON array. */
-export const __rpc = (serverUrl: string, id: string) => {
-  const call = async (...args: unknown[]): Promise<any> => {
-    if (!serverUrl) throw noServer(id)
-    const headers: Record<string, string> = { "content-type": "application/json" }
-    const session = getSession(serverUrl)
-    if (session) headers.authorization = `Bearer ${session}`
-    let res
-    try {
-      res = await fetch(`${serverUrl}/api/${encodeURIComponent(id)}`, { method: "POST", headers, body: JSON.stringify({ args }) })
-    } catch (e) {
-      throw new RpcError(0, `Endpoint ${id}: request failed (${(e as Error)?.message ?? e})`)
-    }
-    let body: any
-    try { body = res.json() } catch { body = null }
-    res.dispose()
-    if (body && typeof body === "object" && "session" in body) setSession(serverUrl, body.session ?? null)
-    if (body && body.ok === true) return body.result
-    if (body && body.ok === false) throw new RpcError(body.status ?? res.status, body.message ?? "")
-    throw new RpcError(res.status, `Endpoint ${id}: unexpected response (HTTP ${res.status})`)
-  }
-  return call
-}
-
-/** A server-only export (db, models, helpers) referenced from client code: any use throws. */
-export const __serverOnly = (id: string): any =>
-  new Proxy(function () {} as any, {
-    get: (_t, prop) => { if (prop === "then") return undefined; throw new RpcError(0, `${id} is server-only — it can't be used in client code`) },
-    apply: () => { throw new RpcError(0, `${id} is server-only — it can't be used in client code`) },
-  })
-
-// ───────────────────────────── channels ─────────────────────────────
-
-type Handlers = Record<string, ((payload: any) => void) | undefined> & {
-  /** The socket dropped and came back: subscriptions were re-sent, but events in between are lost — refetch. */
-  reconnect?: () => void
-  /** The subscription was refused (`onJoin` threw) or the socket can't connect. */
-  error?: (e: RpcError) => void
-}
-type Sub = { id: number, ch: string, topic: string, handlers: Handlers, ready: boolean }
-
-const BACKOFF_MS = [1000, 2000, 5000, 10000, 30000]
-
-/** One multiplexed socket per server URL, shared by every channel of the app. */
-class ChannelSocket {
-  private ws: WebSocket | null = null
-  private open = false
-  private subs = new Map<number, Sub>()
-  private nextId = 1
-  private attempts = 0
-  private timer: ReturnType<typeof setTimeout> | null = null
-  private closedByUs = false
-  private everOpened = false
-  private serverUrl: string
-
-  constructor(serverUrl: string) { this.serverUrl = serverUrl }
-
-  subscribe(ch: string, topic: string, handlers: Handlers): { close(): void } {
-    const sub: Sub = { id: this.nextId++, ch, topic, handlers, ready: false }
-    this.subs.set(sub.id, sub)
-    if (this.open) this.send({ t: "sub", id: sub.id, ch, topic })
-    else this.connect()
-    return {
-      close: () => {
-        if (!this.subs.delete(sub.id)) return
-        if (this.open) this.send({ t: "unsub", id: sub.id })
-        if (this.subs.size === 0) this.shutdown()
-      },
-    }
-  }
-
-  onSessionChanged(token: string | null) {
-    if (this.open) this.send({ t: "hello", session: token })
-  }
-
-  private connect() {
-    if (this.ws || this.timer !== null) return
-    this.closedByUs = false
-    const url = this.serverUrl.replace(/^http/, "ws") + "/ws"
-    const session = getSession(this.serverUrl)
-    const ws = new WebSocket(url, session ? { authorization: `Bearer ${session}` } : undefined)
-    this.ws = ws
-    ws.addEventListener("open", () => {
-      this.open = true
-      this.attempts = 0
-      this.send({ t: "hello", session: getSession(this.serverUrl) })
-      const reconnected = this.everOpened
-      this.everOpened = true
-      for (const sub of this.subs.values()) {
-        sub.ready = false
-        this.send({ t: "sub", id: sub.id, ch: sub.ch, topic: sub.topic })
-        if (reconnected) sub.handlers.reconnect?.()
-      }
-    })
-    ws.addEventListener("message", (data) => {
-      if (typeof data !== "string") return
-      let msg: any
-      try { msg = JSON.parse(data) } catch { return }
-      this.onFrame(msg)
-    })
-    const onDown = () => {
-      if (this.ws !== ws) return
-      this.ws = null
-      this.open = false
-      if (this.closedByUs || this.subs.size === 0) return
-      const delay = BACKOFF_MS[Math.min(this.attempts++, BACKOFF_MS.length - 1)]
-      this.timer = setTimeout(() => { this.timer = null; this.connect() }, delay)
-    }
-    ws.addEventListener("close", onDown)
-    ws.addEventListener("error", onDown)
-  }
-
-  private onFrame(msg: any) {
-    switch (msg?.t) {
-      case "session": setSession(this.serverUrl, msg.session ?? null); break
-      case "ok": { const s = this.subs.get(msg.id); if (s) s.ready = true; break }
-      case "err": {
-        const s = this.subs.get(msg.id)
-        if (!s) break
-        this.subs.delete(msg.id)
-        s.handlers.error?.(new RpcError(msg.status ?? 0, msg.message ?? "subscription refused"))
-        break
-      }
-      case "ev": {
-        for (const s of this.subs.values()) {
-          if (s.ch === msg.ch && s.topic === msg.topic) s.handlers[msg.event]?.(msg.data)
-        }
-        break
-      }
-    }
-  }
-
-  private send(frame: unknown) { this.ws?.send(JSON.stringify(frame)) }
-
-  private shutdown() {
-    this.closedByUs = true
-    if (this.timer !== null) { clearTimeout(this.timer); this.timer = null }
-    this.ws?.close()
-    this.ws = null
-    this.open = false
-    sockets.delete(this.serverUrl)
-  }
-}
-
-const sockets = new Map<string, ChannelSocket>()
-const socketFor = (serverUrl: string) => {
-  let s = sockets.get(serverUrl)
-  if (!s) { s = new ChannelSocket(serverUrl); sockets.set(serverUrl, s) }
-  return s
-}
-
-export interface ClientChannel<E extends Record<string, unknown> = Record<string, unknown>> {
-  /** Subscribe to `topic`; handlers are keyed by event name (+ `reconnect`/`error`). Returns `{ close }`. */
-  subscribe(topic: string, handlers: { [K in keyof E]?: (payload: E[K]) => void } & { reconnect?: () => void, error?: (e: RpcError) => void }): { close(): void }
-}
-
-/** Build the client proxy of channel `id`. */
-export const __channel = (serverUrl: string, id: string): ClientChannel<any> => ({
-  subscribe(topic, handlers) {
-    if (!serverUrl) throw noServer(id)
-    return socketFor(serverUrl).subscribe(id, topic, handlers as Handlers)
-  },
-})

package/runtime/sdk/runtime/service.ts

@@ -1,83 +0,0 @@
-// A host-registered headless service (geolocation, bluetooth, contacts, …) — the UI-less sibling
-// of NativeView (docs/service-channel-plan.md). The host registers a *capability*
-// (`registerService("geolocation") { params, channel -> ... }`); the SDK talks to it over the
-// shared JSON call/event protocol (runtime/channel.ts) via `_creatorUtils.service*`.
-//
-// Not a public global itself: apps meet services through typed plugin wrappers (Geolocation —
-// src/plugins/) or the raw `Service(name)` global (src/plugins/service.ts), both thin layers
-// over this exactly like QRScanner wraps NativeViewElement.
-
-import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "./channel"
-
-/** @internal Base for typed service plugins. The host session opens lazily on the first `call()`
- *  (`on()` only records listeners), and `close()` releases it — a later `call()` reopens a fresh
- *  session. Session ids are host-allocated (websocket model): the `onEvent` callback is handed
- *  over at open, so no SDK-side ref registry is needed. */
-export class ServiceClient {
-  readonly serviceName: string
-  readonly params: any
-  private _serviceId: number | null = null
-  private readonly _listeners: ChannelListeners = {}
-
-  constructor(serviceName: string, params: any = {}) {
-    this.serviceName = serviceName
-    this.params = params
-  }
-
-  /** Whether this host registered a `registerService` factory under `name`. */
-  static isSupported(name: string): boolean {
-    return typeof _creatorUtils !== "undefined" && typeof _creatorUtils.isServiceSupported === "function"
-      && _creatorUtils.isServiceSupported(name)
-  }
-
-  /** @internal open (or reuse) the host session; throws when the host has no channel/factory. */
-  private _ensureOpen(): number {
-    if (this._serviceId !== null) return this._serviceId
-    if (typeof _creatorUtils === "undefined" || typeof _creatorUtils.serviceOpen !== "function") {
-      throw new Error(`Service("${this.serviceName}") is not supported on this host (requires _creatorUtils.serviceOpen)`)
-    }
-    const id = _creatorUtils.serviceOpen(this.serviceName, JSON.stringify(this.params ?? {}),
-      (event: string, dataJson?: string) => _channelEmit(this._listeners, event, dataJson))
-    if (id < 0) {
-      throw new Error(`Service("${this.serviceName}") is not registered on this host`)
-    }
-    this._serviceId = id
-    return id
-  }
-
-  /** Invoke a method on the service (`geo.call("getCurrent", options)`). Args and the result are
-   *  JSON-serialized. Rejects if the host has no such service/method. */
-  call(method: string, ...args: any[]): Promise<any> {
-    let id: number
-    try {
-      id = this._ensureOpen()
-    } catch (e) {
-      return Promise.reject(e)
-    }
-    return _channelCall(
-      typeof _creatorUtils !== "undefined" ? _creatorUtils : undefined, "serviceCall",
-      `Service("${this.serviceName}") is not supported on this host (requires _creatorUtils.serviceCall)`,
-      id, method, args)
-  }
-
-  /** Subscribe to an event the service emits (`geo.on("position", cb)`). */
-  on(event: string, callback: (data?: any) => void): this {
-    _channelOn(this._listeners, event, callback)
-    return this
-  }
-  off(event: string, callback: (data?: any) => void): this {
-    _channelOff(this._listeners, event, callback)
-    return 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 {
-    if (this._serviceId === null) return
-    const id = this._serviceId
-    this._serviceId = null
-    if (typeof _creatorUtils !== "undefined" && typeof _creatorUtils.serviceClose === "function") {
-      _creatorUtils.serviceClose(id)
-    }
-  }
-}

package/runtime/sdk/runtime/share.ts

@@ -1,9 +0,0 @@
-// Share a media File (image/video) via the OS share sheet. Wraps `_creatorUtils.shareMedia`, which
-// takes the host buffer id behind the File. On iOS the sheet also lets the user save to Files/Photos;
-// on web it saves (downloads) the file. `text` is an optional caption/message.
-
-import type { File, FetchResponse } from "./fetch"
-
-export function share(media: File | FetchResponse, text?: string): void {
-  _creatorUtils.shareMedia((media as any)._id, text)
-}

package/runtime/sdk/runtime/storage.ts

@@ -1,13 +0,0 @@
-// Key/value persistence backed by the host. Same shape as the web localStorage subset projects use.
-
-export const localStorage = {
-  getItem(key: string): string | null {
-    return _creatorUtils.localStorageGetValue(key)
-  },
-  setItem(key: string, value: string): void {
-    _creatorUtils.localStorageSetValue(key, value)
-  },
-  removeItem(key: string): void {
-    _creatorUtils.localStorageRemoveValue(key)
-  },
-}

package/runtime/sdk/runtime/touch.ts

@@ -1,76 +0,0 @@
-// Pointer event objects delivered to 3D scene/node touch handlers. Ported from worker/src/TouchEvent.ts.
-// The dispatch wiring (reading the active scene, hit entity) is set up in Phase 4 with the 3D Scene;
-// these classes are the injected globals user code receives. `target` is the hit Node (typed loosely
-// here to avoid a forward dependency on gl/).
-
-export class ClickEvent<T = any> {
-  readonly type = "click"
-  readonly pointerId: number
-  readonly clientX: number
-  readonly clientY: number
-  /** World-space hit position (2D scenes only; undefined in 3D). */
-  worldX?: number
-  worldY?: number
-  target!: T
-  constructor(clientX: number, clientY: number, pointerId: number) {
-    this.clientX = clientX
-    this.clientY = clientY
-    this.pointerId = pointerId
-  }
-}
-
-export interface TrackHandler {
-  onMove?(pos: { clientX: number, clientY: number, deltaX: number, deltaY: number }): void
-  onEnd?(pos: { clientX: number, clientY: number, deltaX: number, deltaY: number }): void
-  onCancel?(): void
-  claim?: boolean | "pan-x" | "pan-y" | "pan-down" | "pan-up" | "pan-left" | "pan-right"
-}
-
-export class TouchStartEvent<T = any> {
-  readonly type = "touchstart"
-  readonly pointerId: number
-  readonly clientX: number
-  readonly clientY: number
-  /** World-space hit position (2D scenes only; undefined in 3D). */
-  worldX?: number
-  worldY?: number
-  target!: T
-  /** @internal — read by the dispatch system after the handler runs. */
-  _trackHandler?: TrackHandler
-  constructor(clientX: number, clientY: number, pointerId: number) {
-    this.clientX = clientX
-    this.clientY = clientY
-    this.pointerId = pointerId
-  }
-
-  /** Capture subsequent moves/end for this pointer (drag/pan gestures). */
-  track(handler: TrackHandler): void {
-    this._trackHandler = handler
-  }
-}
-
-/** Delivered to a `UIButton` `onLongPress` handler when a finger is held on the button past the
- *  host's long-press threshold. Like `TouchStartEvent` it can `track(...)` the rest of the gesture —
- *  so the common "press-and-hold, then drag to move" flow is one handler: start the drag from here. */
-export class LongPressEvent<T = any> {
-  readonly type = "longpress"
-  readonly pointerId: number
-  readonly clientX: number
-  readonly clientY: number
-  /** World-space hit position (2D scenes only; undefined in 3D). */
-  worldX?: number
-  worldY?: number
-  target!: T
-  /** @internal — read by the dispatch system after the handler runs. */
-  _trackHandler?: TrackHandler
-  constructor(clientX: number, clientY: number, pointerId: number) {
-    this.clientX = clientX
-    this.clientY = clientY
-    this.pointerId = pointerId
-  }
-
-  /** Capture subsequent moves/end for this pointer — drag the element after the hold. */
-  track(handler: TrackHandler): void {
-    this._trackHandler = handler
-  }
-}