@tetrascience-npm/tetrascience-react-ui 1.0.0-beta.135.1 → 1.0.0-beta.136.1

package/dist/telemetry/context.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("react"),t=e.createContext(null);exports.TelemetryContext=t;
+//# sourceMappingURL=context.cjs.map

package/dist/telemetry/context.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.cjs","sources":["../../src/telemetry/context.ts"],"sourcesContent":["import {createContext} from \"react\";\n\nimport type {Telemetry} from \"@tetrascience-npm/request/telemetry\";\n\n/**\n * `null` outside a {@link TelemetryProvider} — consumers no-op rather than\n * throw (telemetry never breaks the app; see `use-tetra-events.ts`).\n */\nexport const TelemetryContext = createContext<Telemetry | null>(null);\n"],"names":["TelemetryContext","createContext"],"mappings":"yGAQaA,EAAmBC,EAAAA,cAAgC,IAAI"}

package/dist/telemetry/context.d.ts

@@ -0,0 +1,6 @@
+import { Telemetry } from '@tetrascience-npm/request/telemetry';
+/**
+ * `null` outside a {@link TelemetryProvider} — consumers no-op rather than
+ * throw (telemetry never breaks the app; see `use-tetra-events.ts`).
+ */
+export declare const TelemetryContext: import('react').Context<Telemetry | null>;

package/dist/telemetry/context.js

@@ -0,0 +1,6 @@
+import { createContext as t } from "react";
+const o = t(null);
+export {
+  o as TelemetryContext
+};
+//# sourceMappingURL=context.js.map

package/dist/telemetry/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sources":["../../src/telemetry/context.ts"],"sourcesContent":["import {createContext} from \"react\";\n\nimport type {Telemetry} from \"@tetrascience-npm/request/telemetry\";\n\n/**\n * `null` outside a {@link TelemetryProvider} — consumers no-op rather than\n * throw (telemetry never breaks the app; see `use-tetra-events.ts`).\n */\nexport const TelemetryContext = createContext<Telemetry | null>(null);\n"],"names":["TelemetryContext","createContext"],"mappings":";AAQO,MAAMA,IAAmBC,EAAgC,IAAI;"}

package/dist/telemetry/error-boundary.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("react"),s=require("./context.cjs"),r=require("./events.cjs");class n extends o.Component{static contextType=s.TelemetryContext;state={error:null};static getDerivedStateFromError(t){return{error:t}}componentDidCatch(t,e){this.context?.trackError(t,{name:this.props.eventName??r.TelemetryEvent.ReactError,attributes:{...this.props.attributes,"error.source":"react","react.component_stack":(e.componentStack??"").slice(0,r.MAX_COMPONENT_STACK_LENGTH)}}),this.props.onError?.(t,e)}reset=()=>{this.setState({error:null})};render(){const{error:t}=this.state;if(!t)return this.props.children;const{fallback:e}=this.props;return typeof e=="function"?e(t,this.reset):e??null}}exports.TSErrorBoundary=n;
+//# sourceMappingURL=error-boundary.cjs.map

package/dist/telemetry/error-boundary.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-boundary.cjs","sources":["../../src/telemetry/error-boundary.tsx"],"sourcesContent":["import {Component, type ContextType, type ErrorInfo, type ReactNode} from \"react\";\n\nimport {TelemetryContext} from \"./context\";\nimport {MAX_COMPONENT_STACK_LENGTH, TelemetryEvent} from \"./events\";\n\n/** Props for {@link TSErrorBoundary}. */\nexport interface TSErrorBoundaryProps {\n\tchildren?: ReactNode;\n\t/**\n\t * Rendered instead of the children once a render error is caught. A\n\t * function receives the error and a `reset` callback for retry UI.\n\t */\n\tfallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);\n\t/** Event name override. Default: `App:Error:React`. */\n\teventName?: string;\n\t/** Extra attributes merged into the emitted event. */\n\tattributes?: Record<string, unknown>;\n\t/** Escape hatch for app-side handling (logging, resetting state). */\n\tonError?: (error: Error, info: ErrorInfo) => void;\n}\n\ninterface State {\n\terror: Error | null;\n}\n\n/**\n * React error boundary that records render errors as a stable-named product\n * event with the component stack attached, then renders `fallback`.\n *\n * Boundaries only catch errors thrown during render/lifecycle. Async\n * callbacks and promise rejections need {@link installGlobalErrorHandlers}.\n * The exception message is truncated by the core emitter; the component stack\n * is truncated here.\n */\nexport class TSErrorBoundary extends Component<TSErrorBoundaryProps, State> {\n\tstatic contextType = TelemetryContext;\n\tdeclare context: ContextType<typeof TelemetryContext>;\n\n\tstate: State = {error: null};\n\n\tstatic getDerivedStateFromError(error: Error): State {\n\t\treturn {error};\n\t}\n\n\tcomponentDidCatch(error: Error, info: ErrorInfo): void {\n\t\tthis.context?.trackError(error, {\n\t\t\tname: this.props.eventName ?? TelemetryEvent.ReactError,\n\t\t\tattributes: {\n\t\t\t\t...this.props.attributes,\n\t\t\t\t\"error.source\": \"react\",\n\t\t\t\t\"react.component_stack\": (info.componentStack ?? \"\").slice(0, MAX_COMPONENT_STACK_LENGTH),\n\t\t\t},\n\t\t});\n\t\tthis.props.onError?.(error, info);\n\t}\n\n\tprivate readonly reset = (): void => {\n\t\tthis.setState({error: null});\n\t};\n\n\trender(): ReactNode {\n\t\tconst {error} = this.state;\n\t\tif (!error) return this.props.children;\n\t\tconst {fallback} = this.props;\n\t\treturn typeof fallback === \"function\" ? fallback(error, this.reset) : (fallback ?? null);\n\t}\n}\n"],"names":["TSErrorBoundary","Component","TelemetryContext","error","info","TelemetryEvent","MAX_COMPONENT_STACK_LENGTH","fallback"],"mappings":"8JAkCO,MAAMA,UAAwBC,EAAAA,SAAuC,CAC3E,OAAO,YAAcC,EAAAA,iBAGrB,MAAe,CAAC,MAAO,IAAA,EAEvB,OAAO,yBAAyBC,EAAqB,CACpD,MAAO,CAAC,MAAAA,CAAA,CACT,CAEA,kBAAkBA,EAAcC,EAAuB,CACtD,KAAK,SAAS,WAAWD,EAAO,CAC/B,KAAM,KAAK,MAAM,WAAaE,EAAAA,eAAe,WAC7C,WAAY,CACX,GAAG,KAAK,MAAM,WACd,eAAgB,QAChB,yBAA0BD,EAAK,gBAAkB,IAAI,MAAM,EAAGE,EAAAA,0BAA0B,CAAA,CACzF,CACA,EACD,KAAK,MAAM,UAAUH,EAAOC,CAAI,CACjC,CAEiB,MAAQ,IAAY,CACpC,KAAK,SAAS,CAAC,MAAO,IAAA,CAAK,CAC5B,EAEA,QAAoB,CACnB,KAAM,CAAC,MAAAD,GAAS,KAAK,MACrB,GAAI,CAACA,EAAO,OAAO,KAAK,MAAM,SAC9B,KAAM,CAAC,SAAAI,GAAY,KAAK,MACxB,OAAO,OAAOA,GAAa,WAAaA,EAASJ,EAAO,KAAK,KAAK,EAAKI,GAAY,IACpF,CACD"}

package/dist/telemetry/error-boundary.d.ts

@@ -0,0 +1,39 @@
+import { Component, ContextType, ErrorInfo, ReactNode } from 'react';
+import { TelemetryContext } from './context';
+/** Props for {@link TSErrorBoundary}. */
+export interface TSErrorBoundaryProps {
+    children?: ReactNode;
+    /**
+     * Rendered instead of the children once a render error is caught. A
+     * function receives the error and a `reset` callback for retry UI.
+     */
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /** Event name override. Default: `App:Error:React`. */
+    eventName?: string;
+    /** Extra attributes merged into the emitted event. */
+    attributes?: Record<string, unknown>;
+    /** Escape hatch for app-side handling (logging, resetting state). */
+    onError?: (error: Error, info: ErrorInfo) => void;
+}
+interface State {
+    error: Error | null;
+}
+/**
+ * React error boundary that records render errors as a stable-named product
+ * event with the component stack attached, then renders `fallback`.
+ *
+ * Boundaries only catch errors thrown during render/lifecycle. Async
+ * callbacks and promise rejections need {@link installGlobalErrorHandlers}.
+ * The exception message is truncated by the core emitter; the component stack
+ * is truncated here.
+ */
+export declare class TSErrorBoundary extends Component<TSErrorBoundaryProps, State> {
+    static contextType: import('react').Context<import('@tetrascience-npm/request/telemetry').Telemetry | null>;
+    context: ContextType<typeof TelemetryContext>;
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    private readonly reset;
+    render(): ReactNode;
+}
+export {};

package/dist/telemetry/error-boundary.js

@@ -0,0 +1,33 @@
+import { Component as e } from "react";
+import { TelemetryContext as o } from "./context.js";
+import { TelemetryEvent as s, MAX_COMPONENT_STACK_LENGTH as n } from "./events.js";
+class m extends e {
+  static contextType = o;
+  state = { error: null };
+  static getDerivedStateFromError(t) {
+    return { error: t };
+  }
+  componentDidCatch(t, r) {
+    this.context?.trackError(t, {
+      name: this.props.eventName ?? s.ReactError,
+      attributes: {
+        ...this.props.attributes,
+        "error.source": "react",
+        "react.component_stack": (r.componentStack ?? "").slice(0, n)
+      }
+    }), this.props.onError?.(t, r);
+  }
+  reset = () => {
+    this.setState({ error: null });
+  };
+  render() {
+    const { error: t } = this.state;
+    if (!t) return this.props.children;
+    const { fallback: r } = this.props;
+    return typeof r == "function" ? r(t, this.reset) : r ?? null;
+  }
+}
+export {
+  m as TSErrorBoundary
+};
+//# sourceMappingURL=error-boundary.js.map

package/dist/telemetry/error-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-boundary.js","sources":["../../src/telemetry/error-boundary.tsx"],"sourcesContent":["import {Component, type ContextType, type ErrorInfo, type ReactNode} from \"react\";\n\nimport {TelemetryContext} from \"./context\";\nimport {MAX_COMPONENT_STACK_LENGTH, TelemetryEvent} from \"./events\";\n\n/** Props for {@link TSErrorBoundary}. */\nexport interface TSErrorBoundaryProps {\n\tchildren?: ReactNode;\n\t/**\n\t * Rendered instead of the children once a render error is caught. A\n\t * function receives the error and a `reset` callback for retry UI.\n\t */\n\tfallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);\n\t/** Event name override. Default: `App:Error:React`. */\n\teventName?: string;\n\t/** Extra attributes merged into the emitted event. */\n\tattributes?: Record<string, unknown>;\n\t/** Escape hatch for app-side handling (logging, resetting state). */\n\tonError?: (error: Error, info: ErrorInfo) => void;\n}\n\ninterface State {\n\terror: Error | null;\n}\n\n/**\n * React error boundary that records render errors as a stable-named product\n * event with the component stack attached, then renders `fallback`.\n *\n * Boundaries only catch errors thrown during render/lifecycle. Async\n * callbacks and promise rejections need {@link installGlobalErrorHandlers}.\n * The exception message is truncated by the core emitter; the component stack\n * is truncated here.\n */\nexport class TSErrorBoundary extends Component<TSErrorBoundaryProps, State> {\n\tstatic contextType = TelemetryContext;\n\tdeclare context: ContextType<typeof TelemetryContext>;\n\n\tstate: State = {error: null};\n\n\tstatic getDerivedStateFromError(error: Error): State {\n\t\treturn {error};\n\t}\n\n\tcomponentDidCatch(error: Error, info: ErrorInfo): void {\n\t\tthis.context?.trackError(error, {\n\t\t\tname: this.props.eventName ?? TelemetryEvent.ReactError,\n\t\t\tattributes: {\n\t\t\t\t...this.props.attributes,\n\t\t\t\t\"error.source\": \"react\",\n\t\t\t\t\"react.component_stack\": (info.componentStack ?? \"\").slice(0, MAX_COMPONENT_STACK_LENGTH),\n\t\t\t},\n\t\t});\n\t\tthis.props.onError?.(error, info);\n\t}\n\n\tprivate readonly reset = (): void => {\n\t\tthis.setState({error: null});\n\t};\n\n\trender(): ReactNode {\n\t\tconst {error} = this.state;\n\t\tif (!error) return this.props.children;\n\t\tconst {fallback} = this.props;\n\t\treturn typeof fallback === \"function\" ? fallback(error, this.reset) : (fallback ?? null);\n\t}\n}\n"],"names":["TSErrorBoundary","Component","TelemetryContext","error","info","TelemetryEvent","MAX_COMPONENT_STACK_LENGTH","fallback"],"mappings":";;;AAkCO,MAAMA,UAAwBC,EAAuC;AAAA,EAC3E,OAAO,cAAcC;AAAA,EAGrB,QAAe,EAAC,OAAO,KAAA;AAAA,EAEvB,OAAO,yBAAyBC,GAAqB;AACpD,WAAO,EAAC,OAAAA,EAAA;AAAA,EACT;AAAA,EAEA,kBAAkBA,GAAcC,GAAuB;AACtD,SAAK,SAAS,WAAWD,GAAO;AAAA,MAC/B,MAAM,KAAK,MAAM,aAAaE,EAAe;AAAA,MAC7C,YAAY;AAAA,QACX,GAAG,KAAK,MAAM;AAAA,QACd,gBAAgB;AAAA,QAChB,0BAA0BD,EAAK,kBAAkB,IAAI,MAAM,GAAGE,CAA0B;AAAA,MAAA;AAAA,IACzF,CACA,GACD,KAAK,MAAM,UAAUH,GAAOC,CAAI;AAAA,EACjC;AAAA,EAEiB,QAAQ,MAAY;AACpC,SAAK,SAAS,EAAC,OAAO,KAAA,CAAK;AAAA,EAC5B;AAAA,EAEA,SAAoB;AACnB,UAAM,EAAC,OAAAD,MAAS,KAAK;AACrB,QAAI,CAACA,EAAO,QAAO,KAAK,MAAM;AAC9B,UAAM,EAAC,UAAAI,MAAY,KAAK;AACxB,WAAO,OAAOA,KAAa,aAAaA,EAASJ,GAAO,KAAK,KAAK,IAAKI,KAAY;AAAA,EACpF;AACD;"}

