@uptimizr/godot 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions for
+      use, reproduction, or distribution of Your modifications, or for any
+      such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Uptimizr Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,89 @@
+# @uptimizr/godot
+
+The **Godot (Web export)** connector for Uptimizr (ADR 0045). Godot 4 compiles to
+WebAssembly and renders into a `<canvas>`, so there is no live JS scene to read — this
+connector is built on [`@uptimizr/web-export`](../web-export) and works in **two
+tiers**:
+
+| Tier        | Engine code?                                    | Captures                                                        |
+| ----------- | ----------------------------------------------- | --------------------------------------------------------------- |
+| **JS-only** | none                                            | pointer move/click heatmaps, FPS / long frames, JS errors       |
+| **Bridged** | a thin copy-in shim (see [`bridge/`](./bridge)) | camera pose → view-direction heatmap, world-space picks, replay |
+
+Godot's native world frame is **right-handed, y-up, meters**, so the connector negates
+Z to reach the canonical wire frame (left-handed, y-up — ADR 0018). The engine-side
+shim does **no** coordinate math.
+
+### Verification status
+
+| Tier        | Status       | How it is verified                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **JS-only** | **Stable**   | Unit tests plus the web-export Playwright round trip (`examples/playground/e2e/web-export.spec.ts`).                                                                                                                                                                                                                                                                                                                |
+| **Bridged** | **Verified** | An **automated headless Godot 4.7.2 Web export** of the reference sample project, driven by Playwright in CI (`godot-export-e2e` job → `examples/playground/e2e/godot-export.spec.ts`). It boots the real WASM export with the shipped `UptimizrGodot.gd` autoload and asserts `camera_sample` (Z negated), `mesh_interaction` (raycast pick named `Crate`), `frame_perf`, and the scene proxy reach the collector. |
+
+The **reference integration** is
+[`examples/godot-web-export`](../../../examples/godot-web-export/README.md) — a minimal
+Godot 4 project with the autoload registered, named pickable `StaticBody3D` props, and a
+nothreads Web preset (`pnpm godot:fetch && pnpm godot:export && pnpm test:e2e:godot`
+reproduces the CI proof locally). The sample's copy of the shim is checked byte-for-byte
+against `bridge/UptimizrGodot.gd`, so the test always exercises the asset you ship.
+
+## Install
+
+```bash
+npm install @uptimizr/godot
+```
+
+The engine-side bridge is a **copy-in asset** (a `JavaScriptBridge` autoload), not an
+npm dependency — see [`bridge/`](./bridge).
+
+## Usage
+
+```ts
+import { trackGodot } from "@uptimizr/godot";
+
+const { client, bridge } = trackGodot({
+  projectId: "your-project",
+  endpoint: "https://collect.example.com",
+  canvas: () => document.querySelector("#godot-canvas"),
+});
+
+// ... later, on teardown
+await client.stop("manual");
+```
+
+`trackGodot` creates the client, registers the JS-only tier collector, exposes the
+engine `bridge` (default `window.__uptimizr_godot__`), and starts the session with
+Godot's connector provenance. The JS-only tier captures immediately; wire the
+engine-side shim to `bridge` to add camera pose, picks, and replay.
+
+### Advanced: wire it up yourself
+
+```ts
+import { UptimizrClient } from "@uptimizr/sdk-core";
+import { godotCollector, GODOT_FRAME } from "@uptimizr/godot";
+
+const client = new UptimizrClient({ projectId: "your-project", endpoint: "..." });
+client.use(godotCollector({ canvas: () => document.querySelector("#godot-canvas") }));
+client.start();
+```
+
+## Engine-side bridge
+
+The bridged tier needs a thin copy-in shim that pushes world-space pose / picks / FPS
+across Godot's `JavaScriptBridge`. The package ships ready-to-use autoloads in both
+languages — [`bridge/UptimizrGodot.gd`](./bridge/UptimizrGodot.gd) (GDScript) and
+[`bridge/UptimizrGodot.cs`](./bridge/UptimizrGodot.cs) (C#). Copy one into your Godot 4
+project and register it as an Autoload named `UptimizrGodot` (**Project → Project Settings →
+Globals → Autoload**). It guards on `OS.has_feature("web")`, so it is a no-op outside the
+Web export. Full setup, options, and the bridge contract are in
+[`bridge/README.md`](./bridge/README.md).
+
+## Privacy
+
+No client-side persistent IDs and no PII by default (ADR 0003). `client.stop()` tears
+down every listener, timer, and animation-frame callback.
+
+## License
+
+Apache-2.0.

package/bridge/README.md

@@ -0,0 +1,102 @@
+# Godot engine-side bridge (copy-in asset)
+
+The thin Godot 4 shim that unlocks the **bridged tier** (camera pose / view-direction
+heatmap, world-space picks, FPS, scene proxy, replay) of the
+[`@uptimizr/godot`](../README.md) connector. The **JS-only tier** (pointer heatmaps, FPS,
+and JS errors) already works with **no** engine code — this shim is only needed for the
+3D-native channels.
+
+It ships as a **copy-in asset**, not an npm/NuGet package:
+
+- [`UptimizrGodot.gd`](./UptimizrGodot.gd) — GDScript autoload (recommended).
+- [`UptimizrGodot.cs`](./UptimizrGodot.cs) — C# autoload for Godot 4 .NET projects.
+
+Both are Apache-2.0 and functionally identical — use the one matching your project's
+language.
+
+## What the shim is
+
+A small, dumb shim that pushes per-sample telemetry from Godot across the JS interop
+boundary to the browser-side connector. It carries **no** analytics logic, IDs, or schema
+knowledge (ADR 0045). For Godot 4 Web exports it is an **autoload** that uses
+`JavaScriptBridge` (`JavaScriptBridge.get_interface(...)` / `create_object`) to call the
+connector each sample with the active `Camera3D` pose, raycast picks, and FPS.
+
+## Setup
+
+1. **Host page** — load `@uptimizr/godot` in the page that hosts the Web export and start
+   a session. `trackGodot(...)` exposes the bridge on `window.__uptimizr_godot__`:
+
+   ```ts
+   import { trackGodot } from "@uptimizr/godot";
+
+   trackGodot({
+     projectId: "your-project",
+     endpoint: "https://collect.example.com",
+     canvas: () => document.querySelector("#godot-canvas"),
+   });
+   ```
+
+2. **Godot project** — copy `UptimizrGodot.gd` (or `.cs`) into your project, then register
+   it as a singleton: **Project → Project Settings → Globals → Autoload**, add the script
+   with node name `UptimizrGodot`, and enable it. On the next Web export it finds the
+   bridge and starts pushing poses, picks, and FPS automatically.
+
+Off the Web export (editor, desktop, mobile) the autoload guards on `OS.has_feature("web")`
+and is a no-op, so it is safe to leave enabled in every build.
+
+### Options (exported on the autoload)
+
+| Property                  | Default | Meaning                                                                 |
+| ------------------------- | ------- | ----------------------------------------------------------------------- |
+| `pose_samples_per_second` | `30`    | Pose push rate cap (`<= 0` pushes every frame). FPS is sent each frame. |
+| `capture_picks`           | `true`  | Left-click casts a physics ray and pushes the first named collider.     |
+| `pick_ray_length`         | `1000`  | Ray length (metres) for click picks.                                    |
+
+### Scene proxy (optional)
+
+For world-space object engagement and replay completeness, mark the nodes you want
+described (developer opt-in — keeps the proxy low-cardinality and PII-free), then push once
+after your scene is built:
+
+```gdscript
+$Crate.add_to_group("uptimizr_tracked")   # any VisualInstance3D
+UptimizrGodot.push_scene_proxy()
+```
+
+## The JS API the shim calls
+
+The connector exposes an `EngineBridge` on `window.__uptimizr_godot__` (configurable via
+the connector's `bridgeGlobal` option). **All values are world-space in Godot's native
+frame** (right-handed, y-up, meters); the connector negates Z to reach the canonical wire
+frame and emits the schema events — the shim does **no** coordinate math.
+
+```ts
+interface EngineBridge {
+  readonly protocolVersion: number; // assert against BRIDGE_PROTOCOL_VERSION (1)
+  pushPose(position: [x, y, z], forward: [x, y, z], up: [x, y, z], fov?: number): void;
+  pushPick(objectName: string, hitPoint: [x, y, z]): void;
+  pushPerf(fps: number, longFrames?: number): void;
+  setSceneProxy(nodes: { name: string; aabb: [minX, minY, minZ, maxX, maxY, maxZ] }[]): void;
+  dispose(): void;
+}
+```
+
+The shim asserts `protocolVersion === 1` on startup and disables itself on a mismatch, so a
+newer page bridge never receives malformed pushes.
+
+### Coordinate notes
+
+- Pass the camera's **world-space forward vector** — `-cam.global_transform.basis.z`
+  (Godot cameras look down local −Z), not a local rotation.
+- `Camera3D.fov` is **vertical degrees** by default (`KEEP_HEIGHT`); the bridge wants
+  **radians**, so the shim sends `deg_to_rad(cam.fov)`.
+- Raw GDScript/C# arrays do **not** auto-marshal across the JS boundary, so the shim builds
+  real JS arrays via `JavaScriptBridge.create_object("Array", x, y, z)`.
+
+## Privacy (ADR 0003)
+
+The shim transmits only low-cardinality, non-PII telemetry: poses, FPS, and
+developer-assigned **named** objects. It MUST NOT invent identifiers or forward raw input
+text. Picks send only the node `name` you authored and the world hit point; the scene proxy
+sends only the nodes you explicitly mark.

package/bridge/UptimizrGodot.cs

@@ -0,0 +1,185 @@
+// UptimizrGodot.cs — C# engine-side bridge for the @uptimizr/godot connector (ADR 0045).
+//
+// Copy-in asset (Apache-2.0). NOT a NuGet/npm package. C# parity of UptimizrGodot.gd for
+// Godot 4 .NET projects. Add it as an Autoload singleton to enable the connector's
+// *bridged tier* (camera pose / world-space picks / FPS / scene proxy). The *JS-only
+// tier* (pointer heatmaps + FPS + JS errors) already works with no engine code.
+//
+// Setup:
+//   1. Load @uptimizr/godot in the Web export's host page and call `trackGodot(...)`,
+//      which exposes the bridge on `window.__uptimizr_godot__`.
+//   2. Project > Project Settings > Globals > Autoload: add this script as `UptimizrGodot`.
+//
+// This shim carries NO analytics logic, IDs, or schema knowledge. It hands **world-space
+// values in Godot's NATIVE frame** (right-handed, y-up, meters) to the connector, which
+// owns all normalization (negates Z) and schema mapping.
+//
+// Privacy (ADR 0003): only poses, FPS, and developer-named objects cross the bridge. It
+// MUST NOT invent identifiers or forward raw input.
+using Godot;
+
+public partial class UptimizrGodot : Node
+{
+    // Expected bridge wire-protocol version (must match BRIDGE_PROTOCOL_VERSION in
+    // @uptimizr/web-export).
+    private const int ProtocolVersion = 1;
+
+    // The `window` property the connector exposes the bridge on.
+    private const string BridgeGlobal = "__uptimizr_godot__";
+
+    // Nodes in this group are included when PushSceneProxy() is called (opt-in).
+    private const string SceneProxyGroup = "uptimizr_tracked";
+
+    /// <summary>Push at most this many camera poses per second. Set &lt;= 0 to push every frame.</summary>
+    [Export] public float PoseSamplesPerSecond = 30.0f;
+
+    /// <summary>When true, a left click casts a ray and pushes the first named collider hit.</summary>
+    [Export] public bool CapturePicks = true;
+
+    /// <summary>Physics ray length (metres) used for click picks.</summary>
+    [Export] public float PickRayLength = 1000.0f;
+
+    private JavaScriptObject _bridge;
+    private bool _readyOk;
+    private float _accum;
+
+    public override void _Ready()
+    {
+        if (!OS.HasFeature("web"))
+        {
+            SetProcess(false);
+            SetProcessUnhandledInput(false);
+            return;
+        }
+
+        _bridge = JavaScriptBridge.GetInterface(BridgeGlobal);
+        if (_bridge == null)
+        {
+            GD.PushWarning($"[Uptimizr] bridge global '{BridgeGlobal}' not found — call trackGodot() in the host page before this autoload runs.");
+            SetProcess(false);
+            SetProcessUnhandledInput(false);
+            return;
+        }
+
+        var version = (int)_bridge.Get("protocolVersion");
+        if (version != ProtocolVersion)
+        {
+            GD.PushWarning($"[Uptimizr] bridge protocol mismatch (page={version}, shim={ProtocolVersion}) — disabling pose/pick capture.");
+            _bridge = null;
+            SetProcess(false);
+            SetProcessUnhandledInput(false);
+            return;
+        }
+
+        _readyOk = true;
+    }
+
+    public override void _Process(double delta)
+    {
+        if (!_readyOk)
+            return;
+
+        if (PoseSamplesPerSecond > 0.0f)
+        {
+            _accum += (float)delta;
+            float interval = 1.0f / PoseSamplesPerSecond;
+            if (_accum < interval)
+            {
+                PushPerf();
+                return;
+            }
+            _accum = 0.0f;
+        }
+
+        PushPose();
+        PushPerf();
+    }
+
+    private void PushPose()
+    {
+        var cam = GetViewport().GetCamera3D();
+        if (cam == null)
+            return;
+        var xform = cam.GlobalTransform;
+        var p = xform.Origin;
+        // Godot cameras look down their local -Z; pass the WORLD-space forward vector.
+        var f = -xform.Basis.Z;
+        var u = xform.Basis.Y;
+        // Camera3D.Fov is vertical degrees by default (KEEP_HEIGHT); the bridge wants radians.
+        _bridge.Call("pushPose", Vec3(p), Vec3(f), Vec3(u), Mathf.DegToRad(cam.Fov));
+    }
+
+    private void PushPerf()
+    {
+        _bridge.Call("pushPerf", Engine.GetFramesPerSecond());
+    }
+
+    public override void _UnhandledInput(InputEvent @event)
+    {
+        if (!_readyOk || !CapturePicks)
+            return;
+        if (@event is InputEventMouseButton mb && mb.Pressed && mb.ButtonIndex == MouseButton.Left)
+            PushPickAt(mb.Position);
+    }
+
+    private void PushPickAt(Vector2 screenPos)
+    {
+        var cam = GetViewport().GetCamera3D();
+        if (cam == null)
+            return;
+        var from = cam.ProjectRayOrigin(screenPos);
+        var to = from + cam.ProjectRayNormal(screenPos) * PickRayLength;
+        var space = cam.GetWorld3D().DirectSpaceState;
+        var query = PhysicsRayQueryParameters3D.Create(from, to);
+        var hit = space.IntersectRay(query);
+        if (hit.Count == 0)
+            return;
+        if (hit["collider"].AsGodotObject() is not Node node)
+            return;
+        // Only the developer-assigned node name and the world hit point are sent (ADR 0003).
+        var point = hit["position"].AsVector3();
+        _bridge.Call("pushPick", node.Name.ToString(), Vec3(point));
+    }
+
+    /// <summary>
+    /// Push a spatial proxy of the named, developer-marked nodes in the scene-proxy group.
+    /// Call this once after your scene is built (opt-in keeps the proxy low-cardinality).
+    /// </summary>
+    public void PushSceneProxy()
+    {
+        if (!_readyOk)
+            return;
+        var nodes = JavaScriptBridge.CreateObject("Array");
+        foreach (var node in GetTree().GetNodesInGroup(SceneProxyGroup))
+        {
+            if (node is not VisualInstance3D vi)
+                continue;
+            var local = vi.GetAabb();
+            var world = vi.GlobalTransform * local;
+            var minP = world.Position;
+            var maxP = world.Position + world.Size;
+            var entry = JavaScriptBridge.CreateObject("Object");
+            entry.Set("name", vi.Name.ToString());
+            entry.Set("aabb", JavaScriptBridge.CreateObject(
+                "Array", minP.X, minP.Y, minP.Z, maxP.X, maxP.Y, maxP.Z));
+            nodes.Call("push", entry);
+        }
+        _bridge.Call("setSceneProxy", nodes);
+    }
+
+    /// <summary>Detach the bridge; subsequent pushes become no-ops.</summary>
+    public void Dispose()
+    {
+        _bridge?.Call("dispose");
+        _bridge = null;
+        _readyOk = false;
+        SetProcess(false);
+        SetProcessUnhandledInput(false);
+    }
+
+    // Build a JS `[x, y, z]` array; raw arrays do not auto-marshal across the JS boundary.
+    private static JavaScriptObject Vec3(Vector3 v)
+    {
+        return JavaScriptBridge.CreateObject("Array", v.X, v.Y, v.Z);
+    }
+}