@downdraft/engine 0.1.1 → 0.2.0

package/libraries/entities/src/model-renderer.ts

@@ -121,6 +121,9 @@ export class ModelRenderer {
   private meshNormalTextureSourceId = new Map<string, string>();
   /** Track the current albedo handle per materialKey (for normal texture updates). */
   private meshAlbedoHandle = new Map<string, number>();
+  /** The desired baseColor per materialKey — async texture-load updates re-apply
+   *  it instead of stomping to white, so runtime tints survive texture swaps. */
+  private meshBaseColor = new Map<string, [number, number, number, number]>();
   /** When true, newly registered mesh textures get a full mip chain.
    *  Toggle takes effect on the next uploadModel/reuploadModel (textures are
    *  re-registered into a mipmapped bucket). */
@@ -437,14 +440,26 @@ export class ModelRenderer {
       const vertexCount = mesh.vertexCount;
       const stride = 11; // pos3 + normal3 + uv2 + color3
       const interleaved = new Float32Array(vertexCount * stride);
+      const sOff = mesh.surfaceOffset ?? 0;
+      const sg = mesh.surfaceGirth;
+      const gA = sg ? sg.axes[0] : -1, gB = sg ? sg.axes[1] : -1;
+      const gCA = sg ? sg.centers[0] : 0, gCB = sg ? sg.centers[1] : 0;
+      const p = [0, 0, 0];
 
       for (let v = 0; v < vertexCount; v++) {
-        interleaved[v * stride] = mesh.vertices[v * 6];
-        interleaved[v * stride + 1] = mesh.vertices[v * 6 + 1];
-        interleaved[v * stride + 2] = mesh.vertices[v * 6 + 2];
-        interleaved[v * stride + 3] = mesh.vertices[v * 6 + 3];
-        interleaved[v * stride + 4] = mesh.vertices[v * 6 + 4];
-        interleaved[v * stride + 5] = mesh.vertices[v * 6 + 5];
+        const nx = mesh.vertices[v * 6 + 3], ny = mesh.vertices[v * 6 + 4], nz = mesh.vertices[v * 6 + 5];
+        p[0] = mesh.vertices[v * 6]; p[1] = mesh.vertices[v * 6 + 1]; p[2] = mesh.vertices[v * 6 + 2];
+        if (sg) {
+          const s = 1 + sg.factor * sg.weights[v];
+          p[gA] = gCA + (p[gA] - gCA) * s;
+          p[gB] = gCB + (p[gB] - gCB) * s;
+        }
+        interleaved[v * stride] = p[0] - nx * sOff;
+        interleaved[v * stride + 1] = p[1] - ny * sOff;
+        interleaved[v * stride + 2] = p[2] - nz * sOff;
+        interleaved[v * stride + 3] = nx;
+        interleaved[v * stride + 4] = ny;
+        interleaved[v * stride + 5] = nz;
         interleaved[v * stride + 6] = mesh.uvs ? mesh.uvs[v * 2] : 0;
         interleaved[v * stride + 7] = mesh.uvs ? mesh.uvs[v * 2 + 1] : 0;
         interleaved[v * stride + 8] = mesh.colors ? mesh.colors[v * 3] : 1;
@@ -487,8 +502,9 @@ export class ModelRenderer {
           bindlessMatIndex = existing;
         } else {
           const mat = materials?.[matIdx];
+          const baseColor: [number, number, number, number] = mat?.baseColor ?? [1, 1, 1, 1];
           bindlessMatIndex = this.bindless.materialManager.registerMaterial({
-            baseColor: mat?.baseColor ?? [1, 1, 1, 1],
+            baseColor,
             roughness: mat?.roughness ?? 1,
             metallic: mat?.metallic ?? 0,
             emissiveIntensity: 0,
@@ -499,6 +515,7 @@ export class ModelRenderer {
             emissiveTexHandle: this.bindless.registry.defaultWhiteHandle,
           });
           this.meshMaterialIndex.set(materialKey, bindlessMatIndex);
+          this.meshBaseColor.set(materialKey, baseColor);
 
           // Async load this material's texture (embedded data or external URI)
           if (mat?.textureData && mat.textureData.byteLength > 0) {
@@ -541,7 +558,7 @@ export class ModelRenderer {
 
     if (resources.length < meshes.length) {
       log.warn(
-        "ModelRenderer",
+        "model-renderer",
         `Uniform buffer full: uploaded ${resources.length}/${meshes.length} meshes for "${nodeId}" ` +
         `(${uniformOffset}/${ModelRenderer.MAX_MODELS} slots used). ` +
         `Increase MAX_MODELS to avoid invisible models.`,
@@ -669,7 +686,7 @@ export class ModelRenderer {
       const materialIndex = this.meshMaterialIndex.get(materialKey);
       if (materialIndex !== undefined) {
         const matParams: MaterialParams = {
-          baseColor: [1, 1, 1, 1],
+          baseColor: this.meshBaseColor.get(materialKey) ?? [1, 1, 1, 1],
           roughness: 1,
           metallic: 0,
           emissiveIntensity: 0,
@@ -682,10 +699,10 @@ export class ModelRenderer {
         this.bindless.materialManager.updateMaterial(materialIndex, matParams);
       }
 
-      log.info("ModelRenderer", `Texture ready for ${materialKey}: ${imageBitmap.width}x${imageBitmap.height} (bindless)`);
+      log.info("model-renderer", `Texture ready for ${materialKey}: ${imageBitmap.width}x${imageBitmap.height} (bindless)`);
       imageBitmap.close();
     } catch (e) {
-      log.error("ModelRenderer", `Failed to load texture for ${materialKey}: ${e}`);
+      log.error("model-renderer", `Failed to load texture for ${materialKey}: ${e}`);
     }
   }
 
@@ -723,7 +740,7 @@ export class ModelRenderer {
       const materialIndex = this.meshMaterialIndex.get(materialKey);
       if (materialIndex !== undefined) {
         const matParams: MaterialParams = {
-          baseColor: [1, 1, 1, 1],
+          baseColor: this.meshBaseColor.get(materialKey) ?? [1, 1, 1, 1],
           roughness: 1,
           metallic: 0,
           emissiveIntensity: 0,
@@ -738,7 +755,7 @@ export class ModelRenderer {
 
       imageBitmap.close();
     } catch (e) {
-      log.error("ModelRenderer", `Failed to load texture from URI for ${materialKey} (${textureUri}): ${e}`);
+      log.error("model-renderer", `Failed to load texture from URI for ${materialKey} (${textureUri}): ${e}`);
     }
   }
 
@@ -784,7 +801,7 @@ export class ModelRenderer {
       if (materialIndex !== undefined) {
         const albedoHandle = this.meshAlbedoHandle.get(materialKey) ?? this.bindless.registry.defaultWhiteHandle;
         const matParams: MaterialParams = {
-          baseColor: [1, 1, 1, 1],
+          baseColor: this.meshBaseColor.get(materialKey) ?? [1, 1, 1, 1],
           roughness: 1,
           metallic: 0,
           emissiveIntensity: 0,
@@ -797,10 +814,10 @@ export class ModelRenderer {
         this.bindless.materialManager.updateMaterial(materialIndex, matParams);
       }
 
-      log.info("ModelRenderer", `Normal texture ready for ${materialKey}: ${imageBitmap.width}x${imageBitmap.height}`);
+      log.info("model-renderer", `Normal texture ready for ${materialKey}: ${imageBitmap.width}x${imageBitmap.height}`);
       imageBitmap.close();
     } catch (e) {
-      log.error("ModelRenderer", `Failed to load normal texture for ${materialKey}: ${e}`);
+      log.error("model-renderer", `Failed to load normal texture for ${materialKey}: ${e}`);
     }
   }
 
@@ -829,11 +846,53 @@ export class ModelRenderer {
           this.bindless.materialManager.unregisterMaterial(matIdx);
         }
         this.meshMaterialIndex.delete(materialKey);
+        this.meshBaseColor.delete(materialKey);
+        this.meshAlbedoHandle.delete(materialKey);
+        this.meshNormalTextureSourceId.delete(materialKey);
         this.textureLoadVersion.delete(materialKey);
       }
     }
   }
 
+  /**
+   * Update an already-registered material at runtime: reload its albedo
+   * texture when `mat.textureData` is present (in-place registry update — no
+   * mesh re-upload or texture flicker) and apply its baseColor. Used by the
+   * character customizer for texture options + tints; a no-op for materials
+   * the node never registered.
+   */
+  updateMeshMaterial(nodeId: string, materialIndex: number, mat: MaterialData): void {
+    if (!this.bindless) return;
+    const materialKey = `${nodeId}:${materialIndex}`;
+    const bindlessMatIndex = this.meshMaterialIndex.get(materialKey);
+    if (bindlessMatIndex === undefined) return;
+
+    this.meshBaseColor.set(materialKey, mat.baseColor ?? [1, 1, 1, 1]);
+
+    if (mat.textureData && mat.textureData.byteLength > 0) {
+      const version = (this.textureLoadVersion.get(materialKey) ?? 0) + 1;
+      this.textureLoadVersion.set(materialKey, version);
+      void this.loadMeshTexture(materialKey, mat.textureData, version);
+      // The async load completes the updateMaterial call with the real
+      // texture handle; the immediate write below just applies the tint early.
+    }
+    const normalSourceId = this.meshNormalTextureSourceId.get(materialKey);
+    const normalHandle = normalSourceId
+      ? (this.bindless.registry.getRegistration(normalSourceId)?.handle ?? this.bindless.registry.defaultNormalHandle)
+      : this.bindless.registry.defaultNormalHandle;
+    this.bindless.materialManager.updateMaterial(bindlessMatIndex, {
+      baseColor: this.meshBaseColor.get(materialKey)!,
+      roughness: mat.roughness ?? 1,
+      metallic: mat.metallic ?? 0,
+      emissiveIntensity: 0,
+      albedoTexHandle: this.meshAlbedoHandle.get(materialKey) ?? this.bindless.registry.defaultWhiteHandle,
+      normalTexHandle: normalHandle,
+      metallicRoughnessTexHandle: this.bindless.registry.defaultWhiteHandle,
+      aoTexHandle: this.bindless.registry.defaultWhiteHandle,
+      emissiveTexHandle: this.bindless.registry.defaultWhiteHandle,
+    });
+  }
+
   reuploadModel(nodeId: string, meshes: MeshData[], materials?: MaterialData[], modelBaseUrl?: string): number {
     // Preserve existing per-mesh texture registrations to avoid flickering on
     // part selection changes. Per-mesh material indices are reused.
@@ -857,14 +916,26 @@ export class ModelRenderer {
       const vertexCount = mesh.vertexCount;
       const stride = 11;
       const interleaved = new Float32Array(vertexCount * stride);
+      const sOff = mesh.surfaceOffset ?? 0;
+      const sg = mesh.surfaceGirth;
+      const gA = sg ? sg.axes[0] : -1, gB = sg ? sg.axes[1] : -1;
+      const gCA = sg ? sg.centers[0] : 0, gCB = sg ? sg.centers[1] : 0;
+      const p = [0, 0, 0];
 
       for (let v = 0; v < vertexCount; v++) {
-        interleaved[v * stride] = mesh.vertices[v * 6];
-        interleaved[v * stride + 1] = mesh.vertices[v * 6 + 1];
-        interleaved[v * stride + 2] = mesh.vertices[v * 6 + 2];
-        interleaved[v * stride + 3] = mesh.vertices[v * 6 + 3];
-        interleaved[v * stride + 4] = mesh.vertices[v * 6 + 4];
-        interleaved[v * stride + 5] = mesh.vertices[v * 6 + 5];
+        const nx = mesh.vertices[v * 6 + 3], ny = mesh.vertices[v * 6 + 4], nz = mesh.vertices[v * 6 + 5];
+        p[0] = mesh.vertices[v * 6]; p[1] = mesh.vertices[v * 6 + 1]; p[2] = mesh.vertices[v * 6 + 2];
+        if (sg) {
+          const s = 1 + sg.factor * sg.weights[v];
+          p[gA] = gCA + (p[gA] - gCA) * s;
+          p[gB] = gCB + (p[gB] - gCB) * s;
+        }
+        interleaved[v * stride] = p[0] - nx * sOff;
+        interleaved[v * stride + 1] = p[1] - ny * sOff;
+        interleaved[v * stride + 2] = p[2] - nz * sOff;
+        interleaved[v * stride + 3] = nx;
+        interleaved[v * stride + 4] = ny;
+        interleaved[v * stride + 5] = nz;
         interleaved[v * stride + 6] = mesh.uvs ? mesh.uvs[v * 2] : 0;
         interleaved[v * stride + 7] = mesh.uvs ? mesh.uvs[v * 2 + 1] : 0;
         interleaved[v * stride + 8] = mesh.colors ? mesh.colors[v * 3] : 1;
@@ -905,8 +976,9 @@ export class ModelRenderer {
           bindlessMatIndex = existing;
         } else {
           const mat = materials?.[matIdx];
+          const baseColor: [number, number, number, number] = mat?.baseColor ?? [1, 1, 1, 1];
           bindlessMatIndex = this.bindless.materialManager.registerMaterial({
-            baseColor: mat?.baseColor ?? [1, 1, 1, 1],
+            baseColor,
             roughness: mat?.roughness ?? 1,
             metallic: mat?.metallic ?? 0,
             emissiveIntensity: 0,
@@ -917,6 +989,7 @@ export class ModelRenderer {
             emissiveTexHandle: this.bindless.registry.defaultWhiteHandle,
           });
           this.meshMaterialIndex.set(materialKey, bindlessMatIndex);
+          this.meshBaseColor.set(materialKey, baseColor);
 
           // Start async texture load if this material has texture data and no
           // existing registration (first time seeing this material).

package/libraries/gamepad/src/feed-input.ts

@@ -57,7 +57,7 @@ export function writePadToInput(
     writer.setGamepadButton(playerIdx, b, (d.buttonsLo & (1 << b)) !== 0);
   }
   if (bindings) {
-    for (const bind of bindings) {
+    for (const bind of bindings.values()) {
       let active = false;
       if (bind.button !== undefined) {
         active = (d.buttonsLo & (1 << bind.button)) !== 0;

package/libraries/gamepad/src/hub.ts

@@ -171,10 +171,10 @@ export class GamepadHub {
           ffSupported: (s.flags & PAD_FLAG.FF_SUPPORTED) !== 0,
         });
         this.devices.set(slot, dev);
-        for (const cb of this.listeners.connect) cb(dev);
+        for (const cb of this.listeners.connect.values()) cb(dev);
       } else if (!connected && existing) {
         this.devices.delete(slot);
-        for (const cb of this.listeners.disconnect) cb(existing);
+        for (const cb of this.listeners.disconnect.values()) cb(existing);
       }
     }
     this.lastSeq = this.reader.getSequence();

package/libraries/gamepad/src/library.ts

@@ -14,7 +14,8 @@
 //      still valid for wiring against future sources)
 // ============================================================================
 
-import { resourceToken, type EngineLibrary } from "@downdraft/engine";
+import { resourceToken } from "@downdraft/engine/ecs/resource";
+import type { EngineLibrary } from "@downdraft/engine/library/library";
 import type { GamepadSource } from "@downdraft/engine/input/local-player-manager";
 import { GamepadDevicesChannel } from "@downdraft/engine/sab/gamepad-devices";
 import { GamepadHub, type GamepadHubOptions } from "./hub";

package/libraries/gamepad/src/source-sab.ts

@@ -53,9 +53,9 @@ export class SabGamepadSource implements GamepadSource {
     for (let i = 0; i < GAMEPAD_MAX_SLOTS; i++) {
       if (!(changed & (1 << i))) continue;
       if (mask & (1 << i)) {
-        for (const cb of this.connectCbs) cb(i);
+        for (const cb of this.connectCbs.values()) cb(i);
       } else {
-        for (const cb of this.disconnectCbs) cb(i);
+        for (const cb of this.disconnectCbs.values()) cb(i);
       }
     }
     this.knownMask = mask;

package/libraries/gamepad/src/sysfs-enrich.ts

@@ -58,7 +58,7 @@ async function findBatteryLevel(macHint: string | null): Promise<number | undefi
   try {
     const psDir = "/sys/class/power_supply";
     if (!existsSync(psDir)) return undefined;
-    for (const entry of await fs.readdir(psDir)) {
+    for (const entry of (await fs.readdir(psDir)).values()) {
       const macPath = join(psDir, entry, "mac");
       if (existsSync(macPath)) {
         const mac = (await fs.readFile(macPath, "utf-8")).trim().toLowerCase();
@@ -98,7 +98,7 @@ export class SysfsGamepadEnricher {
   async enrich(slots: GamepadDeviceSlot[]): Promise<EnrichResult[]> {
     if (process.platform !== "linux") return [];
     const out: EnrichResult[] = [];
-    for (const s of slots) {
+    for (const s of slots.values()) {
       if (s.eventNode < 0) continue;
       const r = await this.enrichSlot(s);
       out.push(r);

package/libraries/gpu-kernels/src/kernel.ts

@@ -177,6 +177,7 @@ export class GpuKernel {
     const [, oy, oz] = this.outputSize;
     this.workgroupSize = opts.workgroupSize ?? (oy === 1 && oz === 1 ? [64, 1, 1] : [8, 8, 1]);
     const [wx, wy, wz] = this.workgroupSize;
+    this.label = opts.label ?? "gpu-kernel";
     const lim = this.device?.limits as {
       maxComputeWorkgroupSizeX?: number;
       maxComputeWorkgroupSizeY?: number;
@@ -192,7 +193,6 @@ export class GpuKernel {
         throw new Error(`kernel "${this.label}": workgroupSize ${wx}×${wy}×${wz} exceeds device limits`);
       }
     }
-    this.label = opts.label ?? "gpu-kernel";
     this.memoryBudget = opts.memoryBudget;
     this.extraUsage = opts.outputUsage ?? 0;
     this.externalResult = opts.outputBuffer ?? null;
@@ -586,7 +586,7 @@ export class GpuKernel {
     // Pre-validate against device limits — Adreno-class GPUs allow as few as
     // 16 storage buffers/stage and 256MB/binding, and wgpu otherwise reports a
     // generic "command buffer failed validation" at submit time.
-    const limits = this.device.limits as Record<string, number | undefined> | undefined;
+    const limits = this.device.limits as unknown as Record<string, number | undefined> | undefined;
     const maxStorage = limits?.maxStorageBuffersPerShaderStage ?? Infinity;
     const maxBinding = limits?.maxStorageBufferBindingSize ?? Infinity;
     const storageCount = unit.transpiled.bindings.length

package/libraries/gpu-kernels/src/transpile.ts

@@ -720,7 +720,7 @@ class Emitter {
         if (e.ty === "vec") {
           throw new KernelSyntaxError(`arrays can't live in locals — return them directly`, d.init);
         }
-        const widen = this.widened.has(name) && e.ty !== "f32" && e.ty !== "bool" && e.ty !== "vec";
+        const widen = this.widened.has(name) && e.ty !== "f32" && e.ty !== "bool";
         this.declare(name, widen ? "f32" : e.ty);
         if (node.kind === "const") this.consts.add(name);
         const kw = node.kind === "const" ? "let" : "var";

package/libraries/html-ui-kit/src/nav/nav-controller.ts

@@ -209,7 +209,7 @@ export class NavController {
 
     let best: NavNodeInfo | null = null;
     let bestScore = Infinity;
-    for (const n of cands) {
+    for (const n of cands.values()) {
       if (n === cur || !n.rect) continue;
       const r = n.rect;
       const nx = r.x + r.w / 2, ny = r.y + r.h / 2;

package/libraries/html-ui-kit/src/nav/nav-input.ts

@@ -50,7 +50,7 @@ export class PadNavDriver {
       repeatDelayMs: opts.repeatDelayMs ?? 400,
       repeatIntervalMs: opts.repeatIntervalMs ?? 130,
     };
-    for (const d of ["up", "down", "left", "right"] as const) {
+    for (const d of (["up", "down", "left", "right"] as const).values()) {
       this.dirs.set(d, { held: false, since: 0, lastFire: 0 });
     }
   }
@@ -82,7 +82,7 @@ export class PadNavDriver {
     this.prevDirAxis = stickDir;
     if (stickDir) pressed.add(stickDir);
 
-    for (const [dir, st] of this.dirs) {
+    for (const [dir, st] of this.dirs.entries()) {
       const isDown = pressed.has(dir);
       if (isDown && !st.held) {
         st.held = true; st.since = now; st.lastFire = now;

package/libraries/inspectable/src/index.ts

@@ -0,0 +1,11 @@
+// ============================================================================
+// @downdraft/engine/libraries/inspectable — schema'd registry of named
+// game-state nodes that automation can read and write semantically
+// (no synthetic input). See inspectable.ts for the design notes.
+// ============================================================================
+
+export {
+    InspectableError, InspectableRegistry,
+    type InspectableNode, type InspectableNodeInfo, type InspectableSetResult,
+    type InspectableThread, type InspectableType
+} from "./inspectable";

package/libraries/inspectable/src/inspectable.ts

@@ -0,0 +1,277 @@
+// ============================================================================
+// inspectable.ts — InspectableRegistry: a schema'd, hierarchical registry of
+// named game-state nodes that automation (MCP tools, devtools) can read and
+// write WITHOUT synthesizing user input.
+//
+// Why callbacks instead of field reflection: most interesting state isn't
+// live-bound — e.g. `CharacterCustomization.girth` only takes effect after
+// the game re-runs resolveCustomizationMeshes() and re-uploads meshes. A raw
+// `obj[key] = value` would silently desync the store, the rendered mesh, and
+// the sim. Each node therefore carries a `set()` that routes through the same
+// apply function the game's own UI calls.
+//
+// Hierarchy is derived from dot-separated `path`s ("player.customization.
+// girth") — no class hierarchy or decorator machinery required.
+//
+// Thread model: `set()` runs in whatever thread hosts the registry. For
+// sim-authoritative state, implement `set` as a dispatch over the game's
+// RendererToSimMessage channel and let `get` read the last received snapshot;
+// mark the node `thread: "sim"` so callers know the write isn't synchronous.
+//
+// When to use what:
+//   - inspectable_* tools (this registry) — semantic game state with schema
+//   - add_component (editor MCP)      — ECS component data
+//   - extraTools / set_test_state     — bespoke escape hatches
+//   - inject_input / dispatch_*       — exercising the real input pipeline
+// ============================================================================
+
+export type InspectableType = "number" | "boolean" | "string" | "enum" | "json";
+
+/** Which thread owns the value. Informational — writes always execute in the
+ *  thread hosting the registry. */
+export type InspectableThread = "renderer" | "sim" | "main";
+
+/**
+ * One addressable piece of game state.
+ *
+ * Path convention: dot-separated identifiers ("player.customization.girth").
+ * Segments must not contain `.` — arbitrary map keys (material names with
+ * spaces/dots) belong in a `json` node that writes the whole map.
+ */
+export interface InspectableNode {
+    path: string;
+    label?: string;
+    description?: string;
+    type: InspectableType;
+    /** number only — inclusive bounds enforced on set. */
+    min?: number;
+    max?: number;
+    /** enum only — lazy so dynamic option lists (variant catalogs) stay fresh. */
+    enum?: () => readonly string[];
+    /** Default false. Nodes without `set` are treated as read-only regardless. */
+    readOnly?: boolean;
+    thread?: InspectableThread;
+    get(): unknown;
+    /** Routes through the game's apply pipeline (store update → re-resolve →
+     *  sim dispatch). May be async when the apply involves uploads. */
+    set?(value: unknown): void | Promise<void>;
+}
+
+/** Serializable descriptor returned by list()/tree() — no live `get` call. */
+export interface InspectableNodeInfo {
+    path: string;
+    label?: string;
+    description?: string;
+    type: InspectableType;
+    min?: number;
+    max?: number;
+    options?: readonly string[];
+    readOnly: boolean;
+    thread?: InspectableThread;
+    children?: InspectableNodeInfo[];
+}
+
+export interface InspectableSetResult {
+    path: string;
+    value: unknown;
+}
+
+export class InspectableError extends Error {
+    constructor(
+        message: string,
+        /** Machine-readable hint for callers that want to distinguish failures. */
+        readonly reason: "not_found" | "read_only" | "bad_type" | "out_of_range" | "bad_enum",
+    ) {
+        super(message);
+        this.name = "InspectableError";
+    }
+}
+
+export class InspectableRegistry {
+    private nodes = new Map<string, InspectableNode>();
+    private listeners = new Set<(path: string, value: unknown) => void>();
+
+    /** Register a node. Returns an unregister function. Throws on duplicate paths. */
+    register(node: InspectableNode): () => void {
+        if (!node.path) throw new InspectableError("Node requires a path", "bad_type");
+        if (this.nodes.has(node.path)) {
+            throw new InspectableError(`Node "${node.path}" is already registered`, "bad_type");
+        }
+        this.nodes.set(node.path, node);
+        return () => { this.nodes.delete(node.path); };
+    }
+
+    registerAll(nodes: InspectableNode[]): () => void {
+        const unsubs = nodes.map((n) => this.register(n));
+        return () => { unsubs.forEach((u) => u()); };
+    }
+
+    unregister(path: string): boolean {
+        return this.nodes.delete(path);
+    }
+
+    has(path: string): boolean {
+        return this.nodes.has(path);
+    }
+
+    size(): number {
+        return this.nodes.size;
+    }
+
+    /** Node descriptors (schema only — no live reads), optionally filtered to
+     *  a path prefix ("player" matches "player.health" but not "players.x"). */
+    list(prefix?: string): InspectableNodeInfo[] {
+        const out: InspectableNodeInfo[] = [];
+        for (const node of this.nodes.values()) {
+            if (prefix && node.path !== prefix && !node.path.startsWith(prefix + ".")) continue;
+            out.push(this.describeNode(node));
+        }
+        return out.sort((a, b) => a.path.localeCompare(b.path));
+    }
+
+    /** Nested tree of node descriptors — intermediate path segments become
+     *  grouping objects with `children` and a synthesized `type: "json"`. */
+    tree(prefix?: string): InspectableNodeInfo[] {
+        interface TreeEntry extends InspectableNodeInfo { _kids: Map<string, TreeEntry>; }
+        const roots = new Map<string, TreeEntry>();
+        for (const info of this.list(prefix)) {
+            const segs = info.path.split(".");
+            let kids = roots;
+            for (let i = 0; i < segs.length; i++) {
+                const leaf = i === segs.length - 1;
+                let entry = kids.get(segs[i]);
+                if (!entry) {
+                    entry = {
+                        path: segs.slice(0, i + 1).join("."),
+                        type: "json",
+                        readOnly: true,
+                        children: [],
+                        _kids: new Map(),
+                    } as TreeEntry;
+                    kids.set(segs[i], entry);
+                }
+                if (leaf) Object.assign(entry, info, { children: entry.children, _kids: entry._kids });
+                kids = entry._kids;
+            }
+        }
+        const strip = (entries: Map<string, TreeEntry>): InspectableNodeInfo[] =>
+            [...entries.values()].map(({ _kids, ...info }) => ({
+                ...info,
+                children: _kids.size ? strip(_kids) : undefined,
+            }));
+        return strip(roots);
+    }
+
+    /** Schema descriptor for a single node (throws on unknown path). */
+    describe(path: string): InspectableNodeInfo {
+        return this.describeNode(this.node(path));
+    }
+
+    /** Current value of a node. */
+    get(path: string): InspectableSetResult {
+        const node = this.node(path);
+        return { path, value: node.get() };
+    }
+
+    /** Validate and apply a write through the node's `set()`, then return a
+     *  fresh `get()` echo so callers see what actually landed. */
+    async set(path: string, value: unknown): Promise<InspectableSetResult> {
+        const node = this.node(path);
+        if (node.readOnly || !node.set) {
+            throw new InspectableError(`Node "${path}" is read-only`, "read_only");
+        }
+        this.validate(node, value);
+        await node.set(value);
+        const result = { path, value: node.get() };
+        this.listeners.forEach((l) => {
+            try { l(path, result.value); } catch { /* listener errors don't fail the write */ }
+        });
+        return result;
+    }
+
+    /** Subscribe to successful writes (path + resulting value). */
+    onChanged(listener: (path: string, value: unknown) => void): () => void {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+
+    private node(path: string): InspectableNode {
+        const node = this.nodes.get(path);
+        if (node) return node;
+        // Suggest likely targets: children of the queried path, ancestors, and
+        // siblings sharing the parent prefix ("player.heal" → "player.health").
+        const parent = path.slice(0, path.lastIndexOf("."));
+        const near = [...this.nodes.keys()].filter((k) =>
+            k.startsWith(path + ".") || path.startsWith(k + ".") ||
+            (parent && k.startsWith(parent + ".")));
+        throw new InspectableError(
+            `Unknown inspectable path "${path}"` + (near.length ? `. Did you mean: ${near.slice(0, 8).join(", ")}?` : ""),
+            "not_found",
+        );
+    }
+
+    private validate(node: InspectableNode, value: unknown): void {
+        switch (node.type) {
+            case "number": {
+                if (typeof value !== "number" || !Number.isFinite(value)) {
+                    throw new InspectableError(`"${node.path}" expects a finite number, got ${typeof value}`, "bad_type");
+                }
+                if (node.min !== undefined && value < node.min || node.max !== undefined && value > node.max) {
+                    throw new InspectableError(
+                        `"${node.path}" must be within [${node.min ?? "-∞"}, ${node.max ?? "+∞"}], got ${value}`,
+                        "out_of_range",
+                    );
+                }
+                return;
+            }
+            case "boolean":
+                if (typeof value !== "boolean") {
+                    throw new InspectableError(`"${node.path}" expects a boolean, got ${typeof value}`, "bad_type");
+                }
+                return;
+            case "string":
+                if (typeof value !== "string") {
+                    throw new InspectableError(`"${node.path}" expects a string, got ${typeof value}`, "bad_type");
+                }
+                return;
+            case "enum": {
+                const options = node.enum?.() ?? [];
+                if (typeof value !== "string" || !options.includes(value)) {
+                    throw new InspectableError(
+                        `"${node.path}" must be one of [${options.join(", ")}], got ${JSON.stringify(value)}`,
+                        "bad_enum",
+                    );
+                }
+                return;
+            }
+            case "json":
+                if (!isJsonSerializable(value)) {
+                    throw new InspectableError(`"${node.path}" expects a JSON-serializable value`, "bad_type");
+                }
+                return;
+        }
+    }
+
+    private describeNode(node: InspectableNode): InspectableNodeInfo {
+        return {
+            path: node.path,
+            label: node.label,
+            description: node.description,
+            type: node.type,
+            min: node.min,
+            max: node.max,
+            options: node.type === "enum" ? (node.enum?.() ?? []) : undefined,
+            readOnly: node.readOnly ?? !node.set,
+            thread: node.thread,
+        };
+    }
+}
+
+function isJsonSerializable(value: unknown): boolean {
+    try {
+        JSON.stringify(value);
+        return value === undefined ? false : true;
+    } catch {
+        return false;
+    }
+}