package/dist/telemetry/events.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e={ReactError:"App:Error:React",WindowError:"App:Error:Window",UnhandledRejection:"App:Error:UnhandledRejection"},r=4e3;exports.MAX_COMPONENT_STACK_LENGTH=r;exports.TelemetryEvent=e;
+//# sourceMappingURL=events.cjs.map

package/dist/telemetry/events.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.cjs","sources":["../../src/telemetry/events.ts"],"sourcesContent":["/**\n * Stable event names emitted by the bindings themselves. Apps keep their own\n * `App[:Page][:Object]:Action` names for product events; these three exist so\n * error volume is queryable across every app without per-app naming drift.\n */\nexport const TelemetryEvent = {\n\t/** React render error caught by `TSErrorBoundary`. */\n\tReactError: \"App:Error:React\",\n\t/** Uncaught exception seen by `window.onerror`. */\n\tWindowError: \"App:Error:Window\",\n\t/** Promise rejection with no handler. */\n\tUnhandledRejection: \"App:Error:UnhandledRejection\",\n} as const;\n\n/** Max length of the React component stack attribute. */\nexport const MAX_COMPONENT_STACK_LENGTH = 4000;\n"],"names":["TelemetryEvent","MAX_COMPONENT_STACK_LENGTH"],"mappings":"gFAKO,MAAMA,EAAiB,CAE7B,WAAY,kBAEZ,YAAa,mBAEb,mBAAoB,8BACrB,EAGaC,EAA6B"}

package/dist/telemetry/events.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Stable event names emitted by the bindings themselves. Apps keep their own
+ * `App[:Page][:Object]:Action` names for product events; these three exist so
+ * error volume is queryable across every app without per-app naming drift.
+ */
+export declare const TelemetryEvent: {
+    /** React render error caught by `TSErrorBoundary`. */
+    readonly ReactError: "App:Error:React";
+    /** Uncaught exception seen by `window.onerror`. */
+    readonly WindowError: "App:Error:Window";
+    /** Promise rejection with no handler. */
+    readonly UnhandledRejection: "App:Error:UnhandledRejection";
+};
+/** Max length of the React component stack attribute. */
+export declare const MAX_COMPONENT_STACK_LENGTH = 4000;

package/dist/telemetry/events.js

@@ -0,0 +1,13 @@
+const r = {
+  /** React render error caught by `TSErrorBoundary`. */
+  ReactError: "App:Error:React",
+  /** Uncaught exception seen by `window.onerror`. */
+  WindowError: "App:Error:Window",
+  /** Promise rejection with no handler. */
+  UnhandledRejection: "App:Error:UnhandledRejection"
+}, e = 4e3;
+export {
+  e as MAX_COMPONENT_STACK_LENGTH,
+  r as TelemetryEvent
+};
+//# sourceMappingURL=events.js.map

package/dist/telemetry/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sources":["../../src/telemetry/events.ts"],"sourcesContent":["/**\n * Stable event names emitted by the bindings themselves. Apps keep their own\n * `App[:Page][:Object]:Action` names for product events; these three exist so\n * error volume is queryable across every app without per-app naming drift.\n */\nexport const TelemetryEvent = {\n\t/** React render error caught by `TSErrorBoundary`. */\n\tReactError: \"App:Error:React\",\n\t/** Uncaught exception seen by `window.onerror`. */\n\tWindowError: \"App:Error:Window\",\n\t/** Promise rejection with no handler. */\n\tUnhandledRejection: \"App:Error:UnhandledRejection\",\n} as const;\n\n/** Max length of the React component stack attribute. */\nexport const MAX_COMPONENT_STACK_LENGTH = 4000;\n"],"names":["TelemetryEvent","MAX_COMPONENT_STACK_LENGTH"],"mappings":"AAKO,MAAMA,IAAiB;AAAA;AAAA,EAE7B,YAAY;AAAA;AAAA,EAEZ,aAAa;AAAA;AAAA,EAEb,oBAAoB;AACrB,GAGaC,IAA6B;"}

package/dist/telemetry/facade.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("@tetrascience-npm/request/telemetry"),s={trackEvent(){},trackError(){},startSpan:()=>o.NOOP_SPAN,withSpan:(a,n)=>n(o.NOOP_SPAN),counter(){},gauge(){},histogram(){},upDownCounter(){},async flush(){},async shutdown(){}},u=50;function i(){let a,n=[];const c=t=>{n.length<u&&n.push(t)};return{trackEvent(t,e,r){a?a.trackEvent(t,e,r):c({kind:"event",name:t,attributes:e,body:r})},trackError(t,e){a?a.trackError(t,e):c({kind:"error",error:t,context:e})},startSpan(t,e){return a?a.startSpan(t,e):o.NOOP_SPAN},counter(t,e,r){a?.counter(t,e,r)},gauge(t,e,r){a?.gauge(t,e,r)},histogram(t,e,r){a?.histogram(t,e,r)},upDownCounter(t,e,r){a?.upDownCounter(t,e,r)},withSpan(t,e,r){return a?a.withSpan(t,e,r):e(o.NOOP_SPAN)},async flush(){await a?.flush()},async shutdown(){await a?.shutdown()},attach(t){a=t;const e=n;n=[];for(const r of e)r.kind==="event"?t.trackEvent(r.name,r.attributes,r.body):t.trackError(r.error,r.context)},detach(t){a===t&&(a=void 0)}}}exports.NOOP_TELEMETRY=s;exports.createTelemetryFacade=i;
+//# sourceMappingURL=facade.cjs.map

package/dist/telemetry/facade.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.cjs","sources":["../../src/telemetry/facade.ts"],"sourcesContent":["import {NOOP_SPAN} from \"@tetrascience-npm/request/telemetry\";\n\nimport type {TelemetryFacade} from \"./types\";\nimport type {Telemetry, TrackErrorContext} from \"@tetrascience-npm/request/telemetry\";\n\n/** A client that accepts and drops everything (`enabled={false}`, no provider). */\nexport const NOOP_TELEMETRY: Telemetry = {\n\ttrackEvent() {\n\t\t// disabled: nothing is recorded, nothing is buffered\n\t},\n\ttrackError() {\n\t\t// disabled: nothing is recorded, nothing is buffered\n\t},\n\tstartSpan: () => NOOP_SPAN,\n\t// Still RUNS the callback: withSpan wraps application work, so skipping it\n\t// when telemetry is off would make disabling telemetry change what the app\n\t// does. Only the measurement is dropped.\n\twithSpan: (_name, fn) => fn(NOOP_SPAN),\n\tcounter() {\n\t\t// disabled: nothing is recorded\n\t},\n\tgauge() {\n\t\t// disabled: nothing is recorded\n\t},\n\thistogram() {\n\t\t// disabled: nothing is recorded\n\t},\n\tupDownCounter() {\n\t\t// disabled: nothing is recorded\n\t},\n\tasync flush() {\n\t\t// nothing to flush\n\t},\n\tasync shutdown() {\n\t\t// nothing to tear down\n\t},\n};\n\n/** Records emitted before the provider's effect attaches a client. */\nconst MAX_PENDING = 50;\n\ntype Pending =\n\t| {kind: \"event\"; name: string; attributes?: Record<string, unknown>; body?: unknown}\n\t| {kind: \"error\"; error: unknown; context?: TrackErrorContext};\n\n/**\n * Stable context value that forwards to the currently attached client.\n *\n * The real client is built in an effect (so React StrictMode's mount →\n * unmount → mount cycle disposes it cleanly instead of leaving a shut-down\n * provider behind), but child effects run *before* the provider's effect —\n * so records emitted in that window are held here (bounded) and replayed on\n * attach. The buffer is drained exactly once, so a StrictMode re-attach\n * cannot re-emit it.\n */\nexport function createTelemetryFacade(): TelemetryFacade {\n\tlet target: Telemetry | undefined;\n\tlet pending: Pending[] = [];\n\n\tconst buffer = (record: Pending): void => {\n\t\tif (pending.length < MAX_PENDING) pending.push(record);\n\t};\n\n\treturn {\n\t\ttrackEvent(name, attributes, body) {\n\t\t\tif (target) target.trackEvent(name, attributes, body);\n\t\t\telse buffer({kind: \"event\", name, attributes, body});\n\t\t},\n\t\ttrackError(error, context) {\n\t\t\tif (target) target.trackError(error, context);\n\t\t\telse buffer({kind: \"error\", error, context});\n\t\t},\n\t\t// Spans are NOT buffered, unlike the two above. A span carries a live\n\t\t// start and end, so replaying one after attach would invent a duration\n\t\t// that never happened — worse than not recording it. Work that runs\n\t\t// before the provider's effect attaches a client is simply untraced.\n\t\tstartSpan(name, options) {\n\t\t\treturn target ? target.startSpan(name, options) : NOOP_SPAN;\n\t\t},\n\t\t// Metric recordings before attach are DROPPED, not buffered. A gauge is a\n\t\t// point-in-time reading and a histogram observation is timestamped by the\n\t\t// SDK on record, so replaying either after attach would date it to the\n\t\t// wrong moment. Events buffer because a product event is a fact that\n\t\t// happened, not a sample of a moving value.\n\t\tcounter(name, delta, attributes) {\n\t\t\ttarget?.counter(name, delta, attributes);\n\t\t},\n\t\tgauge(name, value, attributes) {\n\t\t\ttarget?.gauge(name, value, attributes);\n\t\t},\n\t\thistogram(name, value, attributes) {\n\t\t\ttarget?.histogram(name, value, attributes);\n\t\t},\n\t\tupDownCounter(name, delta, attributes) {\n\t\t\ttarget?.upDownCounter(name, delta, attributes);\n\t\t},\n\t\twithSpan(name, fn, options) {\n\t\t\treturn target ? target.withSpan(name, fn, options) : fn(NOOP_SPAN);\n\t\t},\n\t\tasync flush() {\n\t\t\tawait target?.flush();\n\t\t},\n\t\tasync shutdown() {\n\t\t\tawait target?.shutdown();\n\t\t},\n\t\tattach(client) {\n\t\t\ttarget = client;\n\t\t\tconst replay = pending;\n\t\t\tpending = [];\n\t\t\tfor (const record of replay) {\n\t\t\t\tif (record.kind === \"event\") client.trackEvent(record.name, record.attributes, record.body);\n\t\t\t\telse client.trackError(record.error, record.context);\n\t\t\t}\n\t\t},\n\t\tdetach(client) {\n\t\t\t// Guard against an out-of-order cleanup detaching a newer client.\n\t\t\tif (target === client) target = undefined;\n\t\t},\n\t};\n}\n"],"names":["NOOP_TELEMETRY","NOOP_SPAN","_name","fn","MAX_PENDING","createTelemetryFacade","target","pending","buffer","record","name","attributes","body","error","context","options","delta","value","client","replay"],"mappings":"uIAMaA,EAA4B,CACxC,YAAa,CAEb,EACA,YAAa,CAEb,EACA,UAAW,IAAMC,EAAAA,UAIjB,SAAU,CAACC,EAAOC,IAAOA,EAAGF,EAAAA,SAAS,EACrC,SAAU,CAEV,EACA,OAAQ,CAER,EACA,WAAY,CAEZ,EACA,eAAgB,CAEhB,EACA,MAAM,OAAQ,CAEd,EACA,MAAM,UAAW,CAEjB,CACD,EAGMG,EAAc,GAgBb,SAASC,GAAyC,CACxD,IAAIC,EACAC,EAAqB,CAAA,EAEzB,MAAMC,EAAUC,GAA0B,CACrCF,EAAQ,OAASH,GAAaG,EAAQ,KAAKE,CAAM,CACtD,EAEA,MAAO,CACN,WAAWC,EAAMC,EAAYC,EAAM,CAC9BN,EAAQA,EAAO,WAAWI,EAAMC,EAAYC,CAAI,IACxC,CAAC,KAAM,QAAS,KAAAF,EAAM,WAAAC,EAAY,KAAAC,EAAK,CACpD,EACA,WAAWC,EAAOC,EAAS,CACtBR,EAAQA,EAAO,WAAWO,EAAOC,CAAO,IAChC,CAAC,KAAM,QAAS,MAAAD,EAAO,QAAAC,EAAQ,CAC5C,EAKA,UAAUJ,EAAMK,EAAS,CACxB,OAAOT,EAASA,EAAO,UAAUI,EAAMK,CAAO,EAAId,EAAAA,SACnD,EAMA,QAAQS,EAAMM,EAAOL,EAAY,CAChCL,GAAQ,QAAQI,EAAMM,EAAOL,CAAU,CACxC,EACA,MAAMD,EAAMO,EAAON,EAAY,CAC9BL,GAAQ,MAAMI,EAAMO,EAAON,CAAU,CACtC,EACA,UAAUD,EAAMO,EAAON,EAAY,CAClCL,GAAQ,UAAUI,EAAMO,EAAON,CAAU,CAC1C,EACA,cAAcD,EAAMM,EAAOL,EAAY,CACtCL,GAAQ,cAAcI,EAAMM,EAAOL,CAAU,CAC9C,EACA,SAASD,EAAMP,EAAIY,EAAS,CAC3B,OAAOT,EAASA,EAAO,SAASI,EAAMP,EAAIY,CAAO,EAAIZ,EAAGF,WAAS,CAClE,EACA,MAAM,OAAQ,CACb,MAAMK,GAAQ,MAAA,CACf,EACA,MAAM,UAAW,CAChB,MAAMA,GAAQ,SAAA,CACf,EACA,OAAOY,EAAQ,CACdZ,EAASY,EACT,MAAMC,EAASZ,EACfA,EAAU,CAAA,EACV,UAAWE,KAAUU,EAChBV,EAAO,OAAS,QAASS,EAAO,WAAWT,EAAO,KAAMA,EAAO,WAAYA,EAAO,IAAI,EACrFS,EAAO,WAAWT,EAAO,MAAOA,EAAO,OAAO,CAErD,EACA,OAAOS,EAAQ,CAEVZ,IAAWY,IAAQZ,EAAS,OACjC,CAAA,CAEF"}

package/dist/telemetry/facade.d.ts

@@ -0,0 +1,15 @@
+import { TelemetryFacade } from './types';
+import { Telemetry } from '@tetrascience-npm/request/telemetry';
+/** A client that accepts and drops everything (`enabled={false}`, no provider). */
+export declare const NOOP_TELEMETRY: Telemetry;
+/**
+ * Stable context value that forwards to the currently attached client.
+ *
+ * The real client is built in an effect (so React StrictMode's mount →
+ * unmount → mount cycle disposes it cleanly instead of leaving a shut-down
+ * provider behind), but child effects run *before* the provider's effect —
+ * so records emitted in that window are held here (bounded) and replayed on
+ * attach. The buffer is drained exactly once, so a StrictMode re-attach
+ * cannot re-emit it.
+ */
+export declare function createTelemetryFacade(): TelemetryFacade;

