lecodes-cli 0.16.1 → 0.16.2

package/runtime/sdk/gl/IK.ts

@@ -0,0 +1,170 @@
+// IK — precise character actions as late-phase aspects on BONES (docs/animation-plan.md §2.5).
+// They run after the animation wrote the pose (base anim or Animator) and before the skin is
+// flushed, so their bone writes land in the skin. Attach to the END bone of the chain; the chain is
+// walked up through parents — one instance per end effector, any Node hierarchy works.
+//
+//   const foot = hero.bone('LeftFoot')!
+//   foot.aspect(IK.TwoBone, { target: footTarget, pole: kneeHint })     // upLeg → leg → foot
+//   foot.ik.weight = grounded ? 1 : 0                                    // blend in/out
+//   hero.bone('Head')!.aspect(IK.LookAt, { target: camera, limit: 70 })  // head tracks the camera
+//
+// Pure SDK/JS: a handful of world-matrix reads + two quaternion writes per solve. A native solver can
+// slot in later behind the same API.
+
+import { Aspect } from "../core/Aspect"
+import { Vec3, type Vec3Like } from "../math/vec"
+import { Quat } from "../math/quat"
+import type { Node } from "./Node"
+
+type Target = Node | Vec3Like
+
+const targetPos = (t: Target | undefined): Vec3 | null => {
+  if (t === undefined || t === null) return null
+  const n = t as Node
+  if (typeof (n as { worldPosition?: unknown }).worldPosition === "object" && typeof n.id === "number") return n.worldPosition
+  return new Vec3(t as Vec3Like)
+}
+
+/** World rotation of a node (parent chain composed natively). */
+const worldRot = (n: Node): Quat => n.worldMatrix.rotation
+
+/** Write a WORLD rotation to a node by converting through the parent's world rotation. */
+const setWorldRot = (n: Node, q: Quat): void => {
+  const p = n.parent
+  n.quaternion = p ? worldRot(p).invert().mul(q).normalize() : q.normalize()
+}
+
+const clampAngle = (q: Quat, maxRad: number): Quat => {
+  // angle of a unit quaternion = 2·acos(|w|)
+  const w = Math.min(1, Math.abs(q.w))
+  const ang = 2 * Math.acos(w)
+  if (ang <= maxRad || ang < 1e-6) return q
+  const s = Math.sqrt(1 - w * w)
+  const axis = new Vec3(q.x / s, q.y / s, q.z / s)
+  return Quat.fromAxisAngle(axis, q.w < 0 ? -maxRad : maxRad)
+}
+
+/** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })`
+ *  solves upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend
+ *  (knee/elbow) — a Node or world point. */
+class TwoBone extends Aspect<"ik", Node> {
+  static readonly aspect = "ik"
+
+  /** Where the end bone should be (Node or world position). */
+  target?: Target
+  /** Bend hint — the mid joint is pulled toward it (Node or world position). */
+  pole?: Target
+  /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
+  weight = 1
+  /** Solve every frame (default). Set false to drive `solve()` yourself. */
+  enabled = true
+
+  update(): void {
+    if (this.enabled) this.solve()
+  }
+
+  /** One solve at the current pose. Safe to call manually (e.g. from a later-ordered aspect). */
+  solve(): void {
+    const t = targetPos(this.target)
+    if (!t || this.weight <= 0) return
+    const end = this.node
+    const mid = end.parent
+    const root = mid?.parent
+    if (!mid || !root) return
+
+    const w = Math.min(1, this.weight)
+    const midLocal0 = mid.quaternion
+    const rootLocal0 = root.quaternion
+
+    const a = root.worldPosition, b = mid.worldPosition, c = end.worldPosition
+    const l1 = a.distanceTo(b), l2 = b.distanceTo(c)
+    if (l1 < 1e-6 || l2 < 1e-6) return
+    const eps = 1e-4
+    const toT = t.sub(a)
+    const d = Math.min(Math.max(toT.length(), eps), l1 + l2 - eps)
+
+    // 1. bend the mid joint to the angle the target distance demands (law of cosines)
+    const ba = a.sub(b), bc = c.sub(b)
+    const cur = ba.angle(bc)
+    const want = Math.acos(Math.min(1, Math.max(-1, (l1 * l1 + l2 * l2 - d * d) / (2 * l1 * l2))))
+    let axis = bc.cross(ba)
+    if (axis.lengthSq() < 1e-10) {
+      // straight limb: bend toward the pole (or any perpendicular)
+      const p = targetPos(this.pole)
+      const ref = p ? p.sub(b) : new Vec3(0, 0, 1)
+      axis = ba.cross(ref)
+      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(0, 1, 0))
+      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(1, 0, 0))
+    }
+    axis = axis.normalize()
+    // rotating mid by (want - cur) about `axis` opens/closes the angle between ba and bc
+    const midWorld = worldRot(mid)
+    setWorldRot(mid, Quat.fromAxisAngle(axis, want - cur).mul(midWorld))
+
+    // 2. swing the root so the end lands on the target direction
+    const c2 = end.worldPosition
+    const rootWorld = worldRot(root)
+    setWorldRot(root, Quat.fromTo(c2.sub(a), toT).mul(rootWorld))
+
+    // 3. pole: spin the root about the root→target axis so the mid joint lies toward the pole
+    const p = targetPos(this.pole)
+    if (p) {
+      const dir = toT.normalize()
+      const b2 = mid.worldPosition
+      const midProj = b2.sub(a).sub(dir.scale(b2.sub(a).dot(dir)))
+      const poleProj = p.sub(a).sub(dir.scale(p.sub(a).dot(dir)))
+      if (midProj.lengthSq() > 1e-10 && poleProj.lengthSq() > 1e-10) {
+        setWorldRot(root, Quat.fromTo(midProj, poleProj).mul(worldRot(root)))
+      }
+    }
+
+    // 4. weight: blend from the animated pose to the solved one
+    if (w < 1) {
+      root.quaternion = rootLocal0.slerp(root.quaternion, w)
+      mid.quaternion = midLocal0.slerp(mid.quaternion, w)
+    }
+  }
+}
+
+/** Aim a bone at a target (head / eyes / turret). Attach to the bone itself:
+ *  `head.aspect(IK.LookAt, { target: camera, limit: 70 })`. `axis` is the bone's LOCAL forward
+ *  (the direction that should point at the target) — rigs differ; default −Z, Mixamo heads look
+ *  along +Z of the head bone in most exports, so pass `axis: [0, 0, 1]` there if it faces backwards. */
+class LookAt extends Aspect<"lookAt", Node> {
+  static readonly aspect = "lookAt"
+
+  target?: Target
+  /** The bone's local axis that should point at the target. */
+  axis: Vec3Like = [ 0, 0, -1 ]
+  /** Max deflection from the animated direction, in degrees (default 80). */
+  limit = 80
+  /** 0–1 contribution. */
+  weight = 1
+  enabled = true
+
+  update(): void {
+    if (this.enabled) this.solve()
+  }
+
+  solve(): void {
+    const t = targetPos(this.target)
+    if (!t || this.weight <= 0) return
+    const bone = this.node
+    const w = Math.min(1, this.weight)
+    const local0 = bone.quaternion
+    const from = bone.worldPosition
+    const dir = t.sub(from)
+    if (dir.lengthSq() < 1e-10) return
+    const rot = worldRot(bone)
+    const current = new Vec3(this.axis).rotate(rot)
+    let delta = Quat.fromTo(current, dir)
+    delta = clampAngle(delta, (this.limit * Math.PI) / 180)
+    setWorldRot(bone, delta.mul(rot))
+    if (w < 1) bone.quaternion = local0.slerp(bone.quaternion, w)
+  }
+}
+
+/** Inverse kinematics aspects — attach to bones (see file header). */
+export const IK = { TwoBone, LookAt }
+export type IKTwoBone = TwoBone
+export type IKLookAt = LookAt

