lecodes-sdk 2.0.4 → 2.0.6

package/README.md

@@ -1,52 +1,76 @@
-# sdk — the unified, import-free scripting API
+# lecodes-sdk — the import-free LeCodes API
 
-One coherent, **import-free** syntax for le.codes projects across **2D** (creator-2d), **3D**
-(creator-gl), **UI** (creator-ui), and the platform runtime. The whole library is delivered through
-esbuild's `inject()`, so user code uses globals (`Scene`, `Sprite`, `Mesh`, `UIScreen`, `setLoop`, …)
-with **no imports**; tree-shaking drops whatever a project doesn't use.
+The TypeScript API LeCodes apps are written against: **UI**, **2D**, **3D** and the platform
+runtime (network, storage, input, audio, device, plugins) in one surface of **globals** — user code
+writes `UIScreen`, `Scene`, `Sprite`, `fetch`, … with **no imports**. The `lecodes` CLI compiles a
+project through this package into one `app.js`; the bundler (chisel) keeps only the methods a
+project reaches, so a UI app carries no 3D code and a 2D game no UI kit. The same bundle runs on
+the LeCodes hosts: desktop, iOS, Android and the web player.
 
-Replaces the `worker` package. See [PLAN.md](./PLAN.md) for the full design and build log.
+**API reference:** [docs/index.md](./docs/index.md) — every global, example-first; how to build
+a whole thing out of it is the [cookbook](./docs/cookbook/README.md). `bun run docs:check` verifies
+that every global has exactly one page and that the links resolve.
 
-**API reference:** the complete, curated docs live in [docs/](./docs/index.md) — every global, every
-method, example-first. Run `bun run docs:check` to verify coverage + links.
+```ts
+// UI — no imports
+let taps = 0
+const label = UIText('Taps: 0').style({ color: '#fff', fontSize: 22 })
+
+UIScreen(
+  label,
+  UIButton(UIText('Tap me').style({ color: '#fff' }))
+    .style({ bgColor: '#4f7cff', borderRadius: 12, p: 16, $pressed: { opacity: 0.8 } })
+    .onClick(() => { label.text = `Taps: ${++taps}` }),
+)
+  .style({ bgColor: '#1e2230', alignItems: 'center', justifyContent: 'center', gap: 16 })
+  .open()
+```
 
 ```ts
-// 2D — no imports
-const scene = new Scene2D({ background: '#10131a' })
-const player = new Sprite({ texture: await Texture2D.load(asset('hero.png')), anchor: [0.5, 1] })
-  .clips({ size: [32, 48], idle: [0, 1, 2, 3], walk: [4, 5, 6, 7] })
-player.play('idle')
-scene.add(player); scene.open()
-scene.camera.follow(player, { smooth: 0.15 })
-setLoop(dt => { if (Input.key('ArrowRight')) { player.x += 120 * dt; player.play('walk') } })
-
-// 3D — no imports
-const world = new Scene({ bloom: true })
-const ball = Mesh.sphere({ radius: 0.5, material: Material.lit({ color: '#e33' }), position: [0, 5, 0] })
-  .physics({ motion: 'dynamic', shape: { type: 'sphere', radius: 0.5 } })
-world.add(ball, Light.sun({ castShadows: true }))
-world.camera.position = [0, 6, 12]; world.camera.lookAt([0, 0, 0])
-world.open()
-setLoop(() => { if (Input.key('Space')) ball.body.applyImpulse([0, 6, 0]) })
+// 3D — no imports; behaviour is an Aspect attached to a node
+Physics.configure({ gravity: [0, -9.81, 0] })
+
+class Turn extends Aspect<'turn'> {
+  speed = 90                                  // degrees per second
+  private angle = 0
+  protected update(dt: number) {              // every frame; dt = game seconds
+    this.angle += this.speed * dt
+    this.node.eulerAngles = [0, this.angle, 0]
+  }
+}
+
+const scene = new Scene({ skybox: '#10131a' })
+const mat = Material.lit({ color: '#e33' })
+const ground = Mesh.box({ material: mat, scale: [10, 0.2, 10] })
+  .aspect(Shape, {})                          // a box collider fitted to the mesh
+  .aspect(Physics, { motion: 'static' })
+const ball = Mesh.sphere({ material: mat, position: [0, 5, 0] })
+  .aspect(Shape, {})
+  .aspect(Physics, { mass: 1 })               // dynamic: the physics step moves it
+const cube = Mesh.box({ material: mat, position: [2, 1, 0] })
+  .aspect(Turn, { speed: 180 })               // cube.turn is the attached aspect
+scene.add(ground, ball, cube, Light.sun())
+scene.camera.position = [0, 6, 12]
+scene.camera.lookAt([0, 0, 0])
+scene.open()
 ```
 
 ## Fluent math (`Vec2` / `Vec3` / `Quat` / `Mat4`)
 