package/dist/telemetry/facade.js

@@ -0,0 +1,86 @@
+import { NOOP_SPAN as o } from "@tetrascience-npm/request/telemetry";
+const i = {
+  trackEvent() {
+  },
+  trackError() {
+  },
+  startSpan: () => o,
+  // Still RUNS the callback: withSpan wraps application work, so skipping it
+  // when telemetry is off would make disabling telemetry change what the app
+  // does. Only the measurement is dropped.
+  withSpan: (n, a) => a(o),
+  counter() {
+  },
+  gauge() {
+  },
+  histogram() {
+  },
+  upDownCounter() {
+  },
+  async flush() {
+  },
+  async shutdown() {
+  }
+}, c = 50;
+function h() {
+  let n, a = [];
+  const s = (t) => {
+    a.length < c && a.push(t);
+  };
+  return {
+    trackEvent(t, r, e) {
+      n ? n.trackEvent(t, r, e) : s({ kind: "event", name: t, attributes: r, body: e });
+    },
+    trackError(t, r) {
+      n ? n.trackError(t, r) : s({ kind: "error", error: t, context: r });
+    },
+    // Spans are NOT buffered, unlike the two above. A span carries a live
+    // start and end, so replaying one after attach would invent a duration
+    // that never happened — worse than not recording it. Work that runs
+    // before the provider's effect attaches a client is simply untraced.
+    startSpan(t, r) {
+      return n ? n.startSpan(t, r) : o;
+    },
+    // Metric recordings before attach are DROPPED, not buffered. A gauge is a
+    // point-in-time reading and a histogram observation is timestamped by the
+    // SDK on record, so replaying either after attach would date it to the
+    // wrong moment. Events buffer because a product event is a fact that
+    // happened, not a sample of a moving value.
+    counter(t, r, e) {
+      n?.counter(t, r, e);
+    },
+    gauge(t, r, e) {
+      n?.gauge(t, r, e);
+    },
+    histogram(t, r, e) {
+      n?.histogram(t, r, e);
+    },
+    upDownCounter(t, r, e) {
+      n?.upDownCounter(t, r, e);
+    },
+    withSpan(t, r, e) {
+      return n ? n.withSpan(t, r, e) : r(o);
+    },
+    async flush() {
+      await n?.flush();
+    },
+    async shutdown() {
+      await n?.shutdown();
+    },
+    attach(t) {
+      n = t;
+      const r = a;
+      a = [];
+      for (const e of r)
+        e.kind === "event" ? t.trackEvent(e.name, e.attributes, e.body) : t.trackError(e.error, e.context);
+    },
+    detach(t) {
+      n === t && (n = void 0);
+    }
+  };
+}
+export {
+  i as NOOP_TELEMETRY,
+  h as createTelemetryFacade
+};
+//# sourceMappingURL=facade.js.map

package/dist/telemetry/facade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.js","sources":["../../src/telemetry/facade.ts"],"sourcesContent":["import {NOOP_SPAN} from \"@tetrascience-npm/request/telemetry\";\n\nimport type {TelemetryFacade} from \"./types\";\nimport type {Telemetry, TrackErrorContext} from \"@tetrascience-npm/request/telemetry\";\n\n/** A client that accepts and drops everything (`enabled={false}`, no provider). */\nexport const NOOP_TELEMETRY: Telemetry = {\n\ttrackEvent() {\n\t\t// disabled: nothing is recorded, nothing is buffered\n\t},\n\ttrackError() {\n\t\t// disabled: nothing is recorded, nothing is buffered\n\t},\n\tstartSpan: () => NOOP_SPAN,\n\t// Still RUNS the callback: withSpan wraps application work, so skipping it\n\t// when telemetry is off would make disabling telemetry change what the app\n\t// does. Only the measurement is dropped.\n\twithSpan: (_name, fn) => fn(NOOP_SPAN),\n\tcounter() {\n\t\t// disabled: nothing is recorded\n\t},\n\tgauge() {\n\t\t// disabled: nothing is recorded\n\t},\n\thistogram() {\n\t\t// disabled: nothing is recorded\n\t},\n\tupDownCounter() {\n\t\t// disabled: nothing is recorded\n\t},\n\tasync flush() {\n\t\t// nothing to flush\n\t},\n\tasync shutdown() {\n\t\t// nothing to tear down\n\t},\n};\n\n/** Records emitted before the provider's effect attaches a client. */\nconst MAX_PENDING = 50;\n\ntype Pending =\n\t| {kind: \"event\"; name: string; attributes?: Record<string, unknown>; body?: unknown}\n\t| {kind: \"error\"; error: unknown; context?: TrackErrorContext};\n\n/**\n * Stable context value that forwards to the currently attached client.\n *\n * The real client is built in an effect (so React StrictMode's mount →\n * unmount → mount cycle disposes it cleanly instead of leaving a shut-down\n * provider behind), but child effects run *before* the provider's effect —\n * so records emitted in that window are held here (bounded) and replayed on\n * attach. The buffer is drained exactly once, so a StrictMode re-attach\n * cannot re-emit it.\n */\nexport function createTelemetryFacade(): TelemetryFacade {\n\tlet target: Telemetry | undefined;\n\tlet pending: Pending[] = [];\n\n\tconst buffer = (record: Pending): void => {\n\t\tif (pending.length < MAX_PENDING) pending.push(record);\n\t};\n\n\treturn {\n\t\ttrackEvent(name, attributes, body) {\n\t\t\tif (target) target.trackEvent(name, attributes, body);\n\t\t\telse buffer({kind: \"event\", name, attributes, body});\n\t\t},\n\t\ttrackError(error, context) {\n\t\t\tif (target) target.trackError(error, context);\n\t\t\telse buffer({kind: \"error\", error, context});\n\t\t},\n\t\t// Spans are NOT buffered, unlike the two above. A span carries a live\n\t\t// start and end, so replaying one after attach would invent a duration\n\t\t// that never happened — worse than not recording it. Work that runs\n\t\t// before the provider's effect attaches a client is simply untraced.\n\t\tstartSpan(name, options) {\n\t\t\treturn target ? target.startSpan(name, options) : NOOP_SPAN;\n\t\t},\n\t\t// Metric recordings before attach are DROPPED, not buffered. A gauge is a\n\t\t// point-in-time reading and a histogram observation is timestamped by the\n\t\t// SDK on record, so replaying either after attach would date it to the\n\t\t// wrong moment. Events buffer because a product event is a fact that\n\t\t// happened, not a sample of a moving value.\n\t\tcounter(name, delta, attributes) {\n\t\t\ttarget?.counter(name, delta, attributes);\n\t\t},\n\t\tgauge(name, value, attributes) {\n\t\t\ttarget?.gauge(name, value, attributes);\n\t\t},\n\t\thistogram(name, value, attributes) {\n\t\t\ttarget?.histogram(name, value, attributes);\n\t\t},\n\t\tupDownCounter(name, delta, attributes) {\n\t\t\ttarget?.upDownCounter(name, delta, attributes);\n\t\t},\n\t\twithSpan(name, fn, options) {\n\t\t\treturn target ? target.withSpan(name, fn, options) : fn(NOOP_SPAN);\n\t\t},\n\t\tasync flush() {\n\t\t\tawait target?.flush();\n\t\t},\n\t\tasync shutdown() {\n\t\t\tawait target?.shutdown();\n\t\t},\n\t\tattach(client) {\n\t\t\ttarget = client;\n\t\t\tconst replay = pending;\n\t\t\tpending = [];\n\t\t\tfor (const record of replay) {\n\t\t\t\tif (record.kind === \"event\") client.trackEvent(record.name, record.attributes, record.body);\n\t\t\t\telse client.trackError(record.error, record.context);\n\t\t\t}\n\t\t},\n\t\tdetach(client) {\n\t\t\t// Guard against an out-of-order cleanup detaching a newer client.\n\t\t\tif (target === client) target = undefined;\n\t\t},\n\t};\n}\n"],"names":["NOOP_TELEMETRY","NOOP_SPAN","_name","fn","MAX_PENDING","createTelemetryFacade","target","pending","buffer","record","name","attributes","body","error","context","options","delta","value","client","replay"],"mappings":";AAMO,MAAMA,IAA4B;AAAA,EACxC,aAAa;AAAA,EAEb;AAAA,EACA,aAAa;AAAA,EAEb;AAAA,EACA,WAAW,MAAMC;AAAA;AAAA;AAAA;AAAA,EAIjB,UAAU,CAACC,GAAOC,MAAOA,EAAGF,CAAS;AAAA,EACrC,UAAU;AAAA,EAEV;AAAA,EACA,QAAQ;AAAA,EAER;AAAA,EACA,YAAY;AAAA,EAEZ;AAAA,EACA,gBAAgB;AAAA,EAEhB;AAAA,EACA,MAAM,QAAQ;AAAA,EAEd;AAAA,EACA,MAAM,WAAW;AAAA,EAEjB;AACD,GAGMG,IAAc;AAgBb,SAASC,IAAyC;AACxD,MAAIC,GACAC,IAAqB,CAAA;AAEzB,QAAMC,IAAS,CAACC,MAA0B;AACzC,IAAIF,EAAQ,SAASH,KAAaG,EAAQ,KAAKE,CAAM;AAAA,EACtD;AAEA,SAAO;AAAA,IACN,WAAWC,GAAMC,GAAYC,GAAM;AAClC,MAAIN,IAAQA,EAAO,WAAWI,GAAMC,GAAYC,CAAI,MACxC,EAAC,MAAM,SAAS,MAAAF,GAAM,YAAAC,GAAY,MAAAC,GAAK;AAAA,IACpD;AAAA,IACA,WAAWC,GAAOC,GAAS;AAC1B,MAAIR,IAAQA,EAAO,WAAWO,GAAOC,CAAO,MAChC,EAAC,MAAM,SAAS,OAAAD,GAAO,SAAAC,GAAQ;AAAA,IAC5C;AAAA;AAAA;AAAA;AAAA;AAAA,IAKA,UAAUJ,GAAMK,GAAS;AACxB,aAAOT,IAASA,EAAO,UAAUI,GAAMK,CAAO,IAAId;AAAA,IACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAMA,QAAQS,GAAMM,GAAOL,GAAY;AAChC,MAAAL,GAAQ,QAAQI,GAAMM,GAAOL,CAAU;AAAA,IACxC;AAAA,IACA,MAAMD,GAAMO,GAAON,GAAY;AAC9B,MAAAL,GAAQ,MAAMI,GAAMO,GAAON,CAAU;AAAA,IACtC;AAAA,IACA,UAAUD,GAAMO,GAAON,GAAY;AAClC,MAAAL,GAAQ,UAAUI,GAAMO,GAAON,CAAU;AAAA,IAC1C;AAAA,IACA,cAAcD,GAAMM,GAAOL,GAAY;AACtC,MAAAL,GAAQ,cAAcI,GAAMM,GAAOL,CAAU;AAAA,IAC9C;AAAA,IACA,SAASD,GAAMP,GAAIY,GAAS;AAC3B,aAAOT,IAASA,EAAO,SAASI,GAAMP,GAAIY,CAAO,IAAIZ,EAAGF,CAAS;AAAA,IAClE;AAAA,IACA,MAAM,QAAQ;AACb,YAAMK,GAAQ,MAAA;AAAA,IACf;AAAA,IACA,MAAM,WAAW;AAChB,YAAMA,GAAQ,SAAA;AAAA,IACf;AAAA,IACA,OAAOY,GAAQ;AACd,MAAAZ,IAASY;AACT,YAAMC,IAASZ;AACf,MAAAA,IAAU,CAAA;AACV,iBAAWE,KAAUU;AACpB,QAAIV,EAAO,SAAS,UAASS,EAAO,WAAWT,EAAO,MAAMA,EAAO,YAAYA,EAAO,IAAI,IACrFS,EAAO,WAAWT,EAAO,OAAOA,EAAO,OAAO;AAAA,IAErD;AAAA,IACA,OAAOS,GAAQ;AAEd,MAAIZ,MAAWY,MAAQZ,IAAS;AAAA,IACjC;AAAA,EAAA;AAEF;"}

package/dist/telemetry/global-handlers.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./events.cjs"),n=new WeakMap;function u(e,t={}){const a=n.get(e);if(a)return a;if(typeof window>"u"){const r=()=>{};return n.set(e,r),r}const d=r=>{e.trackError(r.error??r.message,{name:t.windowErrorEventName??i.TelemetryEvent.WindowError,attributes:{...t.attributes,"error.source":"window"}})},s=r=>{e.trackError(r.reason,{name:t.unhandledRejectionEventName??i.TelemetryEvent.UnhandledRejection,attributes:{...t.attributes,"error.source":"unhandledrejection"}})};window.addEventListener("error",d),window.addEventListener("unhandledrejection",s);const o=()=>{n.get(e)===o&&(n.delete(e),window.removeEventListener("error",d),window.removeEventListener("unhandledrejection",s))};return n.set(e,o),o}exports.installGlobalErrorHandlers=u;
+//# sourceMappingURL=global-handlers.cjs.map