package/runtime/sdk/gl/Material.ts

@@ -81,7 +81,7 @@ export class Material {
   readonly uniforms: Record<string, UniformValue>
 
   private _colorKey: string | null = null
-  private _useMapFlag = true
+  private _useMapFlag = false
 
   constructor(shader: FetchResponse | number) {
     if (typeof shader === "number") {

package/runtime/sdk/gl/ModelAnimation.ts

@@ -1,8 +1,12 @@
 // GLB skeletal animation as an aspect. Auto-attached by Model (a glb always has its clips), so you
 // reach it directly: model.anim.play('Run'). Clips come baked in the glb; play by name or index.
+// This is the BASE player (one clip at a time, Filament's Animator underneath). For crossfades,
+// blend spaces, layers and clips from other files attach the Animator aspect — it takes the skeleton
+// over while attached and this player is suspended (docs/animation-plan.md).
 
 import { Aspect } from "../core/Aspect"
 import { nodeRegistry } from "./Node"
+import { AnimationClip } from "./AnimationClip"
 import type { Model } from "./Model"
 
 let animatorRegistered = false
@@ -19,6 +23,8 @@ export class ModelAnimation extends Aspect<"anim", Model> {
   private _clip = 0
   private _speed = 1
   private _loop = false
+  private _suspended = false
+  private _clips?: AnimationClip[]
 
   onAttach(): void {
     this.node._animComplete = (clipIndex) => {
@@ -29,17 +35,41 @@ export class ModelAnimation extends Aspect<"anim", Model> {
     }
   }
 
-  /** The clips baked into the glb. */
-  get clips(): { name: string, duration: number }[] { return _creator.getGlbAnimations(this.node.id) }
+  /** The clips baked into the glb, as AnimationClip objects (usable in an Animator's clip table —
+   *  e.g. share one model's baked clip with another model of the same rig). */
+  get clips(): AnimationClip[] {
+    if (this._clips) return this._clips
+    const setId = typeof _creator.getGlbClipSet === "function" ? _creator.getGlbClipSet(this.node.id) : 0
+    if (setId) this._clips = AnimationClip._ofSet(setId)
+    else {
+      // no embedded set (older / lite hosts, or a GLB without animations): name + duration only
+      this._clips = ((_creator.getGlbAnimations(this.node.id) ?? []) as { name: string, duration: number }[])
+        .map((c) => ({ name: c.name, duration: c.duration, trackCount: 0 }) as unknown as AnimationClip)
+    }
+    return this._clips
+  }
+
+  /** @internal — an Animator owns the skeleton while attached; this player goes quiet. */
+  _suspend(on: boolean): void {
+    this._suspended = on
+    if (on && this._playing) { this._playing = false }
+  }
+  private _blocked(): boolean {
+    if (!this._suspended) return false
+    console.warn("model.anim is suspended while an Animator is attached — use model.animator")
+    return true
+  }
 
   get playing(): boolean { return this._playing }
   set playing(value: boolean) {
+    if (this._blocked()) return
     this._playing = value
     _creator.setAnimation(this.node.id, value, this._clip, this._speed)
   }
 
   /** Play a clip by name or index. Chainable. */
   play(clip?: string | number, options: { loop?: boolean } = {}): this {
+    if (this._blocked()) return this
     if (typeof clip === "number") this._clip = clip
     else if (typeof clip === "string") {
       const i = this.clips.findIndex((c) => c.name === clip)
@@ -57,8 +87,9 @@ export class ModelAnimation extends Aspect<"anim", Model> {
   get speed(): number { return this._speed }
   set speed(v: number) {
     this._speed = v
+    if (this._suspended) return
     _creator.setAnimation(this.node.id, this._playing, this._clip, v)
   }
   get time(): number { return _creator.getAnimationTime(this.node.id) }
-  set time(v: number) { _creator.setAnimationTime(this.node.id, this._clip, v) }
+  set time(v: number) { if (!this._blocked()) _creator.setAnimationTime(this.node.id, this._clip, v) }
 }

package/runtime/sdk/gl/Node.ts

@@ -47,6 +47,7 @@ export class Node extends AspectHost<NodeEvents> {
   private _lastSync = 0
   private _worldMatrix?: Float32Array
   private _scaleCache?: [number, number, number]
+  private _boneCache?: Map<string, Node | null>
 
   /** @internal — the active animation aspect's clip-complete handler (installed by ModelAnimation). */
   _animComplete?: (clipIndex: number) => boolean
@@ -178,6 +179,26 @@ export class Node extends AspectHost<NodeEvents> {
     callback(this)
     _creator.traverse(this.id, (id) => callback(nodeRegistry.get(id) ?? new Node(id)))
   }
+  /** Find a descendant by name — bones of a loaded Model included (`hero.bone('RightHand').add(sword)`).
+   *  Exact name first, then the part after the last `:` / `|` (Mixamo `mixamorig:Hips` matches `Hips`).
+   *  Cached per name; null if absent. */
+  bone(name: string): Node | null {
+    const cache = (this._boneCache ??= new Map<string, Node | null>())
+    const hit = cache.get(name)
+    if (hit !== undefined) return hit
+    let exact: Node | null = null
+    let loose: Node | null = null
+    const want = name.slice(name.search(/[^:|]*$/))
+    _creator.traverse(this.id, (id) => {
+      if (exact) return
+      const n = _creator.getName(id)
+      if (n === name) exact = nodeRegistry.get(id) ?? new Node(id)
+      else if (!loose && n.slice(n.search(/[^:|]*$/)) === want) loose = nodeRegistry.get(id) ?? new Node(id)
+    })
+    const found = exact ?? loose
+    cache.set(name, found)
+    return found
+  }
 
   // --- behaviors are aspects: node.aspect(Shape, …) / node.aspect(Physics, …) ---
 

package/runtime/sdk/inject.ts

@@ -34,6 +34,9 @@ export { localStorage } from "./runtime/storage"
 export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
 export { Input } from "./runtime/input"
 export { WebSocket } from "./runtime/net"
+// App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
+// only ever imports its server functions (docs/backend-plan.md §4).
+export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"
 export { openFilePicker } from "./runtime/files"
 export { share } from "./runtime/share"
@@ -115,6 +118,7 @@ export { QRScanner } from "./plugins/qr"
 export { CameraView, type CameraFacing } from "./plugins/camera"
 export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/geolocation"
 export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/push"
+export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/oauth"
 export { Service } from "./plugins/service"
 
 // ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
@@ -139,6 +143,12 @@ export { Physics } from "./gl/Physics"
 export { Trigger } from "./gl/Trigger"
 export { CharacterController } from "./gl/CharacterController"
 export { ModelAnimation } from "./gl/ModelAnimation"
+export { AnimationClip } from "./gl/AnimationClip"
+export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/AnimationClip"
+export { Animator } from "./gl/Animator"
+export type { AnimatorPlayOptions } from "./gl/Animator"
+export { IK } from "./gl/IK"
+export type { IKTwoBone, IKLookAt } from "./gl/IK"
 export { Light } from "./gl/Light"
 export { Material } from "./gl/Material"
 export { Geometry } from "./gl/Geometry"

package/runtime/sdk/plugins/oauth.ts

@@ -0,0 +1,61 @@
+// 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/runtime/rpc.ts

@@ -0,0 +1,218 @@
+/**
+ * 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/server/auth/appConfig.ts

@@ -0,0 +1,12 @@
+/**
+ * The project's `app.json` subset the server runtime reads (name, auth providers).
+ *
+ * This module is a placeholder the COMPILER REPLACES: `compileServerBundle({ app })` puts a module with the
+ * real values at this same path in chisel's file map (project files win over SDK files), so every SDK module
+ * that imports `app` gets the project's config as a plain dependency — no globals, no evaluation-order games.
+ * Outside a compiled bundle (tests, tooling) `globalThis.__lecodesApp` can stand in.
+ */
+export type AuthProvider = "email" | "google" | "apple" | "yandex" | "vk"
+export type AppConfig = { name?: string, auth?: { providers?: AuthProvider[] } }
+
+export const app: AppConfig = {}