lecodes-sdk 2.0.3 → 2.0.5

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
@@ -390,6 +389,7 @@ declare global {
   type NavPath = SDK.NavPath
   type NavQueryOptions = SDK.NavQueryOptions
   type NavRaycastHit = SDK.NavRaycastHit
+  type NetCorrection = SDK.NetCorrection
   type NetEntity<S extends object = any> = SDK.NetEntity<S>
   type NetEvents = SDK.NetEvents
   type NetInput<T extends object = any> = SDK.NetInput<T>
@@ -403,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
@@ -496,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
@@ -574,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

@@ -20,8 +20,9 @@ export { localStorage } from "./runtime/storage";
 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 } from "./net";
-export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc";
+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 } 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/net/codec.d.ts

@@ -3,6 +3,7 @@ export type Field = {
     key: string;
     kind: FieldKind;
     len: number;
+    step: boolean;
 };
 export type Layout = {
     fields: Field[];
@@ -11,7 +12,7 @@ export type Layout = {
     bytes: number;
     sig: string;
 };
-export declare const makeLayout: (defaults: Record<string, unknown>, what: string) => Layout;
+export declare const makeLayout: (defaults: Record<string, unknown>, what: string, discrete?: readonly string[]) => Layout;
 /** A fresh state object shaped like the defaults (arrays copied, never shared). */
 export declare const cloneDefaults: <T extends object>(defaults: T) => T;
 /** Copy the layout's fields from `from` into `into` (array elements copied in place; unknown keys
@@ -19,7 +20,7 @@ export declare const cloneDefaults: <T extends object>(defaults: T) => T;
 export declare const assignState: (layout: Layout, into: any, from: any) => void;
 export declare const packInto: (view: DataView, offset: number, layout: Layout, s: any) => number;
 export declare const unpackFrom: (view: DataView, offset: number, layout: Layout, into: any) => number;
-/** `out = a + (b − a) · t` for the numeric fields; booleans take `b`'s. */
+/** `out = a + (b − a) · t` for the numeric fields; booleans and the discrete ones take `b`'s. */
 export declare const lerpState: (layout: Layout, a: any, b: any, t: number, out: any) => void;
 /** FNV-1a over a string → 8 hex chars. Enough to tell two bundles' schemas apart. */
 export declare const hashString: (s: string) => string;

package/dist/types/net/core.d.ts

@@ -34,7 +34,7 @@ export type NetStats = {
 };
 export declare const CH_RELIABLE = 0;
 export declare const CH_UNRELIABLE = 1;
-export declare const PROTO = 2;
+export declare const PROTO = 3;
 export declare const LOCAL_SLOT = -1;
 export declare const bridge: () => typeof _creatorNet | null;
 export declare class NetPlayer {
@@ -45,6 +45,9 @@ export declare class NetPlayer {
     /** A local bag for game facts (score, team, ready). NOT replicated — anything a client must see
      *  goes through a message or replicated state. */
     data: any;
+    /** Server: what this player's `Net.connect(…, { hello })` carried (the game's own: a build, a
+     *  token) — the value `Net.listen({ accept })` was asked about. Undefined everywhere else. */
+    hello: unknown;
     private _leave;
     constructor(id: number, name: string, slot: number);
     get isMe(): boolean;
@@ -72,6 +75,12 @@ export declare const state: {
     connectResolve: null | (() => void);
     connectReject: null | ((e: Error) => void);
     myName: string;
+    /** client: the game's own part of the `$hello` (`Net.connect(…, { hello })`), opaque to the SDK */
+    hello: unknown;
+    /** server: the game's say in the handshake (`Net.listen({ accept })`) — a reason refuses */
+    accept: null | ((hello: unknown, who: {
+        name: string;
+    }) => string | null | void);
 };
 export declare const hooks: {
     frameEarly: null | ((dt: number) => void);

package/dist/types/net/index.d.ts

@@ -1,7 +1,7 @@
 import { NetPlayer, type NetEvents, type NetLaunch, type NetMessage, type NetRole, type NetStatus } from "./core";
-import { NetEntity, Replicated, stats, type NetInput, type NetKind, type NetTransform } from "./replication";
+import { NetEntity, Replicated, stats, type NetCorrection, type NetInput, type NetKind, type NetTransform } from "./replication";
 export { NetPlayer, NetEntity, Replicated };
-export type { NetEvents, NetLaunch, NetMessage, NetRole, NetStatus, NetInput, NetKind, NetTransform };
+export type { NetEvents, NetLaunch, NetMessage, NetRole, NetStatus, NetInput, NetKind, NetTransform, NetCorrection };
 declare class NetImpl {
     get role(): NetRole;
     get status(): NetStatus;
@@ -19,21 +19,33 @@ declare class NetImpl {
     /** The simulation tick — one per fixed step (`updateFixed`). The server's is THE tick; a client
      *  runs a few ticks ahead so its inputs arrive in time. */
     get tick(): number;
+    /** The server tick this machine is SHOWING the others at: on a client, its estimate of the server's
+     *  clock less the interpolation delay (fractional); `tick` everywhere else, where nothing is
+     *  interpolated. What a client names when it tells the server "as I saw it". */
+    get viewTick(): number;
     /** Live counters: snapshots, input lead / `ahead`, corrections, missed inputs, bytes out. */
     get stats(): typeof stats;
     /** Start serving on `port`. From offline this makes us the host (a player who is also the
-     *  server); on the dedicated exe (`Net.launch.role === "server"`) there is no local player. */
+     *  server); on the dedicated exe (`Net.launch.role === "server"`) there is no local player.
+     *  `accept` is the game's say in the handshake: it is given what the client's `connect` passed as
+     *  `hello` and returns a reason to refuse (the client's `reject` event carries it), nothing to accept. */
     listen(opts?: {
         port?: number;
         maxClients?: number;
         name?: string;
         dedicated?: boolean;
+        accept?: (hello: unknown, who: {
+            name: string;
+        }) => string | null | void;
     }): boolean;
-    /** Connect to a host/server (`address` = "ip:port"). Resolves once the server welcomed us. */
+    /** Connect to a host/server (`address` = "ip:port"). Resolves once the server welcomed us.
+     *  `hello` = anything JSON the game wants the server to see before it lets us in (its
+     *  `Net.listen({ accept })`, then `player.hello`); the SDK only carries it. */
     connect(target: {
         address: string;
     }, opts?: {
         name?: string;
+        hello?: unknown;
     }): Promise<void>;
     /** Client → offline. Host/server → everyone is dropped, back to offline. */
     disconnect(): void;
@@ -62,10 +74,15 @@ declare class NetImpl {
     setInput<T extends object>(inp: NetInput<T>, values: Partial<T>): void;
     /** A replicated entity type: the defaults are the snapshot layout (same field rules as `input`),
      *  `transform` tells the SDK which fields mirror the node's pose, `client` births the proxy on a
-     *  client when the server spawns one (`new Node().aspect(Replicated, { kind, owner })`). */
+     *  client when the server spawns one (`new Node().aspect(Replicated, { kind, owner })`) — it may
+     *  be set later, `Kind.client = …`, where the client's code lives. `discrete` names the numeric
+     *  fields that are never interpolated (an index, a count); `correction` tunes how the owner's
+     *  prediction is brought back to the server's state (all in the game's own units). */
     kind<S extends object>(name: string, defaults: S, opts?: {
         transform?: NetTransform;
         client?: (rep: NetEntity<S>, scene: any) => any;
+        discrete?: readonly (keyof S & string)[];
+        correction?: Partial<NetCorrection>;
     }): NetKind<S>;
     /** Every replicated entity this machine knows. */
     get entities(): readonly NetEntity[];

package/dist/types/net/replication.d.ts

@@ -5,6 +5,18 @@ import { Scene } from "../gl/Scene";
 import { type Layout } from "./codec";
 import { NetPlayer } from "./core";
 export type NetTransform = "pos" | "pos+rot" | "none";
+/** How an owner's prediction is brought back to the server's state. The SDK knows nothing of what
+ *  the entity is, so the defaults are neutral: every disagreement counts, none is a teleport. */
+export type NetCorrection = {
+    /** A vertical disagreement below this is ignored (world units). 0 = none ignored. A body that
+     *  snaps to a floor differs by a little between two machines, and lifting it by that feeds itself. */
+    deadbandY: number;
+    /** A disagreement of this much or more is a teleport: the body jumps and `correction` stays zero
+     *  (world units). Infinity = always smoothed. */
+    snap: number;
+    /** The decay time constant of the visual offset `correction` (seconds). 0 = no smoothing. */
+    tau: number;
+};
 /** The per-tick input layout: `const PlayerInput = Net.input({ moveX: 0, moveY: 0, jump: false })`. */
 export type NetInput<T extends object = any> = {
     readonly layout: Layout;
@@ -19,8 +31,10 @@ export type NetKind<S extends object = any> = {
     /** Which state fields the SDK samples on the server and applies to a client proxy: `pos` (a
      *  `pos: [x,y,z]` field), `pos+rot` (+ a `rot: [x,y,z,w]` quaternion field), or `none`. */
     readonly transform: NetTransform;
-    /** Births the client-side proxy on spawn; the SDK attaches `Replicated` to what it returns. */
-    readonly client?: (rep: NetEntity<S>, scene: Scene | null) => Node | void;
+    readonly correction: NetCorrection;
+    /** Births the client-side proxy on spawn; the SDK attaches `Replicated` to what it returns.
+     *  Assignable: a declaration both ends share may leave it to the client's own module. */
+    client?: (rep: NetEntity<S>, scene: Scene | null) => Node | void;
     readonly __t?: S;
 };
 /** Live counters (`Net.stats`): how the clocks and the prediction are doing. */
@@ -59,6 +73,9 @@ export declare class NetEntity<S extends object = any> {
     /** The owner's input for the tick being simulated — the ring entry on the server (the last one
      *  repeated when it is late), the local input on the owner / host / offline. */
     input<T extends object>(inp: NetInput<T>): T;
+    /** `input()` is an input the owner gave — false until the first one exists (the server before
+     *  the owner's first packet, the owner before its first `Net.setInput`), when it is the defaults. */
+    get hasInput(): boolean;
     /** Client: `state` was refreshed (a snapshot landed / the interpolation moved). */
     on(event: "state", cb: (s: S) => void): this;
     off(event: "state", cb: (s: S) => void): this;
@@ -66,10 +83,13 @@ export declare class NetEntity<S extends object = any> {
 export declare const declareKind: <S extends object>(name: string, defaults: S, opts?: {
     transform?: NetTransform;
     client?: NetKind<S>["client"];
+    discrete?: readonly string[];
+    correction?: Partial<NetCorrection>;
 }) => NetKind<S>;
 export declare const declareInput: <T extends object>(defaults: T) => NetInput<T>;
 export declare const setInput: <T extends object>(inp: NetInput<T>, values: Partial<T>) => void;
 export declare const currentTick: () => number;
+export declare const viewTick: () => number;
 export declare const allEntities: () => NetEntity[];
 export declare const entityById: (netId: number) => NetEntity | undefined;
 /**
@@ -97,5 +117,6 @@ export declare class Replicated extends Aspect<"replicated", Node> {
     get correction(): Vec3;
     /** The owner's input for the tick being simulated (see `NetEntity.input`). */
     input<T extends object>(inp: NetInput<T>): T;
+    get hasInput(): boolean;
 }
 export declare const installReplication: () => void;

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;
+};