lecodes-sdk 2.2.11 → 2.2.14

package/package.json

@@ -12,7 +12,6 @@
     "./inject": "./src/inject.ts",
     "./plugin": "./src/plugin.ts",
     "./server": "./src/server/host.ts",
-    "./prompts/select": "./prompts/select.ts",
     "./global.d.ts": "./dist/global.d.ts",
     "./host.d.ts": "./dist/host.d.ts",
     "./editor.d.ts": "./dist/editor.d.ts",
@@ -30,12 +29,11 @@
     "test": "bun test --randomize",
     "typecheck": "tsc --noEmit",
     "docs:check": "node docs/check.mjs",
-    "prompts:build": "bun prompts/compose.ts",
     "sync:marcidb": "bun scripts/sync-marcidb.ts",
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@letary/chisel": "^0.14.0"
+    "@letary/chisel": "^0.15.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",
@@ -45,11 +43,10 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.2.11",
+  "version": "2.2.14",
   "files": [
     "src",
     "dist",
-    "prompts",
     "tests/helpers",
     "README.md"
   ],

package/src/compile/assetIconMacro.ts

@@ -244,7 +244,8 @@ const iconExpr = (svg: string, call: IconCall): string => {
   return call.tint ? `Object.assign(${src}, { tintColor: (${call.tint}) })` : src
 }
 
