@reliantlabs/forge-web-runtime 0.3.2 → 0.4.1

package/dist/telemetry.js

@@ -1,128 +1,271 @@
-let started = false;
+// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// Browser telemetry: the HyperDX browser SDK, initialised the forge way.
+//
+// Captures errors (uncaught, unhandled rejections, boundary-caught), console
+// output, fetch/XHR spans, document load, long tasks and web vitals, and
+// ships them to ClickStack through a SAME-ORIGIN `/_otel` route.
+//
+// ── Why HyperDX REPLACES the old OTel web wiring, not joins it ───────────
+//
+// @hyperdx/browser wraps @hyperdx/otel-web, which builds its own
+// WebTracerProvider and calls provider.register() — the global tracer
+// provider, context manager and propagator. A second registration (the old
+// `./otel` subpath did exactly that) is rejected by @opentelemetry/api with a
+// "duplicate registration" diagnostic and silently loses: whichever ran
+// second would simply never see a span. Two tracer providers cannot coexist
+// in one page, so there is one, and it is HyperDX's. `./otel` and its eight
+// @opentelemetry/* SDK peer dependencies are gone.
+//
+// traceparent on RPCs is unaffected. traceInterceptor (trace.ts) injects the
+// active span's context into every Connect call, or synthesises a valid
+// traceparent when none is active — with no SDK at all. With the SDK running,
+// the fetch span HyperDX opens for the call carries the same trace id, and
+// `apiOrigins` below makes that hold for a cross-origin API too (which is
+// every dev loop: the API binds its own port).
+//
+// ── The browser holds no secret ──────────────────────────────────────────
+//
+// `url` is `${location.origin}/_otel`. The browser talks only to its own
+// origin; a dev-server proxy (next.config.ts rewrites / Vite server.proxy) or
+// the deployment's ingress forwards `/_otel/v1/{traces,logs}` to the OTLP/HTTP
+// port of a collector, and that hop — never the bundle — owns credentials.
+//
+// The SDK nevertheless wants an `apiKey` and sends it as an `authorization`
+// header. We pass PLACEHOLDER_API_KEY, a constant that grants nothing and is
+// public by construction. A collector that enforces ingestion auth (ClickStack
+// `collectorAuthenticationEnforced`) rejects it with 401, so the proxy in
+// front of such a collector must strip the header or replace it with the real
+// key. The local ClickStack collector does not enforce, and ignores it.
+//
+// ── Replay: shipped, off, masked ─────────────────────────────────────────
+//
+// The SDK bundles an rrweb recorder. It is DISABLED unless `replay: true`.
+// When enabled, masking is forced on — every input and all text — because a
+// replay records the DOM, which for most apps is the most sensitive data they
+// have. There is deliberately no option to turn masking off while replay is
+// on; an app that needs unmasked replay passes its own SDK options.
+//
+// ── Loading ──────────────────────────────────────────────────────────────
+//
+// The SDK is ~600 KB minified (rrweb and the OTel web stack are bundled in
+// it), so it is imported lazily: bundlers split it into its own chunk that
+// loads after the app is interactive and costs the first paint nothing.
+// initBrowserTelemetry is therefore async and idempotent — every caller gets
+// the same promise, which is what survives React StrictMode's double mount and
+// Fast Refresh. It is a no-op without a DOM (SSR, prerender) and without an
+// endpoint, and it never throws.
+import { trace } from "@opentelemetry/api";
+import { setExceptionReporter } from "./error-reporter.js";
+/** Where the browser ships telemetry: this origin's `/_otel`. */
+export const DEFAULT_INGEST_PATH = "/_otel";
 /**
- * initClientTelemetry wires the capture listeners and returns a teardown
- * function. Idempotent and SSR-safe (no-op without a DOM). Call once from the
- * app shell (e.g. inside Providers' mount effect).
+ * The apiKey handed to the SDK. Public by construction: it identifies
+ * nothing and authorises nothing. See the header — the proxy or collector
+ * owns the real credential.
  */
