lecodes-sdk 2.0.3 → 2.0.5

package/src/compile/compileProject.ts

@@ -7,7 +7,7 @@ import { bundleProjectWithMap, scanModulesChisel, type MemoryFiles } from "./bun
 import { detectEntry } from "./detectEntry"
 import { buildHeader } from "./header"
 import { inlineSourceMapComment, offsetSourceMap } from "./sourcemap"
-import { stubServerEntries } from "./serverSplit"
+import { ClientPublishError, clientPublishes, stubServerEntries } from "./serverSplit"
 
 export type CompileFileType = "text" | "resource" | "shader"
 
@@ -185,6 +185,8 @@ export const pluginsOfBundle = (mapJson: string): string[] => {
 
 export const compileProjectWithMap = async (opts: CompileOptions): Promise<CompileResult> => {
   // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
+  const published = clientPublishes(opts.entries)
+  if (published.length) throw new ClientPublishError(published)
   const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
   const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry
   if (!entry) {

package/src/compile/index.ts

@@ -4,6 +4,8 @@
 export { bundleProject, bundleProjectWithMap, scanModulesChisel, CLIENT_INJECT, SERVER_INJECT, type MemoryFiles } from "./bundler"
 export {
   compileServerBundle,
+  clientPublishes,
+  ClientPublishError,
   scanServerExports,
   scanServerModules,
   stubServerEntries,
@@ -17,7 +19,7 @@ export {
   type ServerExportKind,
   type ServerManifest,
 } from "./serverSplit"
-export { deriveEndpointParams, EndpointTypeError, type DeriveResult } from "./serverTypes"
+export { deriveEndpointParams, EndpointTypeError, SyncEndpointError, UnawaitedUserQueryError, WrongSideGlobalError, type DeriveResult } from "./serverTypes"
 export {
   detectEntry,
   scanModulesFallback,

package/src/compile/serverSplit.ts

@@ -9,7 +9,7 @@
  * side effects, not entry exports) — the runner reads that (src/server/runtime.ts).
  *
  * Export kinds are found by a static scan (no TS program needed): a function export is an
- * endpoint, a `channel(...)` export is a channel, anything else is server-only.
+ * endpoint, a `channel<…>()…` export is a channel, anything else is server-only.
  */
 
 import type { AppConfig } from "../server/auth/appConfig"
@@ -129,25 +129,70 @@ export const serverStubSource = (path: string, exports: ServerExport[], serverUr
   return `// client stub of ${mod} — generated by the lecodes compiler\n${lines.join("\n")}\n`
 }
 
+// ───────────────────────────── a channel in the app ─────────────────────────────
+
+/** A channel export has ONE type on both sides, so `publish` type-checks in the app — where the
+ *  export is the subscribing proxy. Said at compile time, with what to do instead. */
+export class ClientPublishError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`a channel goes from the server to the app — the app subscribes; to send, call a server function that publishes:\n  ${problems.join("\n  ")}`)
+    this.name = "ClientPublishError"
+    this.problems = problems
+  }
+}
+
+/** `<channel>.publish(` in the project's client files, for every channel imported from a `*.server.ts`. */
+export const clientPublishes = (entries: CompileEntry[]): string[] => {
+  const channels = new Map<string, Set<string>>()
+  for (const [path, exports] of Object.entries(scanServerModules(entries))) {
+    const names = exports.filter(e => e.kind === "channel").map(e => e.name)
+    if (names.length) channels.set(path.replace(/\.[tj]s$/, ""), new Set(names))
+  }
+  if (channels.size === 0) return []
+  const out: string[] = []
+  for (const e of entries) {
+    if (e.type !== "text" || isServerPath(e.path) || !/\.[tj]sx?$/.test(e.path)) continue
+    const src = e.text ?? ""
+    const dir = normalizePath(e.path).replace(/\/[^/]*$/, "")
+    const locals: string[] = []
+    for (const m of src.matchAll(/import\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g)) {
+      if (!m[2].startsWith(".")) continue
+      const names = channels.get(normalizePath(`${dir}/${m[2]}`).replace(/\.[tj]s$/, ""))
+      if (!names) continue
+      for (const part of m[1].split(",")) {
+        const [imported, local] = part.split(/\s+as\s+/).map(s => s.trim())
+        if (imported && names.has(imported)) locals.push(local ?? imported)
+      }
+    }
+    if (!locals.length) continue
+    const code = blankCommentsAndStrings(src)
+    for (const local of locals) {
+      for (const m of code.matchAll(new RegExp(`(?<![\\w$.])${local.replace(/\$/g, "\\$")}\\s*\\.\\s*publish\\s*\\(`, "g"))) {
+        out.push(`${serverModuleId(e.path)}:${code.slice(0, m.index).split("\n").length}: ${local}.publish(…)`)
+      }
+    }
+  }
+  return out
+}
+
 // ───────────────────────────── server entry ─────────────────────────────
 
 export const SERVER_ENTRY_PATH = "/.server-entry.ts"
 /** The SDK's app-config placeholder (src/server/auth/appConfig.ts) — the compile overrides it in the file map
- *  with the project's real values (project files win over SDK files), so `auth.model.user()` and friends see
+ *  with the project's real values (project files win over SDK files), so an SDK module that imports it sees
  *  app.json as an ordinary import. */
 export const APP_CONFIG_PATH = "/__sdk/server/auth/appConfig.ts"
 
 /** Compile-time manifest embedded in the server bundle (validators land here — see serverTypes.ts). */
 export type ServerManifest = {
   modules: Record<string, ServerExport[]>
-  /** endpoint id → JSON-schema-ish param list (filled by the TS-checker pass; absent = unvalidated). */
+  /** endpoint id → JSON-schema-ish param list (filled by the TS-checker pass; absent = unvalidated).
+   *  A channel id → the parameters of its `groupBy` (what the app passes to `subscribe`). */
   params?: Record<string, unknown[]>
-  /** The `app.json` subset the server runtime reads (name, auth providers); the bundle itself gets it as the
+  /** The `app.json` subset the server runtime reads (the app's name); the bundle itself gets it as the
    *  compiled-in `appConfig` module (APP_CONFIG_PATH). */
   app?: AppConfig
-  /** Some server file references the `auth` global: the runner then resolves a device session on every
-   *  request (minting one on first contact). Projects that never touch `auth` pay nothing. */
-  usesAuth?: boolean
 }
 
 /** The synthetic entry: imports every export by name (chisel has no namespace imports) and registers
@@ -196,12 +241,15 @@ export type CompileServerOptions = {
   /** Derive per-endpoint argument validators from the TS parameter types (serverTypes.ts) and embed
    *  them in the manifest. Default true; throws `EndpointTypeError` on non-JSON parameter types. */
   validate?: boolean
+  /** The TypeScript the validators are derived with, for a caller that brings its own (the CLI takes
+   *  the project's); absent = the `typescript` package this module can import. */
+  typescript?: typeof import("typescript")
   /** Precomputed param schemas to embed instead of deriving them. */
   params?: Record<string, unknown[]>
   /** Server bundles are readable by default (stack traces in the server console). */
   minify?: boolean
   sourcemap?: boolean
-  /** The project's `app.json` (name + auth providers) — embedded in the manifest and exposed to the bundle. */
+  /** The project's `app.json` subset (its name) — embedded in the manifest and exposed to the bundle. */
   app?: AppConfig
 }
 
