@uptimizr/unity 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,108 @@
+# @uptimizr/unity
+
+The **Unity (WebGL export)** connector for Uptimizr (ADR 0045). Unity 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 |
+
+Unity's native world frame is **left-handed, y-up, meters** — already Uptimizr's
+canonical wire frame (ADR 0018), so world-space payloads need **no axis conversion**.
+
+> **Status.** The JS-only tier is covered end to end by the playground's Playwright
+> suite. The bridged tier is **preview**: the `.jslib` shim is sanity-tested under
+> `node:vm` on every `pnpm test`, and the full round trip through a real Unity WebGL
+> export is driven by a Playwright spec against a **local build** of the sample project
+> in [`examples/unity-web-export/`](../../../examples/unity-web-export) — it is labelled
+> **verified against a local build** once a maintainer has run that spec. See
+> [Verifying against a real export](#verifying-against-a-real-export).
+
+## Install
+
+```bash
+npm install @uptimizr/unity
+```
+
+The engine-side bridge is a **copy-in asset** (a `.jslib` plugin + a small
+`MonoBehaviour`), not an npm dependency — see [`bridge/`](./bridge).
+
+## Usage
+
+```ts
+import { trackUnity } from "@uptimizr/unity";
+
+const { client, bridge } = trackUnity({
+  projectId: "your-project",
+  endpoint: "https://collect.example.com",
+  canvas: () => document.querySelector("#unity-canvas"),
+});
+
+// ... later, on teardown
+await client.stop("manual");
+```
+
+`trackUnity` creates the client, registers the JS-only tier collector, exposes the
+engine `bridge` (default `window.__uptimizr_unity__`), and starts the session with
+Unity'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 { unityCollector, UNITY_FRAME } from "@uptimizr/unity";
+
+const client = new UptimizrClient({ projectId: "your-project", endpoint: "..." });
+client.use(unityCollector({ canvas: () => document.querySelector("#unity-canvas") }));
+client.start();
+```
+
+## Engine-side bridge
+
+The bridged tier needs a thin copy-in shim that pushes world-space pose / picks / FPS
+across Unity's JS interop boundary. It ships in [`bridge/`](./bridge) as two copy-in
+files:
+
+- **`Uptimizr.jslib`** → copy to `Assets/Plugins/WebGL/Uptimizr.jslib`.
+- **`UptimizrUnityBridge.cs`** → copy under `Assets/` and add the `UptimizrUnityBridge`
+  component to a GameObject (it samples the active `Camera`, raycast picks, and FPS).
+
+Make sure `trackUnity(...)` runs on the host page before the export starts, so the bridge
+global (`window.__uptimizr_unity__`) exists. The shim does **no** coordinate math — it
+pushes Unity's native-frame values and the connector normalizes them. On start it asserts
+the bridge protocol version matches `BRIDGE_PROTOCOL_VERSION` (1). See
+[`bridge/README.md`](./bridge/README.md) for the full contract and the JS API table.
+
+## Verifying against a real export
+
+Unity is not part of the JS toolchain, so verification is split in two:
+
+- **Always on (CI):** `src/__tests__/jslib.test.ts` loads `bridge/Uptimizr.jslib` as
+  text, evaluates it in a `node:vm` sandbox with mocked Emscripten globals
+  (`mergeInto`, `LibraryManager.library`, `UTF8ToString`, `window`), resolves the
+  `$UptimizrUnityBridge` dependency the way Emscripten does, and asserts every export
+  forwards to `window.__uptimizr_unity__` — plus that each export declares its `__deps`
+  (a missing dep is a silent link-time drop) and that the export set matches the
+  `[DllImport]`s in `UptimizrUnityBridge.cs`.
+- **One manual step (maintainer):** the sample Unity 2022.3 LTS project in
+  [`examples/unity-web-export/`](../../../examples/unity-web-export) carries copies of
+  both bridge files (a lint script fails if they drift), a camera, and three named
+  cubes with colliders. Open it in Unity Hub and **File → Build Settings → WebGL →
+  Build** into `examples/unity-web-export/dist/` with **Compression Format: Disabled**.
+  Then `examples/playground/e2e/unity-export.spec.ts` serves the build, starts
+  `trackUnity` **before** `createUnityInstance`, clicks the centre cube, and asserts
+  `session_start.connector.name === "unity"`, `camera_sample`, `mesh_interaction`, and
+  `frame_perf` reach the collector. Without a build the spec skips (the default in CI).
+
+## 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,86 @@
+# Unity engine-side bridge (copy-in asset)
+
+The **bridged tier** of the [`@uptimizr/unity`](../) connector (ADR 0045). Unity compiles
+to WebAssembly and renders into a `<canvas>`, so its scene graph lives in WASM linear
+memory and JS cannot read the camera or raycast it passively (unlike the Babylon adapter).
+This folder is the thin **engine-side shim** that pushes that data across the JS interop
+boundary to the connector.
+
+> The **JS-only tier** (pointer heatmaps + FPS + JS errors) works with **no** engine code
+> — it reads the `<canvas>` DOM directly. You only need this bridge for the 3D-native
+> channels: camera-pose / view-direction heatmap, world-space picks, scene proxy, and
+> replay.
+
+These are **copy-in assets**, not an npm package. They carry **no** analytics logic, IDs,
+or schema knowledge — they only forward Unity's own camera/raycast/perf to the versioned
+JS bridge the connector exposes on `window.__uptimizr_unity__`.
+
+## Files
+
+| File                                                 | What it is                                                                              |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| [`Uptimizr.jslib`](./Uptimizr.jslib)                 | Emscripten plugin (`mergeInto(LibraryManager.library, …)`) the C# side calls into.      |
+| [`UptimizrUnityBridge.cs`](./UptimizrUnityBridge.cs) | Example `MonoBehaviour` that samples the active `Camera`, picks, and FPS each interval. |
+
+## Install
+
+1. Copy **`Uptimizr.jslib`** to `Assets/Plugins/WebGL/Uptimizr.jslib` in your Unity
+   project. (Unity compiles `.jslib` files under `Plugins/WebGL` into the WebGL build.)
+2. Copy **`UptimizrUnityBridge.cs`** anywhere under `Assets/` and add the
+   `UptimizrUnityBridge` component to a GameObject in your scene (e.g. an empty
+   `Uptimizr` object). Optionally assign a specific `Camera`; it defaults to
+   `Camera.main`.
+3. On the **host page** (the HTML that loads your WebGL export), register the connector
+   so `window.__uptimizr_unity__` exists before the export starts pushing:
+
+   ```ts
+   import { trackUnity } from "@uptimizr/unity";
+
+   trackUnity({
+     projectId: "your-project",
+     endpoint: "https://collect.example.com",
+     canvas: () => document.querySelector("#unity-canvas"),
+   });
+   ```
+
+On `Start()`, the component asserts the bridge protocol version matches
+`BRIDGE_PROTOCOL_VERSION` (1). If the connector is missing or a different version, it logs
+a warning and disables itself rather than pushing to an incompatible bridge.
+
+## The JS API the shim calls
+
+The connector exposes an `EngineBridge` on `window.__uptimizr_unity__` (configurable via
+the `bridgeGlobal` option). The `.jslib` plugin forwards to it. **All values are
+world-space in Unity's native frame** — left-handed, y-up, meters, which is already
+Uptimizr's canonical wire frame, so the connector applies the **identity** normalization
+for Unity. The shim does **no** coordinate math.
+
+```ts
+interface EngineBridge {
+  readonly protocolVersion: number; // assert === BRIDGE_PROTOCOL_VERSION (1)
+  pushPose(position: Vec3, forward: Vec3, up: Vec3, fov?: number): void; // fov in radians
+  pushPick(objectName: string, hitPoint: Vec3): void;
+  pushPerf(fps: number, longFrames?: number): void;
+  setSceneProxy(
+    nodes: { name: string; aabb: [number, number, number, number, number, number] }[],
+  ): void;
+  dispose(): void;
+}
+```
+
+The `.jslib` exposes these to C# (called via `[DllImport("__Internal")]`):
+
+| `.jslib` function                 | Maps to           | Notes                                                                        |
+| --------------------------------- | ----------------- | ---------------------------------------------------------------------------- |
+| `UptimizrUnityGetProtocolVersion` | `protocolVersion` | Returns the version, or `-1` if the connector isn't present yet.             |
+| `UptimizrUnityPushPose`           | `pushPose`        | 9 floats + `fov` (radians); pass `fov < 0` to omit it.                       |
+| `UptimizrUnityPushPick`           | `pushPick`        | UTF-8 object name + 3 floats (world hit point).                              |
+| `UptimizrUnityPushPerf`           | `pushPerf`        | `fps` + `longFrames` (`< 0` to omit).                                        |
+| `UptimizrUnitySetSceneProxy`      | `setSceneProxy`   | A JSON string of `{ name, aabb[6] }` nodes (arrays don't cross `DllImport`). |
+
+## Privacy (ADR 0003)
+
+The shim transmits only low-cardinality, non-PII telemetry: poses, FPS, and
+developer-assigned **named** objects (the GameObject name that was hit). It MUST NOT
+invent identifiers or forward raw input text — the pick channel sends an object name and a
+world point, never pointer coordinates as text or keystrokes.

package/bridge/Uptimizr.jslib

@@ -0,0 +1,95 @@
+// Uptimizr Unity WebGL bridge — Emscripten `.jslib` plugin (copy-in asset).
+//
+// Part of the `@uptimizr/unity` connector (ADR 0045). This is the **engine-side
+// shim**: a small, dumb plugin that pushes per-sample telemetry from Unity's C#
+// side across the WASM<->JS interop boundary to the browser-side connector. It
+// carries **no** analytics logic, IDs, or schema knowledge — it just forwards to the
+// versioned `EngineBridge` the connector exposes on `window.__uptimizr_unity__`.
+//
+// All world-space values are forwarded in Unity's **native** frame (left-handed,
+// y-up, meters). The connector — not this shim — owns coordinate normalization and
+// schema mapping ("one normalization point", ADR 0018). Do NOT do coordinate math
+// here.
+//
+// Privacy (ADR 0003): only poses, FPS, and developer-named objects cross this
+// boundary. The shim MUST NOT invent identifiers or forward raw input text.
+//
+// Install: copy this file to `Assets/Plugins/WebGL/Uptimizr.jslib` in your Unity
+// project, then add the companion `UptimizrUnityBridge.cs` MonoBehaviour to a
+// GameObject. The C# side calls these via `[DllImport("__Internal")]`.
+mergeInto(LibraryManager.library, {
+  // Resolve the connector's EngineBridge, or `null` if the connector has not started
+  // yet (the host page must call `trackUnity(...)` / register `unityCollector()`).
+  $UptimizrUnityBridge__deps: [],
+  $UptimizrUnityBridge: {
+    get: function () {
+      return typeof window !== "undefined" ? window.__uptimizr_unity__ || null : null;
+    },
+  },
+
+  // Returns the bridge protocol version (assert against BRIDGE_PROTOCOL_VERSION on the
+  // C# side), or -1 when the connector is not present yet. Lets the shim fail loudly
+  // on a contract mismatch instead of silently pushing to an incompatible bridge.
+  UptimizrUnityGetProtocolVersion__deps: ["$UptimizrUnityBridge"],
+  UptimizrUnityGetProtocolVersion: function () {
+    var b = UptimizrUnityBridge.get();
+    return b && typeof b.protocolVersion === "number" ? b.protocolVersion : -1;
+  },
+
+  // Push a camera pose. position / forward / up are world-space in Unity's native
+  // frame; `fov` is the vertical field of view in **radians**, or < 0 to omit it.
+  UptimizrUnityPushPose__deps: ["$UptimizrUnityBridge"],
+  UptimizrUnityPushPose: function (px, py, pz, fx, fy, fz, ux, uy, uz, fov) {
+    var b = UptimizrUnityBridge.get();
+    if (!b) return;
+    if (fov >= 0) {
+      b.pushPose([px, py, pz], [fx, fy, fz], [ux, uy, uz], fov);
+    } else {
+      b.pushPose([px, py, pz], [fx, fy, fz], [ux, uy, uz]);
+    }
+  },
+
+  // Push a raycast pick: a developer-named object and its world-space hit point in
+  // Unity's native frame. `namePtr` is a UTF-8 string pointer from Unity.
+  UptimizrUnityPushPick__deps: ["$UptimizrUnityBridge"],
+  UptimizrUnityPushPick: function (namePtr, hx, hy, hz) {
+    var b = UptimizrUnityBridge.get();
+    if (!b) return;
+    var name = UTF8ToString(namePtr);
+    if (!name) return;
+    b.pushPick(name, [hx, hy, hz]);
+  },
+
+  // Push an engine-measured performance sample. `longFrames` < 0 omits the count.
+  UptimizrUnityPushPerf__deps: ["$UptimizrUnityBridge"],
+  UptimizrUnityPushPerf: function (fps, longFrames) {
+    var b = UptimizrUnityBridge.get();
+    if (!b) return;
+    if (longFrames >= 0) {
+      b.pushPerf(fps, longFrames);
+    } else {
+      b.pushPerf(fps);
+    }
+  },
+
+  // Push the scene's spatial proxy. `jsonPtr` is a UTF-8 JSON string of
+  // `[{ name: string, aabb: [minX,minY,minZ,maxX,maxY,maxZ] }, ...]` in Unity's
+  // native frame (arrays don't cross the DllImport boundary cleanly, so the C# side
+  // serializes once). The connector normalizes + builds a wire-correct SceneProxy.
+  UptimizrUnitySetSceneProxy__deps: ["$UptimizrUnityBridge"],
+  UptimizrUnitySetSceneProxy: function (jsonPtr) {
+    var b = UptimizrUnityBridge.get();
+    if (!b) return;
+    var json = UTF8ToString(jsonPtr);
+    if (!json) return;
+    var nodes;
+    try {
+      nodes = JSON.parse(json);
+    } catch (e) {
+      return;
+    }
+    if (Array.isArray(nodes)) {
+      b.setSceneProxy(nodes);
+    }
+  },
+});