package/dist/telemetry/global-handlers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-handlers.cjs","sources":["../../src/telemetry/global-handlers.ts"],"sourcesContent":["import {TelemetryEvent} from \"./events\";\n\nimport type {Telemetry} from \"@tetrascience-npm/request/telemetry\";\n\n/** Options for {@link installGlobalErrorHandlers}. */\nexport interface GlobalErrorHandlerOptions {\n\t/** Event name for `window.onerror`. Default: `App:Error:Window`. */\n\twindowErrorEventName?: string;\n\t/** Event name for unhandled promise rejections. Default: `App:Error:UnhandledRejection`. */\n\tunhandledRejectionEventName?: string;\n\t/** Extra attributes merged into both events. */\n\tattributes?: Record<string, unknown>;\n}\n\n// Keyed by client so two federated apps can each install their own handlers,\n// while a repeated install for the same client (StrictMode, hot reload) is a\n// no-op that returns the original uninstall.\nconst installed = new WeakMap<Telemetry, () => void>();\n\n/**\n * Explicit opt-in: capture uncaught errors and unhandled promise rejections\n * for `client`. Never installed automatically by the provider — global\n * listeners are a host-level decision, and under Module Federation several\n * apps share `window`.\n *\n * Idempotent per client; returns an uninstall function (also idempotent).\n *\n * @example\n * ```tsx\n * const client = useTelemetryClient();\n * useEffect(() => installGlobalErrorHandlers(client), [client]);\n * ```\n */\nexport function installGlobalErrorHandlers(client: Telemetry, options: GlobalErrorHandlerOptions = {}): () => void {\n\tconst existing = installed.get(client);\n\tif (existing) return existing;\n\tif (typeof window === \"undefined\") {\n\t\t// Recorded in the map like any other install, so the documented\n\t\t// once-per-client contract holds here too: without this, every call in an\n\t\t// SSR/non-browser runtime handed back a different uninstall function.\n\t\tconst noop = (): void => {\n\t\t\t// nothing was installed (SSR / non-browser runtime)\n\t\t};\n\t\tinstalled.set(client, noop);\n\t\treturn noop;\n\t}\n\n\tconst onError = (event: ErrorEvent): void => {\n\t\tclient.trackError(event.error ?? event.message, {\n\t\t\tname: options.windowErrorEventName ?? TelemetryEvent.WindowError,\n\t\t\tattributes: {...options.attributes, \"error.source\": \"window\"},\n\t\t});\n\t};\n\tconst onRejection = (event: PromiseRejectionEvent): void => {\n\t\tclient.trackError(event.reason, {\n\t\t\tname: options.unhandledRejectionEventName ?? TelemetryEvent.UnhandledRejection,\n\t\t\tattributes: {...options.attributes, \"error.source\": \"unhandledrejection\"},\n\t\t});\n\t};\n\n\twindow.addEventListener(\"error\", onError);\n\twindow.addEventListener(\"unhandledrejection\", onRejection);\n\n\tconst uninstall = (): void => {\n\t\tif (installed.get(client) !== uninstall) return;\n\t\tinstalled.delete(client);\n\t\twindow.removeEventListener(\"error\", onError);\n\t\twindow.removeEventListener(\"unhandledrejection\", onRejection);\n\t};\n\tinstalled.set(client, uninstall);\n\treturn uninstall;\n}\n"],"names":["installed","installGlobalErrorHandlers","client","options","existing","noop","onError","event","TelemetryEvent","onRejection","uninstall"],"mappings":"gHAiBMA,MAAgB,QAgBf,SAASC,EAA2BC,EAAmBC,EAAqC,GAAgB,CAClH,MAAMC,EAAWJ,EAAU,IAAIE,CAAM,EACrC,GAAIE,EAAU,OAAOA,EACrB,GAAI,OAAO,OAAW,IAAa,CAIlC,MAAMC,EAAO,IAAY,CAEzB,EACA,OAAAL,EAAU,IAAIE,EAAQG,CAAI,EACnBA,CACR,CAEA,MAAMC,EAAWC,GAA4B,CAC5CL,EAAO,WAAWK,EAAM,OAASA,EAAM,QAAS,CAC/C,KAAMJ,EAAQ,sBAAwBK,EAAAA,eAAe,YACrD,WAAY,CAAC,GAAGL,EAAQ,WAAY,eAAgB,QAAA,CAAQ,CAC5D,CACF,EACMM,EAAeF,GAAuC,CAC3DL,EAAO,WAAWK,EAAM,OAAQ,CAC/B,KAAMJ,EAAQ,6BAA+BK,EAAAA,eAAe,mBAC5D,WAAY,CAAC,GAAGL,EAAQ,WAAY,eAAgB,oBAAA,CAAoB,CACxE,CACF,EAEA,OAAO,iBAAiB,QAASG,CAAO,EACxC,OAAO,iBAAiB,qBAAsBG,CAAW,EAEzD,MAAMC,EAAY,IAAY,CACzBV,EAAU,IAAIE,CAAM,IAAMQ,IAC9BV,EAAU,OAAOE,CAAM,EACvB,OAAO,oBAAoB,QAASI,CAAO,EAC3C,OAAO,oBAAoB,qBAAsBG,CAAW,EAC7D,EACA,OAAAT,EAAU,IAAIE,EAAQQ,CAAS,EACxBA,CACR"}

package/dist/telemetry/global-handlers.d.ts

@@ -0,0 +1,25 @@
+import { Telemetry } from '@tetrascience-npm/request/telemetry';
+/** Options for {@link installGlobalErrorHandlers}. */
+export interface GlobalErrorHandlerOptions {
+    /** Event name for `window.onerror`. Default: `App:Error:Window`. */
+    windowErrorEventName?: string;
+    /** Event name for unhandled promise rejections. Default: `App:Error:UnhandledRejection`. */
+    unhandledRejectionEventName?: string;
+    /** Extra attributes merged into both events. */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Explicit opt-in: capture uncaught errors and unhandled promise rejections
+ * for `client`. Never installed automatically by the provider — global
+ * listeners are a host-level decision, and under Module Federation several
+ * apps share `window`.
+ *
+ * Idempotent per client; returns an uninstall function (also idempotent).
+ *
+ * @example
+ * ```tsx
+ * const client = useTelemetryClient();
+ * useEffect(() => installGlobalErrorHandlers(client), [client]);
+ * ```
+ */
+export declare function installGlobalErrorHandlers(client: Telemetry, options?: GlobalErrorHandlerOptions): () => void;

package/dist/telemetry/global-handlers.js

@@ -0,0 +1,31 @@
+import { TelemetryEvent as s } from "./events.js";
+const n = /* @__PURE__ */ new WeakMap();
+function w(e, t = {}) {
+  const d = n.get(e);
+  if (d) return d;
+  if (typeof window > "u") {
+    const r = () => {
+    };
+    return n.set(e, r), r;
+  }
+  const a = (r) => {
+    e.trackError(r.error ?? r.message, {
+      name: t.windowErrorEventName ?? s.WindowError,
+      attributes: { ...t.attributes, "error.source": "window" }
+    });
+  }, i = (r) => {
+    e.trackError(r.reason, {
+      name: t.unhandledRejectionEventName ?? s.UnhandledRejection,
+      attributes: { ...t.attributes, "error.source": "unhandledrejection" }
+    });
+  };
+  window.addEventListener("error", a), window.addEventListener("unhandledrejection", i);
+  const o = () => {
+    n.get(e) === o && (n.delete(e), window.removeEventListener("error", a), window.removeEventListener("unhandledrejection", i));
+  };
+  return n.set(e, o), o;
+}
+export {
+  w as installGlobalErrorHandlers
+};
+//# sourceMappingURL=global-handlers.js.map

package/dist/telemetry/global-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-handlers.js","sources":["../../src/telemetry/global-handlers.ts"],"sourcesContent":["import {TelemetryEvent} from \"./events\";\n\nimport type {Telemetry} from \"@tetrascience-npm/request/telemetry\";\n\n/** Options for {@link installGlobalErrorHandlers}. */\nexport interface GlobalErrorHandlerOptions {\n\t/** Event name for `window.onerror`. Default: `App:Error:Window`. */\n\twindowErrorEventName?: string;\n\t/** Event name for unhandled promise rejections. Default: `App:Error:UnhandledRejection`. */\n\tunhandledRejectionEventName?: string;\n\t/** Extra attributes merged into both events. */\n\tattributes?: Record<string, unknown>;\n}\n\n// Keyed by client so two federated apps can each install their own handlers,\n// while a repeated install for the same client (StrictMode, hot reload) is a\n// no-op that returns the original uninstall.\nconst installed = new WeakMap<Telemetry, () => void>();\n\n/**\n * Explicit opt-in: capture uncaught errors and unhandled promise rejections\n * for `client`. Never installed automatically by the provider — global\n * listeners are a host-level decision, and under Module Federation several\n * apps share `window`.\n *\n * Idempotent per client; returns an uninstall function (also idempotent).\n *\n * @example\n * ```tsx\n * const client = useTelemetryClient();\n * useEffect(() => installGlobalErrorHandlers(client), [client]);\n * ```\n */\nexport function installGlobalErrorHandlers(client: Telemetry, options: GlobalErrorHandlerOptions = {}): () => void {\n\tconst existing = installed.get(client);\n\tif (existing) return existing;\n\tif (typeof window === \"undefined\") {\n\t\t// Recorded in the map like any other install, so the documented\n\t\t// once-per-client contract holds here too: without this, every call in an\n\t\t// SSR/non-browser runtime handed back a different uninstall function.\n\t\tconst noop = (): void => {\n\t\t\t// nothing was installed (SSR / non-browser runtime)\n\t\t};\n\t\tinstalled.set(client, noop);\n\t\treturn noop;\n\t}\n\n\tconst onError = (event: ErrorEvent): void => {\n\t\tclient.trackError(event.error ?? event.message, {\n\t\t\tname: options.windowErrorEventName ?? TelemetryEvent.WindowError,\n\t\t\tattributes: {...options.attributes, \"error.source\": \"window\"},\n\t\t});\n\t};\n\tconst onRejection = (event: PromiseRejectionEvent): void => {\n\t\tclient.trackError(event.reason, {\n\t\t\tname: options.unhandledRejectionEventName ?? TelemetryEvent.UnhandledRejection,\n\t\t\tattributes: {...options.attributes, \"error.source\": \"unhandledrejection\"},\n\t\t});\n\t};\n\n\twindow.addEventListener(\"error\", onError);\n\twindow.addEventListener(\"unhandledrejection\", onRejection);\n\n\tconst uninstall = (): void => {\n\t\tif (installed.get(client) !== uninstall) return;\n\t\tinstalled.delete(client);\n\t\twindow.removeEventListener(\"error\", onError);\n\t\twindow.removeEventListener(\"unhandledrejection\", onRejection);\n\t};\n\tinstalled.set(client, uninstall);\n\treturn uninstall;\n}\n"],"names":["installed","installGlobalErrorHandlers","client","options","existing","noop","onError","event","TelemetryEvent","onRejection","uninstall"],"mappings":";AAiBA,MAAMA,wBAAgB,QAAA;AAgBf,SAASC,EAA2BC,GAAmBC,IAAqC,IAAgB;AAClH,QAAMC,IAAWJ,EAAU,IAAIE,CAAM;AACrC,MAAIE,EAAU,QAAOA;AACrB,MAAI,OAAO,SAAW,KAAa;AAIlC,UAAMC,IAAO,MAAY;AAAA,IAEzB;AACA,WAAAL,EAAU,IAAIE,GAAQG,CAAI,GACnBA;AAAA,EACR;AAEA,QAAMC,IAAU,CAACC,MAA4B;AAC5C,IAAAL,EAAO,WAAWK,EAAM,SAASA,EAAM,SAAS;AAAA,MAC/C,MAAMJ,EAAQ,wBAAwBK,EAAe;AAAA,MACrD,YAAY,EAAC,GAAGL,EAAQ,YAAY,gBAAgB,SAAA;AAAA,IAAQ,CAC5D;AAAA,EACF,GACMM,IAAc,CAACF,MAAuC;AAC3D,IAAAL,EAAO,WAAWK,EAAM,QAAQ;AAAA,MAC/B,MAAMJ,EAAQ,+BAA+BK,EAAe;AAAA,MAC5D,YAAY,EAAC,GAAGL,EAAQ,YAAY,gBAAgB,qBAAA;AAAA,IAAoB,CACxE;AAAA,EACF;AAEA,SAAO,iBAAiB,SAASG,CAAO,GACxC,OAAO,iBAAiB,sBAAsBG,CAAW;AAEzD,QAAMC,IAAY,MAAY;AAC7B,IAAIV,EAAU,IAAIE,CAAM,MAAMQ,MAC9BV,EAAU,OAAOE,CAAM,GACvB,OAAO,oBAAoB,SAASI,CAAO,GAC3C,OAAO,oBAAoB,sBAAsBG,CAAW;AAAA,EAC7D;AACA,SAAAT,EAAU,IAAIE,GAAQQ,CAAS,GACxBA;AACR;"}

package/dist/telemetry/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * React bindings for the product-event telemetry distro (SW-2322).
+ *
+ * One provider mount and one import is the whole integration:
+ *
+ * ```tsx
+ * import {TelemetryProvider, TSErrorBoundary, useTetraEvents} from '@tetrascience-npm/tetrascience-react-ui/telemetry';
+ * ```
+ *
+ * This entry IS the React layer — it exports a provider, a hook and an error
+ * boundary — so importing it pulls React in, and `react` is a required peer of
+ * this package (it carries no `peerDependenciesMeta.optional`).
+ *
+ * If you want telemetry without React, import the framework-agnostic core
+ * directly: `@tetrascience-npm/request/telemetry`. That is what these bindings
+ * wrap, and it is re-exported below so a consumer never needs both imports.
+ */
+export * from './types';
+export * from './events';
+export * from './context';
+export * from './facade';
+export * from './telemetry-provider';
+export * from './use-tetra-events';
+export * from './error-boundary';
+export * from './global-handlers';
+export * from '@tetrascience-npm/request/telemetry';
+export type { ArtifactIdentity } from '@tetrascience-npm/request/telemetry';

package/dist/telemetry/telemetry-provider.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const y=require("react/jsx-runtime"),T=require("@tetrascience-npm/request/telemetry"),u=require("react"),v=require("./context.cjs"),d=require("./facade.cjs");function s(t){if(typeof window>"u")return;const e=window.env?.[t];if(typeof e=="boolean")return e;if(typeof e=="string"){if(/^(true|1|yes)$/i.test(e))return!0;if(/^(false|0|no)$/i.test(e))return!1}}function f(t,e,r="data-app"){const l=t?.namespace??e?.namespace,i=t?.slug??e?.slug,n=t?.version??e?.version,c=t?.type??e?.type??r;return l&&i&&n?{namespace:l,slug:i,version:n,type:c}:void 0}function E({children:t,...e}){const r=e.enabled??s("TELEMETRY_ENABLED")??!0,l=e.debug??s("TELEMETRY_DEBUG")??!1,i=f(e.artifact,e.manifest,e.artifactType),[n]=u.useState(d.createTelemetryFacade),c=u.useRef(e.getAuthToken);c.current=e.getAuthToken;const a={artifact:i,orgSlug:e.orgSlug,logsUrl:e.logsUrl,debug:l,flushTimeoutMillis:e.flushTimeoutMillis,processors:e.processors,logger:e.logger,tracing:e.tracing,metrics:e.metrics,getAuthToken:()=>c.current?.()},g=u.useRef(a);g.current=a;const m=JSON.stringify([r,l,e.logsUrl??null,e.orgSlug??null,i??null,e.tracing?.enabled??null,e.tracing?.tracesUrl??null,e.tracing?.sampleRatio??null,(e.tracing?.spanProcessors?.length??0)>0,e.metrics?.enabled??null,e.metrics?.metricsUrl??null,e.metrics?.exportIntervalMillis??null,(e.metrics?.readers?.length??0)>0]);return u.useEffect(()=>{const o=r?T.createTelemetry(g.current):d.NOOP_TELEMETRY;return n.attach(o),()=>{n.detach(o),o.shutdown()}},[n,m,r]),y.jsx(v.TelemetryContext.Provider,{value:n,children:t})}exports.TelemetryProvider=E;exports.readHostFlag=s;exports.resolveArtifact=f;
+//# sourceMappingURL=telemetry-provider.cjs.map

