@uptimizr/unreal 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,75 @@
+# @uptimizr/unreal
+
+The **Unreal Engine (web export)** connector for Uptimizr (ADR 0045). Unreal renders
+into a `<canvas>` via WebAssembly, 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 |
+
+> **Best-effort.** Unreal's first-party web export is community-maintained, so the
+> bridged tier is best-effort by design (ADR 0045). The JS-only tier always works.
+
+Unreal's native world frame is **left-handed, z-up, centimeters**, so the connector
+rebases **z-up → y-up**, converts **cm → m**, and reaches the canonical wire frame
+(left-handed, y-up, unit scale 1 — ADR 0018). The engine-side shim does **no**
+coordinate math — it pushes raw Unreal values.
+
+## Install
+
+```bash
+npm install @uptimizr/unreal
+```
+
+The engine-side bridge is a **copy-in asset** (Emscripten `EM_JS` glue), not an npm
+dependency — see [`bridge/`](./bridge).
+
+## Usage
+
+```ts
+import { trackUnreal } from "@uptimizr/unreal";
+
+const { client, bridge } = trackUnreal({
+  projectId: "your-project",
+  endpoint: "https://collect.example.com",
+  canvas: () => document.querySelector("#unreal-canvas"),
+});
+
+// ... later, on teardown
+await client.stop("manual");
+```
+
+`trackUnreal` creates the client, registers the JS-only tier collector, exposes the
+engine `bridge` (default `window.__uptimizr_unreal__`), and starts the session with
+Unreal'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 { unrealCollector, UNREAL_FRAME } from "@uptimizr/unreal";
+
+const client = new UptimizrClient({ projectId: "your-project", endpoint: "..." });
+client.use(unrealCollector({ canvas: () => document.querySelector("#unreal-canvas") }));
+client.start();
+```
+
+## Engine-side bridge
+
+The bridged tier needs a thin copy-in shim that pushes world-space pose / picks / FPS
+across Unreal's Emscripten glue. The contract and an `EM_JS` sketch live in
+[`bridge/README.md`](./bridge/README.md). The full shim is authored in the Unreal
+web-export sub-issue (umbrella #111).
+
+## 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,106 @@
+# Unreal engine-side bridge (copy-in asset)
+
+> **Status: shim provided, best-effort.** This folder ships the actual Emscripten
+> shim — [`Uptimizr.h`](./Uptimizr.h) + [`Uptimizr.cpp`](./Uptimizr.cpp) — that
+> pushes camera pose / world-space picks / FPS over the versioned bridge. The
+> **JS-only tier** (pointer heatmaps + FPS + errors) already works with **no** engine
+> code; this shim adds the 3D-native (bridged) tier.
+
+## What the shim is
+
+A small, dumb shim that ships as a **copy-in asset** (not an npm package) and pushes
+per-sample telemetry from an Unreal web export across the JS interop boundary to the
+browser-side `@uptimizr/unreal` connector. It carries **no** analytics logic, IDs, or
+schema knowledge (ADR 0045). It performs **no** coordinate math — it pushes Unreal's
+RAW world-space values and the connector owns the single normalization path.
+
+## Feasibility — which web targets this works on (issue #112)
+
+Epic has **no official UE5 HTML5/WASM target** (it was deprecated after UE 4.24), and
+Pixel Streaming is **server-side** rendering (no client WASM scene to read), so neither
+fits this model. The shim instead targets the real, **Emscripten-based, client-side**
+web exports that render into a `<canvas>` and expose the `EM_JS` / `cwrap` interop seam:
+
+| Target                                                                                                                                                                           | UE versions | Renderer      | Status               |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------- | -------------------- |
+| Community HTML5 forks ([ufna/UE-HTML5](https://github.com/ufna/UE-HTML5), [SpeculativeCoder/UnrealEngine-HTML5-ES3](https://github.com/SpeculativeCoder/UnrealEngine-HTML5-ES3)) | 4.24–4.27   | WebGL2        | community-maintained |
+| [Wonder Interactive / SimplyStream](https://wonderinteractive.com/)                                                                                                              | 5.1–5.4     | WASM + WebGPU | experimental         |
+
+Both are Emscripten, so the `EM_JS` / `cwrap` glue below is available by construction.
+Because every viable target is experimental or community-maintained, the **bridged tier
+is best-effort by design** (ADR 0045); the JS-only tier always works. Outside Emscripten
+(e.g. the desktop editor) every entry point compiles to a no-op, so the shim is safe to
+leave wired in across all your build targets.
+
+## The JS API the shim calls
+
+The connector exposes an `EngineBridge` on `window.__uptimizr_unreal__` (configurable via
+the `bridgeGlobal` option). **All values are world-space in Unreal's native frame**
+(left-handed, **z-up**, **centimeters**); the connector rebases z-up → y-up, converts
+cm → m, and reaches the canonical wire frame, then emits the schema events — the shim does
+**no** coordinate math.
+
+```ts
+interface EngineBridge {
+  readonly protocolVersion: number; // assert against UPTIMIZR_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;
+}
+```
+
+## Wiring it in
+
+1. Copy `Uptimizr.h` + `Uptimizr.cpp` into your project's `Source/<Module>/` (or a
+   plugin), so they build with your **web** target.
+2. Load `@uptimizr/unreal` in the export's host page and call `trackUnreal({...})` (or
+   register `unrealCollector()`), which attaches the bridge to `window.__uptimizr_unreal__`.
+3. Once both are up, initialize the sampler. `Initialize()` reads the live bridge's
+   `protocolVersion` and **asserts it equals `UPTIMIZR_BRIDGE_PROTOCOL_VERSION` (1)** —
+   it stays disabled on a mismatch rather than push against an incompatible API. Drive it
+   from C++:
+
+   ```cpp
+   #include "Uptimizr.h"
+
+   // once, after the page + connector are ready:
+   UptimizrTelemetry().Initialize();
+
+   // every frame (e.g. from an AActor::Tick or a UActorComponent::TickComponent):
+   UptimizrTelemetry().Tick(GetWorld(), DeltaSeconds);
+
+   // from your own click/interaction handler (or let it line-trace for you):
+   UptimizrTelemetry().TraceAndReportPick(GetWorld());
+   ```
+
+   …or drive `Init` / `Shutdown` from JS by symbol via `cwrap`
+   (`Module.cwrap('UptimizrBridge_Init', 'number', [])`).
+
+`Tick` reads the active `APlayerCameraManager` pose and accumulates FPS, pushing a pose
+every frame and a perf sample about once per second — all as **raw centimeters, z-up,
+left-handed** values.
+
+### `EM_JS` sketch (the shim implements the full version)
+
+```cpp
+EM_JS(void, UptimizrPushPoseJS, (double px, double py, double pz,
+                                 double fx, double fy, double fz,
+                                 double ux, double uy, double uz, double fov), {
+  var b = window.__uptimizr_unreal__;
+  if (b) b.pushPose([px, py, pz], [fx, fy, fz], [ux, uy, uz], fov);
+});
+
+// Each frame: read APlayerCameraManager location/rotation (cm, z-up) and call
+// UptimizrPushPoseJS(loc.X, loc.Y, loc.Z, fwd.X, fwd.Y, fwd.Z, up.X, up.Y, up.Z, fovRad);
+```
+
+> Pass raw Unreal values — **centimeters, z-up, left-handed**. Do **not** pre-convert;
+> the connector owns the single normalization path so every engine stays consistent.
+
+## Privacy (ADR 0003)
+
+The shim transmits only low-cardinality, non-PII telemetry: poses, FPS, and
+developer-assigned **named** objects (the picked actor's `GetName()`). It MUST NOT invent
+identifiers or forward raw input text.

package/bridge/Uptimizr.cpp

@@ -0,0 +1,204 @@
+// Uptimizr — Unreal Engine (web export) telemetry bridge shim implementation.
+// See Uptimizr.h for the contract, feasibility notes, and privacy rules (ADR 0045 / 0003).
+
+#include "Uptimizr.h"
+
+#include "Camera/PlayerCameraManager.h"
+#include "Engine/World.h"
+#include "GameFramework/Actor.h"
+#include "GameFramework/PlayerController.h"
+
+#if defined(__EMSCRIPTEN__)
+#include <emscripten/emscripten.h>
+
+// --- C++ -> JS glue (EM_JS) -------------------------------------------------------------
+//
+// Each macro embeds a tiny JS body that forwards to the connector's EngineBridge on
+// `window.__uptimizr_unreal__`. All numeric args are RAW Unreal world-space values; the JS
+// connector does the z-up -> y-up rebase and cm -> m scale. The bridge is looked up fresh on
+// every call so teardown (`dispose()` removing the global) cleanly turns pushes into no-ops.
+
+// Returns the live bridge's protocol version, or -1 when no bridge is attached yet.
+EM_JS(int, UptimizrBridgeProtocolVersionJS, (), {
+	var b = (typeof window !== 'undefined') ? window['__uptimizr_unreal__'] : undefined;
+	return (b && typeof b.protocolVersion === 'number') ? b.protocolVersion : -1;
+});
+
+EM_JS(void, UptimizrPushPoseJS,
+	(double px, double py, double pz,
+	 double fx, double fy, double fz,
+	 double ux, double uy, double uz, double fov), {
+	var b = (typeof window !== 'undefined') ? window['__uptimizr_unreal__'] : undefined;
+	if (b) b.pushPose([px, py, pz], [fx, fy, fz], [ux, uy, uz], fov);
+});
+
+EM_JS(void, UptimizrPushPickJS, (const char* name, double hx, double hy, double hz), {
+	var b = (typeof window !== 'undefined') ? window['__uptimizr_unreal__'] : undefined;
+	if (b) b.pushPick(UTF8ToString(name), [hx, hy, hz]);
+});
+
+EM_JS(void, UptimizrPushPerfJS, (double fps, int longFrames), {
+	var b = (typeof window !== 'undefined') ? window['__uptimizr_unreal__'] : undefined;
+	if (b) b.pushPerf(fps, longFrames);
+});
+
+#else // !__EMSCRIPTEN__ — non-web builds (e.g. desktop editor): compile to no-ops.
+
+static int UptimizrBridgeProtocolVersionJS()
+{
+	return -1;
+}
+static void UptimizrPushPoseJS(double, double, double, double, double, double, double, double,
+	double, double)
+{
+}
+static void UptimizrPushPickJS(const char*, double, double, double) {}
+static void UptimizrPushPerfJS(double, int) {}
+
+#endif // __EMSCRIPTEN__
+
+namespace
+{
+	// Emit a perf sample roughly this often.
+	constexpr float UPTIMIZR_PERF_WINDOW_SECONDS = 1.0f;
+	// A frame slower than this (ms) counts as a long frame (matches the JS-only tier default).
+	constexpr float UPTIMIZR_JANK_FRAME_MS = 50.0f;
+
+	APlayerCameraManager* ResolveCameraManager(UWorld* World)
+	{
+		if (!World)
+		{
+			return nullptr;
+		}
+		APlayerController* PC = World->GetFirstPlayerController();
+		return PC ? PC->PlayerCameraManager : nullptr;
+	}
+}
+
+bool FUptimizrTelemetry::Initialize()
+{
+	const int Reported = UptimizrBridgeProtocolVersionJS();
+	if (Reported != UPTIMIZR_BRIDGE_PROTOCOL_VERSION)
+	{
+		// No bridge yet, or a version this shim was not authored against — stay disabled
+		// rather than push against an incompatible API.
+		UE_LOG(LogTemp, Warning,
+			TEXT("[Uptimizr] bridge protocol mismatch: shim=%d live=%d — telemetry disabled."),
+			UPTIMIZR_BRIDGE_PROTOCOL_VERSION, Reported);
+		bInitialized = false;
+		return false;
+	}
+
+	bInitialized = true;
+	PerfWindowSeconds = 0.0f;
+	PerfWindowFrames = 0;
+	PerfWindowLongFrames = 0;
+	return true;
+}
+
+void FUptimizrTelemetry::Tick(UWorld* World, float DeltaSeconds)
+{
+	if (!bInitialized)
+	{
+		return;
+	}
+
+	if (APlayerCameraManager* Cam = ResolveCameraManager(World))
+	{
+		// RAW Unreal world-space: centimeters, z-up, left-handed. Pushed unconverted.
+		const FVector Loc = Cam->GetCameraLocation();
+		const FRotator Rot = Cam->GetCameraRotation();
+		const FVector Fwd = Rot.Vector();
+		const FVector Up = FRotationMatrix(Rot).GetUnitAxis(EAxis::Z);
+		// UE exposes horizontal FOV in degrees; the bridge wants radians. (Vertical vs
+		// horizontal is best-effort — the connector only uses it as a coarse frustum hint.)
+		const double FovRad = FMath::DegreesToRadians(Cam->GetFOVAngle());
+
+		UptimizrPushPoseJS(Loc.X, Loc.Y, Loc.Z, Fwd.X, Fwd.Y, Fwd.Z, Up.X, Up.Y, Up.Z, FovRad);
+	}
+
+	// Accumulate FPS over a ~1s window so we push a stable rate, not per-frame noise.
+	PerfWindowSeconds += DeltaSeconds;
+	PerfWindowFrames += 1;
+	if (DeltaSeconds * 1000.0f > UPTIMIZR_JANK_FRAME_MS)
+	{
+		PerfWindowLongFrames += 1;
+	}
+
+	if (PerfWindowSeconds >= UPTIMIZR_PERF_WINDOW_SECONDS && PerfWindowFrames > 0)
+	{
+		const double Fps = static_cast<double>(PerfWindowFrames) / PerfWindowSeconds;
+		UptimizrPushPerfJS(Fps, PerfWindowLongFrames);
+		PerfWindowSeconds = 0.0f;
+		PerfWindowFrames = 0;
+		PerfWindowLongFrames = 0;
+	}
+}
+
+void FUptimizrTelemetry::ReportPick(const FString& ObjectName, const FVector& WorldHitPoint)
+{
+	if (!bInitialized || ObjectName.IsEmpty())
+	{
+		return;
+	}
+	// RAW world-space hit point (cm, z-up, left-handed).
+	UptimizrPushPickJS(TCHAR_TO_UTF8(*ObjectName), WorldHitPoint.X, WorldHitPoint.Y,
+		WorldHitPoint.Z);
+}
+
+bool FUptimizrTelemetry::TraceAndReportPick(UWorld* World, float MaxDistanceCm)
+{
+	if (!bInitialized)
+	{
+		return false;
+	}
+	APlayerCameraManager* Cam = ResolveCameraManager(World);
+	if (!Cam)
+	{
+		return false;
+	}
+
+	const FVector Start = Cam->GetCameraLocation();
+	const FVector End = Start + Cam->GetCameraRotation().Vector() * MaxDistanceCm;
+
+	FHitResult Hit;
+	FCollisionQueryParams Params(SCENE_QUERY_STAT(UptimizrPick), /*bTraceComplex=*/false);
+	if (!World->LineTraceSingleByChannel(Hit, Start, End, ECC_Visibility, Params))
+	{
+		return false;
+	}
+
+	// Only the developer-assigned object name crosses the bridge (ADR 0003) — never input
+	// text or invented identifiers.
+	const AActor* HitActor = Hit.GetActor();
+	if (!HitActor)
+	{
+		return false;
+	}
+	ReportPick(HitActor->GetName(), Hit.ImpactPoint);
+	return true;
+}
+
+void FUptimizrTelemetry::Shutdown()
+{
+	bInitialized = false;
+}
+
+FUptimizrTelemetry& UptimizrTelemetry()
+{
+	static FUptimizrTelemetry Instance;
+	return Instance;
+}
+
+extern "C"
+{
+	int UptimizrBridge_Init()
+	{
+		return UptimizrTelemetry().Initialize() ? 1 : 0;
+	}
+
+	void UptimizrBridge_Shutdown()
+	{
+		UptimizrTelemetry().Shutdown();
+	}
+}