@@ -224,12 +272,11 @@ export const compileServerBundle = async (opts: CompileServerOptions): Promise<{
   }
   let params = opts.params
   if (!params && opts.validate !== false) {
-    const derived = await deriveEndpointParams(opts.entries, modules)
+    const derived = await deriveEndpointParams(opts.entries, modules, opts.typescript)
     for (const w of derived.warnings) console.warn(`warning: ${w}`)
     params = derived.params
   }
-  const usesAuth = opts.entries.some(e => e.type === "text" && isServerPath(e.path) && /\bauth\s*\./.test(blankCommentsAndStrings(e.text ?? "")))
-  const manifest: ServerManifest = { modules: Object.fromEntries(Object.entries(modules).map(([p, ex]) => [serverModuleId(p), ex])), params, app: opts.app, usesAuth }
+  const manifest: ServerManifest = { modules: Object.fromEntries(Object.entries(modules).map(([p, ex]) => [serverModuleId(p), ex])), params, app: opts.app }
   if (opts.app) files[APP_CONFIG_PATH] = `export const app = ${JSON.stringify(opts.app)}\n`
   files[SERVER_ENTRY_PATH] = serverEntrySource(modules, manifest)
   const { code } = await bundleProjectWithMap(

package/src/compile/serverTypes.ts

@@ -13,13 +13,17 @@
  * compile error: functions, classes with methods, `Date`, `Map`/`Set`, symbols, recursive types —
  * "endpoint args must be JSON-serializable". Return types are not validated.
  *
+ * A channel's `groupBy(fn)` is the same case: `fn` is called with what the app passed to
+ * `subscribe`, so its parameters get a schema under the channel's id.
+ *
  * `typescript` is loaded lazily (it's a devDependency of the SDK and a dependency of the platform
  * compile step); the browser-safe parts of the compiler never import this module's runtime.
  */
 
 import type { CompileEntry } from "./compileProject"
 import type { ParamSchema, Schema } from "../server/validate"
-import { serverModuleId, type ServerExport } from "./serverSplit"
+import { isServerPath, serverModuleId, type ServerExport } from "./serverSplit"
+import { readInjectSources } from "./bundler"
 
 type TS = typeof import("typescript")
 
@@ -42,6 +46,87 @@ export class EndpointTypeError extends Error {
   }
 }
 