-export function initClientTelemetry(config = {}) {
-    if (started || typeof window === "undefined") {
-        return () => { };
-    }
-    started = true;
-    const serviceName = config.serviceName ?? "frontend";
-    const captureErrors = config.captureErrors ?? true;
-    const captureWebVitals = config.captureWebVitals ?? true;
-    const dispatch = (event) => {
-        if (config.onEvent) {
-            config.onEvent(event);
-        }
-        else if (typeof process !== "undefined" &&
-            process.env?.NODE_ENV === "development") {
-            // The `typeof` guard keeps this framework-agnostic — Vite SPAs and
-            // plain browsers have no `process` at all.
-            console.debug("[telemetry]", event.type, event.name, event.value ?? "");
-        }
-        if (config.endpoint) {
-            exportEvent(config.endpoint, serviceName, event);
+export const PLACEHOLDER_API_KEY = "forge-browser-public";
+let started = null;
+/**
+ * initBrowserTelemetry starts the HyperDX browser SDK once per page load and
+ * resolves to whether it is running. See the module header for the contract.
+ */
+export function initBrowserTelemetry(config) {
+    if (typeof window === "undefined") {
+        return Promise.resolve(false);
+    }
+    if (started) {
+        return started;
+    }
+    const ingest = resolveIngestUrl(config.endpoint, window.location.origin);
+    if (!ingest) {
+        return Promise.resolve(false);
+    }
+    started = start(config, ingest);
+    return started;
+}
+async function start(config, ingest) {
+    try {
+        const hdx = resolveClient(await import("@hyperdx/browser"));
+        if (!hdx) {
+            return false;
         }
-    };
-    const teardowns = [];
-    if (captureErrors) {
-        const onError = (e) => dispatch({
-            type: "error",
-            name: e.error?.name ?? "Error",
-            message: e.message,
-            detail: { filename: e.filename, line: e.lineno, col: e.colno },
-            timestamp: Date.now(),
-        });
-        const onRejection = (e) => dispatch({
-            type: "unhandled-rejection",
-            name: "UnhandledRejection",
-            message: String(e.reason),
-            timestamp: Date.now(),
-        });
-        window.addEventListener("error", onError);
-        window.addEventListener("unhandledrejection", onRejection);
-        teardowns.push(() => window.removeEventListener("error", onError));
-        teardowns.push(() => window.removeEventListener("unhandledrejection", onRejection));
-    }
-    if (captureWebVitals && typeof PerformanceObserver === "function") {
-        let clsValue = 0;
-        const observe = (type, cb) => {
-            try {
-                const obs = new PerformanceObserver((list) => cb(list.getEntries()));
-                obs.observe({ type, buffered: true });
-                teardowns.push(() => obs.disconnect());
-            }
-            catch {
-                // Unsupported entry type in this browser — skip silently.
-            }
-        };
-        observe("largest-contentful-paint", (entries) => {
-            const last = entries.at(-1);
-            if (last) {
-                dispatch({
-                    type: "web-vital",
-                    name: "LCP",
-                    value: Math.round(last.startTime),
-                    timestamp: Date.now(),
-                });
-            }
-        });
-        observe("layout-shift", (entries) => {
-            for (const entry of entries) {
-                if (!entry.hadRecentInput) {
-                    clsValue += entry.value;
-                }
-            }
-            dispatch({
-                type: "web-vital",
-                name: "CLS",
-                value: Number(clsValue.toFixed(4)),
-                timestamp: Date.now(),
-            });
-        });
-        // FID (First Input Delay): processingStart − startTime of the first
-        // input. This is FID, NOT INP — INP needs the full interaction-latency
-        // model from the web-vitals library, which this dependency-free module
-        // deliberately doesn't pull in. Reach for `web-vitals` if you need INP.
-        observe("first-input", (entries) => {
-            const first = entries[0];
-            if (first) {
-                dispatch({
-                    type: "web-vital",
-                    name: "FID",
-                    value: Math.round(first.processingStart - first.startTime),
-                    timestamp: Date.now(),
-                });
+        hdx.init(buildSdkOptions(config, ingest, window.location.origin));
+        tapSdkInputs();
+        setExceptionReporter((error, attributes) => {
+            if (alreadyRecorded(error)) {
+                return;
             }
+            hdx.recordException(error, attributes);
         });
+        return true;
+    }
+    catch (err) {
+        // Blocked chunk, ad-blocker, SDK throw: telemetry must never break the app.
+        console.debug("[telemetry] disabled:", err);
+        return false;
     }
-    return () => {
-        for (const t of teardowns) {
-            t();
+}
+// ── One failure, one record ──────────────────────────────────────────────
+//
+// The SDK records an Error that reaches window "error", window
+// "unhandledrejection", or console.error. React (18 and 19) console.errors an
+// error a boundary catches BEFORE it calls componentDidCatch, and Next
+// dispatches an uncaught render error to window "error" — so by the time
+// reportException runs, the SDK has usually recorded that very error already.
+// Recording it again would count one failure twice, and the issue layer
+// (which groups by fingerprint) would report two.
+//
+// So the taps below remember which Error OBJECTS the SDK was shown, and the
+// installed recorder skips those. Whatever the SDK did not see — a custom
+// onCaughtError that silences React's logging, an error rethrown as a new
+// object — is still recorded. The console tap is installed after the SDK's own
+// wrapper, so it sits outermost and only observes; every call is forwarded
+// untouched.
+//
+// The cost is the React component stack: the SDK's record of a boundary-caught
+// error comes from console.error(error), which carries the error and its
+// stack but not React's componentStack, and attributes passed to a skipped
+// reportException are dropped with it.
+const seenBySdk = new WeakSet();
+let tapped = false;
+function noteSeen(value) {
+    if (typeof value === "object" && value !== null) {
+        seenBySdk.add(value);
+    }
+}
+function tapSdkInputs() {
+    if (tapped) {
+        return;
+    }
+    tapped = true;
+    const wrapped = console.error;
+    console.error = function (...args) {
+        for (const arg of args) {
+            if (arg instanceof Error) {
+                noteSeen(arg);
+            }
         }
-        started = false;
+        return wrapped.apply(this, args);
+    };
+    window.addEventListener("error", (e) => noteSeen(e.error), true);
+    window.addEventListener("unhandledrejection", (e) => noteSeen(e.reason), true);
+}
+function alreadyRecorded(error) {
+    return typeof error === "object" && error !== null && seenBySdk.has(error);
+}
+/**
+ * The options passed to HyperDX.init. Exported for tests and for apps that
+ * want to see exactly what is configured — it is pure.
+ */
+export function buildSdkOptions(config, ingestUrl, pageOrigin) {
+    const replay = config.replay === true;
+    const resourceAttributes = {};
+    if (config.serviceVersion) {
+        resourceAttributes["service.version"] = config.serviceVersion;
+    }
+    if (config.serviceNamespace) {
+        resourceAttributes["service.namespace"] = config.serviceNamespace;
+    }
+    if (config.environment) {
+        resourceAttributes["deployment.environment.name"] = config.environment;
+        resourceAttributes["deployment.environment"] = config.environment;
+    }
+    const options = {
+        apiKey: PLACEHOLDER_API_KEY,
+        service: config.serviceName,
+        url: ingestUrl,
+        tracePropagationTargets: propagationTargets(pageOrigin, config.apiOrigins),
+        // The SDK would otherwise trace its own exports, and it must never
+        // observe the route it ships through.
+        ignoreUrls: [new RegExp(`^${escapeRegExp(ingestUrl)}`)],
+        consoleCapture: config.consoleCapture ?? true,
+        advancedNetworkCapture: config.advancedNetworkCapture ?? false,
+        // Polls for window.Intercom on a timer; nothing here uses Intercom.
+        disableIntercom: true,
+        disableReplay: !replay,
+        otelResourceAttributes: resourceAttributes,
+        debug: config.debug ?? false,
     };
+    if (replay) {
+        // The SDK's own default masks inputs but NOT text; text is where chat
+        // content and records live. Force both.
+        options.maskAllInputs = true;
+        options.maskAllText = true;
+        options.recordCanvas = false;
+    }
+    return options;
 }
-/** Best-effort beacon of one event. Never throws into the caller. */
-function exportEvent(endpoint, serviceName, event) {
+/**
+ * resolveIngestUrl turns the configured endpoint into the absolute URL the SDK
+ * is given, or null when telemetry is off. A path resolves against the page
+ * origin, so the default is same-origin by construction.
+ */
+export function resolveIngestUrl(endpoint, pageOrigin) {
+    const value = (endpoint ?? "").trim();
+    if (value === "" || value.toLowerCase() === "off") {
+        return null;
+    }
     try {
-        const body = JSON.stringify({ service: serviceName, ...event });
-        if (typeof navigator !== "undefined" && navigator.sendBeacon) {
-            navigator.sendBeacon(endpoint, body);
+        return new URL(value, pageOrigin).toString().replace(/\/+$/, "");
+    }
+    catch {
+        return null;
+    }
+}
+function propagationTargets(pageOrigin, apiOrigins = []) {
+    const origins = new Set([pageOrigin]);
+    for (const raw of apiOrigins) {
+        if (!raw) {
+            continue;
+        }
+        try {
+            origins.add(new URL(raw, pageOrigin).origin);
         }
-        else {
-            void fetch(endpoint, {
-                method: "POST",
-                body,
-                keepalive: true,
-                headers: { "Content-Type": "application/json" },
-            }).catch(() => { });
+        catch {
+            // An unparsable origin is not a target.
+        }
+    }
+    return [...origins].map((o) => new RegExp(`^${escapeRegExp(o)}(?:[/?#]|$)`));
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+// @hyperdx/browser is a UMD/CJS bundle whose module.exports IS the client, and
+// its methods use `this`. A bundler hands back a module NAMESPACE that exposes
+// both the client's members at the top level (as read-only getters) and the
+// client itself as `default`. Calling init on the namespace binds `this` to that
+// frozen object and the SDK throws on its first property write, which disabled
+// telemetry silently. So descend to the deepest `default` that is still a
+// client, the real instance, and never settle for the namespace in front of it.
+function resolveClient(mod) {
+    let cur = mod;
+    for (let depth = 0; depth < 4; depth++) {
+        const next = peek(cur, "default");
+        if (!isClient(next)) {
+            break;
         }
+        cur = next;
+    }
+    return isClient(cur) ? cur : null;
+}
+function isClient(v) {
+    return (typeof peek(v, "init") === "function" &&
+        typeof peek(v, "recordException") === "function");
+}
+// A module namespace object may throw on an absent key (strict ESM
+// interop shims and test doubles do), and "absent" is an answer here.
+function peek(obj, key) {
+    try {
+        return obj[key];
     }
     catch {
-        // Telemetry must never break the app.
+        return undefined;
     }
 }
+/** The tracer to open manual spans on. Resolves HyperDX's provider once it is running. */
+export function getTracer(name = "default") {
+    return trace.getTracer(name);
+}
+export { context, propagation, trace } from "@opentelemetry/api";
 //# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Lightweight client RUM: unhandled errors + core Web Vitals, captured with\n// native browser APIs (no extra dependency). Export is OPT-IN: by default\n// events go to an in-process sink (console.debug in dev). Set `endpoint` to\n// beacon them to a browser-reachable OTLP/HTTP collector (needs CORS on that\n// collector — stand it up before relying on export). This is the config seam;\n// distributed tracing itself (the traceparent on every RPC) is always on and\n// lives in trace.ts — it does NOT depend on this module.\nexport interface TelemetryEvent {\n  type: \"error\" | \"unhandled-rejection\" | \"web-vital\";\n  name: string;\n  value?: number;\n  message?: string;\n  detail?: Record<string, unknown>;\n  timestamp: number;\n}\n\nexport interface TelemetryConfig {\n  serviceName?: string;\n  /** OTLP/HTTP-ish collector URL. Unset = no network export (default). */\n  endpoint?: string;\n  /** In-process sink for every event. Default: console.debug in dev. */\n  onEvent?: (event: TelemetryEvent) => void;\n  /** Capture window errors + unhandled rejections. Default true. */\n  captureErrors?: boolean;\n  /** Capture LCP / CLS / FID via PerformanceObserver. Default true. */\n  captureWebVitals?: boolean;\n}\n\ninterface LayoutShiftEntry extends PerformanceEntry {\n  value: number;\n  hadRecentInput: boolean;\n}\n\ninterface FirstInputEntry extends PerformanceEntry {\n  processingStart: number;\n}\n\n// `process` is a bundler-injected global (Next replaces the literal\n// `process.env.NODE_ENV` at build time), not a browser one. Declaring it\n// locally keeps this package free of a @types/node dependency while leaving\n// the expression textually intact so that replacement still happens.\ndeclare const process: { env?: Record<string, string | undefined> } | undefined;\n\nlet started = false;\n\n/**\n * initClientTelemetry wires the capture listeners and returns a teardown\n * function. Idempotent and SSR-safe (no-op without a DOM). Call once from the\n * app shell (e.g. inside Providers' mount effect).\n */\nexport function initClientTelemetry(config: TelemetryConfig = {}): () => void {\n  if (started || typeof window === \"undefined\") {\n    return () => {};\n  }\n  started = true;\n\n  const serviceName = config.serviceName ?? \"frontend\";\n  const captureErrors = config.captureErrors ?? true;\n  const captureWebVitals = config.captureWebVitals ?? true;\n\n  const dispatch = (event: TelemetryEvent) => {\n    if (config.onEvent) {\n      config.onEvent(event);\n    } else if (\n      typeof process !== \"undefined\" &&\n      process.env?.NODE_ENV === \"development\"\n    ) {\n      // The `typeof` guard keeps this framework-agnostic — Vite SPAs and\n      // plain browsers have no `process` at all.\n      console.debug(\"[telemetry]\", event.type, event.name, event.value ?? \"\");\n    }\n    if (config.endpoint) {\n      exportEvent(config.endpoint, serviceName, event);\n    }\n  };\n\n  const teardowns: Array<() => void> = [];\n\n  if (captureErrors) {\n    const onError = (e: ErrorEvent) =>\n      dispatch({\n        type: \"error\",\n        name: e.error?.name ?? \"Error\",\n        message: e.message,\n        detail: { filename: e.filename, line: e.lineno, col: e.colno },\n        timestamp: Date.now(),\n      });\n    const onRejection = (e: PromiseRejectionEvent) =>\n      dispatch({\n        type: \"unhandled-rejection\",\n        name: \"UnhandledRejection\",\n        message: String(e.reason),\n        timestamp: Date.now(),\n      });\n    window.addEventListener(\"error\", onError);\n    window.addEventListener(\"unhandledrejection\", onRejection);\n    teardowns.push(() => window.removeEventListener(\"error\", onError));\n    teardowns.push(() =>\n      window.removeEventListener(\"unhandledrejection\", onRejection),\n    );\n  }\n\n  if (captureWebVitals && typeof PerformanceObserver === \"function\") {\n    let clsValue = 0;\n    const observe = (\n      type: string,\n      cb: (entries: PerformanceEntryList) => void,\n    ) => {\n      try {\n        const obs = new PerformanceObserver((list) => cb(list.getEntries()));\n        obs.observe({ type, buffered: true });\n        teardowns.push(() => obs.disconnect());\n      } catch {\n        // Unsupported entry type in this browser — skip silently.\n      }\n    };\n\n    observe(\"largest-contentful-paint\", (entries) => {\n      const last = entries.at(-1);\n      if (last) {\n        dispatch({\n          type: \"web-vital\",\n          name: \"LCP\",\n          value: Math.round(last.startTime),\n          timestamp: Date.now(),\n        });\n      }\n    });\n\n    observe(\"layout-shift\", (entries) => {\n      for (const entry of entries as LayoutShiftEntry[]) {\n        if (!entry.hadRecentInput) {\n          clsValue += entry.value;\n        }\n      }\n      dispatch({\n        type: \"web-vital\",\n        name: \"CLS\",\n        value: Number(clsValue.toFixed(4)),\n        timestamp: Date.now(),\n      });\n    });\n\n    // FID (First Input Delay): processingStart − startTime of the first\n    // input. This is FID, NOT INP — INP needs the full interaction-latency\n    // model from the web-vitals library, which this dependency-free module\n    // deliberately doesn't pull in. Reach for `web-vitals` if you need INP.\n    observe(\"first-input\", (entries) => {\n      const first = entries[0] as FirstInputEntry | undefined;\n      if (first) {\n        dispatch({\n          type: \"web-vital\",\n          name: \"FID\",\n          value: Math.round(first.processingStart - first.startTime),\n          timestamp: Date.now(),\n        });\n      }\n    });\n  }\n\n  return () => {\n    for (const t of teardowns) {\n      t();\n    }\n    started = false;\n  };\n}\n\n/** Best-effort beacon of one event. Never throws into the caller. */\nfunction exportEvent(\n  endpoint: string,\n  serviceName: string,\n  event: TelemetryEvent,\n): void {\n  try {\n    const body = JSON.stringify({ service: serviceName, ...event });\n    if (typeof navigator !== \"undefined\" && navigator.sendBeacon) {\n      navigator.sendBeacon(endpoint, body);\n    } else {\n      void fetch(endpoint, {\n        method: \"POST\",\n        body,\n        keepalive: true,\n        headers: { \"Content-Type\": \"application/json\" },\n      }).catch(() => {});\n    }\n  } catch {\n    // Telemetry must never break the app.\n  }\n}\n"]}
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Browser telemetry: the HyperDX browser SDK, initialised the forge way.\n//\n// Captures errors (uncaught, unhandled rejections, boundary-caught), console\n// output, fetch/XHR spans, document load, long tasks and web vitals, and\n// ships them to ClickStack through a SAME-ORIGIN `/_otel` route.\n//\n// ── Why HyperDX REPLACES the old OTel web wiring, not joins it ───────────\n//\n// @hyperdx/browser wraps @hyperdx/otel-web, which builds its own\n// WebTracerProvider and calls provider.register() — the global tracer\n// provider, context manager and propagator. A second registration (the old\n// `./otel` subpath did exactly that) is rejected by @opentelemetry/api with a\n// \"duplicate registration\" diagnostic and silently loses: whichever ran\n// second would simply never see a span. Two tracer providers cannot coexist\n// in one page, so there is one, and it is HyperDX's. `./otel` and its eight\n// @opentelemetry/* SDK peer dependencies are gone.\n//\n// traceparent on RPCs is unaffected. traceInterceptor (trace.ts) injects the\n// active span's context into every Connect call, or synthesises a valid\n// traceparent when none is active — with no SDK at all. With the SDK running,\n// the fetch span HyperDX opens for the call carries the same trace id, and\n// `apiOrigins` below makes that hold for a cross-origin API too (which is\n// every dev loop: the API binds its own port).\n//\n// ── The browser holds no secret ──────────────────────────────────────────\n//\n// `url` is `${location.origin}/_otel`. The browser talks only to its own\n// origin; a dev-server proxy (next.config.ts rewrites / Vite server.proxy) or\n// the deployment's ingress forwards `/_otel/v1/{traces,logs}` to the OTLP/HTTP\n// port of a collector, and that hop — never the bundle — owns credentials.\n//\n// The SDK nevertheless wants an `apiKey` and sends it as an `authorization`\n// header. We pass PLACEHOLDER_API_KEY, a constant that grants nothing and is\n// public by construction. A collector that enforces ingestion auth (ClickStack\n// `collectorAuthenticationEnforced`) rejects it with 401, so the proxy in\n// front of such a collector must strip the header or replace it with the real\n// key. The local ClickStack collector does not enforce, and ignores it.\n//\n// ── Replay: shipped, off, masked ─────────────────────────────────────────\n//\n// The SDK bundles an rrweb recorder. It is DISABLED unless `replay: true`.\n// When enabled, masking is forced on — every input and all text — because a\n// replay records the DOM, which for most apps is the most sensitive data they\n// have. There is deliberately no option to turn masking off while replay is\n// on; an app that needs unmasked replay passes its own SDK options.\n//\n// ── Loading ──────────────────────────────────────────────────────────────\n//\n// The SDK is ~600 KB minified (rrweb and the OTel web stack are bundled in\n// it), so it is imported lazily: bundlers split it into its own chunk that\n// loads after the app is interactive and costs the first paint nothing.\n// initBrowserTelemetry is therefore async and idempotent — every caller gets\n// the same promise, which is what survives React StrictMode's double mount and\n// Fast Refresh. It is a no-op without a DOM (SSR, prerender) and without an\n// endpoint, and it never throws.\nimport { trace } from \"@opentelemetry/api\";\n\nimport { setExceptionReporter } from \"./error-reporter.js\";\n\n/** Where the browser ships telemetry: this origin's `/_otel`. */\nexport const DEFAULT_INGEST_PATH = \"/_otel\";\n\n/**\n * The apiKey handed to the SDK. Public by construction: it identifies\n * nothing and authorises nothing. See the header — the proxy or collector\n * owns the real credential.\n */\nexport const PLACEHOLDER_API_KEY = \"forge-browser-public\";\n\nexport interface BrowserTelemetryConfig {\n  /** `service.name` on everything this page emits. */\n  serviceName: string;\n  /** `service.version`. Omit for none. */\n  serviceVersion?: string;\n  /**\n   * The forge environment name. Emitted as BOTH `deployment.environment.name`\n   * (current semconv) and `deployment.environment` (the legacy key HyperDX's\n   * default sources still key on).\n   */\n  environment?: string;\n  /** `service.namespace`, conventionally the project name. */\n  serviceNamespace?: string;\n  /**\n   * Ingest base: a path on this origin (`/_otel`) or, as an escape hatch, an\n   * absolute URL. Unset, empty, or `off` disables telemetry — the app runs\n   * untraced rather than throwing, which is what makes it safe to call\n   * unconditionally from the app shell.\n   */\n  endpoint?: string;\n  /**\n   * Origins (or URLs — only the origin is used) of the app's own backend.\n   * Requests to them always get a `traceparent` from the SDK's fetch/XHR\n   * spans. This page's own origin is always included.\n   */\n  apiOrigins?: Array<string | undefined>;\n  /** Mirror console.* into telemetry. Default true. */\n  consoleCapture?: boolean;\n  /**\n   * Capture full request/response headers AND BODIES on fetch/XHR spans.\n   * Default false, and it should stay false: bodies are user data.\n   */\n  advancedNetworkCapture?: boolean;\n  /** Session replay (rrweb). Default false. When true, all text and inputs are masked. */\n  replay?: boolean;\n  /** Verbose SDK diagnostics to the console. Default false. */\n  debug?: boolean;\n}\n\n/** The slice of the SDK this module calls. Typed here, not imported, so the module loads without it. */\ninterface HyperDXClient {\n  init(config: Record<string, unknown>): void;\n  recordException(error: unknown, attributes?: Record<string, unknown>): void;\n}\n\nlet started: Promise<boolean> | null = null;\n\n/**\n * initBrowserTelemetry starts the HyperDX browser SDK once per page load and\n * resolves to whether it is running. See the module header for the contract.\n */\nexport function initBrowserTelemetry(\n  config: BrowserTelemetryConfig,\n): Promise<boolean> {\n  if (typeof window === \"undefined\") {\n    return Promise.resolve(false);\n  }\n  if (started) {\n    return started;\n  }\n  const ingest = resolveIngestUrl(config.endpoint, window.location.origin);\n  if (!ingest) {\n    return Promise.resolve(false);\n  }\n  started = start(config, ingest);\n  return started;\n}\n\nasync function start(\n  config: BrowserTelemetryConfig,\n  ingest: string,\n): Promise<boolean> {\n  try {\n    const hdx = resolveClient(await import(\"@hyperdx/browser\"));\n    if (!hdx) {\n      return false;\n    }\n    hdx.init(buildSdkOptions(config, ingest, window.location.origin));\n    tapSdkInputs();\n    setExceptionReporter((error, attributes) => {\n      if (alreadyRecorded(error)) {\n        return;\n      }\n      hdx.recordException(error, attributes);\n    });\n    return true;\n  } catch (err) {\n    // Blocked chunk, ad-blocker, SDK throw: telemetry must never break the app.\n    console.debug(\"[telemetry] disabled:\", err);\n    return false;\n  }\n}\n\n// ── One failure, one record ──────────────────────────────────────────────\n//\n// The SDK records an Error that reaches window \"error\", window\n// \"unhandledrejection\", or console.error. React (18 and 19) console.errors an\n// error a boundary catches BEFORE it calls componentDidCatch, and Next\n// dispatches an uncaught render error to window \"error\" — so by the time\n// reportException runs, the SDK has usually recorded that very error already.\n// Recording it again would count one failure twice, and the issue layer\n// (which groups by fingerprint) would report two.\n//\n// So the taps below remember which Error OBJECTS the SDK was shown, and the\n// installed recorder skips those. Whatever the SDK did not see — a custom\n// onCaughtError that silences React's logging, an error rethrown as a new\n// object — is still recorded. The console tap is installed after the SDK's own\n// wrapper, so it sits outermost and only observes; every call is forwarded\n// untouched.\n//\n// The cost is the React component stack: the SDK's record of a boundary-caught\n// error comes from console.error(error), which carries the error and its\n// stack but not React's componentStack, and attributes passed to a skipped\n// reportException are dropped with it.\nconst seenBySdk = new WeakSet<object>();\nlet tapped = false;\n\nfunction noteSeen(value: unknown): void {\n  if (typeof value === \"object\" && value !== null) {\n    seenBySdk.add(value);\n  }\n}\n\nfunction tapSdkInputs(): void {\n  if (tapped) {\n    return;\n  }\n  tapped = true;\n  const wrapped = console.error;\n  console.error = function (this: unknown, ...args: unknown[]) {\n    for (const arg of args) {\n      if (arg instanceof Error) {\n        noteSeen(arg);\n      }\n    }\n    return wrapped.apply(this, args);\n  };\n  window.addEventListener(\"error\", (e) => noteSeen(e.error), true);\n  window.addEventListener(\n    \"unhandledrejection\",\n    (e) => noteSeen(e.reason),\n    true,\n  );\n}\n\nfunction alreadyRecorded(error: unknown): boolean {\n  return typeof error === \"object\" && error !== null && seenBySdk.has(error);\n}\n\n/**\n * The options passed to HyperDX.init. Exported for tests and for apps that\n * want to see exactly what is configured — it is pure.\n */\nexport function buildSdkOptions(\n  config: BrowserTelemetryConfig,\n  ingestUrl: string,\n  pageOrigin: string,\n): Record<string, unknown> {\n  const replay = config.replay === true;\n  const resourceAttributes: Record<string, string> = {};\n  if (config.serviceVersion) {\n    resourceAttributes[\"service.version\"] = config.serviceVersion;\n  }\n  if (config.serviceNamespace) {\n    resourceAttributes[\"service.namespace\"] = config.serviceNamespace;\n  }\n  if (config.environment) {\n    resourceAttributes[\"deployment.environment.name\"] = config.environment;\n    resourceAttributes[\"deployment.environment\"] = config.environment;\n  }\n\n  const options: Record<string, unknown> = {\n    apiKey: PLACEHOLDER_API_KEY,\n    service: config.serviceName,\n    url: ingestUrl,\n    tracePropagationTargets: propagationTargets(pageOrigin, config.apiOrigins),\n    // The SDK would otherwise trace its own exports, and it must never\n    // observe the route it ships through.\n    ignoreUrls: [new RegExp(`^${escapeRegExp(ingestUrl)}`)],\n    consoleCapture: config.consoleCapture ?? true,\n    advancedNetworkCapture: config.advancedNetworkCapture ?? false,\n    // Polls for window.Intercom on a timer; nothing here uses Intercom.\n    disableIntercom: true,\n    disableReplay: !replay,\n    otelResourceAttributes: resourceAttributes,\n    debug: config.debug ?? false,\n  };\n  if (replay) {\n    // The SDK's own default masks inputs but NOT text; text is where chat\n    // content and records live. Force both.\n    options.maskAllInputs = true;\n    options.maskAllText = true;\n    options.recordCanvas = false;\n  }\n  return options;\n}\n\n/**\n * resolveIngestUrl turns the configured endpoint into the absolute URL the SDK\n * is given, or null when telemetry is off. A path resolves against the page\n * origin, so the default is same-origin by construction.\n */\nexport function resolveIngestUrl(\n  endpoint: string | undefined,\n  pageOrigin: string,\n): string | null {\n  const value = (endpoint ?? \"\").trim();\n  if (value === \"\" || value.toLowerCase() === \"off\") {\n    return null;\n  }\n  try {\n    return new URL(value, pageOrigin).toString().replace(/\\/+$/, \"\");\n  } catch {\n    return null;\n  }\n}\n\nfunction propagationTargets(\n  pageOrigin: string,\n  apiOrigins: Array<string | undefined> = [],\n): RegExp[] {\n  const origins = new Set<string>([pageOrigin]);\n  for (const raw of apiOrigins) {\n    if (!raw) {\n      continue;\n    }\n    try {\n      origins.add(new URL(raw, pageOrigin).origin);\n    } catch {\n      // An unparsable origin is not a target.\n    }\n  }\n  return [...origins].map((o) => new RegExp(`^${escapeRegExp(o)}(?:[/?#]|$)`));\n}\n\nfunction escapeRegExp(s: string): string {\n  return s.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n\n// @hyperdx/browser is a UMD/CJS bundle whose module.exports IS the client, and\n// its methods use `this`. A bundler hands back a module NAMESPACE that exposes\n// both the client's members at the top level (as read-only getters) and the\n// client itself as `default`. Calling init on the namespace binds `this` to that\n// frozen object and the SDK throws on its first property write, which disabled\n// telemetry silently. So descend to the deepest `default` that is still a\n// client, the real instance, and never settle for the namespace in front of it.\nfunction resolveClient(mod: unknown): HyperDXClient | null {\n  let cur: unknown = mod;\n  for (let depth = 0; depth < 4; depth++) {\n    const next = peek(cur, \"default\");\n    if (!isClient(next)) {\n      break;\n    }\n    cur = next;\n  }\n  return isClient(cur) ? cur : null;\n}\n\nfunction isClient(v: unknown): v is HyperDXClient {\n  return (\n    typeof peek(v, \"init\") === \"function\" &&\n    typeof peek(v, \"recordException\") === \"function\"\n  );\n}\n\n// A module namespace object may throw on an absent key (strict ESM\n// interop shims and test doubles do), and \"absent\" is an answer here.\nfunction peek(obj: unknown, key: string): unknown {\n  try {\n    return (obj as Record<string, unknown>)[key];\n  } catch {\n    return undefined;\n  }\n}\n\n/** The tracer to open manual spans on. Resolves HyperDX's provider once it is running. */\nexport function getTracer(name = \"default\") {\n  return trace.getTracer(name);\n}\n\nexport { context, propagation, trace } from \"@opentelemetry/api\";\n"]}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@reliantlabs/forge-web-runtime",
-  "version": "0.3.2",
-  "description": "The forge frontend runtime: Connect interceptor stack, session, error boundary, toast queue, <Resource> container, W3C trace propagation and client RUM. The web twin of forge/pkg.",
-  "license": "BUSL-1.1",
+  "version": "0.4.1",
+  "description": "The forge frontend runtime: Connect interceptor stack, session, error boundary, toast queue, <Resource> container, W3C trace propagation and the HyperDX browser SDK wiring (errors, console, network, traces; replay off by default). The web twin of forge/pkg.",
+  "license": "Apache-2.0",
   "//repository note": "REQUIRED for `npm publish --provenance`, not decoration. npm cross-checks this against the repository in the signed provenance statement and rejects the publish with a 422 if they disagree — an absent field reads as \"\" and fails that comparison. `directory` names the subdirectory this package lives in, so the provenance points at the real source. Omitting this is what made the first 0.3.1 publish fail AFTER the tarball had been signed and written to the sigstore transparency log.",
   "repository": {
     "type": "git",
@@ -22,7 +22,8 @@
   "files": [
     "dist",
     "interceptors",
-    "README.md"
+    "README.md",
+    "NOTICE"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -39,14 +40,14 @@
       "types": "./dist/mock-transport.d.ts",
       "default": "./dist/mock-transport.js"
     },
-    "./otel": {
-      "types": "./dist/otel.d.ts",
-      "default": "./dist/otel.js"
-    },
     "./service-hooks": {
       "types": "./dist/service-hooks.d.ts",
       "default": "./dist/service-hooks.js"
     },
+    "./telemetry": {
+      "types": "./dist/telemetry.d.ts",
+      "default": "./dist/telemetry.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -57,19 +58,12 @@
     "pretest": "node scripts/build.mjs",
     "test": "vitest run"
   },
-  "// peerDependencies note": "@opentelemetry/api is REQUIRED (trace.ts propagates traceparent on every RPC — always on, no collector). The eight SDK packages below it are OPTIONAL: they are imported only by the './otel' subpath, which only the Next.js scaffold reaches. A Vite-SPA or React-Native frontend installs @opentelemetry/api alone and imports the barrel, and must not be told it is missing dependencies it will never resolve.",
+  "// peerDependencies note": "@opentelemetry/api is REQUIRED (trace.ts propagates traceparent on every RPC — always on, no collector). @hyperdx/browser is OPTIONAL and exact-pinned: it is imported only (and lazily) by the './telemetry' subpath, which the Next.js and Vite scaffolds reach. It carries the whole OpenTelemetry web SDK and the rrweb recorder as its own dependencies, so a frontend that never imports './telemetry' (React Native) installs none of it and is not told it is missing a package it will never resolve.",
   "peerDependencies": {
     "@bufbuild/protobuf": "^2.5.0",
     "@connectrpc/connect": "^2.0.0",
+    "@hyperdx/browser": "0.26.0",
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/auto-instrumentations-web": "^0.67.0",
-    "@opentelemetry/core": "^2.8.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
-    "@opentelemetry/instrumentation": "^0.222.0",
-    "@opentelemetry/resources": "^2.8.0",
-    "@opentelemetry/sdk-trace-base": "^2.8.0",
-    "@opentelemetry/sdk-trace-web": "^2.8.0",
-    "@opentelemetry/semantic-conventions": "^1.28.0",
     "@tanstack/react-query": "^5.59.0",
     "react": "^18.3.0 || ^19.0.0"
   },
@@ -77,48 +71,22 @@
     "@tanstack/react-query": {
       "optional": true
     },
-    "@opentelemetry/auto-instrumentations-web": {
-      "optional": true
-    },
-    "@opentelemetry/core": {
-      "optional": true
-    },
-    "@opentelemetry/exporter-trace-otlp-http": {
-      "optional": true
-    },
-    "@opentelemetry/instrumentation": {
-      "optional": true
-    },
-    "@opentelemetry/resources": {
-      "optional": true
-    },
-    "@opentelemetry/sdk-trace-base": {
-      "optional": true
-    },
-    "@opentelemetry/sdk-trace-web": {
-      "optional": true
-    },
-    "@opentelemetry/semantic-conventions": {
+    "@hyperdx/browser": {
       "optional": true
     }
   },
   "devDependencies": {
     "@bufbuild/protobuf": "^2.5.0",
     "@connectrpc/connect": "^2.0.0",
+    "@hyperdx/browser": "0.26.0",
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/auto-instrumentations-web": "^0.67.0",
-    "@opentelemetry/core": "^2.8.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
-    "@opentelemetry/instrumentation": "^0.222.0",
-    "@opentelemetry/resources": "^2.8.0",
-    "@opentelemetry/sdk-trace-base": "^2.8.0",
-    "@opentelemetry/sdk-trace-web": "^2.8.0",
-    "@opentelemetry/semantic-conventions": "^1.28.0",
     "@tanstack/react-query": "^5.59.0",
     "@types/node": "^22.14.0",
     "@types/react": "^19.1.0",
     "@types/react-18": "npm:@types/react@~18.3.0",
+    "@types/react-dom": "^19.3.0",
     "react": "^19.1.0",
+    "react-dom": "^19.3.0",
     "typescript": "^5.8.0",
     "vitest": "^4.1.11"
   },

package/dist/otel.d.ts

@@ -1,31 +0,0 @@
-import { context, propagation, trace } from "@opentelemetry/api";
-export interface BrowserTracingConfig {
-    /**
-     * Collector base URL. Spans are POSTed to `${endpoint}/v1/traces`. Unset or
-     * empty is a no-op — the app runs untraced rather than throwing, which is
-     * what makes this safe to call unconditionally from the app shell.
-     */
-    endpoint?: string;
-    /** `service.name` on every span. */
-    serviceName: string;
-    /** `service.version` on every span. Defaults to "0.0.0". */
-    serviceVersion?: string;
-}
-/**
- * initBrowserTracing registers the browser tracer provider and the fetch /
- * XHR / document-load auto-instrumentations.
- *
- * No-ops without an `endpoint` (nothing to export to) and without a DOM
- * (SSR / prerender). Idempotent: a second call while a provider is already
- * registered returns without double-registering, which is what survives
- * React StrictMode's double-mount and Fast Refresh.
- *
- * The env vars that carry the endpoint stay in APPLICATION code
- * (`NEXT_PUBLIC_OTEL_ENDPOINT` and friends) — a bundler replaces those
- * literals at build time, and it can only do that where they are written
- * out verbatim.
- */
-export declare function initBrowserTracing(config: BrowserTracingConfig): void;
-/** The tracer to open manual spans on. */
-export declare function getTracer(name?: string): import("@opentelemetry/api").Tracer;
-export { context, propagation, trace };