package/dist/telemetry/telemetry-provider.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-provider.cjs","sources":["../../src/telemetry/telemetry-provider.tsx"],"sourcesContent":["import {\n\tcreateTelemetry,\n\ttype ArtifactType,\n\ttype TelemetryArtifact,\n\ttype TelemetryOptions,\n} from \"@tetrascience-npm/request/telemetry\";\nimport { useEffect, useRef, useState } from \"react\";\n\nimport { TelemetryContext } from \"./context\";\nimport { NOOP_TELEMETRY, createTelemetryFacade } from \"./facade\";\n\nimport type { TelemetryProviderProps } from \"./types\";\n\n/**\n * Read a boolean flag from the host-provided browser config (`window.env`) —\n * the same seam the core uses for `API_URI`. Accepts real booleans and the\n * string forms hosts inject through templated config.\n */\nexport function readHostFlag(key: string): boolean | undefined {\n  if (typeof window === \"undefined\") return undefined;\n  const value = (window as { env?: Record<string, unknown> }).env?.[key];\n  if (typeof value === \"boolean\") return value;\n  if (typeof value === \"string\") {\n    if (/^(true|1|yes)$/i.test(value)) return true;\n    if (/^(false|0|no)$/i.test(value)) return false;\n  }\n  return undefined;\n}\n\n/**\n * Merge host mount props with the manifest fallback, field by field. Returns\n * undefined when identity is still incomplete — the core then emits without\n * artifact identity rather than with placeholder values.\n */\nexport function resolveArtifact(\n  artifact: Partial<TelemetryArtifact> | undefined,\n  manifest: Partial<TelemetryArtifact> | undefined,\n  artifactType: ArtifactType = \"data-app\",\n): TelemetryArtifact | undefined {\n  const namespace = artifact?.namespace ?? manifest?.namespace;\n  const slug = artifact?.slug ?? manifest?.slug;\n  const version = artifact?.version ?? manifest?.version;\n  const type = artifact?.type ?? manifest?.type ?? artifactType;\n  return namespace && slug && version ? { namespace, slug, version, type } : undefined;\n}\n\n/**\n * Mount once, near the app root: builds a PER-INSTANCE telemetry client from\n * the app's identity and exposes it to `useTetraEvents` / `TSErrorBoundary`.\n *\n * The client is never module-global — federated apps share `globalThis` with\n * the host and siblings, so a global client would cross-attribute events.\n * It is built inside an effect and shut down (which flushes) on unmount, so\n * StrictMode's mount → unmount → mount cycle disposes the first client\n * cleanly instead of leaving a dead provider attached. The context value is a\n * stable façade, so hook callback identities never change.\n *\n * No user identity is ever attached client-side: `user.id` is stamped\n * server-side at the gateway from the authenticated principal.\n *\n * @example\n * ```tsx\n * <TelemetryProvider artifact={hostProps.artifact} manifest={manifest} orgSlug={org?.slug}>\n *   <App />\n * </TelemetryProvider>\n * ```\n */\nexport function TelemetryProvider({ children, ...props }: TelemetryProviderProps) {\n  const enabled = props.enabled ?? readHostFlag(\"TELEMETRY_ENABLED\") ?? true;\n  const debug = props.debug ?? readHostFlag(\"TELEMETRY_DEBUG\") ?? false;\n  const artifact = resolveArtifact(props.artifact, props.manifest, props.artifactType);\n\n  const [facade] = useState(createTelemetryFacade);\n\n  // Options are read at construction time; only identity-shaped changes\n  // rebuild the client (a new `processors`/`logger` object per render must not).\n  // The client is built ONCE per identity change, but the token resolver has to\n  // track re-renders: an app writing `getAuthToken={() => token}` produces a new\n  // closure each render, and the client would otherwise keep calling the first\n  // one — capturing whatever token existed at mount. That fails silently and\n  // late, as 401s appearing only after the first token rotation. Holding the\n  // prop in a ref and calling through it means the client always invokes the\n  // CURRENT closure without being rebuilt.\n  const getAuthTokenRef = useRef(props.getAuthToken);\n  getAuthTokenRef.current = props.getAuthToken;\n\n  const options: TelemetryOptions = {\n    artifact,\n    orgSlug: props.orgSlug,\n    logsUrl: props.logsUrl,\n    debug,\n    flushTimeoutMillis: props.flushTimeoutMillis,\n    processors: props.processors,\n    logger: props.logger,\n    tracing: props.tracing,\n    metrics: props.metrics,\n    getAuthToken: () => getAuthTokenRef.current?.(),\n  };\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n\n  // `tracing` is part of the identity: without it, flipping tracing on (or\n  // changing the sample ratio) would not rebuild the client, so the change\n  // would silently take effect only when some UNRELATED identity field\n  // happened to change. Read field-by-field rather than by reference so an\n  // inline `tracing={{enabled: true}}` object literal does not rebuild every\n  // render.\n  // Only SCALARS go in the key. `tracing.spanProcessors` and `metrics.readers`\n  // hold live SDK instances — serialising those would make the key depend on\n  // an exporter's internal state (spurious rebuilds), and a processor with a\n  // circular reference would throw here and take the whole provider down on\n  // render. Their PRESENCE is part of the identity; their contents are not.\n  const identityKey = JSON.stringify([\n    enabled,\n    debug,\n    props.logsUrl ?? null,\n    props.orgSlug ?? null,\n    artifact ?? null,\n    props.tracing?.enabled ?? null,\n    props.tracing?.tracesUrl ?? null,\n    props.tracing?.sampleRatio ?? null,\n    (props.tracing?.spanProcessors?.length ?? 0) > 0,\n    // Same argument as `tracing`: without metrics in the identity, flipping\n    // it on would not rebuild the client, so the change would take effect\n    // only when some UNRELATED identity field happened to change.\n    props.metrics?.enabled ?? null,\n    props.metrics?.metricsUrl ?? null,\n    props.metrics?.exportIntervalMillis ?? null,\n    (props.metrics?.readers?.length ?? 0) > 0,\n  ]);\n\n  useEffect(() => {\n    const client = enabled ? createTelemetry(optionsRef.current) : NOOP_TELEMETRY;\n    facade.attach(client);\n    return () => {\n      facade.detach(client);\n      // shutdown() flushes what is buffered, then tears the pipeline down.\n      void client.shutdown();\n    };\n    // `enabled` is encoded in identityKey; optionsRef is intentionally not a dep.\n  }, [facade, identityKey, enabled]);\n\n  return <TelemetryContext.Provider value={facade}>{children}</TelemetryContext.Provider>;\n}\n"],"names":["readHostFlag","key","value","resolveArtifact","artifact","manifest","artifactType","namespace","slug","version","type","TelemetryProvider","children","props","enabled","debug","facade","useState","createTelemetryFacade","getAuthTokenRef","useRef","options","optionsRef","identityKey","useEffect","client","createTelemetry","NOOP_TELEMETRY","TelemetryContext"],"mappings":"8OAkBO,SAASA,EAAaC,EAAkC,CAC7D,GAAI,OAAO,OAAW,IAAa,OACnC,MAAMC,EAAS,OAA6C,MAAMD,CAAG,EACrE,GAAI,OAAOC,GAAU,UAAW,OAAOA,EACvC,GAAI,OAAOA,GAAU,SAAU,CAC7B,GAAI,kBAAkB,KAAKA,CAAK,EAAG,MAAO,GAC1C,GAAI,kBAAkB,KAAKA,CAAK,EAAG,MAAO,EAC5C,CAEF,CAOO,SAASC,EACdC,EACAC,EACAC,EAA6B,WACE,CAC/B,MAAMC,EAAYH,GAAU,WAAaC,GAAU,UAC7CG,EAAOJ,GAAU,MAAQC,GAAU,KACnCI,EAAUL,GAAU,SAAWC,GAAU,QACzCK,EAAON,GAAU,MAAQC,GAAU,MAAQC,EACjD,OAAOC,GAAaC,GAAQC,EAAU,CAAE,UAAAF,EAAW,KAAAC,EAAM,QAAAC,EAAS,KAAAC,GAAS,MAC7E,CAuBO,SAASC,EAAkB,CAAE,SAAAC,EAAU,GAAGC,GAAiC,CAChF,MAAMC,EAAUD,EAAM,SAAWb,EAAa,mBAAmB,GAAK,GAChEe,EAAQF,EAAM,OAASb,EAAa,iBAAiB,GAAK,GAC1DI,EAAWD,EAAgBU,EAAM,SAAUA,EAAM,SAAUA,EAAM,YAAY,EAE7E,CAACG,CAAM,EAAIC,EAAAA,SAASC,uBAAqB,EAWzCC,EAAkBC,EAAAA,OAAOP,EAAM,YAAY,EACjDM,EAAgB,QAAUN,EAAM,aAEhC,MAAMQ,EAA4B,CAChC,SAAAjB,EACA,QAASS,EAAM,QACf,QAASA,EAAM,QACf,MAAAE,EACA,mBAAoBF,EAAM,mBAC1B,WAAYA,EAAM,WAClB,OAAQA,EAAM,OACd,QAASA,EAAM,QACf,QAASA,EAAM,QACf,aAAc,IAAMM,EAAgB,UAAA,CAAU,EAE1CG,EAAaF,EAAAA,OAAOC,CAAO,EACjCC,EAAW,QAAUD,EAarB,MAAME,EAAc,KAAK,UAAU,CACjCT,EACAC,EACAF,EAAM,SAAW,KACjBA,EAAM,SAAW,KACjBT,GAAY,KACZS,EAAM,SAAS,SAAW,KAC1BA,EAAM,SAAS,WAAa,KAC5BA,EAAM,SAAS,aAAe,MAC7BA,EAAM,SAAS,gBAAgB,QAAU,GAAK,EAI/CA,EAAM,SAAS,SAAW,KAC1BA,EAAM,SAAS,YAAc,KAC7BA,EAAM,SAAS,sBAAwB,MACtCA,EAAM,SAAS,SAAS,QAAU,GAAK,CAAA,CACzC,EAEDW,OAAAA,EAAAA,UAAU,IAAM,CACd,MAAMC,EAASX,EAAUY,EAAAA,gBAAgBJ,EAAW,OAAO,EAAIK,EAAAA,eAC/DX,OAAAA,EAAO,OAAOS,CAAM,EACb,IAAM,CACXT,EAAO,OAAOS,CAAM,EAEfA,EAAO,SAAA,CACd,CAEF,EAAG,CAACT,EAAQO,EAAaT,CAAO,CAAC,QAEzBc,EAAAA,iBAAiB,SAAjB,CAA0B,MAAOZ,EAAS,SAAAJ,EAAS,CAC7D"}

package/dist/telemetry/telemetry-provider.d.ts

