lecodes-sdk 1.1.0 → 2.0.0

package/src/compile/compileProject.ts

@@ -45,7 +45,7 @@ export type CompileOptions = {
   /** "esm" (default, shipped) or "iife" (self-running, for the local renderer). */
   format?: "esm" | "iife"
   /** Resolve `asset()` resources to a LOCAL host asset at runtime instead of a `publicUrl` URL: each
-   *  resource compiles to `"id:" + _creatorUtils.fetchLocal(<name>)` (the host reads the file by name
+   *  resource compiles to `"id:" + _creatorFetch.local(<name>)` (the host reads the file by name
    *  and returns its systemId). For hosts with no asset server (the desktop native host), where a URL
    *  can't be fetched. Off by default — the shipped/web build keeps the URL form. */
   localAssets?: boolean
@@ -62,6 +62,12 @@ export type CompileOptions = {
    *  `/__lib/<slug>/…` and reachable from project code via `import … from "<slug>"`. See
    *  docs/library-system-plan.md §4. */
   libraries?: Record<string, MemoryFiles>
+  /** The plugins of the app, by id — the `// plugins:` line of the header. Default: the keys of
+   *  `"plugins"` in the project's app.json, when it is among the entries. */
+  plugins?: string[]
+  /** What the compile has to say that is not an error: a plugin the bundle uses and app.json does
+   *  not list. */
+  onWarning?: (message: string) => void
   /** Base URL of the project's deployed server (draft or prod), baked into the RPC/channel stubs
    *  that replace every `*.server.ts` module in the client bundle (docs/backend-plan.md §4). Server
    *  files never reach the client bundle either way; with no URL, calling an endpoint fails with
@@ -109,13 +115,14 @@ export const localAssetNames = (entries: readonly { path: string, type: string }
 export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: string, localAssets?: boolean }): Record<string, string> => {
   const files: Record<string, string> = {}
   const localNames = localAssetNames(entries)
+  const localAssetId = (nameExpr: string) => `_creatorFetch.local(${nameExpr})`
   for (const e of entries) {
     if (e.type === "resource") {
       if (opts.localAssets && !e.remote) {
         // The host resolves the asset by name at runtime (reads the local file → systemId); the
         // "id:" prefix is the host's local-resource URL scheme (parsed by the UI + 2D texture paths).
         const name = localNames.get(e.path) ?? localAssetBase(e.path)
-        files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(name)}))`
+        files[e.path] = `export default ("id:" + ${localAssetId(JSON.stringify(name))})`
       } else {
         files[e.path] = `export default "${opts.publicUrl}${e.fileSrc ?? ""}"`
       }
@@ -131,7 +138,7 @@ export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: strin
         // (URLs) and un-staged ones keep the URL forms below.
         const name = shaders[0].src.split(/[\/]/).pop() ?? ""
         const [prefix, suffix = ".filamat"] = name.split("_opengl")
-        files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(prefix + "_")} + _creator.backend + ${JSON.stringify(suffix)}))`
+        files[e.path] = `export default ("id:" + ${localAssetId(`${JSON.stringify(prefix + "_")} + _creator.backend + ${JSON.stringify(suffix)}`)})`
       } else if (shaders.length > 0) {
         files[e.path] = `export default \`${opts.publicUrl}${shaders[0].src.replace("_opengl", "_${_creator.backend}")}\``
       } else {
@@ -151,6 +158,31 @@ export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: strin
   return files
 }
 
+/** The ids app.json lists under `"plugins"` (id → version), 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) : []
+  } catch {
+    return []   // a broken app.json is reported by whoever reads it as a config
+  }
+}
+
+/** The plugins whose WRAPPER has code in the bundle, by id — read off the source map's sources:
+ *  what chisel shook away is not there, so an app that never names a plugin carries none. */
+export const pluginsOfBundle = (mapJson: string): string[] => {
+  const ids = new Set<string>()
+  try {
+    for (const source of (JSON.parse(mapJson) as { sources?: string[] }).sources ?? []) {
+      const m = /\/plugins\/gen\/([^/]+)\/sdk\//.exec(source)
+      if (m) ids.add(m[1]!)
+    }
+  } catch { /* no map, no answer */ }
+  return [...ids].sort()
+}
+
 export const compileProjectWithMap = async (opts: CompileOptions): Promise<CompileResult> => {
   // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
   const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
@@ -163,8 +195,15 @@ export const compileProjectWithMap = async (opts: CompileOptions): Promise<Compi
   const { code, map } = await bundleProjectWithMap(
     entry, files, opts.format ?? "esm", opts.minify, opts.editor, opts.libraries, opts.sourcemap ?? true,
   )
+  const plugins = opts.plugins ?? pluginsOfAppJson(entries)
+  if (map && opts.onWarning) {
+    const missing = pluginsOfBundle(map).filter(id => !plugins.includes(id))
+    if (missing.length) {
+      opts.onWarning(`The app uses ${missing.map(id => `"${id}"`).join(", ")} and app.json does not list ${missing.length === 1 ? "it" : "them"}: a plugin that is not listed is not there — in a shell built from this project and in the browser alike. Add to app.json: "plugins": { ${missing.map(id => `"${id}": "*"`).join(", ")} }`)
+    }
+  }
   if (opts.header === false) return { code, map, entry }
-  const header = buildHeader(opts.name, code, { icon: opts.icon, fonts: opts.fontsHeader, icons: opts.iconsHeader })
+  const header = buildHeader(opts.name, code, { icon: opts.icon, fonts: opts.fontsHeader, icons: opts.iconsHeader, plugins })
   // Shift the map down past the header (prepended before the code).
   const headerLines = (header.match(/\n/g) ?? []).length
   return { code: header + code, map: map ? offsetSourceMap(map, headerLines) : null, entry }

package/src/compile/fontMacro.ts

@@ -9,7 +9,7 @@
 //
 // Registry ids resolve against the vendored snapshot (fontRegistry.ts). Two source modes:
 //   cdn    — faces stay remote: the generated code bakes registry URLs, picking woff2/ttf via the
-//            host's `_creatorUI.fontFormat` (absent → ttf). Platform/server-backed compiles.
+//            host's `_creatorTree.fontFormat` (absent → ttf). Platform/server-backed compiles.
 //   vendor — the caller downloads faces into the project (assets/fonts/ + fonts.lock.json) and
 //            hands back their entry paths; faces then ride the normal asset pipeline (dev URLs,
 //            `id:` + fetchLocal, lecodesfile://) — fully offline, and local faces register
@@ -417,7 +417,7 @@ export const applyFontMacro = async (entries: FontMacroEntry[], opts: FontMacroO
       const ref = faces.get(key)!
       let urlExpr: string
       if (ref.source.kind === "cdn") {
-        urlExpr = `${JSON.stringify(ref.source.urlBase)} + (_creatorUI.fontFormat ?? "ttf")`
+        urlExpr = `${JSON.stringify(ref.source.urlBase)} + (_creatorTree.fontFormat ?? "ttf")`
       } else {
         let ident = faceImports.get(ref.source.path)
         if (!ident) {
@@ -427,8 +427,7 @@ export const applyFontMacro = async (entries: FontMacroEntry[], opts: FontMacroO
         }
         urlExpr = ident
       }
-      const optionsExpr = ref.italic ? `{ weight: ${ref.weight}, style: "italic" }` : `{ weight: ${ref.weight} }`
-      body.push(`_creatorUI.registerFont(${JSON.stringify(ref.family)}, ${urlExpr}, ${optionsExpr}, () => {}, () => {})`)
+      body.push(`_creatorTree.registerFont(${JSON.stringify(ref.family)}, ${urlExpr}, ${ref.weight}, ${ref.italic ? 2 : 0}, () => {}, () => {})`)
     }
     for (const [family, ident] of idents) lines.push(`export const ${ident} = ${JSON.stringify(family)}`)
     lines.push(...body)

package/src/compile/header.ts

@@ -1,11 +1,18 @@
-// The metadata header the launcher reads from the compiled bundle: name / icon / gl / 2d / ar /
-// preload / fonts / icons. Single source of truth — the backend and CLI both call this (today they
+// The metadata header the launcher reads from the compiled bundle: sdk / name / icon / gl / 2d / ar /
+// plugins / preload / fonts / icons. Single source of truth — the backend and CLI both call this (today they
 // mirror it by hand).
 //
+// `// sdk: <version>` is the FIRST line: the SDK this bundle was compiled with (sdk/src/version.ts).
+// Its major is the bundle ↔ runtime contract — the launchers send it as `?sdk=` when they fetch a
+// published bundle (the platform keeps one bundle per major), and every host refuses a bundle whose
+// major is not its own before evaluating it. A bundle without the line predates 2.0.
+//
 // Detection keys on the *bundled* `_creator*` calls, which the SDK's thin wrappers still emit
 // (new Scene() → _creator.createScene, new Scene2D() → _creator2d.createScene), so the re-skin keeps
 // the exact same signals the old worker bundles produced.
 
+import { SDK_VERSION } from "../version"
+
 export type HeaderOptions = {
   /** Generated-icon URL (backend supplies it; the CLI omits it). */
   icon?: string
@@ -15,10 +22,15 @@ export type HeaderOptions = {
   /** `// icons:` payload from the assetIcon() macro (buildIconsHeaderValue) — the icon packs whose
    *  glyphs are inlined in the bundle. Purely informational (attribution record); hosts ignore it. */
   icons?: string
+  /** `// plugins:` — the ids app.json lists (`"plugins"`), ONE list for every platform: what a
+   *  native shell installs is what a web host registers, so an app cannot work in the browser and
+   *  fail in its shell. A bundle without the line has no plugin. */
+  plugins?: string[]
 }
 
 export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}): string => {
-  let header = `// name: ${name.slice(0, 20)}\n`
+  let header = `// sdk: ${SDK_VERSION}\n`
+  header += `// name: ${name.slice(0, 20)}\n`
   if (opts.icon) header += `// icon: ${opts.icon}\n`
   header += `// last-updated: ${new Date().toISOString()}\n`
 
@@ -41,9 +53,14 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
 
   if (code.includes("_creator.createARController")) header += `// ar: enable\n`
 
-  // Local assets to preload: explicit fetchLocal() calls + implicit engine archives.
+  // Short, so with the engine lines: a host reads it before it registers anything.
+  if (opts.plugins?.length) header += `// plugins: ${opts.plugins.join(";")}\n`
+
+  // Local assets to preload: explicit `.local()` calls on the fetch bridge + implicit engine archives.
+  // Any receiver counts (the SDK and the asset stub of compileProject call `_creatorFetch.local`);
+  // the string-literal test below is what keeps a stray `.local(` out.
   const localAssets = new Set<string>()
-  for (const m of code.matchAll(/_creatorUtils\.fetchLocal\((.+?)\)/g)) {
+  for (const m of code.matchAll(/[\w$]\.local\((.+?)\)/g)) {
     const arg = m[1].trim()
     // Only a plain string literal names a file. A computed argument (the local-shader lookup
     // builds `"<hash>_" + _creator.backend + ".filamat"` at runtime, since one bundle serves
@@ -51,6 +68,10 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
     if (!/^(['"])[^'"]*\1$/.test(arg)) continue
     localAssets.add(arg.slice(1, -1).trim())
   }
+  // The engine's own materials, asked for by name (`_creator.builtinMaterial("lit")`): the header
+  // says WHICH (`material:lit`), never where they are — how a host keeps them (one archive, several
+  // it fetches by need) is the host's, and may change under a bundle compiled long ago.
+  for (const m of code.matchAll(/\.builtinMaterial\((['"])([^'"]+)\1\)/g)) localAssets.add(`material:${m[2]}`)
   if (/_creator\.createGlb/.test(code)) localAssets.add("uberarchive")
   if (/_creator\.captureImage/.test(code)) localAssets.add("capture")
   if (localAssets.size > 0) header += `// preload: ${[ ...localAssets ].join(";")}\n`

package/src/compile/index.ts

@@ -28,6 +28,7 @@ export {
   type ScanModule,
 } from "./detectEntry"
 export { sanitizeAssetName, isCanonicalAssetName } from "./assetName"
+export { SDK_VERSION, sdkMajor, bundleSdkVersion, bundleRunsOn } from "../version"
 export {
   PLATFORM_BUILD,
   LOCAL_PLATFORM_BUILD,
@@ -64,6 +65,8 @@ export { buildHeader, detectProjectKind, type HeaderOptions } from "./header"
 export {
   compileProject,
   compileProjectWithMap,
+  pluginsOfAppJson,
+  pluginsOfBundle,
   entriesToFiles,
   localAssetNames,
   localAssetBase,
@@ -73,7 +76,6 @@ export {
   type CompileResult,
 } from "./compileProject"
 export {
-  loadSceneHarness,
   sceneEditorEntries,
   sceneImportsOf,
   SCENE_ENTRY_PATH,

package/src/compile/liteMaterial.ts

@@ -1,7 +1,7 @@
 // .mat source → Web Lite material artifact.
 //
 // matc validates and compiles the .mat for the native platforms; the lite web runtime
-// (packages/viewer-lite) has no Filament, so it gets this JSON artifact instead: the parsed
+// (engines/gl-lite) has no Filament, so it gets this JSON artifact instead: the parsed
 // material definition (parameters, shading model, blending) plus the author's fragment body with
 // `materialParams.x` rewritten to `materialParams_x`. viewer-lite wraps that body in its own GLSL
 // template (src/gl/customMaterial.ts mirrors the artifact type) — GLSL knowledge stays there, this

package/src/compile/sceneEditor.ts

@@ -1,11 +1,13 @@
 // The scene-editor compile composition, shared by every host that compiles an edit-mode bundle
-// for a .scene.ts file: the platform backend (src/scene/compileSceneEditor.ts), the standalone
-// scene-editor dev server, and (later) the lecodes CLI. One bundle on purpose: chisel's
-// method-granular DCE trims each bundle's SDK copy to its own calls, so a separately-compiled
-// harness could not call scene methods on objects the scene bundle created.
+// for a .scene.ts file: the lecodes CLI (`lecodes scene`), the platform's build service, the scene
+// editor's own playground. One bundle on purpose: chisel's method-granular DCE trims each bundle's
+// SDK copy to its own calls, so a separately-compiled harness could not call scene methods on
+// objects the scene bundle created.
+//
+// The HARNESS — the editor's half that runs in the scene's world — is not the SDK's: it ships with
+// the editor (lecodes-3d-editor, `sceneHarness()` of its server entry) and the caller hands its
+// sources in. What it may use of the SDK is the editor contract (src/scene/editor.ts).
 
-import { existsSync, readdirSync, readFileSync } from "node:fs"
-import { join } from "node:path"
 import type { CompileEntry } from "./compileProject"
 
 /** Where the harness sources land in the compile's file map. The dotfolder can't collide with
@@ -15,24 +17,6 @@ export const SCENE_HARNESS_DIR = "./.scene-editor"
 /** The virtual entrypoint path (`entryOverride`). */
 export const SCENE_ENTRY_PATH = "./.scene-entry.ts"
 
-/**
- * Read the harness sources (packages/projects/src/scene-editor) from a directory:
- * `LECODES_SCENE_HARNESS_DIR` env override first (deployments vendor the sources, like
- * LECODES_SDK_INJECT does for the SDK), else the given fallback dir. Returns name → source.
- */
-export const loadSceneHarness = (fallbackDir?: string): Record<string, string> => {
-  const override = process.env.LECODES_SCENE_HARNESS_DIR
-  const dir = override && existsSync(override) ? override
-    : fallbackDir && existsSync(fallbackDir) ? fallbackDir
-    : null
-  if (!dir) throw new Error("scene-editor harness sources not found (set LECODES_SCENE_HARNESS_DIR)")
-  const out: Record<string, string> = {}
-  for (const f of readdirSync(dir)) {
-    if (f.endsWith(".ts")) out[f] = readFileSync(join(dir, f), "utf8")
-  }
-  return out
-}
-
 /**
  * The extra entries that turn a project compile into a scene-editor compile: the harness modules
  * plus a virtual entry that (1) sets the edit-mode flag in its own module — imports hoist, so the
@@ -43,8 +27,9 @@ export const loadSceneHarness = (fallbackDir?: string): Record<string, string> =
  * FULL extensions everywhere — exact-match specifiers need no resolver guesswork on dotted names,
  * so even the unpatched published chisel resolves the `.scene.ts` import.
  *
- * `scenePath` is the project path of the scene file ("./scenes/city.scene.ts"); `projectPaths` is
- * the project's file list — `.editor.ts` entries are picked out of it. Compile with
+ * `scenePath` is the project path of the scene file ("./scenes/city.scene.ts"); `harness` is the
+ * editor's harness, module name → source (its entry is `main.ts`); `projectPaths` is the project's
+ * file list — `.editor.ts` entries are picked out of it. Compile with
  * `entryOverride: SCENE_ENTRY_PATH`, `header: false`, `format: "iife"`, `editor: true`.
  */
 /** Resolve a relative import specifier against a project path ("./src/map.scene.ts" + "./map/x.scene"

package/src/core/color.ts

@@ -1,7 +1,12 @@
-// Shared color parsing for both engines. Users pass colors the natural ways — a CSS-ish hex string
-// ('#10131a', '#abc', '#rrggbbaa'), a packed number (0xff0000), or normalized components
-// ([r,g,b] / [r,g,b,a] in 0..1). The engines want different forms (2D wants 0..1 floats, 3D wants a
-// packed int), so this module is the single place that converts.
+// The one color conversion of the SDK. Users pass colors the natural ways — any CSS color string
+// ('#10131a', '#abc', 'red', 'rgb(0 0 0 / 50%)', 'hsl(210 50% 40%)', 'transparent'), a packed number
+// (0xff0000 = opaque 0xRRGGBB) or normalized components ([r,g,b] / [r,g,b,a] in 0..1). The engines
+// want different forms (2D wants 0..1 floats, 3D a packed int, the UI core '#rrggbbaa'), so this
+// module is the single place that converts. Strings go through the vendored AnyCanvas twin of
+// anycanvas/css_color.h (the parser every native layer uses), so the SDK and the engines agree on
+// every name and every byte. Anything that is not a color throws with the value.
+
+import { cssToByte, parseCssColor } from "../canvas/gen/cssColor"
 
 export type ColorInput =
   | string
@@ -9,38 +14,75 @@ export type ColorInput =
   | readonly [number, number, number]
   | readonly [number, number, number, number]
 
-const parseHexString = (input: string): [number, number, number, number] => {
-  let s = input.trim()
-  if (s[0] === "#") s = s.slice(1)
-  // #rgb / #rgba shorthand → double each nibble
-  if (s.length === 3 || s.length === 4) s = s.split("").map((c) => c + c).join("")
-  const int = parseInt(s, 16)
-  if (s.length === 8) return [ (int >>> 24) & 255, (int >> 16) & 255, (int >> 8) & 255, int & 255 ]
-  // default 6-digit (rrggbb); anything malformed falls back to opaque black
-  if (s.length === 6) return [ (int >> 16) & 255, (int >> 8) & 255, int & 255, 255 ]
-  return [ 0, 0, 0, 255 ]
+type Rgba = [number, number, number, number]
+
+const f = Math.fround
+
+// A non-string input as four floats, or null when it is not a color. Arrays pass through losslessly
+// (HDR components above 1 stay); a number is an integer 0..0xFFFFFF. Kept apart from the string
+// path so the UI wire (numericColorToHex) reaches no CSS parser: a bundle that never hands a
+// string to `Color` carries no name table.
+const parseNumeric = (c: unknown): Rgba | null => {
+  if (typeof c === "number") {
+    if (!Number.isInteger(c) || c < 0 || c > 0xFFFFFF) return null
+    return [ f(((c >> 16) & 255) / 255), f(((c >> 8) & 255) / 255), f((c & 255) / 255), 1 ]
+  }
+  if (typeof c === "object" && c !== null && typeof (c as ArrayLike<number>).length === "number") {
+    const a = c as ArrayLike<unknown>
+    if (a.length !== 3 && a.length !== 4) return null
+    for (let i = 0; i < a.length; i++) if (typeof a[i] !== "number" || !Number.isFinite(a[i])) return null
+    const n = a as ArrayLike<number>
+    return [ n[0], n[1], n[2], a.length === 4 ? n[3] : 1 ]
+  }
+  return null
 }
 
-/** Normalize any ColorInput to four 0..1 float components (array inputs pass through losslessly). */
-const toFloats = (c: ColorInput): [number, number, number, number] => {
-  if (typeof c === "number") return [ ((c >> 16) & 255) / 255, ((c >> 8) & 255) / 255, (c & 255) / 255, 1 ]
+// The input as four floats, or null when it is not a color.
+const parse = (c: unknown): Rgba | null => {
   if (typeof c === "string") {
-    const b = parseHexString(c)
-    return [ b[0] / 255, b[1] / 255, b[2] / 255, b[3] / 255 ]
+    const p = parseCssColor(c)
+    return p ? [ p.r, p.g, p.b, p.a ] : null
+  }
+  return parseNumeric(c)
+}
+
+const show = (c: unknown): string =>
+  typeof c === "string" ? JSON.stringify(c)
+    : typeof c === "number" && Number.isInteger(c) && c >= 0 ? `0x${c.toString(16)} (${c})`
+      : Array.isArray(c) ? `[${c.join(", ")}]` : String(c)
+
+// The throw for a value that is not a color, naming it.
+const notAColor = (c: unknown): never => {
+  if (typeof c === "number") {
+    throw new RangeError(`Color: ${show(c)} is not a color — a number is an opaque 0xRRGGBB (an integer 0..0xFFFFFF); write alpha as "#rrggbbaa" or [r, g, b, a]`)
   }
-  return [ c[0], c[1], c[2], (c as readonly number[])[3] ?? 1 ]
+  if (typeof c === "string") throw new TypeError(`Color: ${show(c)} is not a CSS color`)
+  throw new TypeError(`Color: ${show(c)} is not a color — a string, an 0xRRGGBB number or [r, g, b(, a)] in 0..1`)
 }
 
-const toBytes = (c: ColorInput): [number, number, number, number] => {
-  const f = toFloats(c)
-  return [ Math.round(f[0] * 255), Math.round(f[1] * 255), Math.round(f[2] * 255), Math.round(f[3] * 255) ]
+/** Normalize any ColorInput to four 0..1 float components; throws with the value when it is not one. */
+const toFloats = (c: ColorInput): Rgba => parse(c) ?? notAColor(c)
+
+// Bytes by the one rounding rule of the engines (anycanvas css::toByte: float32, clamped, half up).
+const toBytes = (c: ColorInput): Rgba => {
+  const v = toFloats(c)
+  return [ cssToByte(v[0]), cssToByte(v[1]), cssToByte(v[2]), cssToByte(v[3]) ]
 }
 
+const hex2 = (n: number): string => (n < 16 ? "0" : "") + n.toString(16)
+const floatsToHex = (v: Rgba): string =>
+  "#" + hex2(cssToByte(v[0])) + hex2(cssToByte(v[1])) + hex2(cssToByte(v[2])) + hex2(cssToByte(v[3]))
+
+/** @internal '#rrggbbaa' of a NON-STRING color — the UI wire's own conversion (ui/styleColor.ts).
+ *  Strings never come here: the UI core parses CSS itself with the same parser, so the SDK hands
+ *  them over as written. Throws like `Color` when the value is not a color. */
+export const numericColorToHex = (c: unknown): string => floatsToHex(parseNumeric(c) ?? notAColor(c))
+
 export const Color = {
   /** [r,g,b] in 0..1 — for the 2D engine's float color setters. */
   toRgb01(c: ColorInput): [number, number, number] {
-    const f = toFloats(c)
-    return [ f[0], f[1], f[2] ]
+    const v = toFloats(c)
+    return [ v[0], v[1], v[2] ]
   },
   /** [r,g,b,a] in 0..1. */
   toRgba01(c: ColorInput): [number, number, number, number] {
@@ -56,11 +98,12 @@ export const Color = {
     const b = toBytes(c)
     return ((b[0] << 24) | (b[1] << 16) | (b[2] << 8) | b[3]) >>> 0
   },
-  /** '#rrggbb' (or '#rrggbbaa' when alpha < 1) — for the 3D material color uniforms. */
+  /** '#rrggbbaa' (lower-case, always eight digits) — the UI wire form and the 3D material color. */
   toHexString(c: ColorInput): string {
-    const b = toBytes(c)
-    const hex = (n: number) => n.toString(16).padStart(2, "0")
-    const base = `#${hex(b[0])}${hex(b[1])}${hex(b[2])}`
-    return b[3] >= 255 ? base : base + hex(b[3])
+    return floatsToHex(toFloats(c))
+  },
+  /** [r,g,b,a] in 0..1, or `null` when `c` is not a color — the non-throwing probe. */
+  tryParse(c: unknown): [number, number, number, number] | null {
+    return parse(c)
   },
 }

package/src/core/pins.ts

@@ -0,0 +1,51 @@
+// Pins — the JS side of owned handles (docs/plans/hosts-unification-plan.md, phase 10). A wrapper over a
+// native resource holds `_h`, the handle the runtime returned; the runtime frees the resource once
+// the wrapper is collected AND nothing native owns it. Native can only send an event to a resource
+// it owns (a node in a tree / scene, a playing player), so those wrappers — and only those — are
+// pinned here: kept alive and findable by id while native holds them. A loose wrapper is not in
+// the map and collects freely. The SDK writes the map in the call that creates a native owner
+// (append, add, setParent, show) and clears it on its own detach calls or when the runtime reports
+// a free (`_creatorApp.setFreedEmitter`: a subtree the app dropped or destroyed).
+
+/** The handle of a wrapper whose resource is gone: `id` 0, nothing to finalize. Replacing `_h`
+ *  with it drops the real handle, so the runtime's record can go. */
+export const DEAD_HANDLE: Handle = Object.freeze({ id: 0 })
+
+export interface Pinned {
+  readonly _h: Handle
+  /** The runtime freed the resource underneath (an ancestor's free): mark the wrapper dead. */
+  _freed?(): void
+}
+
+export class Pins<T extends Pinned> {
+  private readonly map = new Map<number, T>()
+  /** Keep `obj` alive and findable while native owns its resource. */
+  pin(obj: T | null | undefined): void {
+    if (obj && obj._h.id !== 0) this.map.set(obj._h.id, obj)
+  }
+  unpin(id: number): void { this.map.delete(id) }
+  get(id: number): T | undefined { return this.map.get(id) }
+  has(id: number): boolean { return this.map.has(id) }
+  /** The runtime freed these resources: drop the pins, tell the wrappers. */
+  freed(ids: number[]): void {
+    for (const id of ids) {
+      const obj = this.map.get(id)
+      this.map.delete(id)
+      obj?._freed?.()
+    }
+  }
+}
+
+// ---- the freed channel ---------------------------------------------------------------------------
+const byKind = new Map<number, Pins<any>>()
+let installed = false
+
+/** @internal Route the runtime's freed reports of `kind` (OWNED_KIND_*) to `pins`. Called lazily
+ *  from the wrappers' constructors (a top-level call would be dropped by the bundler's DCE). */
+export const registerFreedKind = (kind: number, pins: Pins<any>): void => {
+  byKind.set(kind, pins)
+  if (installed) return
+  if (typeof _creatorApp === "undefined" || typeof _creatorApp.setFreedEmitter !== "function") return   // a test stub
+  installed = true
+  _creatorApp.setFreedEmitter((k, ids) => { byKind.get(k)?.freed(ids) })
+}

package/src/core/signals.ts

@@ -80,7 +80,14 @@ const flush = () => {
     }
     const first: EffectImpl = queue.values().next().value!
     queue.delete(first)
-    first._run()
+    // One effect's error must not stop the others — nor every flush after it: escaping here would
+    // leave flushScheduled set, and no signal write would ever re-run anything again (on
+    // JavaScriptCore the rejected flush promise is not even reported — the app just freezes).
+    try {
+      first._run()
+    } catch (e) {
+      console.error("signals: an effect threw (the others still run):", e instanceof Error ? (e.stack || e.message) : e)
+    }
   }
   flushScheduled = false
 }

package/src/g2/CharacterController2D.ts

@@ -41,7 +41,7 @@ import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
 import type { CompAxis, CompWriter } from "../core/compWrite"
 import { PhysicsGroup2D, _watchGroupChanges, _unwatchGroupChanges, categoryOf, solidMask } from "./groups2d"
 import { Shape2D } from "./Shape2D"
-import { node2dRegistry, type Node2D } from "./Node2D"
+import { nodes2d, type Node2D } from "./Node2D"
 
 /** Where the character's feet are, as reported by the solver after the last step. */
 export type GroundState2D = "ground" | "slope" | "air"
@@ -192,7 +192,7 @@ export class CharacterController2D extends Aspect<"controller", Node2D> implemen
    *  the game can read. The engine already carries the character along a kinematic platform. */
   get groundNode(): Node2D | null {
     const id = this._state()[5]
-    return id ? node2dRegistry.get(id) ?? null : null
+    return id ? nodes2d.get(id) ?? null : null
   }
 
   /**
@@ -210,7 +210,7 @@ export class CharacterController2D extends Aspect<"controller", Node2D> implemen
     const o = _creator2d.characterGetCollisions(this._id, MAX_COLLISIONS)
     const out: Collision2D[] = []
     for (let i = 0; i + 2 < o.length; i += 3) {
-      out.push({ node: o[i] ? node2dRegistry.get(o[i]) ?? null : null, normal: new Vec2(o[i + 1], o[i + 2]) })
+      out.push({ node: o[i] ? nodes2d.get(o[i]) ?? null : null, normal: new Vec2(o[i + 1], o[i + 2]) })
     }
     return out
   }