-Per-frame math reads like the formula — no imports, no out-params. Vectors are *mutable structs with
-pure methods*: fields are settable (`v.x = 3`, `v.set(…)`), but every method returns a NEW value and
-never mutates its source. They're iterable and accept raw tuples anywhere, so `[0, 1, 0]` works wherever
-a vector does.
+Per-frame math reads like the formula — no out-params. Vectors are *mutable structs with pure
+methods*: fields are settable (`v.x = 3`, `v.set(…)`), but every method returns a NEW value and
+never mutates its source. They are iterable and accept raw tuples anywhere, so `[0, 1, 0]` works
+wherever a vector does.
 
 ```ts
-const dir  = target.position.sub(self.position).normalize()
+const dir = target.position.sub(self.position).normalize()
 self.position = self.position.add(dir.scale(speed * dt))
 if (a.distanceTo(b) < 2) explode()
 node.quaternion = node.quaternion.mul(Quat.fromAxisAngle(Vec3.up, turn))
 
-// the node API returns fresh copies (value semantics, like Unity):
-node.x = 3                                   // loud single-axis nudge
-const p = node.position; p.y = 5; node.position = p   // local-mutate, then assign back
-// node.position.x = 3  ← a no-op (mutates a discarded copy); use node.x instead
+// node getters return fresh copies (value semantics, like Unity):
+node.position.x = 3                                    // compiled to a single-axis write — the direct spelling works
+const p = node.position; p.y = 5; node.position = p    // a stored copy: mutate it, assign it back
 
 // Mat4 keeps the metal exposed (public .m) for low-level surgery:
 let m = node.matrix.translate(pivot).rotateY(yaw * dt).translate(pivot.negate())
@@ -54,64 +78,68 @@ m.m[12] += vx * dt
 node.matrix = m
 ```
 
-`Quat`/`Mat4` cover the rest: `Quat.fromEuler/lookRotation/slerp`, `Mat4.compose/decompose/lookAt/
-perspective`. All of it is fuzz-tested against gl-matrix (dev-only oracle) in `tests/math/oracle.test.ts`.
+`Quat` / `Mat4` cover the rest: `Quat.fromEuler / lookRotation / slerp`, `Mat4.compose / decompose /
+lookAt / perspective`. All of it is fuzz-tested against gl-matrix (a dev-only oracle) in
+`tests/math/oracle.test.ts`.
 
 ## Design rules
 