@@ -0,0 +1,36 @@
+import { ArtifactType, TelemetryArtifact } from '@tetrascience-npm/request/telemetry';
+import { TelemetryProviderProps } from './types';
+/**
+ * Read a boolean flag from the host-provided browser config (`window.env`) —
+ * the same seam the core uses for `API_URI`. Accepts real booleans and the
+ * string forms hosts inject through templated config.
+ */
+export declare function readHostFlag(key: string): boolean | undefined;
+/**
+ * Merge host mount props with the manifest fallback, field by field. Returns
+ * undefined when identity is still incomplete — the core then emits without
+ * artifact identity rather than with placeholder values.
+ */
+export declare function resolveArtifact(artifact: Partial<TelemetryArtifact> | undefined, manifest: Partial<TelemetryArtifact> | undefined, artifactType?: ArtifactType): TelemetryArtifact | undefined;
+/**
+ * Mount once, near the app root: builds a PER-INSTANCE telemetry client from
+ * the app's identity and exposes it to `useTetraEvents` / `TSErrorBoundary`.
+ *
+ * The client is never module-global — federated apps share `globalThis` with
+ * the host and siblings, so a global client would cross-attribute events.
+ * It is built inside an effect and shut down (which flushes) on unmount, so
+ * StrictMode's mount → unmount → mount cycle disposes the first client
+ * cleanly instead of leaving a dead provider attached. The context value is a
+ * stable façade, so hook callback identities never change.
+ *
+ * No user identity is ever attached client-side: `user.id` is stamped
+ * server-side at the gateway from the authenticated principal.
+ *
+ * @example
+ * ```tsx
+ * <TelemetryProvider artifact={hostProps.artifact} manifest={manifest} orgSlug={org?.slug}>
+ *   <App />
+ * </TelemetryProvider>
+ * ```
+ */
+export declare function TelemetryProvider({ children, ...props }: TelemetryProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/telemetry/telemetry-provider.js

@@ -0,0 +1,65 @@
+import { jsx as m } from "react/jsx-runtime";
+import { createTelemetry as d } from "@tetrascience-npm/request/telemetry";
+import { useState as T, useRef as a, useEffect as y } from "react";
+import { TelemetryContext as v } from "./context.js";
+import { createTelemetryFacade as E, NOOP_TELEMETRY as h } from "./facade.js";
+function g(t) {
+  if (typeof window > "u") return;
+  const e = window.env?.[t];
+  if (typeof e == "boolean") return e;
+  if (typeof e == "string") {
+    if (/^(true|1|yes)$/i.test(e)) return !0;
+    if (/^(false|0|no)$/i.test(e)) return !1;
+  }
+}
+function b(t, e, r = "data-app") {
+  const l = t?.namespace ?? e?.namespace, i = t?.slug ?? e?.slug, n = t?.version ?? e?.version, o = t?.type ?? e?.type ?? r;
+  return l && i && n ? { namespace: l, slug: i, version: n, type: o } : void 0;
+}
+function S({ children: t, ...e }) {
+  const r = e.enabled ?? g("TELEMETRY_ENABLED") ?? !0, l = e.debug ?? g("TELEMETRY_DEBUG") ?? !1, i = b(e.artifact, e.manifest, e.artifactType), [n] = T(E), o = a(e.getAuthToken);
+  o.current = e.getAuthToken;
+  const u = {
+    artifact: i,
+    orgSlug: e.orgSlug,
+    logsUrl: e.logsUrl,
+    debug: l,
+    flushTimeoutMillis: e.flushTimeoutMillis,
+    processors: e.processors,
+    logger: e.logger,
+    tracing: e.tracing,
+    metrics: e.metrics,
+    getAuthToken: () => o.current?.()
+  }, s = a(u);
+  s.current = u;
+  const f = JSON.stringify([
+    r,
+    l,
+    e.logsUrl ?? null,
+    e.orgSlug ?? null,
+    i ?? null,
+    e.tracing?.enabled ?? null,
+    e.tracing?.tracesUrl ?? null,
+    e.tracing?.sampleRatio ?? null,
+    (e.tracing?.spanProcessors?.length ?? 0) > 0,
+    // Same argument as `tracing`: without metrics in the identity, flipping
+    // it on would not rebuild the client, so the change would take effect
+    // only when some UNRELATED identity field happened to change.
+    e.metrics?.enabled ?? null,
+    e.metrics?.metricsUrl ?? null,
+    e.metrics?.exportIntervalMillis ?? null,
+    (e.metrics?.readers?.length ?? 0) > 0
+  ]);
+  return y(() => {
+    const c = r ? d(s.current) : h;
+    return n.attach(c), () => {
+      n.detach(c), c.shutdown();
+    };
+  }, [n, f, r]), /* @__PURE__ */ m(v.Provider, { value: n, children: t });
+}
+export {
+  S as TelemetryProvider,
+  g as readHostFlag,
+  b as resolveArtifact
+};
+//# sourceMappingURL=telemetry-provider.js.map

package/dist/telemetry/telemetry-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-provider.js","sources":["../../src/telemetry/telemetry-provider.tsx"],"sourcesContent":["import {\n\tcreateTelemetry,\n\ttype ArtifactType,\n\ttype TelemetryArtifact,\n\ttype TelemetryOptions,\n} from \"@tetrascience-npm/request/telemetry\";\nimport { useEffect, useRef, useState } from \"react\";\n\nimport { TelemetryContext } from \"./context\";\nimport { NOOP_TELEMETRY, createTelemetryFacade } from \"./facade\";\n\nimport type { TelemetryProviderProps } from \"./types\";\n\n/**\n * Read a boolean flag from the host-provided browser config (`window.env`) —\n * the same seam the core uses for `API_URI`. Accepts real booleans and the\n * string forms hosts inject through templated config.\n */\nexport function readHostFlag(key: string): boolean | undefined {\n  if (typeof window === \"undefined\") return undefined;\n  const value = (window as { env?: Record<string, unknown> }).env?.[key];\n  if (typeof value === \"boolean\") return value;\n  if (typeof value === \"string\") {\n    if (/^(true|1|yes)$/i.test(value)) return true;\n    if (/^(false|0|no)$/i.test(value)) return false;\n  }\n  return undefined;\n}\n\n/**\n * Merge host mount props with the manifest fallback, field by field. Returns\n * undefined when identity is still incomplete — the core then emits without\n * artifact identity rather than with placeholder values.\n */\nexport function resolveArtifact(\n  artifact: Partial<TelemetryArtifact> | undefined,\n  manifest: Partial<TelemetryArtifact> | undefined,\n  artifactType: ArtifactType = \"data-app\",\n): TelemetryArtifact | undefined {\n  const namespace = artifact?.namespace ?? manifest?.namespace;\n  const slug = artifact?.slug ?? manifest?.slug;\n  const version = artifact?.version ?? manifest?.version;\n  const type = artifact?.type ?? manifest?.type ?? artifactType;\n  return namespace && slug && version ? { namespace, slug, version, type } : undefined;\n}\n\n/**\n * Mount once, near the app root: builds a PER-INSTANCE telemetry client from\n * the app's identity and exposes it to `useTetraEvents` / `TSErrorBoundary`.\n *\n * The client is never module-global — federated apps share `globalThis` with\n * the host and siblings, so a global client would cross-attribute events.\n * It is built inside an effect and shut down (which flushes) on unmount, so\n * StrictMode's mount → unmount → mount cycle disposes the first client\n * cleanly instead of leaving a dead provider attached. The context value is a\n * stable façade, so hook callback identities never change.\n *\n * No user identity is ever attached client-side: `user.id` is stamped\n * server-side at the gateway from the authenticated principal.\n *\n * @example\n * ```tsx\n * <TelemetryProvider artifact={hostProps.artifact} manifest={manifest} orgSlug={org?.slug}>\n *   <App />\n * </TelemetryProvider>\n * ```\n */\nexport function TelemetryProvider({ children, ...props }: TelemetryProviderProps) {\n  const enabled = props.enabled ?? readHostFlag(\"TELEMETRY_ENABLED\") ?? true;\n  const debug = props.debug ?? readHostFlag(\"TELEMETRY_DEBUG\") ?? false;\n  const artifact = resolveArtifact(props.artifact, props.manifest, props.artifactType);\n\n  const [facade] = useState(createTelemetryFacade);\n\n  // Options are read at construction time; only identity-shaped changes\n  // rebuild the client (a new `processors`/`logger` object per render must not).\n  // The client is built ONCE per identity change, but the token resolver has to\n  // track re-renders: an app writing `getAuthToken={() => token}` produces a new\n  // closure each render, and the client would otherwise keep calling the first\n  // one — capturing whatever token existed at mount. That fails silently and\n  // late, as 401s appearing only after the first token rotation. Holding the\n  // prop in a ref and calling through it means the client always invokes the\n  // CURRENT closure without being rebuilt.\n  const getAuthTokenRef = useRef(props.getAuthToken);\n  getAuthTokenRef.current = props.getAuthToken;\n\n  const options: TelemetryOptions = {\n    artifact,\n    orgSlug: props.orgSlug,\n    logsUrl: props.logsUrl,\n    debug,\n    flushTimeoutMillis: props.flushTimeoutMillis,\n    processors: props.processors,\n    logger: props.logger,\n    tracing: props.tracing,\n    metrics: props.metrics,\n    getAuthToken: () => getAuthTokenRef.current?.(),\n  };\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n\n  // `tracing` is part of the identity: without it, flipping tracing on (or\n  // changing the sample ratio) would not rebuild the client, so the change\n  // would silently take effect only when some UNRELATED identity field\n  // happened to change. Read field-by-field rather than by reference so an\n  // inline `tracing={{enabled: true}}` object literal does not rebuild every\n  // render.\n  // Only SCALARS go in the key. `tracing.spanProcessors` and `metrics.readers`\n  // hold live SDK instances — serialising those would make the key depend on\n  // an exporter's internal state (spurious rebuilds), and a processor with a\n  // circular reference would throw here and take the whole provider down on\n  // render. Their PRESENCE is part of the identity; their contents are not.\n  const identityKey = JSON.stringify([\n    enabled,\n    debug,\n    props.logsUrl ?? null,\n    props.orgSlug ?? null,\n    artifact ?? null,\n    props.tracing?.enabled ?? null,\n    props.tracing?.tracesUrl ?? null,\n    props.tracing?.sampleRatio ?? null,\n    (props.tracing?.spanProcessors?.length ?? 0) > 0,\n    // Same argument as `tracing`: without metrics in the identity, flipping\n    // it on would not rebuild the client, so the change would take effect\n    // only when some UNRELATED identity field happened to change.\n    props.metrics?.enabled ?? null,\n    props.metrics?.metricsUrl ?? null,\n    props.metrics?.exportIntervalMillis ?? null,\n    (props.metrics?.readers?.length ?? 0) > 0,\n  ]);\n\n  useEffect(() => {\n    const client = enabled ? createTelemetry(optionsRef.current) : NOOP_TELEMETRY;\n    facade.attach(client);\n    return () => {\n      facade.detach(client);\n      // shutdown() flushes what is buffered, then tears the pipeline down.\n      void client.shutdown();\n    };\n    // `enabled` is encoded in identityKey; optionsRef is intentionally not a dep.\n  }, [facade, identityKey, enabled]);\n\n  return <TelemetryContext.Provider value={facade}>{children}</TelemetryContext.Provider>;\n}\n"],"names":["readHostFlag","key","value","resolveArtifact","artifact","manifest","artifactType","namespace","slug","version","type","TelemetryProvider","children","props","enabled","debug","facade","useState","createTelemetryFacade","getAuthTokenRef","useRef","options","optionsRef","identityKey","useEffect","client","createTelemetry","NOOP_TELEMETRY","TelemetryContext"],"mappings":";;;;;AAkBO,SAASA,EAAaC,GAAkC;AAC7D,MAAI,OAAO,SAAW,IAAa;AACnC,QAAMC,IAAS,OAA6C,MAAMD,CAAG;AACrE,MAAI,OAAOC,KAAU,UAAW,QAAOA;AACvC,MAAI,OAAOA,KAAU,UAAU;AAC7B,QAAI,kBAAkB,KAAKA,CAAK,EAAG,QAAO;AAC1C,QAAI,kBAAkB,KAAKA,CAAK,EAAG,QAAO;AAAA,EAC5C;AAEF;AAOO,SAASC,EACdC,GACAC,GACAC,IAA6B,YACE;AAC/B,QAAMC,IAAYH,GAAU,aAAaC,GAAU,WAC7CG,IAAOJ,GAAU,QAAQC,GAAU,MACnCI,IAAUL,GAAU,WAAWC,GAAU,SACzCK,IAAON,GAAU,QAAQC,GAAU,QAAQC;AACjD,SAAOC,KAAaC,KAAQC,IAAU,EAAE,WAAAF,GAAW,MAAAC,GAAM,SAAAC,GAAS,MAAAC,MAAS;AAC7E;AAuBO,SAASC,EAAkB,EAAE,UAAAC,GAAU,GAAGC,KAAiC;AAChF,QAAMC,IAAUD,EAAM,WAAWb,EAAa,mBAAmB,KAAK,IAChEe,IAAQF,EAAM,SAASb,EAAa,iBAAiB,KAAK,IAC1DI,IAAWD,EAAgBU,EAAM,UAAUA,EAAM,UAAUA,EAAM,YAAY,GAE7E,CAACG,CAAM,IAAIC,EAASC,CAAqB,GAWzCC,IAAkBC,EAAOP,EAAM,YAAY;AACjD,EAAAM,EAAgB,UAAUN,EAAM;AAEhC,QAAMQ,IAA4B;AAAA,IAChC,UAAAjB;AAAA,IACA,SAASS,EAAM;AAAA,IACf,SAASA,EAAM;AAAA,IACf,OAAAE;AAAA,IACA,oBAAoBF,EAAM;AAAA,IAC1B,YAAYA,EAAM;AAAA,IAClB,QAAQA,EAAM;AAAA,IACd,SAASA,EAAM;AAAA,IACf,SAASA,EAAM;AAAA,IACf,cAAc,MAAMM,EAAgB,UAAA;AAAA,EAAU,GAE1CG,IAAaF,EAAOC,CAAO;AACjC,EAAAC,EAAW,UAAUD;AAarB,QAAME,IAAc,KAAK,UAAU;AAAA,IACjCT;AAAA,IACAC;AAAA,IACAF,EAAM,WAAW;AAAA,IACjBA,EAAM,WAAW;AAAA,IACjBT,KAAY;AAAA,IACZS,EAAM,SAAS,WAAW;AAAA,IAC1BA,EAAM,SAAS,aAAa;AAAA,IAC5BA,EAAM,SAAS,eAAe;AAAA,KAC7BA,EAAM,SAAS,gBAAgB,UAAU,KAAK;AAAA;AAAA;AAAA;AAAA,IAI/CA,EAAM,SAAS,WAAW;AAAA,IAC1BA,EAAM,SAAS,cAAc;AAAA,IAC7BA,EAAM,SAAS,wBAAwB;AAAA,KACtCA,EAAM,SAAS,SAAS,UAAU,KAAK;AAAA,EAAA,CACzC;AAED,SAAAW,EAAU,MAAM;AACd,UAAMC,IAASX,IAAUY,EAAgBJ,EAAW,OAAO,IAAIK;AAC/D,WAAAX,EAAO,OAAOS,CAAM,GACb,MAAM;AACX,MAAAT,EAAO,OAAOS,CAAM,GAEfA,EAAO,SAAA;AAAA,IACd;AAAA,EAEF,GAAG,CAACT,GAAQO,GAAaT,CAAO,CAAC,qBAEzBc,EAAiB,UAAjB,EAA0B,OAAOZ,GAAS,UAAAJ,GAAS;AAC7D;"}

package/dist/telemetry/types.d.ts

