lecodes-sdk 2.0.2 → 2.0.4

package/package.json

@@ -20,6 +20,7 @@
     "./bridges/*": "./src/bridges/*.d.ts",
     "./ui/tree": "./src/ui/tree.ts",
     "./tween/easing": "./src/animate/tween/easing.ts",
+    "./tween/read": "./src/animate/tween/read.ts",
     "./testing": "./tests/helpers/index.ts",
     "./testing/preload": "./tests/helpers/preload.ts",
     "./version": "./src/version.ts"
@@ -42,7 +43,7 @@
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4"
   },
-  "version": "2.0.2",
+  "version": "2.0.4",
   "files": [
     "src",
     "dist",

package/src/animate/tween/read.ts

@@ -0,0 +1,146 @@
+// The READER of the tween blob: `buildBlob`'s layout (./spec.ts) back into tracks and keys. For a
+// host that plays an animation with no creator-tween in it (Web Lite hands the tracks to the
+// browser's animations) — creator-tween reads the same layout in C (blob.h).
+//
+// The reader is the builder's twin and lives beside it: tests/animate/blob.test.ts builds a spec,
+// reads it back and holds the two against each other, so a change of the layout that reaches one
+// side only fails there.
+
+import { EASE_TABLE, EASE_TABLE_SIZE, evalEasing, type EasingSpec } from "./easing"
+
+/** The version of the layout this reader knows (./spec.ts BLOB_VERSION). */
+const VERSION = 1
+// The kinds whose one lane is an index into the string table (./spec.ts KIND_*).
+const KIND_TRANSFORM_MATRIX = 4, KIND_DISCRETE = 8, KIND_STRING = 9
+
+export type BlobKey = {
+  /** 0..1 within the track. */
+  t: number
+  easing: EasingSpec
+  /** Absent = the target's value when the animation first plays. */
+  value?: { lanes: number[] } | { str: string }
+}
+
+export type BlobTrack = {
+  domain: number
+  /** An index into the `targets` handed over next to the blob (a role, in a transition's blob). */
+  target: number
+  prop: string
+  kind: number
+  lanes: number
+  /** The unit of a FLOAT_UNIT, the function list of a TRANSFORM. */
+  sig?: string
+  atMs: number
+  durMs: number
+  commit: boolean
+  keys: BlobKey[]
+}
+
+export type ReadBlob = {
+  clock: number
+  /** One iteration, ms. */
+  durationMs: number
+  delayMs: number
+  /** -1 = forever. */
+  iterations: number
+  pingPong: boolean
+  rate: number
+  /** Time-callbacks, ms; the index is what the host reports. */
+  calls: number[]
+  tracks: BlobTrack[]
+}
+
+/** The blob as tracks, or null for data that is not a blob of this version (or is cut short). */
+export const readBlob = (data: ArrayLike<number>, strings: readonly string[]): ReadBlob | null => {
+  if (data.length < 10 || data[0] !== VERSION) return null
+  const nTracks = data[7]!, nCalls = data[8]!, nTables = data[9]!
+  let at = 10
+  if (at + nCalls + nTables * EASE_TABLE_SIZE > data.length) return null
+  const calls: number[] = []
+  for (let i = 0; i < nCalls; i++) calls.push(data[at++]!)
+  const tables: Float32Array[] = []
+  for (let i = 0; i < nTables; i++) {
+    const table = new Float32Array(EASE_TABLE_SIZE)
+    for (let k = 0; k < EASE_TABLE_SIZE; k++) table[k] = data[at++]!
+    tables.push(table)
+  }
+  const str = (index: number): string | undefined => (index >= 0 ? strings[index] : undefined)
+
+  const tracks: BlobTrack[] = []
+  for (let t = 0; t < nTracks; t++) {
+    if (at + 10 > data.length) return null
+    const kind = data[at + 3]!, lanes = data[at + 4]!, nKeys = data[at + 8]!
+    const track: BlobTrack = {
+      domain: data[at]!, target: data[at + 1]!, prop: str(data[at + 2]!) ?? "", kind, lanes,
+      sig: str(data[at + 9]!), atMs: data[at + 5]!, durMs: data[at + 6]!, commit: data[at + 7]! !== 0, keys: [],
+    }
+    at += 10
+    if (at + nKeys * (7 + lanes) > data.length) return null
+    const stringLane = kind === KIND_TRANSFORM_MATRIX || kind === KIND_DISCRETE || kind === KIND_STRING
+    for (let k = 0; k < nKeys; k++) {
+      const easeKind = data[at + 1]!
+      const p: [number, number, number, number] = [data[at + 2]!, data[at + 3]!, data[at + 4]!, data[at + 5]!]
+      const easing: EasingSpec = easeKind === EASE_TABLE ? { kind: easeKind, p, table: tables[p[0]] } : { kind: easeKind, p }
+      const key: BlobKey = { t: data[at]!, easing }
+      if (data[at + 6]! !== 0) {
+        if (stringLane) key.value = { str: str(data[at + 7]!) ?? "" }
+        else {
+          const values: number[] = []
+          for (let l = 0; l < lanes; l++) values.push(data[at + 7 + l]!)
+          key.value = { lanes: values }
+        }
+      }
+      at += 7 + lanes
+      track.keys.push(key)
+    }
+    tracks.push(track)
+  }
+  if (at !== data.length) return null
+  return { clock: data[1]!, durationMs: data[2]!, delayMs: data[3]!, iterations: data[4]!, pingPong: data[5]! !== 0, rate: data[6]!, calls, tracks }
+}
+
+// ---- a track's value at a time -------------------------------------------------------------------
+
+const KIND_QUAT = 6, KIND_MAT4 = 11
+
+const slerp = (out: number[], o: number, a: number[], b: number[], s: number): void => {
+  let bx = b[o] ?? 0, by = b[o + 1] ?? 0, bz = b[o + 2] ?? 0, bw = b[o + 3] ?? 1
+  const ax = a[o] ?? 0, ay = a[o + 1] ?? 0, az = a[o + 2] ?? 0, aw = a[o + 3] ?? 1
+  let cosom = ax * bx + ay * by + az * bz + aw * bw
+  if (cosom < 0) { cosom = -cosom; bx = -bx; by = -by; bz = -bz; bw = -bw }
+  let k0 = 1 - s, k1 = s
+  if (1 - cosom > 1e-6) {
+    const omega = Math.acos(Math.min(1, cosom)), sinom = Math.sin(omega)
+    k0 = Math.sin((1 - s) * omega) / sinom
+    k1 = Math.sin(s * omega) / sinom
+  }
+  out[o] = k0 * ax + k1 * bx; out[o + 1] = k0 * ay + k1 * by; out[o + 2] = k0 * az + k1 * bz; out[o + 3] = k0 * aw + k1 * bw
+}
+
+/** The two keys around the local time `ms` of a track and how far between them the track is,
+ *  eased: the first key holds before the track, the last one after it. */
+export const segmentAt = (track: BlobTrack, ms: number): { from: BlobKey, to: BlobKey, s: number } | null => {
+  const keys = track.keys
+  if (keys.length === 0) return null
+  const u = track.durMs <= 0 ? (ms >= track.atMs ? 1 : 0) : Math.min(1, Math.max(0, (ms - track.atMs) / track.durMs))
+  const first = keys[0]!, last = keys[keys.length - 1]!
+  if (keys.length === 1 || u <= first.t) return { from: first, to: first, s: 0 }
+  if (u >= last.t) return { from: last, to: last, s: 0 }
+  let i = 0
+  while (i + 1 < keys.length && keys[i + 1]!.t <= u) i++
+  const from = keys[i]!, to = keys[i + 1]!
+  const span = to.t - from.t
+  return { from, to, s: evalEasing(from.easing, span > 0 ? (u - from.t) / span : 1) }
+}
+
+/** The lanes of a numeric track at the local time `ms`, into `out` (a key with no value reads as zeros). */
+export const sampleTrack = (track: BlobTrack, ms: number, out: number[]): void => {
+  const at = segmentAt(track, ms)
+  if (!at) return
+  const lanesOf = (key: BlobKey): number[] => (key.value && "lanes" in key.value ? key.value.lanes : [])
+  const a = lanesOf(at.from), b = lanesOf(at.to), s = at.s
+  const lerp = (from: number, to: number) => { for (let k = from; k < to; k++) out[k] = (a[k] ?? 0) + ((b[k] ?? 0) - (a[k] ?? 0)) * s }
+  if (track.kind === KIND_QUAT) { slerp(out, 0, a, b, s); return }
+  if (track.kind === KIND_MAT4) { lerp(0, 3); slerp(out, 3, a, b, s); lerp(7, 10); return }
+  lerp(0, track.lanes)
+}

package/src/bridges/tree.d.ts

@@ -95,6 +95,10 @@ declare global {
     routerPop(index: i32, transition: i32): void
     routerHide(transition: i32): void
     routerRestore(transition: i32): void
+    // The ADDRESS of a destination (`UIScreen.url`): a route (`/product/42`) a host with an address
+    // bar shows while the destination is the one on screen; null takes it away. OPTIONAL: a host
+    // without an address bar has no such method (the SDK feature-detects) — Web Lite has it.
+    setDestUrl?(kind: u8, id: f64, url: string | null): void
     // Does the host registerView(name)? / the contract version its half was generated from (0 = no
     // such view; on a host that does not say, 1 for a view it has) / the NativeView method channel:
     // `args` is the array of the call's arguments, the callbacks settle exactly once through the

package/src/canvas/gen/cssColor.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/cssColor.ts @ ae6bc30b952b — do not edit here.
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/cssColor.ts @ 72e545dab1f5 — do not edit here.
 // Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
 // The CSS color parser — the TypeScript twin of core/include/anycanvas/css_color.h: the same grammar,
 // the same name table, float32 emulated op for op (Math.fround, in the header's order), so both give

package/src/canvas/gen/recorder.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/recorder.ts @ ae6bc30b952b — do not edit here.
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/recorder.ts @ 72e545dab1f5 — do not edit here.
 // Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
 // The TypeScript recorder: a Canvas2D-shaped API whose calls WRITE the opcode stream of spec/ops.h.
 // Nothing is drawn here — the stream goes to the core interpreter (native, or wasm on the web), which

package/src/canvas/gen/spec.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/vendor-canvas.ts from engines/canvas/spec/gen/spec.ts @ ae6bc30b952b — do not edit here.
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/spec/gen/spec.ts @ 72e545dab1f5 — do not edit here.
 // Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
 // GENERATED by spec/generate.ts from spec/*.h — do not edit.
 

package/src/chisel.ts

@@ -128,7 +128,7 @@ export const chiselVocab: ChiselVocab = {
       "onScroll", "onScrollRelease", "onOverscroll", "onRefresh", "onSubmit",
       "onSelect", "onChange", "onFocus", "onBlur", "onOverlayTap", "onDetent",
       "onEndReached", "onStartReached",
-      "append", "insert", "remove", "setContent", "keepAlive",
+      "append", "insert", "remove", "setContent", "keepAlive", "url",
       "attachTo", "detents", "dismissible", "transition", "setSourceRect",
       "push", "pop", "popToRoot", "replace", "select",
       // UITabs / UIVirtualizedList / the native views (NativeView, CameraView, MapView, QRScanner)

package/src/inject.ts

@@ -39,7 +39,7 @@ 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"
 // Multiplayer (docs/multiplayer-plan.md): roles, players, JSON messages over the _creatorNet transport.
-export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform } from "./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"
 // 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"

package/src/net/codec.ts

@@ -6,23 +6,31 @@
 // Nothing else: no strings, no nesting, no optionals — snapshot fields are flat and fixed-size by
 // design. Both sides run the same bundle, so the layout is derived, never transmitted; the `sig`
 // feeds the schema hash the handshake compares.
+//
+// A numeric field is INTERPOLATED between two snapshots unless the kind names it `discrete` (an
+// index, a count, an id): a discrete field takes the later snapshot's value whole, as a boolean does.
+// That is a rule of the reader — the wire is the same f32.
 
 export type FieldKind = 0 | 1 | 2   // f32 · bool · f32[]
-export type Field = { key: string; kind: FieldKind; len: number }
+export type Field = { key: string; kind: FieldKind; len: number; step: boolean }
 export type Layout = { fields: Field[]; floats: number; bools: number; bytes: number; sig: string }
 
 const describe = (v: unknown): string => Array.isArray(v) ? `array of ${v.length}` : v === null ? "null" : typeof v
 
-export const makeLayout = (defaults: Record<string, unknown>, what: string): Layout => {
+export const makeLayout = (defaults: Record<string, unknown>, what: string, discrete: readonly string[] = []): Layout => {
   const fields: Field[] = []
   let floats = 0
   let bools = 0
+  for (const key of discrete) {
+    if (!(key in defaults)) throw new Error(`${what}: discrete field '${key}' is not in the defaults`)
+  }
   for (const key of Object.keys(defaults)) {
     const v = defaults[key]
-    if (typeof v === "number") { fields.push({ key, kind: 0, len: 1 }); floats++ }
-    else if (typeof v === "boolean") { fields.push({ key, kind: 1, len: 1 }); bools++ }
+    const step = discrete.includes(key)
+    if (typeof v === "number") { fields.push({ key, kind: 0, len: 1, step }); floats++ }
+    else if (typeof v === "boolean") { fields.push({ key, kind: 1, len: 1, step: true }); bools++ }
     else if (Array.isArray(v) && v.length > 0 && v.length <= 64 && v.every((n) => typeof n === "number")) {
-      fields.push({ key, kind: 2, len: v.length }); floats += v.length
+      fields.push({ key, kind: 2, len: v.length, step }); floats += v.length
     } else {
       throw new Error(`${what}: field '${key}' must be a number, a boolean or a fixed-length number[] (got ${describe(v)})`)
     }
@@ -97,14 +105,15 @@ export const unpackFrom = (view: DataView, offset: number, layout: Layout, into:
   return o
 }
 
-/** `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 const lerpState = (layout: Layout, a: any, b: any, t: number, out: any): void => {
   for (const f of layout.fields) {
-    if (f.kind === 0) out[f.key] = a[f.key] + (b[f.key] - a[f.key]) * t
-    else if (f.kind === 2) {
+    if (f.kind === 2) {
       const pa = a[f.key] as number[], pb = b[f.key] as number[], po = out[f.key] as number[]
-      for (let i = 0; i < f.len; i++) po[i] = pa[i] + (pb[i] - pa[i]) * t
-    } else out[f.key] = b[f.key]
+      const k = f.step ? 1 : t
+      for (let i = 0; i < f.len; i++) po[i] = pa[i] + (pb[i] - pa[i]) * k
+    } else if (f.step) out[f.key] = b[f.key]
+    else out[f.key] = a[f.key] + (b[f.key] - a[f.key]) * t
   }
 }
 

package/src/net/core.ts

@@ -48,7 +48,7 @@ export type NetStats = { rtt: number; loss: number; sentKbps: number; receivedKb
 
 export const CH_RELIABLE = 0
 export const CH_UNRELIABLE = 1
-export const PROTO = 2
+export const PROTO = 3
 export const LOCAL_SLOT = -1
 
 // Record kinds from creator-net (creator-net.h CNET_RECORD_*).
@@ -67,6 +67,9 @@ export 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 = undefined
   /** @internal transport slot on the server; LOCAL_SLOT for the in-process player */
   _slot: number
   /** @internal server side: this player's input ring (replication.ts) */
@@ -129,6 +132,10 @@ export const state = {
   connectResolve: null as null | (() => void),
   connectReject: null as null | ((e: Error) => void),
   myName: "Player",
+  /** client: the game's own part of the `$hello` (`Net.connect(…, { hello })`), opaque to the SDK */
+  hello: undefined as unknown,
+  /** server: the game's say in the handshake (`Net.listen({ accept })`) — a reason refuses */
+  accept: null as null | ((hello: unknown, who: { name: string }) => string | null | void),
 }
 
 // Replication's seams into the roster / pump (set by replication.ts when a session starts — from a
@@ -255,6 +262,8 @@ export const resetToOffline = (): void => {
   state.nextId = 1
   state.connectResolve = null
   state.connectReject = null
+  state.hello = undefined
+  state.accept = null
 }
 
 // ---- server side ------------------------------------------------------------------------------------
@@ -283,13 +292,17 @@ const onServerRecord = (kind: number, slot: number, arg: number, payload: unknow
   const [name, data] = parsed
   if (name === "$hello") {
     if (playerBySlot(slot)) return
-    const reason = !data || data.proto !== PROTO ? "version" : hooks.helloCheck?.(data) ?? null
+    const name = String(data?.name ?? `Player ${state.nextId}`)
+    // the SDK's own checks first, then the game's say (it never sees a client of another protocol)
+    const reason = !data || data.proto !== PROTO ? "version"
+      : hooks.helloCheck?.(data) ?? state.accept?.(data.hello, { name }) ?? null
     if (reason) {
-      sendRaw(slot, CH_RELIABLE, JSON.stringify(["$reject", { reason }]))
+      sendRaw(slot, CH_RELIABLE, JSON.stringify(["$reject", { reason: String(reason) }]))
       b.kick(slot)
       return
     }
-    const p = addPlayer(state.nextId++, String(data.name ?? `Player ${state.nextId - 1}`), slot)
+    const p = addPlayer(state.nextId++, name, slot)
+    p.hello = data.hello
     sendRaw(slot, CH_RELIABLE, JSON.stringify(["$welcome", {
       id: p.id,
       players: state.players.filter((q) => q !== p).map((q) => ({ id: q.id, name: q.name })),
@@ -310,7 +323,7 @@ const onServerRecord = (kind: number, slot: number, arg: number, payload: unknow
 const onClientRecord = (kind: number, slot: number, arg: number, payload: unknown): void => {
   const b = bridge()!
   if (kind === REC_CONNECTED) {
-    sendRaw(0, CH_RELIABLE, JSON.stringify(["$hello", { proto: PROTO, name: state.myName, ...(hooks.helloExtra?.() ?? {}) }]))
+    sendRaw(0, CH_RELIABLE, JSON.stringify(["$hello", { proto: PROTO, name: state.myName, hello: state.hello, ...(hooks.helloExtra?.() ?? {}) }]))
     return
   }
   if (kind === REC_CONNECT_FAILED || kind === REC_DISCONNECTED) {

package/src/net/index.ts

@@ -10,12 +10,12 @@ import {
   type Listener, type NetEvents, type NetLaunch, type NetMessage, type NetRole, type NetStatus,
 } from "./core"
 import {
-  NetEntity, Replicated, allEntities, currentTick, declareInput, declareKind, entityById, installReplication, setInput, stats,
-  type NetInput, type NetKind, type NetTransform,
+  NetEntity, Replicated, allEntities, currentTick, declareInput, declareKind, entityById, installReplication, setInput, stats, viewTick,
+  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 }
 
 class NetImpl {
   get role(): NetRole { return state.role }
@@ -34,12 +34,21 @@ 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 { return currentTick() }
+  /** 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 { return viewTick() }
   /** Live counters: snapshots, input lead / `ahead`, corrections, missed inputs, bytes out. */
   get stats(): typeof stats { return 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. */
-  listen(opts: { port?: number; maxClients?: number; name?: string; dedicated?: boolean } = {}): boolean {
+   *  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 {
     const b = bridge()
     if (!b) { emit("error", "multiplayer is not supported on this host"); return false }
     if (state.role !== "offline") this.disconnect()
@@ -56,6 +65,7 @@ class NetImpl {
     state.isServer = true
     state.isClient = !dedicated
     state.status = "online"
+    state.accept = opts.accept ?? null
     if (!dedicated) ensureMe()
     installReplication()
     startPhases()
@@ -63,12 +73,15 @@ class NetImpl {
     return true
   }
 
-  /** Connect to a host/server (`address` = "ip:port"). Resolves once the server welcomed us. */
-  connect(target: { address: string }, opts: { name?: string } = {}): Promise<void> {
+  /** 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> {
     const b = bridge()
     if (!b) return Promise.reject(new Error("multiplayer is not supported on this host"))
     if (state.role !== "offline") this.disconnect()
     if (opts.name) state.myName = opts.name
+    state.hello = opts.hello
     return new Promise<void>((resolve, reject) => {
       if (!b.connect(target.address)) { reject(new Error(`bad address '${target.address}'`)); return }
       state.role = "client"
@@ -163,8 +176,16 @@ class NetImpl {
 
   /** 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 })`). */
-  kind<S extends object>(name: string, defaults: S, opts: { transform?: NetTransform; client?: (rep: NetEntity<S>, scene: any) => any } = {}): NetKind<S> {
+   *  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> {
     return declareKind(name, defaults, opts as any)
   }