+/**
+ * In the app an endpoint's call is always a promise: it goes over the network. An endpoint that is
+ * not `async` is imported with the type it was written with (`number`), so `const n = add(1, 2)`
+ * type-checks and holds a promise. Declared `async`, the two agree.
+ */
+export class SyncEndpointError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`an endpoint is called over the network, so in the app its result is a promise — declare it async:\n  ${problems.join("\n  ")}`)
+    this.name = "SyncEndpointError"
+    this.problems = problems
+  }
+}
+
+/**
+ * The app and the server are two programs with two sets of globals: `UIText`, `Vec3`, `toast` exist
+ * in the app only, `defineDb`, `ApiError`, `channel` in server files only. The project's types
+ * declare both sets everywhere (one tsconfig), so a global used on the wrong side type-checks — and
+ * is a ReferenceError when that line runs. The compile refuses it instead.
+ */
+export class WrongSideGlobalError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`the app and the server have their own globals — one is used on the wrong side:\n  ${problems.join("\n  ")}`)
+    this.name = "WrongSideGlobalError"
+    this.problems = problems
+  }
+}
+
+/** The value names an inject module exports (`export { a, b as c, type T } from "…"`). */
+const injectNames = (ts: TS, source: string): Set<string> => {
+  const out = new Set<string>()
+  const sf = ts.createSourceFile("inject.ts", source, ts.ScriptTarget.ESNext, false)
+  for (const st of sf.statements) {
+    if (!ts.isExportDeclaration(st) || st.isTypeOnly || !st.exportClause || !ts.isNamedExports(st.exportClause)) continue
+    for (const el of st.exportClause.elements) if (!el.isTypeOnly) out.add(el.name.text)
+  }
+  return out
+}
+
+/**
+ * Uses of a global of the other side, in the project's files of `program`. A name counts when it is
+ * a VALUE the file does not declare or import itself (the checker finds no symbol for it: this
+ * program has no SDK types) — so a local `t`, a parameter `request`, a property `x.model` are not
+ * touched. A name both sides have (`ref`), and one the server's runtime has by itself (`fetch`), are
+ * nobody's mistake.
+ */
+const wrongSideGlobals = (ts: TS, program: import("typescript").Program, checker: import("typescript").TypeChecker, projectFiles: Set<string>): string[] => {
+  const sources = readInjectSources()
+  const app = injectNames(ts, sources.client), server = injectNames(ts, sources.server)
+  const appOnly = new Set([...app].filter(n => !server.has(n) && !(n in globalThis)))
+  const serverOnly = new Set([...server].filter(n => !app.has(n)))
+  const out: string[] = []
+  for (const sf of program.getSourceFiles()) {
+    if (!projectFiles.has(sf.fileName) || sf.isDeclarationFile) continue
+    const onServer = isServerPath(sf.fileName)
+    const foreign = onServer ? appOnly : serverOnly
+    const file = serverModuleId(sf.fileName)
+    const seen = new Set<string>()
+    const visit = (node: import("typescript").Node) => {
+      if (ts.isTypeNode(node)) return                                   // a type is erased: no harm at run time
+      if (ts.isIdentifier(node) && foreign.has(node.text) && !seen.has(node.text)) {
+        const parent = node.parent as import("typescript").Node & { name?: import("typescript").Node, propertyName?: import("typescript").Node }
+        // the name of a declaration, of a property (`x.model`, `{ model: 1 }`), of an import / export specifier
+        const isName = (parent.name === node || parent.propertyName === node) && !ts.isShorthandPropertyAssignment(parent)
+        const symbol = isName ? null : ts.isShorthandPropertyAssignment(parent) ? checker.getShorthandAssignmentValueSymbol(parent) : checker.getSymbolAtLocation(node)
+        if (!isName && !symbol) {
+          seen.add(node.text)                                           // once per file: the first use
+          const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
+          out.push(onServer
+            ? `${file}:${line + 1}: ${node.text} is a global of the app — it does not exist in server code`
+            : `${file}:${line + 1}: ${node.text} is a global of server files (*.server.ts) — it does not exist in the app: call an endpoint that uses it`)
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(sf)
+  }
+  return out
+}
+
 export type DeriveResult = {
   /** endpoint id → parameter schemas (only endpoints the checker could see). */
   params: Record<string, ParamSchema[]>
@@ -52,9 +137,10 @@ export type DeriveResult = {
  * Derive `{ "<module>#<fn>": ParamSchema[] }` for every function export of every `*.server.ts` entry.
  * Throws `EndpointTypeError` when a parameter type can't be validated at runtime.
  */
-export const deriveEndpointParams = async (entries: CompileEntry[], modules: Record<string, ServerExport[]>): Promise<DeriveResult> => {
+export const deriveEndpointParams = async (entries: CompileEntry[], modules: Record<string, ServerExport[]>, typescript?: TS): Promise<DeriveResult> => {
   let ts: TS
-  try {
+  if (typescript) ts = typescript
+  else try {
     ts = (await import("typescript")).default ?? (await import("typescript")) as unknown as TS
   } catch {
     throw new Error("serverTypes: the `typescript` package is required to compile server endpoints")
@@ -66,7 +152,8 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
     if (!/\.[tj]sx?$/.test(e.path)) continue
     files.set(normalizePath(e.path), e.text)
   }
-  const roots = Object.keys(modules).map(normalizePath).filter(p => files.has(p))
+  // the server modules, and every other file of the project: the app's are read for the globals they use
+  const roots = [...new Set([...Object.keys(modules).map(normalizePath).filter(p => files.has(p)), ...files.keys()])]
 
   const options: import("typescript").CompilerOptions = {
     target: ts.ScriptTarget.ESNext,
@@ -104,6 +191,11 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
   const params: Record<string, ParamSchema[]> = {}
   const warnings: string[] = []
   const problems: string[] = []
+  const sync: string[] = []
+  // a promise, or anything awaited the same way (a query handed back as it is); `any` is not judged
+  const awaitable = (type: import("typescript").Type): boolean =>
+    !!(type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))
+    || (type.flags & ts.TypeFlags.Union ? (type as import("typescript").UnionType).types.every(awaitable) : !!type.getProperty("then"))
 
   for (const [path, exports] of Object.entries(modules)) {
     const sf = program.getSourceFile(normalizePath(path))
@@ -112,26 +204,45 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
     if (!modSym) continue
     const exported = new Map(checker.getExportsOfModule(modSym).map(s => [s.name, s]))
     for (const ex of exports) {
-      if (ex.kind !== "fn") continue
+      if (ex.kind === "other") continue
       const id = `${serverModuleId(path)}#${ex.name}`
       let sym = exported.get(ex.name)
       if (!sym) { warnings.push(`${id}: export not found by the checker — unvalidated`); continue }
       if (sym.flags & ts.SymbolFlags.Alias) sym = checker.getAliasedSymbol(sym)
       const decl = sym.valueDeclaration ?? sym.declarations?.[0]
       if (!decl) { warnings.push(`${id}: no declaration — unvalidated`); continue }
-      const type = checker.getTypeOfSymbolAtLocation(sym, decl)
+      let type: import("typescript").Type
+      let where = id
+      if (ex.kind === "channel") {
+        // `channel` is a global this program has no types for: the hook is found in the text of the export
+        const hook = groupByHook(ts, decl)
+        if (!hook) { params[id] = []; continue }
+        type = checker.getTypeAtLocation(hook)
+        where = `${id}.groupBy`
+      } else {
+        type = checker.getTypeOfSymbolAtLocation(sym, decl)
+      }
       const sig = type.getCallSignatures()[0]
-      if (!sig) { warnings.push(`${id}: not callable — unvalidated`); continue }
+      if (!sig) { warnings.push(`${where}: not callable — unvalidated`); continue }
+      if (ex.kind === "fn" && !awaitable(checker.getReturnTypeOfSignature(sig))) {
+        const { line } = sf.getLineAndCharacterOfPosition(decl.getStart(sf))
+        sync.push(`${serverModuleId(path)}:${line + 1}: ${ex.name} — write \`async\` before it`)
+      }
       const list: ParamSchema[] = []
       for (const p of sig.getParameters()) {
         const pd = p.valueDeclaration as import("typescript").ParameterDeclaration | undefined
+        // nothing here gives a hook's parameter a type but its own annotation — without one it is `any`, unchecked
+        if (ex.kind === "channel" && pd && !pd.type && !pd.initializer) {
+          problems.push(`${where}(${p.name}): give the parameter a type — it is what the app passes to subscribe, and it is checked against it`)
+          continue
+        }
         const ptype = checker.getTypeOfSymbolAtLocation(p, pd ?? decl)
         const rest = !!pd?.dotDotDotToken
         const optional = !!pd?.questionToken || !!pd?.initializer || rest
         try {
           // `x?: T` carries `undefined` in its type — the optional flag covers it, strip it from the schema
           const members = ptype.flags & ts.TypeFlags.Union ? (ptype as import("typescript").UnionType).types : [ptype]
-          const schema = lowerMembers(ts, checker, pd?.questionToken ? members.filter(t => !(t.flags & ts.TypeFlags.Undefined)) : members, `${id}(${p.name})`, new Set())
+          const schema = lowerMembers(ts, checker, pd?.questionToken ? members.filter(t => !(t.flags & ts.TypeFlags.Undefined)) : members, `${where}(${p.name})`, new Set())
           list.push({ name: p.name, schema, optional, rest })
         } catch (e) {
           problems.push((e as Error).message)
@@ -141,9 +252,79 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
     }
   }
   if (problems.length) throw new EndpointTypeError(problems)
+  if (sync.length) throw new SyncEndpointError(sync)
+  const wrongSide = wrongSideGlobals(ts, program, checker, new Set(files.keys()))
+  if (wrongSide.length) throw new WrongSideGlobalError(wrongSide)
+  const unawaited: string[] = []
+  for (const path of Object.keys(modules)) {
+    const sf = program.getSourceFile(normalizePath(path))
+    if (sf) unawaited.push(...unawaitedUserQueries(ts, sf, serverModuleId(path)))
+  }
+  if (unawaited.length) throw new UnawaitedUserQueryError(unawaited)
   return { params, warnings }
 }
 
+/** The function given to `.groupBy(…)` in a channel export's initializer (`channel<M>().authorize(…).groupBy(fn)`). */
+const groupByHook = (ts: TS, decl: import("typescript").Declaration): import("typescript").Expression | null => {
+  let node: import("typescript").Expression | undefined = ts.isVariableDeclaration(decl) ? decl.initializer : undefined
+  while (node) {
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node)) { node = node.expression; continue }
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return null
+    if (node.expression.name.text === "groupBy") return node.arguments[0] ?? null
+    node = node.expression.expression
+  }
+  return null
+}
+
+// ───────────────────────────── the user of a request is a QUERY ─────────────────────────────
+
+/**
+ * `db.auth.requireUser(...)` / `db.auth.user()` build a query: the check of who is calling happens when
+ * it is AWAITED. Written as a statement, or tested in a condition, it does nothing — and an endpoint
+ * that looks guarded is open to anyone. So such a query must be awaited (or returned) where it is made.
+ */
+export class UnawaitedUserQueryError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`the user of a request is read with await — a query that is not awaited checks nothing:\n  ${problems.join("\n  ")}`)
+    this.name = "UnawaitedUserQueryError"
+    this.problems = problems
+  }
+}
+
+const unawaitedUserQueries = (ts: TS, sf: import("typescript").SourceFile, file: string): string[] => {
+  const out: string[] = []
+  // `<x>.requireUser(…)` whatever it is called on; `.user()` only on something named `auth` (`auth.user()`, `db.auth.user()`)
+  const isUserQuery = (node: import("typescript").Node): node is import("typescript").CallExpression => {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return false
+    const name = node.expression.name.text
+    if (name === "requireUser") return true
+    if (name !== "user" || node.arguments.length) return false
+    const on = node.expression.expression
+    return (ts.isIdentifier(on) && on.text === "auth") || (ts.isPropertyAccessExpression(on) && on.name.text === "auth")
+  }
+  const awaited = (node: import("typescript").Node): boolean => {
+    const parent = node.parent
+    if (ts.isParenthesizedExpression(parent) || ts.isAsExpression(parent) || ts.isNonNullExpression(parent)) return awaited(parent)
+    // `.select(…)` continues the same query
+    if (ts.isPropertyAccessExpression(parent) && parent.expression === node && parent.name.text === "select" && ts.isCallExpression(parent.parent)) return awaited(parent.parent)
+    if (ts.isAwaitExpression(parent) || ts.isReturnStatement(parent)) return true
+    if (ts.isArrowFunction(parent) && parent.body === node) return true
+    // one of several things awaited together: `await Promise.all([db.auth.requireUser(), …])`
+    if (ts.isArrayLiteralExpression(parent) && ts.isCallExpression(parent.parent)) return awaited(parent.parent)
+    return false
+  }
+  const visit = (node: import("typescript").Node) => {
+    if (isUserQuery(node) && !awaited(node)) {
+      const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
+      out.push(`${file}:${line + 1}: ${node.expression.getText(sf)}(…) — write \`await\` before it`)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return out
+}
+
 // ───────────────────────────── type → schema ─────────────────────────────
 
 const lower = (ts: TS, checker: import("typescript").TypeChecker, type: import("typescript").Type, where: string, stack: Set<import("typescript").Type>): Schema => {

package/src/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/src/inject.ts

@@ -39,10 +39,11 @@ 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"
+export { __rpc, __channel, __serverOnly, RpcError } from "./runtime/rpc"
+export type { ChannelSubscription } from "./server/channel"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"
 // Game audio (docs/audio-plan.md): decoded clips, a voice pool, buses with effects; 3D through the
 // AudioSource / AudioZone aspects (gl/) and scene.audio.
@@ -118,9 +119,9 @@ export type { DismissOptions, PresentOptions, Transition, TransitionName, Transi
 // The base node type + the union a container accepts as children — documented as the signature of
 // UIColumn/UIRow/append/etc., so they must be global (type-only; erased at runtime).
 export type { UINode, UINodeChild } from "./ui/UINode"
-// App theme variables (docs/ui-theme-plan.md): theme({...}) merges + returns typed var()
-// accessors; system vars are static props (theme.primaryColor, theme["comfort-top"], …).
-export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme"
+// App theme variables: theme({...}) merges + returns the var() accessors; the roles the SDK reads
+// are static props (theme.accent, theme["comfort-top"], …). `el.theme({...})` scopes a subtree.
+export { theme, type ThemeValues, type ThemeAccessors, type ThemeRoles } from "./ui/theme"
 
 // ---- animate ----
 // animate() runs on the keyframe core (a VALUE track) since 2026-09-14: same handle, easing and clocks
@@ -136,7 +137,7 @@ export { type EasingInput } from "./animate/tween/easing"
 export { easeIn, easeOut, easeInOut } from "./animate/easings"
 
 // ---- plugins (optional, host-provided capabilities — typed NativeView/service wrappers). The first-party
-// ones are VENDORED from the plugin repo (src/plugins/gen, `bun run vendor:plugins`); oauth / service are the SDK's. ----
+// ones are VENDORED from the plugin repo (src/plugins/gen, `bun run vendor:plugins`); service is the SDK's. ----
 export { QRScanner } from "./plugins/gen/qr-scanner/sdk/qr-scanner"
 export { CameraView, type CameraFacing } from "./plugins/gen/camera/sdk/camera"
 export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/gen/geolocation/sdk/geolocation"
@@ -146,7 +147,6 @@ export {
   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"
 
 // ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----

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) {