@@ -0,0 +1,140 @@
+import { LogRecordProcessor } from '@opentelemetry/sdk-logs';
+import { RequestTrackingLogger } from '@tetrascience-npm/request';
+import { ArtifactType, MetricsOptions, StartSpanOptions, Telemetry, TelemetryArtifact, TelemetryTracingOptions, TetraSpan, TrackErrorContext } from '@tetrascience-npm/request/telemetry';
+import { ReactNode } from 'react';
+/** Props for {@link TelemetryProvider}. */
+export interface TelemetryProviderProps {
+    /**
+     * Artifact identity from the host mount props (`hostProps.artifact`).
+     * Fields missing here fall back to {@link TelemetryProviderProps.manifest}.
+     */
+    artifact?: Partial<TelemetryArtifact>;
+    /**
+     * Manifest fallback for standalone dev, e.g. `import manifest from './manifest.json'`.
+     * Used field-by-field wherever `artifact` is incomplete.
+     */
+    manifest?: Partial<TelemetryArtifact>;
+    /**
+     * What KIND of artifact is mounting this — `"data-app"` unless stated.
+     *
+     * The core distro refuses to guess this (it serves data apps and connectors
+     * alike, and mislabelling one as the other is worse than emitting no kind at
+     * all). This kit can: it is React bindings for a browser mount, and on this
+     * platform that is a data app. The default is a DECLARATION by a component
+     * only data apps mount, not a fallback for producers that do not know what
+     * they are — and anything else mounting it says so here.
+     *
+     * `artifact.type` / `manifest.type` win over this when present.
+     */
+    artifactType?: ArtifactType;
+    /**
+     * Org slug hint. Producer-asserted only — the gateway stamps the
+     * authenticated org server-side and that value wins (SW-2319).
+     */
+    orgSlug?: string;
+    /**
+     * Resolve the current user's auth token for the `ts-auth-token` header.
+     *
+     * REQUIRED for a browser data app to deliver anything. The gateway reads
+     * credentials from headers only, and its CORS config (`origin: ['*']`, no
+     * `credentials`) means a browser cannot send a session cookie — so without
+     * this every batch 401s and the app emits into the void.
+     *
+     * Called on every export, so pass a function that reads the host's CURRENT
+     * token rather than a captured string: a data app outlives any single
+     * short-lived token.
+     */
+    getAuthToken?: () => string | undefined | Promise<string | undefined>;
+    /** OTLP/HTTP logs URL override. Default: the core's endpoint resolution. */
+    logsUrl?: string;
+    /**
+     * Master switch. Default: `window.env.TELEMETRY_ENABLED` when the host
+     * provides it, otherwise `true`. When disabled the context client is a
+     * no-op — no OTel provider, no exporter, no network, no buffers.
+     */
+    enabled?: boolean;
+    /**
+     * Route records to the stock console exporter in addition to OTLP, so
+     * authors see the exact pre-gateway payload. Default:
+     * `window.env.TELEMETRY_DEBUG` when the host provides it, otherwise `false`.
+     */
+    debug?: boolean;
+    /** Log record processors override (tests, custom pipelines). */
+    processors?: LogRecordProcessor[];
+    /**
+     * Distributed tracing (SW-2478). Off unless `tracing.enabled` is true —
+     * tracing adds a second exporter and a per-span network cost, so an app
+     * opts in rather than acquiring it by upgrading the library.
+     */
+    tracing?: TelemetryTracingOptions;
+    /**
+     * OTel metrics (SW-2478). Off unless `metrics.enabled` is true, for the same
+     * reason tracing is: a metrics reader is a recurring timer and a recurring
+     * export.
+     *
+     * Forwarded here rather than left to the core's defaults because apps build
+     * their client through THIS provider — an option the provider does not pass
+     * through is one no React data app can ever set, which is how
+     * `gauge()`/`histogram()` came to be callable but permanently inert.
+     */
+    metrics?: MetricsOptions;
+    /**
+     * Cap on how long `flush()` and `shutdown()` wait for the exporter, in ms.
+     * Forwarded to the core, which defaults to 5000. Worth setting when the
+     * host unmounts on a route change and cannot afford a 5s teardown.
+     */
+    flushTimeoutMillis?: number;
+    /** Logger for setup failures and stripped attributes. */
+    logger?: RequestTrackingLogger;
+    children?: ReactNode;
+}
+/** Bound emitters returned by {@link useTetraEvents}. */
+export interface TetraEvents {
+    /** Record a product event (`App[:Page][:Object]:Action`). */
+    trackEvent(name: string, attributes?: Record<string, unknown>, body?: unknown): void;
+    /** Record an error event with `exception.*` attributes. */
+    trackError(error: unknown, context?: TrackErrorContext): void;
+    /**
+     * Start a span (SW-2478). No-op unless the provider was given
+     * `tracing.enabled`. The caller must `end()` it — prefer `withSpan`.
+     */
+    startSpan(name: string, options?: StartSpanOptions): TetraSpan;
+    /**
+     * Run `fn` inside a span, ending it when the work settles (promises
+     * included) and on the error path. Errors are recorded and re-thrown.
+     */
+    withSpan<T>(name: string, fn: (span: TetraSpan) => T, options?: StartSpanOptions): T;
+    /**
+     * Add to a running total that only ever goes up (SW-2478). No-op unless the
+     * provider was given `metrics.enabled`.
+     *
+     * The core client and the Python distro have both exposed this from the
+     * start; the React bindings did not, so a data app could reach `gauge`,
+     * `histogram` and `upDownCounter` but not the most basic instrument of the
+     * four. Found by the bindings' own e2e — `events.counter is not a function`.
+     */
+    counter(name: string, delta?: number, attributes?: Record<string, unknown>): void;
+    /**
+     * Record the current value of something (SW-2478). No-op unless the
+     * provider was given `metrics.enabled`.
+     *
+     * Unlike {@link TetraEvents.trackEvent}, this carries a VALUE — counting is
+     * one-record-one-increment and cannot express "the reading right now".
+     */
+    gauge(name: string, value: number, attributes?: Record<string, unknown>): void;
+    /** Record a distribution sample — a duration, a size. Same opt-in as `gauge`. */
+    histogram(name: string, value: number, attributes?: Record<string, unknown>): void;
+    /** Add to a running total that can go both ways. Same opt-in as `gauge`. */
+    upDownCounter(name: string, delta: number, attributes?: Record<string, unknown>): void;
+}
+/**
+ * The context client: a stable façade whose underlying per-instance client is
+ * attached by {@link TelemetryProvider} in an effect. Identity is stable for
+ * the provider's lifetime, so hook callbacks never change identity.
+ */
+export type TelemetryFacade = Telemetry & {
+    /** @internal */
+    attach(client: Telemetry): void;
+    /** @internal */
+    detach(client: Telemetry): void;
+};

package/dist/telemetry/use-tetra-events.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react"),d=require("./context.cjs"),k=require("./facade.cjs");let a=!1;function E(){a||(a=!0,!(typeof process<"u"&&process.env?.NODE_ENV==="production")&&console.warn("[telemetry] useTetraEvents() called outside <TelemetryProvider> — events are dropped."))}function m(){a=!1}function p(){const e=s.useContext(d.TelemetryContext);return e||E(),e??k.NOOP_TELEMETRY}function b(){const e=p(),o=s.useCallback((t,n,r)=>{e.trackEvent(t,n,r)},[e]),c=s.useCallback((t,n)=>{e.trackError(t,n)},[e]),u=s.useCallback((t,n)=>e.startSpan(t,n),[e]),l=s.useCallback((t,n,r)=>e.counter(t,n,r),[e]),i=s.useCallback((t,n,r)=>e.gauge(t,n,r),[e]),C=s.useCallback((t,n,r)=>e.histogram(t,n,r),[e]),T=s.useCallback((t,n,r)=>e.upDownCounter(t,n,r),[e]),f=s.useCallback((t,n,r)=>e.withSpan(t,n,r),[e]);return s.useMemo(()=>({trackEvent:o,trackError:c,startSpan:u,withSpan:f,counter:l,gauge:i,histogram:C,upDownCounter:T}),[o,c,u,f,l,i,C,T])}exports.__resetTelemetryWarningForTests=m;exports.useTelemetryClient=p;exports.useTetraEvents=b;
+//# sourceMappingURL=use-tetra-events.cjs.map

package/dist/telemetry/use-tetra-events.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tetra-events.cjs","sources":["../../src/telemetry/use-tetra-events.ts"],"sourcesContent":["import { useCallback, useContext, useMemo } from \"react\";\n\nimport { TelemetryContext } from \"./context\";\nimport { NOOP_TELEMETRY } from \"./facade\";\n\nimport type { TetraEvents } from \"./types\";\nimport type { StartSpanOptions, Telemetry, TetraSpan, TrackErrorContext } from \"@tetrascience-npm/request/telemetry\";\n\nlet warned = false;\n\n/**\n * Outside a provider the hook no-ops with one development warning rather than\n * throwing. Rationale: the core's contract is that telemetry never throws into\n * application code — a missing provider is an instrumentation defect, and\n * crashing a customer's app over it inverts the risk. The warning (dev only,\n * once per module instance) keeps the mistake visible during development and\n * is asserted in tests.\n */\nfunction warnOnce(): void {\n  if (warned) return;\n  warned = true;\n  if (typeof process !== \"undefined\" && process.env?.NODE_ENV === \"production\") return;\n\n  console.warn(\"[telemetry] useTetraEvents() called outside <TelemetryProvider> — events are dropped.\");\n}\n\n/** @internal test seam: reset the once-per-module warning latch. */\nexport function __resetTelemetryWarningForTests(): void {\n  warned = false;\n}\n\n/** Access the raw context client — e.g. to wire {@link installGlobalErrorHandlers}. */\nexport function useTelemetryClient(): Telemetry {\n  const client = useContext(TelemetryContext);\n  if (!client) warnOnce();\n  return client ?? NOOP_TELEMETRY;\n}\n\n/**\n * The app-facing emitters, bound to the provider's client.\n *\n * Identities are stable for the provider's lifetime (the context value is a\n * stable façade), so these are safe as effect dependencies.\n *\n * @example\n * ```tsx\n * const {trackEvent} = useTetraEvents();\n * trackEvent('Sandbox:Chat:Submit', {model});\n * ```\n */\nexport function useTetraEvents(): TetraEvents {\n  const client = useTelemetryClient();\n\n  const trackEvent = useCallback(\n    (name: string, attributes?: Record<string, unknown>, body?: unknown) => {\n      client.trackEvent(name, attributes, body);\n    },\n    [client],\n  );\n\n  const trackError = useCallback(\n    (error: unknown, context?: TrackErrorContext) => {\n      client.trackError(error, context);\n    },\n    [client],\n  );\n\n  // SW-2478. Every method here delegates to the core rather than\n  // re-implementing anything, so React and non-React consumers cannot drift.\n  const startSpan = useCallback(\n    (name: string, options?: StartSpanOptions) => client.startSpan(name, options),\n    [client],\n  );\n\n  // SW-2478 metrics. Same delegation rule as startSpan: the\n  // instrument caching, the value guards and the publishable-name warning all\n  // live in the core client, so re-implementing any of it here would give\n  // React apps different behaviour from Node ones for the same call.\n  const counter = useCallback(\n    (name: string, delta?: number, attributes?: Record<string, unknown>) => client.counter(name, delta, attributes),\n    [client],\n  );\n\n  const gauge = useCallback(\n    (name: string, value: number, attributes?: Record<string, unknown>) => client.gauge(name, value, attributes),\n    [client],\n  );\n\n  const histogram = useCallback(\n    (name: string, value: number, attributes?: Record<string, unknown>) => client.histogram(name, value, attributes),\n    [client],\n  );\n\n  const upDownCounter = useCallback(\n    (name: string, delta: number, attributes?: Record<string, unknown>) =>\n      client.upDownCounter(name, delta, attributes),\n    [client],\n  );\n\n  const withSpan = useCallback(\n    <T>(name: string, fn: (span: TetraSpan) => T, options?: StartSpanOptions) => client.withSpan(name, fn, options),\n    [client],\n  );\n\n  return useMemo(\n    () => ({ trackEvent, trackError, startSpan, withSpan, counter, gauge, histogram, upDownCounter }),\n    [trackEvent, trackError, startSpan, withSpan, counter, gauge, histogram, upDownCounter],\n  );\n}\n"],"names":["warned","warnOnce","__resetTelemetryWarningForTests","useTelemetryClient","client","useContext","TelemetryContext","NOOP_TELEMETRY","useTetraEvents","trackEvent","useCallback","name","attributes","body","trackError","error","context","startSpan","options","counter","delta","gauge","value","histogram","upDownCounter","withSpan","fn","useMemo"],"mappings":"8JAQA,IAAIA,EAAS,GAUb,SAASC,GAAiB,CACpBD,IACJA,EAAS,GACL,SAAO,QAAY,KAAe,QAAQ,KAAK,WAAa,eAEhE,QAAQ,KAAK,uFAAuF,EACtG,CAGO,SAASE,GAAwC,CACtDF,EAAS,EACX,CAGO,SAASG,GAAgC,CAC9C,MAAMC,EAASC,EAAAA,WAAWC,kBAAgB,EAC1C,OAAKF,GAAQH,EAAA,EACNG,GAAUG,EAAAA,cACnB,CAcO,SAASC,GAA8B,CAC5C,MAAMJ,EAASD,EAAA,EAETM,EAAaC,EAAAA,YACjB,CAACC,EAAcC,EAAsCC,IAAmB,CACtET,EAAO,WAAWO,EAAMC,EAAYC,CAAI,CAC1C,EACA,CAACT,CAAM,CAAA,EAGHU,EAAaJ,EAAAA,YACjB,CAACK,EAAgBC,IAAgC,CAC/CZ,EAAO,WAAWW,EAAOC,CAAO,CAClC,EACA,CAACZ,CAAM,CAAA,EAKHa,EAAYP,EAAAA,YAChB,CAACC,EAAcO,IAA+Bd,EAAO,UAAUO,EAAMO,CAAO,EAC5E,CAACd,CAAM,CAAA,EAOHe,EAAUT,EAAAA,YACd,CAACC,EAAcS,EAAgBR,IAAyCR,EAAO,QAAQO,EAAMS,EAAOR,CAAU,EAC9G,CAACR,CAAM,CAAA,EAGHiB,EAAQX,EAAAA,YACZ,CAACC,EAAcW,EAAeV,IAAyCR,EAAO,MAAMO,EAAMW,EAAOV,CAAU,EAC3G,CAACR,CAAM,CAAA,EAGHmB,EAAYb,EAAAA,YAChB,CAACC,EAAcW,EAAeV,IAAyCR,EAAO,UAAUO,EAAMW,EAAOV,CAAU,EAC/G,CAACR,CAAM,CAAA,EAGHoB,EAAgBd,EAAAA,YACpB,CAACC,EAAcS,EAAeR,IAC5BR,EAAO,cAAcO,EAAMS,EAAOR,CAAU,EAC9C,CAACR,CAAM,CAAA,EAGHqB,EAAWf,EAAAA,YACf,CAAIC,EAAce,EAA4BR,IAA+Bd,EAAO,SAASO,EAAMe,EAAIR,CAAO,EAC9G,CAACd,CAAM,CAAA,EAGT,OAAOuB,EAAAA,QACL,KAAO,CAAE,WAAAlB,EAAY,WAAAK,EAAY,UAAAG,EAAW,SAAAQ,EAAU,QAAAN,EAAS,MAAAE,EAAO,UAAAE,EAAW,cAAAC,IACjF,CAACf,EAAYK,EAAYG,EAAWQ,EAAUN,EAASE,EAAOE,EAAWC,CAAa,CAAA,CAE1F"}

package/dist/telemetry/use-tetra-events.d.ts

@@ -0,0 +1,19 @@
+import { TetraEvents } from './types';
+import { Telemetry } from '@tetrascience-npm/request/telemetry';
+/** @internal test seam: reset the once-per-module warning latch. */
+export declare function __resetTelemetryWarningForTests(): void;
+/** Access the raw context client — e.g. to wire {@link installGlobalErrorHandlers}. */
+export declare function useTelemetryClient(): Telemetry;
+/**
+ * The app-facing emitters, bound to the provider's client.
+ *
+ * Identities are stable for the provider's lifetime (the context value is a
+ * stable façade), so these are safe as effect dependencies.
+ *
+ * @example
+ * ```tsx
+ * const {trackEvent} = useTetraEvents();
+ * trackEvent('Sandbox:Chat:Submit', {model});
+ * ```
+ */
+export declare function useTetraEvents(): TetraEvents;

package/dist/telemetry/use-tetra-events.js

