lecodes-sdk 2.2.10 → 2.2.13

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.10",
+  "version": "2.2.13",
   "files": [
     "src",
     "dist",
-    "prompts",
     "tests/helpers",
     "README.md"
   ],

package/src/bridges/media.d.ts

@@ -18,7 +18,9 @@ import type { f32, f64, i32 } from "./types"
 declare global {
   /** @host media @optional */
   var _creatorMedia: {
-    /** A player for `src` as an owned Handle (null = the host failed to create one). @custom */
+    /** A player for `src` as an owned Handle (null = the host failed to create one). `src` is a url
+     *  or `"id:<bufferId>"` (a host buffer: a local asset, a File, a FetchResponse), which the host
+     *  resolves. @custom */
     createAudio(src: string): Handle | null
     /** @custom */
     createVideo(src: string): Handle | null

package/src/canvas/Canvas.ts

@@ -115,14 +115,14 @@ export class Canvas extends Recorder {
   }
 
   /** Decode an image source into a standalone `Bitmap` you can blit with `drawImage()` — either an
-   *  `SvgSource(...)` (drawn by the core, painted by the host) or a `FetchResponse` holding already-fetched
-   *  image bytes (decoded; an SVG file is detected). This is async because the web host decodes with the
-   *  browser; `await` it ONCE, then `drawImage(bitmap, …)` is synchronous and the Bitmap is reusable. The
-   *  returned Bitmap owns a native surface at the image's natural pixel size (`pixelRatio` 1), freed
-   *  once nothing references the Bitmap (`destroy()` frees it early). Typical use:
+   *  `SvgSource(...)` (drawn by the core, painted by the host) or a `FetchResponse` / `File` holding
+   *  already-fetched image bytes (decoded; an SVG file is detected). This is async because the web host
+   *  decodes with the browser; `await` it ONCE, then `drawImage(bitmap, …)` is synchronous and the Bitmap
+   *  is reusable. The returned Bitmap owns a native surface at the image's natural pixel size
+   *  (`pixelRatio` 1), freed once nothing references the Bitmap (`destroy()` frees it early). Typical use:
    *    const logo = await canvas.loadImage(SvgSource(svg))   // or: await fetch(url) → the response
    *    canvas.drawImage(logo, 0, 0)                          // sync, blit as often as you like */
-  loadImage(source: SvgSourceValue | FetchResponse): Promise<Bitmap> {
+  loadImage(source: SvgSourceValue | FetchResponse | File): Promise<Bitmap> {
     // Discriminate without touching FetchResponse internals: only an SvgSource carries `.svg`.
     const isSvg = typeof (source as SvgSourceValue).svg === "string"
     const svg = isSvg ? (source as SvgSourceValue).svg : ""

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/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"

package/src/runtime/app.ts

@@ -56,8 +56,10 @@ export const app = {
   sdkVersion: SDK_VERSION,
   /** The INSTALLED app: the store build this bundle runs in. After an over-the-air update the code
    *  is newer than the binary, so a feature that needs native support added in a later store build
-   *  (a plugin, an SDK method) branches on `app.host.sdk` / `app.host.build` — and on `typeof` of
-   *  the method itself, which is the final word. Minor and patch of the SDK never gate anything. */
+   *  (a plugin, an SDK method) branches on `app.host.sdk` / `app.host.build` — and on the feature's
+   *  own check (`Push.isSupported`, `Physics.supported`), which is the final word. Not `typeof` of
+   *  the global: every SDK wrapper is compiled into the bundle, so `typeof Push` is "object" on a
+   *  host without the plugin. Minor and patch of the SDK never gate anything. */
   get host(): AppHost {
     return {
       version: _creatorApp.appVersion?.(),

package/src/runtime/fetch.ts

@@ -21,6 +21,9 @@ export interface FetchResponse {
   readonly status: number
   json<T = any>(): T
   text(): string
+  /** The body's bytes, a copy — a binary format of your own (`asset('./levels/1.bin')`), parsed in
+   *  code with a DataView. Synchronous, like `text()`. */
+  bytes(): Uint8Array
   /** @deprecated A no-op: the body is freed with the response's handle (owned handles). Apps written
    *  against the pre-owned SDK still call it after `text()` / `json()`; remove the call. */
   dispose(): void
@@ -42,6 +45,9 @@ class FetchResponseImpl implements FetchResponse {
   text(): string {
     return _creatorFetch.toText(this._h.id)
   }
+  bytes(): Uint8Array {
+    return _creatorFetch.toBytes(this._h.id)
+  }
   /** @deprecated see the interface */
   dispose(): void {}
 }

package/src/runtime/media.ts

@@ -7,10 +7,14 @@
 // then; a paused player you stop referencing is released at once. There is nothing to dispose. The
 // end-of-playback report comes by id through ONE emitter per world; a playing player is pinned so
 // the report finds it.
+//
+// `src` is a url, or a `File` / `FetchResponse`: those play from the host's buffer store
+// (`"id:<bufferId>"`, the whole bytes in memory, no streaming).
 
 import { Emitter } from "../core/events"
 import { Pins } from "../core/pins"
 import { Texture } from "../gl/Texture"
+import type { File, FetchResponse } from "./fetch"
 
 type MediaEvents = {
   /** Fired at each loop boundary while `loop` is true. */
@@ -30,6 +34,9 @@ const ensureEmitter = (): void => {
   emitterInstalled = true
   m.setEmitter((id) => { players.get(id)?._finished() })
 }
+/** The wire spelling of a source: a url as is, a buffer (File / FetchResponse) as "id:<bufferId>". */
+const wireSrc = (src?: string | File | FetchResponse): string =>
+  src == null ? "" : typeof src === "string" ? src : "id:" + (src as any)._h.id
 
 abstract class MediaPlayer extends Emitter<MediaEvents> {
   /** @internal The player's owned handle (`_h.id` = the host player id; -1 = no host player). */
@@ -92,18 +99,18 @@ abstract class MediaPlayer extends Emitter<MediaEvents> {
 }
 
 export class AudioPlayer extends MediaPlayer {
-  constructor(src?: string) {
+  constructor(src?: string | File | FetchResponse) {
     super()
-    this._src = src ?? ""
+    this._src = wireSrc(src)
     ensureEmitter()
     this._h = media()?.createAudio(this._src) ?? { id: -1 }
   }
 }
 
 export class VideoPlayer extends MediaPlayer {
-  constructor(src?: string) {
+  constructor(src?: string | File | FetchResponse) {
     super()
-    this._src = src ?? ""
+    this._src = wireSrc(src)
     ensureEmitter()
     this._h = media()?.createVideo(this._src) ?? { id: -1 }
   }

package/src/runtime/storage.ts

@@ -1,15 +1,25 @@
 // Key/value persistence backed by the host (`_creatorStorage`). Same shape as the web localStorage
-// subset projects use.
+// subset projects use — including `localStorage['theme'] = 'dark'` / `localStorage.theme`, the
+// browser habit: a Proxy routes any key that is not one of the three methods to the host, so the
+// habit saves instead of setting a field on a plain object that nothing persists.
 
-
-export const localStorage = {
+const methods = {
   getItem(key: string): string | null {
     return _creatorStorage.get(key)
   },
   setItem(key: string, value: string): void {
-    _creatorStorage.set(key, value)
+    _creatorStorage.set(key, String(value))
   },
   removeItem(key: string): void {
     _creatorStorage.remove(key)
   },
 }
+
+export type LocalStorage = typeof methods & { [key: string]: any }
+
+export const localStorage: LocalStorage = new Proxy(methods as LocalStorage, {
+  get: (t, key) => typeof key === "string" && !(key in t) ? t.getItem(key) ?? undefined : (t as any)[key],
+  set: (t, key, value) => { if (typeof key === "string" && !(key in t)) t.setItem(key, value); return true },
+  deleteProperty: (t, key) => { if (typeof key === "string" && !(key in t)) t.removeItem(key); return true },
+  has: (t, key) => key in t || (typeof key === "string" && t.getItem(key) !== null),
+})

package/src/server/db/marci/query.ts

@@ -173,7 +173,13 @@ export type AggregateResult<TModel, T> =
 // A lazily-executed operation. `await` runs it as a single request;
 // passing it into `db.$transaction([...])` bundles it into one atomic transaction
 declare const __op: unique symbol
-export type Op<T> = PromiseLike<T> & { readonly [__op]: T }
+/** What a query or an op offers of a promise: `then`, `catch`, `finally` — the runtime object has
+ *  all three (`op()` / the collection builder below), so `db.x.insert(…).catch(…)` type-checks. */
+export type Settles<T> = PromiseLike<T> & {
+  catch<R = never>(onRejected?: ((reason: any) => R | PromiseLike<R>) | null): Promise<T | R>
+  finally(onFinally?: (() => void) | null): Promise<T>
+}
+export type Op<T> = Settles<T> & { readonly [__op]: T }
 
 // A transport-neutral operation descriptor and the pluggable transport that runs it. The HTTP transport
 // is selected by passing a URL string; marcidb-embedded provides an in-process FFI transport.
@@ -229,7 +235,7 @@ export type IdArg<I> = I | BareId<I>
  * it to `$transaction` batches it; placing it in another query's select makes it a sub-select. `Sel` is the
  * projection: id + scalars until `select(...)` sets a shape.
  */
-export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends PromiseLike<Rows<T, Sel>[]> {
+export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Settles<Rows<T, Sel>[]> {
   readonly [__op]: Rows<T, Sel>[]
   readonly [__sub]: T["name"]
   readonly [__sel]: Effective<T, Sel>

package/src/ui/UIButton.ts

@@ -1,9 +1,9 @@
 import { ClickEvent, TouchStartEvent, LongPressEvent, MouseEnterEvent } from "../runtime/touch"
 import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType, LongPressEvent as LongPressEventType, MouseEnterEvent as MouseEnterEventType } from "../runtime/touch"
-import { type ElementStyle, type ContainerStyle, ContainerElement, buildUI, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color } from "./UINode"
+import { type ElementStyle, type ContainerStyle, ContainerElement, buildUI, type DrawableStyle, type TextStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color } from "./UINode"
 import { TREE_FLAG_CLICK, TREE_FLAG_HOVER, TREE_FLAG_INTERACTIVE, TREE_FLAG_LONG_PRESS, tree } from "./tree"
 
-export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { rippleColor?: Color | "default" }
+export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & TextStyle & { rippleColor?: Color | "default" }
 
 /** A tappable container — row + centered children by default. Press feedback via the `$pressed`
  *  class block or `rippleColor`. */

package/src/ui/UIContainer.ts

@@ -1,6 +1,8 @@
-import { ContainerElement, buildUI, type ChildrenFn, type ContainerStyle, type DrawableStyle, type ElementStyle, type UIChildArg, type UIContainerBase, type UINodeChild } from "./UINode"
+import { ContainerElement, buildUI, type ChildrenFn, type ContainerStyle, type DrawableStyle, type ElementStyle, type TextStyle, type UIChildArg, type UIContainerBase, type UINodeChild } from "./UINode"
 
-export type UIContainerStyle = ElementStyle & DrawableStyle & ContainerStyle
+/** A container's style: its box and layout, plus the text props (`color`, `fontSize`, `textWrap` …)
+ *  the texts inside inherit from it. */
+export type UIContainerStyle = ElementStyle & DrawableStyle & ContainerStyle & TextStyle
 
 /** A vertical flex container — children stack top to bottom. */
 export interface UIColumn extends UIContainerBase<UIContainerStyle> {