-const escapeTemplate = (s: string) => s.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${")
+/** Text into a template literal: backslash, backtick and `${` escaped. */
+export const escapeTemplate = (s: string) => s.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${")
 
 // ---- the macro pass -----------------------------------------------------------------------------
 

package/src/compile/assetMacro.ts

@@ -92,7 +92,8 @@ export type AssetMacroRef = { path: string, index: number, length: number, line:
  *  image, a sound, a video, a model, a font, raw bytes) plus `.svg` (an SvgSource, what UIImage
  *  takes). Not `.json`, whose asset is its parsed data — a `.json` path in a string stays a string. */
 const BARE_PATH_EXT = /\.(png|jpe?g|webp|gif|avif|bmp|svg|mp3|wav|ogg|m4a|aac|flac|mp4|webm|mov|m4v|glb|gltf|ktx2|hdr|exr|ttf|otf|woff2?|bin|bake|filamat)$/i
-const CODE_EXT = /\.([tj]sx?|mjs|cjs|json)$/i
+/** A module the bundler parses as code (and .json, which is data it understands): never a text asset. */
+export const CODE_EXT = /\.([tj]sx?|mjs|cjs|json)$/i
 // What precedes an import specifier: the literal is a module path, never a resource reference.
 const IMPORT_BEFORE = /(?:\bfrom|\bimport|\bimport\s*\(|\brequire\s*\()\s*$/
 

package/src/compile/compileProject.ts

@@ -8,6 +8,8 @@ import { detectEntry } from "./detectEntry"
 import { buildHeader } from "./header"
 import { inlineSourceMapComment, offsetSourceMap } from "./sourcemap"
 import { ClientPublishError, clientPublishes, stubServerEntries } from "./serverSplit"
+import { CODE_EXT } from "./assetMacro"
+import { escapeTemplate } from "./assetIconMacro"
 
 export type CompileFileType = "text" | "resource" | "shader"
 
@@ -145,12 +147,20 @@ export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: strin
         files[e.path] = `export default ""` // local-only shader with no compiled artifact yet
       }
     } else if (e.path.toLowerCase().endsWith(".svg")) {
-      files[e.path] = `export default SvgSource(\`${e.text ?? ""}\`)`
+      // The file's text sits in a template literal: a backtick, `${` or a backslash in it (an
+      // editor's `<!-- exported by \`tool\` -->` comment) would otherwise end the literal and fail
+      // the compile with a chisel parse error that names nothing a person can act on.
+      files[e.path] = `export default SvgSource(\`${escapeTemplate(e.text ?? "")}\`)`
     } else if (e.path.toLowerCase().endsWith(".json")) {
       // A .json project file is DATA, not code: `import data from "./x.json"` — and `asset("./x.json")`,
       // which desugars to that import — yields the parsed value. The bundler would otherwise try to
       // parse the file as JS. JSON is an expression, so a default export is the whole translation.
       files[e.path] = `export default ${e.text?.trim() || "null"}`
+    } else if (!CODE_EXT.test(e.path)) {
+      // Any other text file (.txt, .csv, .md, .css, .html, .xml, .yml …) is its TEXT: `asset("./levels.csv")`
+      // yields the string. Handing the raw text to the bundler as a module parsed as JS failed at
+      // run time instead (`__asset_0 is not defined`), after a compile that said nothing.
+      files[e.path] = `export default ${JSON.stringify(e.text ?? "")}`
     } else {
       files[e.path] = e.text ?? ""
     }
@@ -158,13 +168,27 @@ export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: strin
   return files
 }
 
-/** The ids app.json lists under `"plugins"` (id → version), in its order. */
+/** app.json's `"plugins"` in either shape — `{ "camera": "*" }` (id → version spec) or
+ *  `["camera"]` (ids, every version `*`) — as id → spec. Anything else is no plugin. The list
+ *  form is what CLAUDE.md and most hands write first; reading it as "no plugins" dropped the
+ *  plugin from a web build and a shell with one warning nobody tied to the shape. */
+export const pluginSpecsOf = (plugins: unknown): Record<string, string> => {
+  if (Array.isArray(plugins)) return Object.fromEntries(plugins.filter((p): p is string => typeof p === "string").map((id) => [id, "*"]))
+  if (plugins && typeof plugins === "object") {
+    return Object.fromEntries(Object.entries(plugins as Record<string, unknown>).map(([id, v]) => [id, typeof v === "string" ? v : "*"]))
+  }
+  return {}
+}
+
+/** The ids of app.json's `"plugins"` (either shape), in its order. */
+export const pluginIdsOf = (plugins: unknown): string[] => Object.keys(pluginSpecsOf(plugins))
+
+/** The ids app.json lists under `"plugins"`, in its order. */
 export const pluginsOfAppJson = (entries: CompileEntry[]): string[] => {
   const app = entries.find(e => e.path.replace(/^[./\\]+/, "") === "app.json")
   if (!app?.text) return []
   try {
-    const plugins = (JSON.parse(app.text) as { plugins?: unknown }).plugins
-    return plugins && typeof plugins === "object" && !Array.isArray(plugins) ? Object.keys(plugins) : []
+    return pluginIdsOf((JSON.parse(app.text) as { plugins?: unknown }).plugins)
   } catch {
     return []   // a broken app.json is reported by whoever reads it as a config
   }

package/src/compile/header.ts

@@ -28,6 +28,18 @@ export type HeaderOptions = {
   plugins?: string[]
 }
 
+/** The optional engines of the game stack, by the bundled bridge calls that mean "in use": a body,
+ *  a character, a vehicle or a ragdoll created, a ray cast, a sound loaded or played, the net
+ *  bridge named, a navmesh call. Not the calls every 3D bundle carries (Node's body pose setters,
+ *  Scene's audio listener). A `Physics.supported` probe pulls the Physics class whole, so it
+ *  counts as use — the full variant is the safe side of that line. */
+export const ENGINE_SIGNALS: readonly (readonly [name: "physics" | "net" | "nav" | "audio", re: RegExp])[] = [
+  ["physics", /_creator\.(?:physicsCreateBody|physicsConfigure|physicsRaycast|characterCreate|vehicleCreate|ragdollCreate)\(/],
+  ["net", /\b_creatorNet\b/],   // the net core takes the bridge into a local once (core.ts bridge()): its calls never name it
+  ["nav", /_creatorNav\.\w+\(/],
+  ["audio", /_creatorAudio\.(?:loadClip|play)\(/],   // a sound loaded or played; Scene's listener setters ride in every 3D bundle
+]
+
 export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}): string => {
   let header = `// sdk: ${SDK_VERSION}\n`
   header += `// name: ${name.slice(0, 20)}\n`
@@ -51,6 +63,11 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
   // bundle, and nothing 2D works without a Scene2D anyway.
   if (code.includes("_creator2d.createScene")) header += `// 2d: enable\n`
 
+  // The game stack a shell's SDK variant must carry (the `3d` variant has no Jolt, net, nav or
+  // game audio; `2d` / `core` no net or nav): the CLI's resolveVariant reads these lines, so a 3D
+  // game with physics no longer gets a variant where Physics.configure throws on the device.
+  for (const [name, re] of ENGINE_SIGNALS) if (re.test(code)) header += `// ${name}: enable\n`
+
   if (usesAR(code, opts.plugins)) header += `// ar: enable\n`
 
   // Short, so with the engine lines: a host reads it before it registers anything.

package/src/compile/index.ts

@@ -68,6 +68,8 @@ export {
   compileProject,
   compileProjectWithMap,
   pluginsOfAppJson,
+  pluginSpecsOf,
+  pluginIdsOf,
   pluginsOfBundle,
   entriesToFiles,
   localAssetNames,

package/src/compile/serverSplit.ts

@@ -2,14 +2,14 @@
  * The client/server split of a project (docs/backend-plan.md §4).
  *
  * `*.server.ts` files never reach the client bundle: `compileProject` swaps each one for a STUB
- * module whose exports are RPC/channel proxies (`__rpc`, `__channel`, `__serverOnly` — client SDK
+ * module whose exports are RPC/channel proxies (`__rpc`, `__channel`, `__pushChannel`, `__serverOnly` — client SDK
  * globals, src/runtime/rpc.ts), so `import { listNotes } from "./notes.server"` in client code keeps
  * its types and calls the server. `compileServerBundle` bundles the same files with the SERVER inject
  * behind a synthetic entry that registers every module on `globalThis.__lecodesServer` (chisel keeps
  * 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, a `pushChannel<…>()` export a push channel, anything else is server-only.
  */
 
 import type { AppConfig } from "../server/auth/appConfig"
@@ -29,7 +29,7 @@ export const serverModuleId = (path: string) => path.split("\\").join("/").repla
  * a helper: a function that is not async is used by server files alone, and the app's import of
  * it is refused at compile time (serverTypes.ts), never a call that silently holds a promise.
  */
-export type ServerExportKind = "fn" | "channel" | "other"
+export type ServerExportKind = "fn" | "channel" | "push" | "other"
 export type ServerExport = { name: string, kind: ServerExportKind }
 
 // ───────────────────────────── static export scan ─────────────────────────────
@@ -66,6 +66,7 @@ const IDENT = "[A-Za-z_$][\\w$]*"
 const classifyInit = (init: string): ServerExportKind => {
   const s = init.trimStart()
   if (/^channel\s*[<(]/.test(s)) return "channel"
+  if (/^pushChannel\s*[<(]/.test(s)) return "push"
   if (/^async\s+function\b/.test(s)) return "fn"
   if (/^async\b/.test(s)) return "fn"                              // async (…) => / async x =>
   return "other"                                                    // a sync function, a value: the server's own
@@ -113,38 +114,43 @@ export const scanServerExports = (source: string, path = "<server module>"): Ser
 // ───────────────────────────── client stubs ─────────────────────────────
 
 /** The client-side replacement of a `*.server.ts` module. `serverUrl` is baked in (draft/prod are
- *  separate compiles); "" means "no server deployed" — calls fail with a clear error. */
-export const serverStubSource = (path: string, exports: ServerExport[], serverUrl: string): string => {
+ *  separate compiles); "" means "no server deployed" — calls fail with a clear error. `push` = the project
+ *  has push channels (in this module or another): the stub opens by installing the push runtime, so the
+ *  transport registers the device when the server asks, whether or not the app hears a channel itself. */
+export const serverStubSource = (path: string, exports: ServerExport[], serverUrl: string, push = exports.some(e => e.kind === "push")): string => {
   const mod = serverModuleId(path)
   const url = JSON.stringify(serverUrl)
   const lines = exports.map(({ name, kind }) => {
     const id = JSON.stringify(`${mod}#${name}`)
     if (kind === "fn") return `export const ${name} = __rpc(${url}, ${id})`
     if (kind === "channel") return `export const ${name} = __channel(${url}, ${id})`
+    if (kind === "push") return `export const ${name} = __pushChannel(${url}, ${id})`
     return `export const ${name} = __serverOnly(${id})`
   })
+  if (push) lines.unshift("__pushEnable()")
   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 is the subscribing proxy; a push channel's `send` likewise. 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  ")}`)
+    super(`a channel goes from the server to the app — the app listens; to send, call a server function that publishes (a push channel: that sends):\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`. */
+/** `<channel>.publish(` and `<pushChannel>.send(` 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>>()
+  /** module → export name → the server's verb */
+  const channels = new Map<string, Map<string, 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))
+    const names = new Map(exports.filter(e => e.kind === "channel" || e.kind === "push").map(e => [e.name, e.kind === "push" ? "send" : "publish"]))
+    if (names.size) channels.set(path.replace(/\.[tj]s$/, ""), names)
   }
   if (channels.size === 0) return []
   const out: string[] = []
@@ -152,21 +158,22 @@ export const clientPublishes = (entries: CompileEntry[]): string[] => {
     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[] = []
+    const locals: [string, 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)
+        const verb = imported ? names.get(imported) : undefined
+        if (verb) locals.push([local ?? imported, verb])
       }
     }
     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(…)`)
+    for (const [local, verb] of locals) {
+      for (const m of code.matchAll(new RegExp(`(?<![\\w$.])${local.replace(/\$/g, "\\$")}\\s*\\.\\s*${verb}\\s*\\(`, "g"))) {
+        out.push(`${serverModuleId(e.path)}:${code.slice(0, m.index).split("\n").length}: ${local}.${verb}(…)`)
       }
     }
   }
@@ -228,10 +235,13 @@ export const scanServerModules = (entries: CompileEntry[]): Record<string, Serve
 }
 
 /** Replace each `*.server.ts` entry with its client stub (returns a new entries array). */
-export const stubServerEntries = (entries: CompileEntry[], serverUrl: string): CompileEntry[] =>
-  entries.map(e => e.type === "text" && isServerPath(e.path)
-    ? { ...e, text: serverStubSource(e.path, scanServerExports(e.text ?? "", serverModuleId(e.path)), serverUrl) }
+export const stubServerEntries = (entries: CompileEntry[], serverUrl: string): CompileEntry[] => {
+  const modules = scanServerModules(entries)
+  const push = Object.values(modules).some(exports => exports.some(e => e.kind === "push"))
+  return entries.map(e => e.type === "text" && isServerPath(e.path)
+    ? { ...e, text: serverStubSource(e.path, modules[normalizePath(e.path)] ?? [], serverUrl, push) }
     : e)
+}
 
 export type CompileServerOptions = {
   entries: CompileEntry[]

package/src/compile/serverTypes.ts

@@ -237,7 +237,7 @@ 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 === "other") continue
+      if (ex.kind === "other" || ex.kind === "push") 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 }

package/src/core/Aspect.ts

@@ -403,7 +403,8 @@ export abstract class AspectHost<E extends EventMap = EventMap> extends Emitter<
 }
 
 // ---- systems: aspects of a scene --------------------------------------------
-/** @internal What a scene needs to carry systems. Scene / Scene2D implement it over these helpers. */
+/** What a scene needs to carry systems: Scene and Scene2D implement it over the helpers below. Public
+ *  (never stripped from the public types: the `System` type names it). */
 export type SystemHost = { readonly _systems: Map<Function, Aspect<any, any, any>> }
 
 /** @internal `scene.system(Ctor, opts)`. */

package/src/g2/Physics2D.ts

@@ -231,9 +231,12 @@ export class Physics2D extends Aspect<"physics", Node2D> {
   }
   private static _gravity: [number, number] = [ 0, -980 ]
 
-  /** Whether this build has physics support (CREATOR_2D_PHYSICS). NOTE: this reports the BUILD, not
-   *  the world — there is nothing else to guard, since the world creates itself. */
-  static get supported(): boolean { return !!_creator2d.physicsHasSupport && _creator2d.physicsHasSupport() }
+  /** Whether this host has 2D physics (a 2D engine built with CREATOR_2D_PHYSICS). False, never a
+   *  throw, where there is no 2D engine at all (Web Lite, a 3d / core engine variant). It reports
+   *  the build, not the world — there is nothing else to guard, since the world creates itself. */
+  static get supported(): boolean {
+    return typeof _creator2d !== "undefined" && !!_creator2d && typeof _creator2d.physicsHasSupport === "function" && _creator2d.physicsHasSupport()
+  }
 
   /** Render interpolation of body transforms between the fixed 60 Hz steps (global; default on). Turn
    *  off to save per-frame transform writes when you have many moving bodies / don't need >60 Hz

package/src/g2/Scene2D.ts

@@ -62,6 +62,12 @@ export class Scene2D implements Presentable {
   private static _active: Scene2D | null = null
   static get active(): Scene2D | null { return Scene2D._active }
 
+  /** Whether this host has the 2D engine. False on Web Lite (UI and 3D only) and in a 3d / core
+   *  engine variant of an app built with `lecodes app`; there `new Scene2D()` throws. */
+  static get supported(): boolean {
+    return typeof _creator2d !== "undefined" && !!_creator2d && typeof _creator2d.createScene === "function"
+  }
+
   /** @internal — scene-level pointer listeners (the catch-all; target = hit node or null). */
   readonly _clickListeners: Array<(ev: ClickEvent<Node2D | null>) => void> = []
   readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node2D | null>) => void> = []
@@ -70,6 +76,7 @@ export class Scene2D implements Presentable {
   private readonly _filter?: 'nearest' | 'linear'
 
   constructor(options: Scene2DOptions = {}) {
+    if (!Scene2D.supported) throw new Error("Scene2D: this host has no 2D engine (Web Lite runs UI and 3D apps; a 3d / core engine variant has no 2D) — check Scene2D.supported before creating one")
     installRenderSyncedFrames()
     this.id = _creator2d.createScene()
     this.camera = new Camera2D(this.id)
@@ -121,7 +128,8 @@ export class Scene2D implements Presentable {
   }
 
   // ---- systems: aspects of the scene (core/Aspect.ts `System<'x', Scene2D>`) ----
-  /** @internal class → instance, the authoritative store (named accessors mirror this). */
+  /** class → instance, the authoritative store (named accessors mirror this). Kept in the public
+   *  types: it is what makes a Scene2D a `SystemHost` there. */
   readonly _systems = new Map<Function, Aspect<any, any, any>>()
 
   /** Attach (and configure) a system, or reconfigure it if already present. Returns the scene typed

package/src/gl/Scene.ts

@@ -206,7 +206,14 @@ export class Scene implements Presentable {
   private static _active: Scene | null = null
   static get active(): Scene | null { return Scene._active }
 
+  /** Whether this host has the 3D engine. False where the bundle was marked `gl: disable` (no scene
+   *  created anywhere in it) and in a 2d / core engine variant; there `new Scene()` throws. */
+  static get supported(): boolean {
+    return typeof _creator !== "undefined" && !!_creator && typeof _creator.createScene === "function"
+  }
+
   constructor(options: SceneOptions = {}) {
+    if (!Scene.supported) throw new Error("Scene: this host has no 3D engine (a 2d / core engine variant, or a bundle that creates no scene) — check Scene.supported before creating one")
     installRenderSyncedFrames()
     const parent = (options as any)._parent as Scene | undefined
     if (parent) {
@@ -366,7 +373,8 @@ export class Scene implements Presentable {
   }
 
   // ---- systems: aspects of the scene (core/Aspect.ts `System`) ----
-  /** @internal class → instance, the authoritative store (named accessors mirror this). */
+  /** class → instance, the authoritative store (named accessors mirror this). Kept in the public
+   *  types: it is what makes a Scene a `SystemHost` there. */
   readonly _systems = new Map<Function, Aspect<any, any, any>>()
 
   /** Attach (and configure) a system, or reconfigure it if already present. Returns the scene typed

package/src/gl/Texture.ts

@@ -1,6 +1,7 @@
 // A 3D GPU texture, decoded natively by creator-gl. Load from a URL or an already-fetched response.
 
 import { fetch, type FetchResponse, type File } from "../runtime/fetch"
+import type { Canvas } from "../canvas/Canvas"
 
 /** `Texture.load` options. */
 export type TextureLoadOptions = {
@@ -57,7 +58,7 @@ export class Texture {
   // Wrap a Canvas's baked surface as a 3D texture (RGBA8, already rasterized → synchronous, no decode).
   // The id is cached on the canvas (opaque _tex3dId), so backing several materials shares one texture and
   // canvas.update() re-uploads it. Structural type avoids a Canvas import (keeps 3D free of 2D-canvas code).
-  static fromCanvas(canvas: { _bakeSurface(): number, width: number, height: number, pixelRatio: number, _tex3dId: number }): Texture {
+  static fromCanvas(canvas: Canvas): Texture {
     if (!canvas._tex3dId) {
       const surfaceId = canvas._bakeSurface()
       canvas._tex3dId = _creator.createTextureFromCanvas(surfaceId)

package/src/gl/animation/DynamicBone.ts

@@ -54,8 +54,8 @@ const FLOOR_NONE = 0, FLOOR_PLANE = 1, FLOOR_PROBE = 2
 
 let warned = false
 const supported = (): boolean => {
-  if (_creator.dynamicBoneCreate) return true
-  if (!warned) { warned = true; console.warn("DynamicBone needs a newer host (no dynamicBoneCreate) — the animation shows as is") }
+  if (DynamicBone.supported) return true
+  if (!warned) { warned = true; console.warn("DynamicBone: this host has no dynamic bones (DynamicBone.supported is false) — the animation shows as is") }
   return false
 }
 
@@ -134,6 +134,10 @@ export class DynamicBoneCollider extends Aspect<"dynamicBoneCollider", Node> {
 export class DynamicBone extends Aspect<"dynamicBone", Node> {
   static readonly aspect = "dynamicBone"
 
+  /** Whether this host simulates dynamic bones. False, never a throw, on Web Lite and in headless
+   *  tests; there the aspect attaches, warns once, and `chain` stays empty. */
+  static get supported(): boolean { return typeof _creator !== "undefined" && !!_creator && typeof _creator.dynamicBoneCreate === "function" }
+
   /** Only these bones (by name) join the chain — the root always does, a bone left out takes its
    *  subtree with it. Default: the root's whole subtree. */
   bones?: string[]

package/src/gl/animation/Locomotion.ts

@@ -225,9 +225,15 @@ export type LocomotionEvents = {
   state: (state: LocomotionState) => void
 }
 
+let locoWarned = false
+
 export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
   static readonly aspect = "loco"
 
+  /** Whether this host runs the locomotion selector. False, never a throw, on Web Lite and in
+   *  headless tests; there the aspect attaches, warns once, and the body stays `'idle'`. */
+  static get supported(): boolean { return typeof _creator !== "undefined" && !!_creator && typeof _creator.locoCreate === "function" }
+
   /** The animator whose clips are shown. Default: the first one on this node or under it (a Model
    *  child), which is the usual character — a capsule node with the model inside. */
   animator?: Animator
@@ -281,7 +287,11 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
    *  walk, a slowed-down character). */
   rebuild(): void {
     const anim = this.anim
-    if (!anim || !_creator.locoCreate) return
+    if (!Locomotion.supported) {
+      if (!locoWarned) { locoWarned = true; console.warn("Locomotion: this host has no locomotion engine (Locomotion.supported is false) — the character stays idle") }
+      return
+    }
+    if (!anim) return
     if (!this._loco) {
       const first = this.set.idle ?? (this.set.gaits ?? [])[0]     // binding a clip is what creates the native animator
       if (first !== undefined) anim._slot(name(first))

package/src/gl/physics/Physics.ts

@@ -209,9 +209,10 @@ export class Physics extends Aspect<"physics", Node> implements CompWriter {
     _creator.physicsConfigure(cx(g), cy(g), cz(g), config.maxBodies ?? 0)
   }
 
-  /** Whether this build has physics support (CREATOR_GL_PHYSICS). */
+  /** Whether this host has 3D physics (an engine built with CREATOR_GL_PHYSICS). False, never a
+   *  throw, where there is no 3D engine at all. */
   static get supported(): boolean {
-    return !!_creator.physicsHasSupport && _creator.physicsHasSupport()
+    return typeof _creator !== "undefined" && !!_creator && typeof _creator.physicsHasSupport === "function" && _creator.physicsHasSupport()
   }
 
   /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. */

package/src/gl/physics/Ragdoll.ts

@@ -45,7 +45,7 @@ import type { FieldMeta } from "../../core/fields"
 import { Mathf } from "../../math/Mathf"
 import { cx, cy, cz, Vec3, type Vec3Like } from "../../math/vec"
 import { Node } from "../Node"
-import { DEFAULT_FRICTION } from "./Physics"
+import { DEFAULT_FRICTION, Physics } from "./Physics"
 
 export interface RagdollHinge {
   /** The hinge axis in the MODEL's space (its rest pose: +Z forward, +Y up, +X the model's left in
@@ -169,6 +169,11 @@ export const humanoidParts = (find: (role: string) => string | null): RagdollPar
 export class Ragdoll extends Aspect<"ragdoll", Node> {
   static readonly aspect = "ragdoll"
 
+  /** Whether this host can drop a body: 3D physics with ragdoll parts. False, never a throw,
+   *  without physics or on an older host. A host that has it can still refuse the parts
+   *  (`activate()` returns false). */
+  static get supported(): boolean { return Physics.supported && typeof _creator.ragdollCreate === "function" }
+
   /** The parts: `'humanoid'` (default) finds the standard bones by name; a list places bodies on any
    *  bones — parents before children. */
   parts: RagdollPart[] | "humanoid" = "humanoid"
@@ -243,9 +248,9 @@ export class Ragdoll extends Aspect<"ragdoll", Node> {
   private _release: { left: number; blend: number } | null = null
 
   onAttach(): void {
-    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    if (!Physics.supported) return
     if (!_creator.ragdollCreate) {
-      console.warn("Ragdoll needs a newer host (no ragdollCreate) — the body will not fall")
+      console.warn("Ragdoll: this host has no ragdoll parts (Ragdoll.supported is false) — the body will not fall")
       return
     }
     const find = (role: string): string | null => {

package/src/gl/vehicle/Vehicle.ts

@@ -194,6 +194,11 @@ const clamp = (v: number, lo: number, hi: number): number => (v < lo ? lo : v >
 export class Vehicle extends Aspect<"vehicle", Node> {
   static readonly aspect = "vehicle"
 
+  /** Whether this host can drive a car: 3D physics with the vehicle model. False, never a throw,
+   *  without physics or on an older host. A host that has it can still refuse a car's settings
+   *  (`id` stays 0, with a warning). */
+  static get supported(): boolean { return Physics.supported && typeof _creator.vehicleCreate === "function" }
+
   /** Chassis mass in kg (default 1200). Wheels are massless in this model. */
   mass = 1200
   /** Centre of mass height in chassis space (metres, negative = lower). Left out, it drops to halfway
@@ -274,9 +279,9 @@ export class Vehicle extends Aspect<"vehicle", Node> {
   private _retunePending = false
 
   onAttach(): void {
-    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    if (!Physics.supported) return
     if (!_creator.vehicleCreate) {
-      console.warn("Vehicle needs a newer host (no vehicleCreate) — the car will not move")
+      console.warn("Vehicle: this host has no vehicle model (Vehicle.supported is false) — the car will not move")
       return
     }
     const shape = this.node.get(Shape)

package/src/host.d.ts

@@ -6,8 +6,11 @@
 import type { SvgSource } from "./runtime/misc"
 
 declare global {
-  function setTimeout(handler: (...args: any[]) => void, timeout?: number): number
-  function setInterval(handler: (...args: any[]) => void, timeout?: number): number
+  /** As in the browser, but the delay is REQUIRED (the native runtime throws without it) and no
+   *  extra argument reaches the handler. Timers tick with the frame on every native host: one
+   *  frame is the resolution. */
+  function setTimeout(handler: () => void, timeout: number): number
+  function setInterval(handler: () => void, timeout: number): number
   function clearTimeout(id: number): void
   function clearInterval(id: number): void
   /** Per-frame loop, driven by the host (viewer RAF / desktop runTick). `dt` is **seconds** since
@@ -38,6 +41,9 @@ declare global {
   /** Compile-time macro: `asset('./logo.svg')` yields the file as an SVG image source — for
    *  `UIImage(...)` and `bgImage`. */
   function asset(path: `${string}.svg`): SvgSource
+  /** Compile-time macro: `asset('./levels.csv')` yields a text file's TEXT (.txt, .csv, .md, .css,
+   *  .html, .xml, .yml — it ships inside the bundle). Parse it yourself. */
+  function asset(path: `${string}.${"txt" | "csv" | "md" | "css" | "html" | "xml" | "yml" | "yaml"}`): string
   /** 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

@@ -9,7 +9,7 @@
 
 // ---- math ----
 export { Mathf } from "./math/Mathf"
-export { Vec2, Vec3 } from "./math/vec"
+export { Vec2, Vec3, type Vec2Like, type Vec3Like } from "./math/vec"
 export { Quat } from "./math/quat"
 export { Mat4 } from "./math/mat4"
 export { Color } from "./core/color"
@@ -43,10 +43,11 @@ export { WebSocket } from "./runtime/net"
 export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform, type NetCorrection } from "./net"
 // 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 } from "./runtime/rpc"
+export { __rpc, __channel, __pushChannel, __serverOnly, RpcError } from "./runtime/rpc"
 // What a screen asks of the server, as reactive state: a request a screen follows, an action with its own busy / error.
 export { resource, action, dataOf, failureOf, type Loaded, type Failure, type Resource, type Action } from "./runtime/resource"
 export type { ChannelSubscription } from "./server/channel"
+export type { PushChannel, PushMessage, PushNotification, PushTarget } from "./server/pushChannel"
 export type { StoredFile, StoredImage } from "./server/files/models"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"
 // Game audio (docs/audio-plan.md): decoded clips, a voice pool, buses with effects; 3D through the
@@ -162,7 +163,7 @@ export {
   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 { Push, __pushEnable, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/gen/push/sdk/push"
 export { Browser, WebView, type BrowserOpenOptions, type WebViewParams, type WebViewEvents } from "./plugins/gen/browser/sdk/browser"
 export {
   RTCPeerConnection, MediaStream, MediaStreamTrack, RTCDataChannel, RTCRtpSender, RTCRtpReceiver, RTCRtpTransceiver,

package/src/plugin.ts

@@ -44,6 +44,9 @@ export { Quat, type QuatLike } from "./math/quat"
 export { Mat4 } from "./math/mat4"
 export type { ClickEvent, TouchStartEvent } from "./runtime/touch"
 export type { DismissOptions } from "./ui/presentable"
+/** The seam the push plugin's wrapper installs its runtime on (src/runtime/pushSeam.ts): what the app's transport
+ *  reads the device's address from, registers through, and a push channel's handlers are kept by. */
+export { _pushRuntime, type PushRuntime } from "./runtime/pushSeam"
 /** @internal The navigation epoch: a destination that prepares before it presents (ARScene) reads it
  *  before its awaits and gives up when another navigation moved it meanwhile. */
 export { _navEpoch }