-- **No ECS / no components.** Built-in behaviors are chainable node methods (`.physics()`,
-  `.collider()`, `.clips()/.play()`); reuse is a factory function. Per-frame logic is `setLoop(dt => …)`.
-- **Few globals.** Variants are static factory methods (`Mesh.box()`, `Material.lit()`,
-  `Texture2D.load()`), not free functions.
-- **Pure re-skin.** Calls the existing `_creator` / `_creator2d` / `_creatorTree` / `_creatorUtils`
-  host bridges — no native engine changes.
+- **Globals only.** `src/inject.ts` is the one file that exports public names; a project's imports
+  are relative paths to its own files and assets. Variants are static factories (`Mesh.box()`,
+  `Material.lit()`, `Texture2D.load()`), not free functions.
+- **UI elements are handles** to the runtime's tree (docs/tree.md at the repo root): factories take
+  content, appearance goes through chained `.style()`, states are `$name` class blocks.
+- **Behaviour is an `Aspect`** on a node and a **`System`** on a scene; the phases are methods
+  (`updateBefore` / `update` / `updateFixed`) — no hand-written game loops.
+- **Native resources are owned handles**: a node, texture, material or player is freed once nothing
+  references it and nothing native owns it; `destroy()` frees a node early.
+- **Hosts differ, the API does not**: an optional host capability is feature-detected
+  (`Physics.supported`, a plugin's `isSupported`), never versioned.
 
 ## Layout
 
 ```
 src/
-  inject.ts         # THE aggregation point — the only file that exports public globals
-  bridges.d.ts      # ambient host ABI (_creator*, declared, never bundled)
-  host.d.ts         # ambient host runtime globals (setLoop, console, DEG2RAD, asset)
-  core/             # handle registry, color, event Emitter
-  math/             # Mathf (scalar) + fluent Vec2/Vec3 (vec), Quat (quat), Mat4 (mat4) — no gl-matrix shipped
-  runtime/          # fetch, storage, device, input, media, net, files, touch, misc
-  g2/               # 2D: Scene2D, Node2D, Sprite, Tilemap, Texture2D, Camera2D
-  gl/               # 3D: Scene, ARScene, Node, Mesh, Light, Material, Geometry, Texture,
-                    #     Camera, Ray, Plane, Noise, Particles
-  ui/               # UIScreen/Row/Column/Text/Button/… + Router + registerFont
-  animate/          # animate, cubicBezier, easings
-  plugins/          # optional, host-provided capabilities (QRScanner, CameraView) — gated on host support
-  compile/          # the user-project compiler (bundler + header + compileProject) — backend/CLI use it
+  inject.ts         THE aggregation point — the only file that exports public globals
+  host.d.ts         host-provided globals (setTimeout, setLoop, console, asset, font, DEG2RAD, EDITOR)
+  bridges/          the host contract: one .d.ts per bridge (_creator*, host tables) — never bundled
+  chisel.ts         the chisel vocabulary: every SDK name the bundler's passes key on
+  version.ts        SDK_VERSION — its major is the bundle ↔ runtime contract
+  core/             Aspect / System, signals, events, Time, StateMachine, color, owned-handle pins
+  math/             Mathf, Vec2 / Vec3, Quat, Mat4 (no gl-matrix shipped)
+  canvas/           Canvas / Bitmap — vector drawing over the AnyCanvas core
+  animate/          animate(), Timeline, easings — the keyframe tween core
+  runtime/          fetch, storage, files, device, input, media, touch, app, share, date, rpc
+  audio/            game audio: Sound, Voice, Bus, audio
+  net/              multiplayer: Net, replication
+  ui/               UIScreen / UIRow / UIText / … + Router, UIPager, widgets, theme, transitions
+  g2/               2D: Scene2D, Node2D, Sprite, Tilemap, tilesets, Box2D physics
+  gl/               3D: Scene, Node, Mesh, Model, Material, Light, physics/, vehicle/, animation/, nav/, terrain/
+  scene/            scenes as data (defineScene), materials, Level, editor plugins
+  plugins/          OAuth, Service + the first-party plugins vendored under plugins/gen
+  server/           the host side of app backends (`lecodes-sdk/server`)
+  compile/          the project compiler (bundler, entry detection, macros) — `lecodes-sdk/compile`
+docs/               the API reference + cookbook
+prompts/            codegen prompts for the platform's in-editor assistant (`bun run prompts:build`)
+tests/<area>/       bun tests, one folder per src area; tests/helpers = the fake host (`lecodes-sdk/testing`)
 ```
 
 ## Build & test
 
 ```sh
-bun run build       # → dist/inject.js (runtime), dist/global.d.ts + host.d.ts + types.json (editor types)
-bun test            # compile/parity + math/color + 2D + 3D-runtime + UI tests
+bun run build       # dist/global.d.ts + host.d.ts + editor.d.ts + types.json — the editor types
+bun test            # every suite; `bun test tests/<area>` for one area
 bun run typecheck   # tsc --noEmit
+bun run docs:check  # every global documented exactly once, sources + links resolve
 ```
 
-Tests live in `tests/<area>/`, one folder per `src/<area>` they exercise; [tests/README.md](tests/README.md)
-has the layout, the shared stubs and the one-process rules.
-
-`tests/headless/` holds live WebGL2 render harnesses (manual; need chrome-headless-shell). The 2D
-harness is green: a project compiled through the real `compileProject` renders correct pixels.
+[tests/README.md](tests/README.md) has the test layout, the shared stubs and the one-process rules.
 
 ## How it integrates
 
-The backend (`backend/src/utils/compileProject.ts`) and CLI (`lecodes-cli`) compile **every** user
-project through this SDK (`sdk/compile`) — the legacy `worker` path was removed from user-project
-compilation. A bare `import` from a runtime module (`creator`/`ui`/`animate`/`utils`/`2d`) is no longer
-special-cased; it's just an unresolved import, so the build fails loudly and points at the file. The
-`worker` package still exists for internal tooling (scene-viewer / model-preview), not for user code.
-
-## Deferred (API present, native pending)
-
-- 2D physics / collider triggers (`.collider()` is a no-op stub; `Node2D.add()` hierarchy).
-- Live 2D↔3D engine switching is wired in the viewer host (two canvases) but pending a real dual
-  project to verify.
-
-`ARScene.addControls(target, options?)` ports the AR object-placement gesture recipe (one-finger drag,
-two-finger pinch-scale + twist-rotate) onto the fluent math; returns a `{ remove() }` handle.
+The CLI (`lecodes compile | render | test | dev`) and the build service compile every project
+through `lecodes-sdk/compile`: entry detection (`main.ts`, else the import-graph root), the
+`asset()` / `font()` / `assetIcon()` macros, then chisel over the SDK **source** — the bundle is
+built from `src/`, not from a prebuilt runtime. Every bundle opens with `// sdk: <version>`; a host
+refuses a bundle whose major differs from its runtime's (the SDK and the runtimes are one version,
+`bun run set-version` at the repo root). Plugins import the SDK through `lecodes-sdk/plugin`.