@@ -0,0 +1,55 @@
+import { useContext as E, useCallback as o, useMemo as d } from "react";
+import { TelemetryContext as T } from "./context.js";
+import { NOOP_TELEMETRY as g } from "./facade.js";
+let s = !1;
+function v() {
+  s || (s = !0, !(typeof process < "u" && process.env?.NODE_ENV === "production") && console.warn("[telemetry] useTetraEvents() called outside <TelemetryProvider> — events are dropped."));
+}
+function h() {
+  s = !1;
+}
+function w() {
+  const e = E(T);
+  return e || v(), e ?? g;
+}
+function O() {
+  const e = w(), c = o(
+    (t, r, n) => {
+      e.trackEvent(t, r, n);
+    },
+    [e]
+  ), a = o(
+    (t, r) => {
+      e.trackError(t, r);
+    },
+    [e]
+  ), u = o(
+    (t, r) => e.startSpan(t, r),
+    [e]
+  ), i = o(
+    (t, r, n) => e.counter(t, r, n),
+    [e]
+  ), l = o(
+    (t, r, n) => e.gauge(t, r, n),
+    [e]
+  ), p = o(
+    (t, r, n) => e.histogram(t, r, n),
+    [e]
+  ), f = o(
+    (t, r, n) => e.upDownCounter(t, r, n),
+    [e]
+  ), m = o(
+    (t, r, n) => e.withSpan(t, r, n),
+    [e]
+  );
+  return d(
+    () => ({ trackEvent: c, trackError: a, startSpan: u, withSpan: m, counter: i, gauge: l, histogram: p, upDownCounter: f }),
+    [c, a, u, m, i, l, p, f]
+  );
+}
+export {
+  h as __resetTelemetryWarningForTests,
+  w as useTelemetryClient,
+  O as useTetraEvents
+};
+//# sourceMappingURL=use-tetra-events.js.map

package/dist/telemetry/use-tetra-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tetra-events.js","sources":["../../src/telemetry/use-tetra-events.ts"],"sourcesContent":["import { useCallback, useContext, useMemo } from \"react\";\n\nimport { TelemetryContext } from \"./context\";\nimport { NOOP_TELEMETRY } from \"./facade\";\n\nimport type { TetraEvents } from \"./types\";\nimport type { StartSpanOptions, Telemetry, TetraSpan, TrackErrorContext } from \"@tetrascience-npm/request/telemetry\";\n\nlet warned = false;\n\n/**\n * Outside a provider the hook no-ops with one development warning rather than\n * throwing. Rationale: the core's contract is that telemetry never throws into\n * application code — a missing provider is an instrumentation defect, and\n * crashing a customer's app over it inverts the risk. The warning (dev only,\n * once per module instance) keeps the mistake visible during development and\n * is asserted in tests.\n */\nfunction warnOnce(): void {\n  if (warned) return;\n  warned = true;\n  if (typeof process !== \"undefined\" && process.env?.NODE_ENV === \"production\") return;\n\n  console.warn(\"[telemetry] useTetraEvents() called outside <TelemetryProvider> — events are dropped.\");\n}\n\n/** @internal test seam: reset the once-per-module warning latch. */\nexport function __resetTelemetryWarningForTests(): void {\n  warned = false;\n}\n\n/** Access the raw context client — e.g. to wire {@link installGlobalErrorHandlers}. */\nexport function useTelemetryClient(): Telemetry {\n  const client = useContext(TelemetryContext);\n  if (!client) warnOnce();\n  return client ?? NOOP_TELEMETRY;\n}\n\n/**\n * The app-facing emitters, bound to the provider's client.\n *\n * Identities are stable for the provider's lifetime (the context value is a\n * stable façade), so these are safe as effect dependencies.\n *\n * @example\n * ```tsx\n * const {trackEvent} = useTetraEvents();\n * trackEvent('Sandbox:Chat:Submit', {model});\n * ```\n */\nexport function useTetraEvents(): TetraEvents {\n  const client = useTelemetryClient();\n\n  const trackEvent = useCallback(\n    (name: string, attributes?: Record<string, unknown>, body?: unknown) => {\n      client.trackEvent(name, attributes, body);\n    },\n    [client],\n  );\n\n  const trackError = useCallback(\n    (error: unknown, context?: TrackErrorContext) => {\n      client.trackError(error, context);\n    },\n    [client],\n  );\n\n  // SW-2478. Every method here delegates to the core rather than\n  // re-implementing anything, so React and non-React consumers cannot drift.\n  const startSpan = useCallback(\n    (name: string, options?: StartSpanOptions) => client.startSpan(name, options),\n    [client],\n  );\n\n  // SW-2478 metrics. Same delegation rule as startSpan: the\n  // instrument caching, the value guards and the publishable-name warning all\n  // live in the core client, so re-implementing any of it here would give\n  // React apps different behaviour from Node ones for the same call.\n  const counter = useCallback(\n    (name: string, delta?: number, attributes?: Record<string, unknown>) => client.counter(name, delta, attributes),\n    [client],\n  );\n\n  const gauge = useCallback(\n    (name: string, value: number, attributes?: Record<string, unknown>) => client.gauge(name, value, attributes),\n    [client],\n  );\n\n  const histogram = useCallback(\n    (name: string, value: number, attributes?: Record<string, unknown>) => client.histogram(name, value, attributes),\n    [client],\n  );\n\n  const upDownCounter = useCallback(\n    (name: string, delta: number, attributes?: Record<string, unknown>) =>\n      client.upDownCounter(name, delta, attributes),\n    [client],\n  );\n\n  const withSpan = useCallback(\n    <T>(name: string, fn: (span: TetraSpan) => T, options?: StartSpanOptions) => client.withSpan(name, fn, options),\n    [client],\n  );\n\n  return useMemo(\n    () => ({ trackEvent, trackError, startSpan, withSpan, counter, gauge, histogram, upDownCounter }),\n    [trackEvent, trackError, startSpan, withSpan, counter, gauge, histogram, upDownCounter],\n  );\n}\n"],"names":["warned","warnOnce","__resetTelemetryWarningForTests","useTelemetryClient","client","useContext","TelemetryContext","NOOP_TELEMETRY","useTetraEvents","trackEvent","useCallback","name","attributes","body","trackError","error","context","startSpan","options","counter","delta","gauge","value","histogram","upDownCounter","withSpan","fn","useMemo"],"mappings":";;;AAQA,IAAIA,IAAS;AAUb,SAASC,IAAiB;AACxB,EAAID,MACJA,IAAS,IACL,SAAO,UAAY,OAAe,QAAQ,KAAK,aAAa,iBAEhE,QAAQ,KAAK,uFAAuF;AACtG;AAGO,SAASE,IAAwC;AACtD,EAAAF,IAAS;AACX;AAGO,SAASG,IAAgC;AAC9C,QAAMC,IAASC,EAAWC,CAAgB;AAC1C,SAAKF,KAAQH,EAAA,GACNG,KAAUG;AACnB;AAcO,SAASC,IAA8B;AAC5C,QAAMJ,IAASD,EAAA,GAETM,IAAaC;AAAA,IACjB,CAACC,GAAcC,GAAsCC,MAAmB;AACtE,MAAAT,EAAO,WAAWO,GAAMC,GAAYC,CAAI;AAAA,IAC1C;AAAA,IACA,CAACT,CAAM;AAAA,EAAA,GAGHU,IAAaJ;AAAA,IACjB,CAACK,GAAgBC,MAAgC;AAC/C,MAAAZ,EAAO,WAAWW,GAAOC,CAAO;AAAA,IAClC;AAAA,IACA,CAACZ,CAAM;AAAA,EAAA,GAKHa,IAAYP;AAAA,IAChB,CAACC,GAAcO,MAA+Bd,EAAO,UAAUO,GAAMO,CAAO;AAAA,IAC5E,CAACd,CAAM;AAAA,EAAA,GAOHe,IAAUT;AAAA,IACd,CAACC,GAAcS,GAAgBR,MAAyCR,EAAO,QAAQO,GAAMS,GAAOR,CAAU;AAAA,IAC9G,CAACR,CAAM;AAAA,EAAA,GAGHiB,IAAQX;AAAA,IACZ,CAACC,GAAcW,GAAeV,MAAyCR,EAAO,MAAMO,GAAMW,GAAOV,CAAU;AAAA,IAC3G,CAACR,CAAM;AAAA,EAAA,GAGHmB,IAAYb;AAAA,IAChB,CAACC,GAAcW,GAAeV,MAAyCR,EAAO,UAAUO,GAAMW,GAAOV,CAAU;AAAA,IAC/G,CAACR,CAAM;AAAA,EAAA,GAGHoB,IAAgBd;AAAA,IACpB,CAACC,GAAcS,GAAeR,MAC5BR,EAAO,cAAcO,GAAMS,GAAOR,CAAU;AAAA,IAC9C,CAACR,CAAM;AAAA,EAAA,GAGHqB,IAAWf;AAAA,IACf,CAAIC,GAAce,GAA4BR,MAA+Bd,EAAO,SAASO,GAAMe,GAAIR,CAAO;AAAA,IAC9G,CAACd,CAAM;AAAA,EAAA;AAGT,SAAOuB;AAAA,IACL,OAAO,EAAE,YAAAlB,GAAY,YAAAK,GAAY,WAAAG,GAAW,UAAAQ,GAAU,SAAAN,GAAS,OAAAE,GAAO,WAAAE,GAAW,eAAAC;IACjF,CAACf,GAAYK,GAAYG,GAAWQ,GAAUN,GAASE,GAAOE,GAAWC,CAAa;AAAA,EAAA;AAE1F;"}

package/dist/telemetry.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./telemetry/events.cjs"),n=require("./telemetry/context.cjs"),a=require("./telemetry/facade.cjs"),r=require("./telemetry/telemetry-provider.cjs"),t=require("./telemetry/use-tetra-events.cjs"),s=require("./telemetry/error-boundary.cjs"),T=require("./telemetry/global-handlers.cjs"),l=require("@tetrascience-npm/request/telemetry");exports.MAX_COMPONENT_STACK_LENGTH=o.MAX_COMPONENT_STACK_LENGTH;exports.TelemetryEvent=o.TelemetryEvent;exports.TelemetryContext=n.TelemetryContext;exports.NOOP_TELEMETRY=a.NOOP_TELEMETRY;exports.createTelemetryFacade=a.createTelemetryFacade;exports.TelemetryProvider=r.TelemetryProvider;exports.readHostFlag=r.readHostFlag;exports.resolveArtifact=r.resolveArtifact;exports.__resetTelemetryWarningForTests=t.__resetTelemetryWarningForTests;exports.useTelemetryClient=t.useTelemetryClient;exports.useTetraEvents=t.useTetraEvents;exports.TSErrorBoundary=s.TSErrorBoundary;exports.installGlobalErrorHandlers=T.installGlobalErrorHandlers;Object.keys(l).forEach(e=>{e!=="default"&&!Object.prototype.hasOwnProperty.call(exports,e)&&Object.defineProperty(exports,e,{enumerable:!0,get:()=>l[e]})});
+//# sourceMappingURL=telemetry.cjs.map

package/dist/telemetry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/telemetry.js

@@ -0,0 +1,24 @@
+import { MAX_COMPONENT_STACK_LENGTH as t, TelemetryEvent as o } from "./telemetry/events.js";
+import { TelemetryContext as m } from "./telemetry/context.js";
+import { NOOP_TELEMETRY as a, createTelemetryFacade as s } from "./telemetry/facade.js";
+import { TelemetryProvider as n, readHostFlag as x, resolveArtifact as E } from "./telemetry/telemetry-provider.js";
+import { __resetTelemetryWarningForTests as y, useTelemetryClient as _, useTetraEvents as d } from "./telemetry/use-tetra-events.js";
+import { TSErrorBoundary as v } from "./telemetry/error-boundary.js";
+import { installGlobalErrorHandlers as N } from "./telemetry/global-handlers.js";
+export * from "@tetrascience-npm/request/telemetry";
+export {
+  t as MAX_COMPONENT_STACK_LENGTH,
+  a as NOOP_TELEMETRY,
+  v as TSErrorBoundary,
+  m as TelemetryContext,
+  o as TelemetryEvent,
+  n as TelemetryProvider,
+  y as __resetTelemetryWarningForTests,
+  s as createTelemetryFacade,
+  N as installGlobalErrorHandlers,
+  x as readHostFlag,
+  E as resolveArtifact,
+  _ as useTelemetryClient,
+  d as useTetraEvents
+};
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tetrascience-npm/tetrascience-react-ui",
-  "version": "1.0.0-beta.135.1",
+  "version": "1.0.0-beta.136.1",
   "description": "TetraScience React UI",
   "type": "module",
   "author": "TetraScience",
@@ -30,6 +30,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./telemetry": {
+      "import": {
+        "types": "./dist/telemetry/index.d.ts",
+        "default": "./dist/telemetry.js"
+      },
+      "require": {
+        "types": "./dist/telemetry/index.d.ts",
+        "default": "./dist/telemetry.cjs"
+      }
+    },
     "./server": {
       "import": {
         "types": "./dist/server/index.d.ts",
@@ -200,7 +210,9 @@
     "lint:fix": "eslint . --fix --max-warnings 0",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "typecheck:e2e": "tsc --noEmit -p tsconfig.e2e.json"
   },
   "dependencies": {
     "@aws-sdk/client-cloudwatch-logs": ">=3.0.0 <4.0.0",
@@ -250,6 +262,7 @@
     "@rdkit/rdkit": "2025.3.4-1.0.0",
     "@streamdown/math": "^1.0.2",
     "@streamdown/mermaid": "^1.0.2",
+    "@tetrascience-npm/request": ">=0.4.0",
     "plotly.js-dist": "^2.35.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -280,6 +293,9 @@
   },
   "devDependencies": {
     "@aws-sdk/client-athena": "^3.975.0",
+    "@aws-sdk/client-cloudwatch": "^3.699.0",
+    "@aws-sdk/client-cloudwatch-logs": "^3.699.0",
+    "@aws-sdk/client-ssm": "^3.699.0",
     "@commitlint/cli": "^20.5.0",
     "@commitlint/config-conventional": "^20.5.0",
     "@databricks/sql": "^1.12.0",
@@ -303,6 +319,7 @@
     "@streamdown/math": "^1.0.2",
     "@streamdown/mermaid": "^1.0.2",
     "@tailwindcss/vite": "^4.2.2",
+    "@tetrascience-npm/request": "0.4.0",
     "@types/eslint-plugin-jsx-a11y": "^6",
     "@types/jsdom": "^27",
     "@types/node": "^25.3.3",