autotel-web 1.7.0 → 1.8.0

package/README.md

@@ -22,7 +22,7 @@ Ultra-lightweight browser SDK for distributed tracing (**1.6KB gzipped**)
 ✅ **W3C trace propagation** - Automatic `traceparent` header injection on fetch/XHR
 ✅ **SSR-safe** - Works with Next.js, Remix, and other SSR frameworks
 ✅ **Framework-agnostic** - Works with React, Vue, Svelte, Angular, vanilla JS
-✅ **No real spans** - Browser just propagates context, backend does real tracing
+✅ **No Zone.js** - [Context propagation without global patching](#context-propagation-without-zonejs)
 
 ## Installation
 
@@ -34,7 +34,14 @@ pnpm add autotel-web
 yarn add autotel-web
 ```
 
-**Important:** You do NOT need to install any `@opentelemetry/*` packages. This package has **zero dependencies**.
+**Important:** You do NOT need to install any `@opentelemetry/*` packages yourself. One install gives you both modes below.
+
+### Lean vs Full mode
+
+- **Lean (default)** – `import { init } from 'autotel-web'`. Zero dependencies, ~1.6KB gzipped. Only injects W3C `traceparent` on fetch/XHR; no real spans in the browser. Backend does the real tracing.
+- **Full** – `import { initFull } from 'autotel-web/full'`. Real spans (navigation, fetch/XHR, optional user interaction), optional `http.client.network_timing` events, **Web Vitals** (LCP, INP, CLS, FCP, TTFB), **unhandled error capture**, optional long-task capture, sampling, and OTLP export. No Zone.js; bundle size is larger (~40–50KB gzipped). Use when you need client-side spans and export from the browser.
+
+Use lean mode by default; use full mode when you need real browser spans and network timing. You can use dynamic import to load full mode only when needed: `import('autotel-web/full').then(({ initFull }) => initFull(config))`.
 
 ## Quick Start
 
@@ -78,6 +85,37 @@ app.get('/api/users', async (req, res) => {
 
 Open your observability platform (Honeycomb, Datadog, Jaeger, etc.) and see the complete trace from browser → backend → database!
 
+## Full mode (real spans)
+
+When you need real browser spans, network timing events, and optional export from the client, use full mode. Same install: `autotel-web`. No Zone.js.
+
+```typescript
+import { initFull } from 'autotel-web/full'
+
+initFull({
+  service: 'my-app',
+  endpoint: 'https://your-collector.example.com/v1/traces',  // OTLP HTTP
+  sampleRate: 0.1,                    // e.g. 10% in production
+  captureNavigation: true,            // document load spans (default: true)
+  captureFetch: true,
+  captureXHR: true,
+  captureNetworkTiming: true,         // http.client.network_timing events (semantic-conventions#3385)
+  captureErrors: true,                // unhandled errors → span.recordException (default: true)
+  captureWebVitals: true,             // LCP, INP, CLS, FCP, TTFB as web_vitals span (default: true)
+  webVitals: { reportAllChanges: false },  // pass through to web-vitals (default: false)
+  captureLongTasks: false,            // long-task spans (main thread >= 50ms); opt-in, can be noisy
+  copyHttpSpanAttributesToEvent: false,
+  userInteraction: {
+    enabled: true,
+    selectors: ['button', 'a', '[data-track]'],
+  },
+  privacy: { allowedOrigins: ['api.myapp.com'], respectDoNotTrack: true },
+  debug: false,
+})
+```
+
+With sensible defaults, **one `initFull()`** gives you: **navigation spans**, **fetch/XHR spans** with W3C propagation, **http.client.network_timing** events, **Web Vitals** (LCP, INP, CLS, FCP, TTFB) as a single `web_vitals` span per page, and **unhandled error capture** (window errors and unhandled promise rejections). Optional: **user interaction** spans (clicks on configurable selectors), **long-task** spans (opt-in via `captureLongTasks: true`), **sampling** (`sampleRate` or custom `sampler`), and **setAttribute** / **addEvent** / **span()** on the active span. Async context propagation is best-effort (no Zone.js).
+
 ## Framework Integration
 
 ### React (Client-Only)
@@ -348,6 +386,32 @@ init({
 })
 ```
 
+### `initFull(config)` (full mode)
+
+Initialize full browser tracing. Import from `autotel-web/full`. Call once, client-side only.
+
+```typescript
+interface AutotelWebFullConfig {
+  service: string
+  endpoint?: string                    // OTLP traces URL (e.g. https://api.example.com/v1/traces)
+  spanProcessor?: SpanProcessor        // Custom processor instead of endpoint
+  sampleRate?: number                  // 0–1, e.g. 0.1 in production
+  sampler?: Sampler                    // Custom sampler (overrides sampleRate)
+  captureNavigation?: boolean          // default true
+  captureFetch?: boolean               // default true
+  captureXHR?: boolean                 // default true
+  captureNetworkTiming?: boolean       // http.client.network_timing events (default true)
+  captureErrors?: boolean              // unhandled errors → span.recordException (default true)
+  captureWebVitals?: boolean          // LCP, INP, CLS, FCP, TTFB as web_vitals span (default true)
+  webVitals?: { reportAllChanges?: boolean }  // pass through to web-vitals (default false)
+  captureLongTasks?: boolean          // long-task spans (main thread >= 50ms); opt-in (default false)
+  copyHttpSpanAttributesToEvent?: boolean
+  userInteraction?: { enabled: boolean; selectors?: string[] }
+  privacy?: PrivacyConfig
+  debug?: boolean
+}
+```
+
 ### `trace(fn)` and `trace(ctx => fn)`
 
 Wrap functions with automatic tracing.
@@ -370,32 +434,36 @@ const user = await fetchUser('123')
 
 ```typescript
 export const fetchUser = trace(ctx => async (id: string) => {
-  ctx.setAttribute('user.id', id)
-
+  // ctx.traceId, ctx.spanId available (lean mode)
   const response = await fetch(`/api/users/${id}`)
-  const user = await response.json()
-
-  ctx.setAttribute('user.email', user.email)
-  return user
+  return response.json()
 })
 
 // Usage
 const user = await fetchUser('123')
 ```
 
-### `span(name, fn)`
+For **custom attributes and real spans** in the browser, use **full mode** (`autotel-web/full`): `setAttribute`, `addEvent`, and `span()` operate on the active OTel span.
+
+### `span(name, fn)` (full mode only)
 
-Create a manual span for a block of code:
+Create a manual span. Import from `autotel-web/full`:
 
 ```typescript
-import { span } from 'autotel-web'
+import { span } from 'autotel-web/full'
 
-const result = await span('processData', async (ctx) => {
-  ctx.setAttribute('data.size', data.length)
-  return await processData(data)
+const result = await span('processData', (s) => {
+  s.setAttribute('data.size', data.length)
+  const out = processData(data)
+  s.end()
+  return out
 })
 ```
 
+### `setAttribute(key, value)` / `addEvent(name, attributes)` (full mode only)
+
+Set attributes or add events on the active span. Import from `autotel-web/full`.
+
 ### `getActiveContext()`
 
 Get the current active trace context:
@@ -769,11 +837,8 @@ export default function MyComponent() { ... }
 
 ## Bundle Size
 
-- **Unminified:** 5.05KB
-- **Gzipped:** **1.6KB** 🎉
-- **Brotli:** ~1.4KB (typical)
-
-**Zero dependencies.** No `@opentelemetry/*` packages. Just pure JavaScript using native `crypto.getRandomValues()`.
+- **Lean mode** (`autotel-web`): **~1.6KB gzipped**. Zero dependencies. Pure JavaScript using native `crypto.getRandomValues()`.
+- **Full mode** (`autotel-web/full`): ~40–50KB gzipped (includes OpenTelemetry SDK and instrumentations). No Zone.js. Use when you need real spans and export from the browser.
 
 ## Architecture: Header-Only Approach
 
@@ -820,13 +885,14 @@ The official OpenTelemetry browser SDK (`@opentelemetry/sdk-trace-web`) is a **f
 
 ### When to Use autotel-web (This Package)
 
-✅ You only need **trace correlation** between frontend and backend
+✅ You only need **trace correlation** between frontend and backend → use **lean mode** (`init` from `autotel-web`)
+✅ You want **real browser spans and network timing** but **one install and no Zone.js** → use **full mode** (`initFull` from `autotel-web/full`)
 ✅ Your backend **already exports to a collector** (OTLP, Datadog, etc.)
-✅ You want **minimal bundle size impact** (~1.6KB vs ~55KB)
+✅ You want **minimal bundle size impact** (~1.6KB for lean vs ~55KB for full OTel with Zone)
 ✅ You want to **avoid Zone.js** (conflicts with Angular, adds complexity)
 ✅ You prefer **zero dependencies** and simpler maintenance
 
-**Bottom Line:** If your backend already does tracing, you don't need full OpenTelemetry in the browser. Just propagate the trace context with autotel-web.
+**Bottom Line:** For trace correlation only, use lean mode. For real browser spans and network timing with a single install and no Zone.js, use full mode (`autotel-web/full`).
 
 ## Performance Impact
 
@@ -850,6 +916,101 @@ autotel-web has **effectively zero performance overhead**:
 
 **Real-world impact:** Imperceptible. The network request itself takes orders of magnitude longer than the header injection.
 
+## Context Propagation Without Zone.js
+
+Browser tracing with OpenTelemetry typically needs **context propagation**: when you start a span (e.g., "user clicked button"), any async work that follows—fetch, setTimeout, Promise chains—should run in that same trace context so the backend sees one continuous trace. In Node.js, OpenTelemetry uses AsyncLocalStorage to keep context across async boundaries. In the browser, there is no built-in "async context" that follows every boundary. **Zone.js** is the usual way to get that: it patches globals (setTimeout, Promise, fetch, etc.) so that any code that runs "later" still runs inside the same zone—and thus the same trace context.
+
+This section explains when you might need Zone.js, its pitfalls, and how autotel-web gets you reliable tracing without it.
+
+### When You Might Think You Need Zone.js
+
+You might think you need **async context that survives every boundary** when:
+
+- You start a span in one place (e.g., click handler) and want **all** follow-up work—nested setTimeout, microtasks, fetch callbacks, requestAnimationFrame—to stay under that span without you wrapping each boundary
+- You have deep or framework-driven async (e.g., React state updates → effects → fetch → more effects) and you can't or don't want to wrap every step
+- You rely on "current span" or "current trace ID" in code that runs in callbacks you don't control (e.g., third-party lib that calls your callback after a delay)
+
+In those cases, Zone.js gives you one execution context that follows the entire async tree. OpenTelemetry can attach the active span to that zone, and every callback runs in the same context.
+
+### Pitfalls of Zone.js
+
+**1. Bundle size and cost**
+Zone.js is on the order of ~12–15 KB minified/gzipped. For a browser SDK that aims to be small (autotel-web lean is ~1.6 KB), adding Zone significantly increases size for every user.
+
+**2. Global patching**
+Zone.js patches `setTimeout`, `setInterval`, `Promise`, `fetch`, `XHR`, `addEventListener`, and more. That can:
+
+- Conflict with other libraries that also patch or depend on "vanilla" behavior
+- Cause hard-to-debug issues in frameworks (e.g., Angular uses Zone; other frameworks don't and sometimes assume no patching)
+- Break or confuse code that relies on exact timing or microtask ordering
+
+**3. Framework and tooling friction**
+Some bundlers, test runners, and frameworks have had issues with Zone (e.g., Next.js, Vite, or Jest in the past). You can end up debugging "why is my context wrong only in tests" or "why does this break in production build."
+
+**4. Implicit behavior**
+Context "just following" everywhere is convenient but implicit. When something goes wrong (wrong span, wrong trace), the cause is not obvious: it's "whatever Zone did." Explicit propagation (e.g., "this span covers this function") is easier to reason about and debug.
+
+**5. Maintenance**
+Zone.js is not part of the web platform. New APIs (e.g., new promise helpers, scheduler APIs) may need new patches. You depend on the Zone maintainers and the OpenTelemetry Zone plugin to keep up.
+
+### How autotel-web Works Without Zone.js
+
+autotel-web is designed so you can get **useful, reliable browser → backend tracing** without Zone.js. It does that in three ways: lean mode, full mode with targeted instrumentation, and an explicit `trace()` API.
+
+#### 1. Lean Mode: No Real Browser Spans
+
+In **lean mode** (`init()` from `autotel-web`), the browser does **not** create real OpenTelemetry spans. It only:
+
+- Injects the W3C `traceparent` header on every `fetch` and XHR request
+
+So the "context" that matters is on the **request**: the backend receives `traceparent`, continues the trace, and does all span creation and export. There is no "current span" in the browser to lose across async boundaries. You don't need Zone for this.
+
+**Use lean mode when:** You care about distributed traces (browser → API → services) and are fine with the backend owning the spans.
+
+#### 2. Full Mode: Instrumentation That Propagates on the Wire
+
+In **full mode** (`initFull()` from `autotel-web/full`), the browser **does** create real spans (navigation, fetch/XHR, Web Vitals, etc.). Context can be lost across arbitrary async boundaries (e.g., `setTimeout`), but autotel-web focuses on the boundaries that matter for tracing:
+
+- **Fetch / XHR**: The OpenTelemetry fetch and XHR instrumentations wrap the real `fetch` and `XMLHttpRequest`. When your code calls `fetch()`, the instrumentation starts a span and injects `traceparent` into the request. When the response comes back, the callback runs in the same invocation chain as the one that called `fetch`, so the span is still active and can be ended. You don't cross a "lost" boundary in the common case.
+- **Document load / navigation**: Handled by the document-load instrumentation; the span covers the load and its natural async work.
+
+So for "user did something → app called fetch → backend continued the trace," context is preserved **along the path that the instrumentation controls**. You don't need Zone for that.
+
+**Use full mode when:** You want real browser spans (and optional Web Vitals, errors, etc.) and your critical paths are "start → fetch/XHR → done" or "navigation."
+
+#### 3. Explicit `trace()` for Critical Paths
+
+When you have a flow that **does** cross boundaries where context would be lost (e.g., "click → setTimeout → fetch → update UI"), you can wrap the whole logical operation in **one** `trace()`:
+
+```typescript
+import { trace } from 'autotel-web'
+
+const handleConvert = trace(ctx => async () => {
+  setLoading(true)
+  await new Promise(r => setTimeout(r, 0))  // context still inside this trace()
+  const res = await fetch('/api/convert', { ... })
+  const data = await res.json()
+  setResult(data)
+  setLoading(false)
+})
+```
+
+Because the entire flow is inside a single `trace()` call, the fetch call runs "under" that logical span; the fetch instrumentation will see the active context (in full mode) or at least the header injection (in lean mode) keeps the same trace ID on the request. You don't need Zone to keep context inside that one async function.
+
+**Use explicit `trace()` when:** You have a clear "one user action → one chain of async work" and you're okay wrapping that chain once.
+
+### Summary: Zone.js vs autotel-web
+
+| Need | Zone.js | autotel-web approach |
+|------|--------|------------------------|
+| Trace from browser to backend | Not required | Lean mode: inject `traceparent`; backend continues trace. |
+| Real browser spans (navigation, fetch, Web Vitals) | Not required for the common path | Full mode: instrument fetch/XHR and document load so context is preserved on the wire and in the main async chain. |
+| Context across arbitrary async (setTimeout, third‑party callbacks) | Helps | Explicit `trace()` around the whole flow; or accept best-effort. |
+| Small bundle, no global patching | N/A | Lean mode is ~1.6 KB; full mode avoids Zone. |
+| Fewer framework/tooling issues | N/A | No Zone dependency. |
+
+**Bottom line:** You might need Zone.js if you want "current span" to follow **every** async boundary with no explicit wrapping. autotel-web avoids Zone by: (1) not creating real browser spans in lean mode, (2) in full mode, instrumenting the boundaries that matter for tracing (fetch, XHR, load), and (3) offering an explicit `trace()` so you can wrap critical paths once. That covers most real-world needs without Zone's pitfalls.
+
 ## Examples
 
 See the `apps/` directory at the repository root for complete working examples:

package/dist/chunk-FYEN2WET.js

@@ -0,0 +1,89 @@
+// src/traceparent.ts
+function randomHex(bytes) {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  return Array.from(buffer).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function generateTraceId() {
+  return randomHex(16);
+}
+function generateSpanId() {
+  return randomHex(8);
+}
+function createTraceparent(traceId, _parentSpanId) {
+  const tid = traceId ?? generateTraceId();
+  const sid = generateSpanId();
+  const flags = "01";
+  return `00-${tid}-${sid}-${flags}`;
+}
+function parseTraceparent(traceparent) {
+  const parts = traceparent.split("-");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const [version, traceId, spanId, flags] = parts;
+  if (version.length !== 2 || traceId.length !== 32 || spanId.length !== 16 || flags.length !== 2) {
+    return null;
+  }
+  return { version, traceId, spanId, flags };
+}
+
+// src/functional.ts
+var currentContext;
+function trace(fn) {
+  const expectsContext = isFactoryPattern(fn);
+  if (expectsContext) {
+    return ((...args) => {
+      const ctx = createContext();
+      const actualFn = fn(ctx);
+      return actualFn(...args);
+    });
+  }
+  return fn;
+}
+function isFactoryPattern(fn) {
+  if (typeof fn !== "function") return false;
+  const fnStr = fn.toString();
+  const contextHints = ["ctx", "context", "traceContext"];
+  return contextHints.some((hint) => {
+    const regex = new RegExp(`^\\s*(?:async\\s+)?(?:function\\s*)?\\(?\\s*${hint}\\s*[,)]`);
+    return regex.test(fnStr);
+  });
+}
+function createContext() {
+  const traceparent = createTraceparent();
+  const parsed = parseTraceparent(traceparent);
+  if (!parsed) {
+    return {
+      traceId: "",
+      spanId: "",
+      correlationId: ""
+    };
+  }
+  const ctx = {
+    traceId: parsed.traceId,
+    spanId: parsed.spanId,
+    correlationId: parsed.traceId
+  };
+  currentContext = ctx;
+  return ctx;
+}
+function getActiveContext() {
+  return currentContext;
+}
+function getTraceparent() {
+  return createTraceparent();
+}
+function extractContext(traceparent) {
+  const parsed = parseTraceparent(traceparent);
+  if (!parsed) return void 0;
+  return {
+    traceId: parsed.traceId,
+    spanId: parsed.spanId,
+    correlationId: parsed.traceId
+  };
+}
+
+export { createTraceparent, extractContext, generateSpanId, generateTraceId, getActiveContext, getTraceparent, parseTraceparent, trace };
+//# sourceMappingURL=chunk-FYEN2WET.js.map
+//# sourceMappingURL=chunk-FYEN2WET.js.map

package/dist/chunk-FYEN2WET.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/traceparent.ts","../src/functional.ts"],"names":[],"mappings":"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","file":"chunk-FYEN2WET.js","sourcesContent":["/**\n * Minimal W3C Trace Context implementation for browser\n *\n * Generates traceparent headers in the W3C format:\n * traceparent: 00-{trace-id}-{span-id}-{flags}\n *\n * No OpenTelemetry dependencies - just crypto.getRandomValues()\n */\n\n/**\n * Generate random hex string of specified byte length\n */\nfunction randomHex(bytes: number): string {\n  const buffer = new Uint8Array(bytes);\n  crypto.getRandomValues(buffer);\n  return Array.from(buffer)\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('');\n}\n\n/**\n * Generate a random 128-bit (16 byte) trace ID\n * @returns 32 character hex string\n */\nexport function generateTraceId(): string {\n  return randomHex(16); // 16 bytes = 32 hex chars\n}\n\n/**\n * Generate a random 64-bit (8 byte) span ID\n * @returns 16 character hex string\n */\nexport function generateSpanId(): string {\n  return randomHex(8); // 8 bytes = 16 hex chars\n}\n\n/**\n * Create a W3C traceparent header value\n *\n * Format: version-traceId-spanId-flags\n * - version: 00 (W3C Trace Context spec)\n * - traceId: 128-bit hex (32 chars)\n * - spanId: 64-bit hex (16 chars)\n * - flags: 01 (sampled)\n *\n * @param traceId - Optional existing trace ID (for continuing traces)\n * @param parentSpanId - Optional parent span ID (unused in browser, included for API compat)\n * @returns W3C traceparent header value\n *\n * @example\n * ```typescript\n * const header = createTraceparent()\n * // \"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01\"\n * ```\n */\nexport function createTraceparent(\n  traceId?: string,\n  _parentSpanId?: string\n): string {\n  const tid = traceId ?? generateTraceId();\n  const sid = generateSpanId();\n  const flags = '01'; // sampled=1\n\n  return `00-${tid}-${sid}-${flags}`;\n}\n\n/**\n * Parse a traceparent header value\n * Useful for extracting trace context from incoming headers\n *\n * @param traceparent - W3C traceparent header value\n * @returns Parsed components or null if invalid\n *\n * @example\n * ```typescript\n * const parsed = parseTraceparent('00-4bf92f...0e4736-00f067...902b7-01')\n * console.log(parsed?.traceId) // \"4bf92f...0e4736\"\n * ```\n */\nexport function parseTraceparent(traceparent: string): {\n  version: string;\n  traceId: string;\n  spanId: string;\n  flags: string;\n} | null {\n  const parts = traceparent.split('-');\n\n  if (parts.length !== 4) {\n    return null;\n  }\n\n  const [version, traceId, spanId, flags] = parts;\n\n  // Validate format\n  if (\n    version.length !== 2 ||\n    traceId.length !== 32 ||\n    spanId.length !== 16 ||\n    flags.length !== 2\n  ) {\n    return null;\n  }\n\n  return { version, traceId, spanId, flags };\n}\n","/**\n * Minimal functional API for browser tracing\n *\n * These are DX wrappers that DON'T create real browser spans.\n * The real spans and timing happen on the backend via Autotel.\n *\n * The browser's job is just to propagate trace context via headers.\n */\n\nimport { createTraceparent, parseTraceparent } from './traceparent';\n\n/**\n * Minimal trace context (browser-side)\n *\n * This is a lightweight version that just holds IDs.\n * NO actual span object - the real span lives on the backend.\n */\nexport interface TraceContext {\n  /** Current trace ID (may be extracted from request) */\n  readonly traceId: string;\n  /** Current span ID (generated for this browser \"span\") */\n  readonly spanId: string;\n  /** Correlation ID (same as trace ID) */\n  readonly correlationId: string;\n}\n\n// Store current trace context (if any)\nlet currentContext: TraceContext | undefined;\n\n/**\n * Wrap a function with trace() for better DX\n *\n * **Important:** This does NOT create real spans in the browser.\n * It's purely for API consistency. The real tracing happens on the backend.\n *\n * The traceparent header is automatically injected by init() on fetch/XHR calls.\n *\n * @example Basic usage\n * ```typescript\n * const fetchUser = trace(async (id: string) => {\n *   const response = await fetch(`/api/users/${id}`)\n *   return response.json()\n * })\n * ```\n *\n * @example With context (for accessing trace IDs)\n * ```typescript\n * const fetchUser = trace(ctx => async (id: string) => {\n *   console.log('Trace ID:', ctx.traceId)\n *   const response = await fetch(`/api/users/${id}`)\n *   return response.json()\n * })\n * ```\n */\nexport function trace<T extends (...args: any[]) => any>(\n  fn: T | ((ctx: TraceContext) => T)\n): T {\n  // Check if function expects a context parameter (factory pattern)\n  const expectsContext = isFactoryPattern(fn);\n\n  if (expectsContext) {\n    // Factory pattern: trace(ctx => async (data) => ...)\n    return ((...args: any[]) => {\n      // Generate a new trace context for this call\n      const ctx = createContext();\n\n      // Call factory to get the actual function\n      const actualFn = (fn as (ctx: TraceContext) => T)(ctx);\n\n      // Execute the function\n      return actualFn(...args);\n    }) as T;\n  }\n\n  // Direct pattern: trace(async (data) => ...)\n  // Just return the function as-is since headers are auto-injected\n  return fn as T;\n}\n\n/**\n * Check if a function expects a context parameter (factory pattern)\n */\nfunction isFactoryPattern(fn: unknown): boolean {\n  if (typeof fn !== 'function') return false;\n\n  const fnStr = fn.toString();\n\n  // Look for common parameter names that indicate context\n  const contextHints = ['ctx', 'context', 'traceContext'];\n\n  return contextHints.some((hint) => {\n    // Match parameter name at start of function\n    const regex = new RegExp(`^\\\\s*(?:async\\\\s+)?(?:function\\\\s*)?\\\\(?\\\\s*${hint}\\\\s*[,)]`);\n    return regex.test(fnStr);\n  });\n}\n\n/**\n * Create a minimal trace context\n * Generates new IDs for this \"span\" (browser-side only)\n */\nfunction createContext(): TraceContext {\n  // Parse the current traceparent if we have one\n  // (This would come from SSR or previous span)\n  const traceparent = createTraceparent();\n  const parsed = parseTraceparent(traceparent);\n\n  if (!parsed) {\n    // Fallback if parsing fails\n    return {\n      traceId: '',\n      spanId: '',\n      correlationId: '',\n    };\n  }\n\n  const ctx: TraceContext = {\n    traceId: parsed.traceId,\n    spanId: parsed.spanId,\n    correlationId: parsed.traceId,\n  };\n\n  currentContext = ctx;\n  return ctx;\n}\n\n/**\n * Get the current trace context (if any)\n *\n * @returns Current trace context or undefined\n *\n * @example\n * ```typescript\n * const ctx = getActiveContext()\n * if (ctx) {\n *   console.log('Trace ID:', ctx.traceId)\n * }\n * ```\n */\nexport function getActiveContext(): TraceContext | undefined {\n  return currentContext;\n}\n\n/**\n * Manual helper to create a traceparent header\n *\n * Useful if you need to manually set headers or disable auto-instrumentation.\n *\n * @returns W3C traceparent header value\n *\n * @example\n * ```typescript\n * import { init, getTraceparent } from 'autotel-web'\n *\n * // Disable auto-instrumentation\n * init({ service: 'my-app', instrumentFetch: false })\n *\n * // Manually inject headers\n * fetch('/api/data', {\n *   headers: {\n *     'traceparent': getTraceparent()\n *   }\n * })\n * ```\n */\nexport function getTraceparent(): string {\n  return createTraceparent();\n}\n\n/**\n * Extract trace context from a traceparent header\n *\n * Useful for SSR scenarios where you want to continue a trace from the server.\n *\n * @param traceparent - W3C traceparent header value\n * @returns Parsed trace context or undefined if invalid\n *\n * @example\n * ```typescript\n * // In an SSR handler\n * const traceparent = request.headers.get('traceparent')\n * if (traceparent) {\n *   const ctx = extractContext(traceparent)\n *   console.log('Continuing trace:', ctx?.traceId)\n * }\n * ```\n */\nexport function extractContext(traceparent: string): TraceContext | undefined {\n  const parsed = parseTraceparent(traceparent);\n  if (!parsed) return undefined;\n\n  return {\n    traceId: parsed.traceId,\n    spanId: parsed.spanId,\n    correlationId: parsed.traceId,\n  };\n}\n"]}

package/dist/full.d.ts

@@ -0,0 +1,126 @@
+import { context } from '@opentelemetry/api';
+import { SpanProcessor, Sampler } from '@opentelemetry/sdk-trace-base';
+import { P as PrivacyConfig } from './functional-04Wr-1U_.js';
+export { T as TraceContext, e as extractContext, g as getActiveContext, a as getTraceparent, t as trace } from './functional-04Wr-1U_.js';
+
+/**
+ * Full browser tracing with OpenTelemetry SDK
+ *
+ * Single install: npm install autotel-web. Import from 'autotel-web/full'.
+ * No Zone.js - uses default context manager. Async context propagation is best-effort.
+ *
+ * @see https://github.com/open-telemetry/semantic-conventions/issues/3385 (http.client.network_timing)
+ */
+
+interface AutotelWebFullConfig {
+    /** Service name for the browser application */
+    service: string;
+    /**
+     * OTLP endpoint URL for trace export (e.g. https://api.example.com/v1/traces).
+     * If not set, no export (spans still created; use spanProcessor for custom export).
+     */
+    endpoint?: string;
+    /**
+     * Custom span processor(s). If provided, used instead of default BatchSpanProcessor + OTLP exporter.
+     * When endpoint is set, this is ignored.
+     */
+    spanProcessor?: SpanProcessor;
+    /**
+     * Sample rate 0–1. Default 1.0. Use e.g. 0.1 in production.
+     */
+    sampleRate?: number;
+    /** Custom sampler. If set, sampleRate is ignored. */
+    sampler?: Sampler;
+    /** Enable document load / navigation spans. @default true */
+    captureNavigation?: boolean;
+    /** Enable fetch instrumentation. @default true */
+    captureFetch?: boolean;
+    /** Enable XMLHttpRequest instrumentation. @default true */
+    captureXHR?: boolean;
+    /**
+     * Emit http.client.network_timing events from Resource Timing API.
+     * @default true
+     */
+    captureNetworkTiming?: boolean;
+    /**
+     * Copy original HTTP span attributes onto network_timing event for backends that need them.
+     * @default false
+     */
+    copyHttpSpanAttributesToEvent?: boolean;
+    /** Optional user interaction (click) spans. */
+    userInteraction?: {
+        enabled: boolean;
+        /** CSS selectors for elements to track (e.g. ['button', '[data-track]']). Default: ['button', 'a'] */
+        selectors?: string[];
+    };
+    /**
+     * Record unhandled errors (window.onerror, unhandledrejection) on active span or create unhandled_error span.
+     * @default true
+     */
+    captureErrors?: boolean;
+    /**
+     * Capture Web Vitals (LCP, INP, CLS, FCP, TTFB) and report as attributes on a web_vitals span.
+     * @default true
+     */
+    captureWebVitals?: boolean;
+    /**
+     * Options for Web Vitals. reportAllChanges: pass through to web-vitals (default false for stability).
+     */
+    webVitals?: {
+        reportAllChanges?: boolean;
+    };
+    /**
+     * Capture long tasks (main thread blocking >= 50ms) as long_task spans. Opt-in; can be noisy.
+     * @default false
+     */
+    captureLongTasks?: boolean;
+    /** Privacy controls (origin filtering, DNT, GPC). Applied to which requests get traced. */
+    privacy?: PrivacyConfig;
+    /** Enable debug logging. @default false */
+    debug?: boolean;
+}
+/**
+ * Initialize full browser tracing (spans + optional export).
+ *
+ * Call once, client-side only. Uses OpenTelemetry WebTracerProvider; no Zone.js.
+ *
+ * @example
+ * ```ts
+ * import { initFull } from 'autotel-web/full'
+ * initFull({
+ *   service: 'my-app',
+ *   endpoint: 'https://api.example.com/v1/traces',
+ *   sampleRate: 0.1,
+ *   captureNetworkTiming: true,
+ *   userInteraction: { enabled: true, selectors: ['button', '[data-track]'] }
+ * })
+ * ```
+ */
+declare function initFull(config: AutotelWebFullConfig): void;
+/**
+ * Create a span with the current context (full mode).
+ */
+declare function span<T>(name: string, fn: (s: {
+    setAttribute: (k: string, v: string | number | boolean) => void;
+    end: () => void;
+}) => T): T;
+/**
+ * Set attribute on the active span (full mode).
+ */
+declare function setAttribute(key: string, value: string | number | boolean): void;
+/**
+ * Add an event to the active span (full mode).
+ */
+declare function addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+/**
+ * Run a function with the given context (for manual async propagation in full mode).
+ */
+declare function runWithContext<T>(ctx: ReturnType<typeof context.active>, fn: () => T): T;
+
+/**
+ * Reset full initialization state (for testing).
+ * @internal
+ */
+declare function resetFullForTesting(): void;
+
+export { type AutotelWebFullConfig, addEvent, initFull, resetFullForTesting, runWithContext, setAttribute, span };