package/dist/global.d.ts

@@ -71,7 +71,6 @@ declare global {
   const Node: typeof SDK.Node
   const Node2D: typeof SDK.Node2D
   const Noise: typeof SDK.Noise
-  const OAuth: typeof SDK.OAuth
   const OneWay2D: typeof SDK.OneWay2D
   const Particles: typeof SDK.Particles
   const Physics: typeof SDK.Physics
@@ -246,10 +245,10 @@ declare global {
   type CameraView = SDK.CameraView
   type Canvas = SDK.Canvas
   type CellsData = SDK.CellsData
+  type ChannelSubscription = SDK.ChannelSubscription
   type CharacterController = SDK.CharacterController
   type CharacterController2D = SDK.CharacterController2D
   type ClickEvent<T = any> = SDK.ClickEvent<T>
-  type ClientChannel<E extends Record<string, unknown> = Record<string, unknown>> = SDK.ClientChannel<E>
   type ClipAlign = SDK.ClipAlign
   type ClipCycle = SDK.ClipCycle
   type ClipDef = SDK.ClipDef
@@ -404,8 +403,6 @@ declare global {
   type Node = SDK.Node
   type Node2D = SDK.Node2D
   type Noise = SDK.Noise
-  type OAuthCredential = SDK.OAuthCredential
-  type OAuthProviderName = SDK.OAuthProviderName
   type OneWay2D = SDK.OneWay2D
   type OrientationLock = SDK.OrientationLock
   type Particles = SDK.Particles
@@ -497,6 +494,7 @@ declare global {
   type Texture2D = SDK.Texture2D
   type TextureLoadOptions = SDK.TextureLoadOptions
   type ThemeAccessors<T> = SDK.ThemeAccessors<T>
+  type ThemeRoles = SDK.ThemeRoles
   type ThemeValues = SDK.ThemeValues
   type TileBlock = SDK.TileBlock
   type TileMaterial = SDK.TileMaterial
@@ -575,7 +573,6 @@ declare global {
   type With<N, A extends Aspect<any, any, any>> = SDK.With<N, A>
   // ---- server globals (available in *.server.ts; using them in client code is a build error) ----
   const ApiError: typeof SERVER.ApiError
-  const auth: typeof SERVER.auth
   const channel: typeof SERVER.channel
   const defineDb: typeof SERVER.defineDb
   const model: typeof SERVER.model

package/dist/host.d.ts

@@ -31,6 +31,9 @@ declare global {
   /** Compile-time macro: `asset('./data.json')` yields the file's PARSED data (a .json file is
    *  data, not code — it ships inside the bundle). See the `string` overload for everything else. */
   function asset(path: `${string}.json`): any
+  /** Compile-time macro: `asset('./logo.svg')` yields the file as an SVG image source — for
+   *  `UIImage(...)` and `bgImage`. */
+  function asset(path: `${string}.svg`): { readonly svg: string, tintColor: string | null }
   /** Compile-time macro: `asset('./hero.png')` is desugared by the bundler into the module import
    *  for that resource. The file must exist — a path that resolves to nothing fails the compile
    *  (`asset not found: ./hero.png (main.ts:3)`); there is no runtime fallback. Calls inside

package/dist/types/inject.d.ts

@@ -21,7 +21,8 @@ export { device, type HapticStyle, type MotionOptions } from "./runtime/device";
 export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input";
 export { WebSocket } from "./runtime/net";
 export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform, type NetCorrection } from "./net";
-export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc";
+export { __rpc, __channel, __serverOnly, RpcError } from "./runtime/rpc";
+export type { ChannelSubscription } from "./server/channel";
 export { AudioPlayer, VideoPlayer } from "./runtime/media";
 export { Sound, type SoundOptions } from "./audio/Sound";
 export { Voice, type VoiceEvents } from "./audio/Voice";
@@ -57,7 +58,7 @@ export { UIScreen, type UIScreenStyle, UIRow, UIColumn, UIBox, type UIContainerS
 export { Presentable } from "./ui/UI";
 export type { DismissOptions, PresentOptions, Transition, TransitionName, TransitionPose, TransitionSpec } from "./ui/UI";
 export type { UINode, UINodeChild } from "./ui/UINode";
-export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme";
+export { theme, type ThemeValues, type ThemeAccessors, type ThemeRoles } from "./ui/theme";
 export { animate, type AnimateOptions, type AnimateValue, type AnimateOut } from "./animate/tween/animateValue";
 export { cubicBezier } from "./animate/bezier";
 export { Timeline, type TimelineOptions, type TimelineAddOptions, type TimelinePosition } from "./animate/tween/Timeline";
@@ -70,7 +71,6 @@ export { CameraView, type CameraFacing } from "./plugins/gen/camera/sdk/camera";
 export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/gen/geolocation/sdk/geolocation";
 export { MapView, type MapOptions, type MapStyle, type MapStyleName, type MapCamera, type MapTap, type LngLat, type CameraMove, type FitOptions, type MapPaddingValues, type MarkerItem, type MarkerTap, type MarkerLayer, type MarkerLayerOptions, type LineLayer, type LineLayerOptions, type UserLocationOptions, } from "./plugins/gen/map/sdk/map";
 export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/gen/push/sdk/push";
-export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/oauth";
 export { Service } from "./plugins/service";
 export { defineScene, use, ref, make, SceneHandle } from "./scene/defineScene";
 export { defineMaterial, MaterialHandle } from "./scene/material";

package/dist/types/runtime/device.d.ts

@@ -56,6 +56,13 @@ export declare const device: {
      *  feels native on each platform; see {@link HapticStyle}. Host-gated: a silent no-op where there's
      *  no haptic hardware (iPad, older iPhones, web, headless). */
     vibrate(style?: HapticStyle): void;
+    /** The host's performance overlay: one line over everything with the frames per second the
+     *  display actually got, how evenly they came (`66 fps · 73% even` is judder, `60 fps · 100% even`
+     *  is smooth), and the GPU's and the main thread's milliseconds per frame. The host measures and
+     *  draws it itself about once a second — nothing of it runs in the app's JS, so it does not change
+     *  what it measures. It belongs to the host, not to the project: it stays on when another project
+     *  is opened. Reads `false`, and writing does nothing, on hosts without one (web, headless). */
+    statsOverlay: boolean;
     /** Device-orientation sensor (gyro + accelerometer, fused) for tilt/steering and magic-window /
      *  360° panoramas. Poll `attitude` / `gravity` inside setLoop; they return the freshest fused
      *  sample, so the sensor rate need not match your frame rate. Host-gated: a no-op with no sensor. */

package/dist/types/runtime/rpc.d.ts

@@ -10,15 +10,13 @@
  * 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.)
+ *   WS   <serverUrl>/ws  the channel socket — its frames are ./wire.ts
  *
  * 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 type { ChannelSubscription } from "../server/channel";
 /** Rejection value of a failed endpoint call: `status` mirrors the server's `ApiError`
  *  (0 = the request itself failed: no network / no server). */
 export declare class RpcError extends Error {
@@ -29,16 +27,12 @@ export declare class RpcError extends Error {
 export declare const __rpc: (serverUrl: string, id: string) => (...args: unknown[]) => Promise<any>;
 /** A server-only export (db, models, helpers) referenced from client code: any use throws. */
 export declare const __serverOnly: (id: string) => any;
-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 declare const __channel: (serverUrl: string, id: string) => ClientChannel<any>;
+/**
+ * Build the client proxy of channel `id` — what a `channel()` export of a `*.server.ts` file is in
+ * the app (its type is the server's: src/server/channel.ts). `subscribe([...args,] handler, options?)`:
+ * what stands before the handler travels to the channel's `groupBy`.
+ */
+export declare const __channel: (serverUrl: string, id: string) => {
+    subscribe(...all: unknown[]): ChannelSubscription;
+    publish(): never;
+};

package/dist/types/runtime/wire.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The frames of the channel socket (`<serverUrl>/ws`) — the ONE description both ends are written
+ * against: the client transport (./rpc.ts) and the server's hub (../server/channelHub.ts, which the
+ * runner and the local backend of `lecodes dev` both run). JSON text frames, one per message.
+ *
+ *   → hello   who is on this socket. Sent first, and again whenever the session changes: the server
+ *             then DROPS the socket's subscriptions (they were granted to someone else) and the
+ *             client sends them again, under new ids.
+ *   → sub     subscribe to channel `ch`; `args` are what the app passed to `subscribe` before the
+ *             handler — the channel's `groupBy` reads them.
+ *   → unsub
+ *   ← session a token minted while the socket was served (the first contact of a guest): the client
+ *             stores it; nothing is dropped, the server already has it.
+ *   ← ok      the subscription stands; `group` is where the server put it (null = a channel without
+ *             groups). The client learns its group only here — it never names one.
+ *   ← err     refused (a hook threw) — the subscription is gone.
+ *   ← ev      one published message, addressed by channel + group so the server sends one frame to
+ *             every socket of a group; the client hands it to each of its subscriptions there.
+ *
+ * A group's value is not a secret: its subscriber is told it.
+ */
+/** What `groupBy` may answer. `42` and `"42"` are two groups. */
+export type ChannelGroup = string | number;
+export type ClientFrame = {
+    t: "hello";
+    session: string | null;
+} | {
+    t: "sub";
+    id: number;
+    ch: string;
+    args: unknown[];
+} | {
+    t: "unsub";
+    id: number;
+};
+export type ServerFrame = {
+    t: "session";
+    session: string;
+} | {
+    t: "ok";
+    id: number;
+    group: ChannelGroup | null;
+} | {
+    t: "err";
+    id: number;
+    status: number;
+    message: string;
+} | {
+    t: "ev";
+    ch: string;
+    group: ChannelGroup | null;
+    data: unknown;
+};

package/dist/types/server/auth/api.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `db.auth` — the BUNDLE side of sign-in, what `*.server.ts` code calls on a db made with
+ * `defineDb({...}).withAuth({ model: "User" })`:
+ *
+ *   const db = defineDb({ User, Post }).withAuth({ model: "User" })
+ *
+ *   export async function register(login: string, password: string, name: string) {
+ *     await db.auth.signUpWithPassword(login, password, { name })
+ *   }
+ *   export async function me()                { return db.auth.user().select({ id: true, name: true }) }
+ *   export async function removePost(id: number) {
+ *     await db.auth.requireUser({ role: "admin" }).select({ id: true })
+ *     …
+ *   }
+ *
+ * The platform knows a request's session and the ID of its user (the host resolved the token before
+ * the endpoint ran). Everything else about a user is a row of the project's own model, and is READ:
+ * `user()` / `requireUser()` are queries over that model — typed by it, run when awaited — narrowed to
+ * the user of the request. Sign-in operations forward to the host's `AuthOps` on
+ * `globalThis.__lecodesAuth` (a seam: the compiled bundle carries its own SDK copy).
+ */
+/** The collections of a db with auth, by role (defineDb.ts). */
+export type AuthCollections = {
+    model: string;
+    user: any;
+    session: any;
+    identity: any;
+};
+export declare const createAuthApi: (tables: () => AuthCollections) => {
+    user: () => any;
+    requireUser: (where?: Record<string, unknown>) => any;
+    readonly sessionId: number;
+    signUpWithPassword: (login: string, password: string, data?: Record<string, unknown>) => Promise<void>;
+    signInWithPassword: (login: string, password: string) => Promise<void>;
+    setPassword: (password: string) => Promise<void>;
+    sendCode: (email: string) => Promise<void>;
+    signInWithCode: (email: string, code: string) => Promise<void>;
+    signIn: (userId: number) => Promise<void>;
+    signOut: () => Promise<void>;
+    readonly sessions: any;
+    readonly identities: any;
+};

package/dist/types/server/auth/appConfig.d.ts

@@ -1,16 +1,12 @@
 /**
- * The project's `app.json` subset the server runtime reads (name, auth providers).
+ * The project's `app.json` subset the server runtime reads: the app's name (the sign-in mail).
  *
  * 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 declare const app: AppConfig;