@scalebun-release/web 2.2.2

package/dist/features/journey/uiState.js

@@ -0,0 +1,158 @@
+/**
+ * UI STATE AT INTERACTION TIME — which visual surface the visitor was actually looking at.
+ *
+ * A page is not just `/products`. It is `/products` with the cart drawer shut, or with it open, or
+ * with the reviews tab selected. Those are different interaction surfaces, and a click on one must
+ * never be counted on another: heat from the open drawer painted over the closed layout is a picture
+ * of something that never existed.
+ *
+ * WHAT WAS WRONG WITH THE PREVIOUS SHAPE. State was captured as an opaque set of the things that
+ * happened to be OPEN — `menu|dialog`, sorted and joined. Two consequences:
+ *
+ *   1. `sidebar = closed` was not representable. Absence meant "nothing open", which conflates a shut
+ *      sidebar with a page that has no sidebar. But the click that OPENS a drawer belongs to the
+ *      closed state — that is what the visitor saw when they reached for it — so the closed value has
+ *      to exist to receive it.
+ *   2. It could not be queried by dimension. Asking for `sidebar=open` meant matching the whole
+ *      signature, so every unrelated dimension had to match too and the buckets fragmented
+ *      combinatorially.
+ *
+ * THE SHAPE NOW: `name:value` pairs, sorted, joined with `;`. Still ONE short string on the wire — no
+ * new field — but the backend can split it and match one dimension without constraining the others.
+ *
+ * DELIBERATELY NARROW, because every byte here is eager. Only `aria-expanded` (read in BOTH states,
+ * which is what makes "closed" a value rather than an absence) and `dialog` (likewise). No
+ * `aria-selected`, no `aria-current`, no `details` — those were measured at ~90 B of bundle for
+ * dimensions the host can declare explicitly for free. No class-name guessing at any price: `.is-open`
+ * is right on some sites and silently wrong on others, and a wrong state key partitions clicks into
+ * buckets that correspond to nothing.
+ *
+ * Anything the platform does not express is `setUiState`'s job, and an explicit dimension WINS for the
+ * same name — a heuristic that silently overrode a declaration would make the API pointless.
+ */
+/** Explicit host-declared state, merged over automatic detection. */
+const explicit = new Map();
+/**
+ * `;` and `:` are the wire separators, so they cannot appear inside a name or value, and the length is
+ * bounded. Names and values are IDENTIFIERS, not content: they become query keys in the dashboard, so
+ * a value carrying a person's name would put user data into an aggregation key.
+ */
+const clean = (s) => typeof s === 'string' ? s.replace(/[;:|]/g, '').trim().slice(0, 32) : '';
+/** Declare a UI state dimension the DOM does not express. */
+export function setUiState(name, value) {
+    const n = clean(name);
+    const v = clean(value);
+    if (n && v)
+        explicit.set(n, v);
+}
+/**
+ * Stop reporting a dimension — or, with no name, every declared dimension.
+ *
+ * Later interactions carry no value for it, which is not the same as carrying a value. Clearing all is
+ * what a single-page app wants on route change: declarations from the previous screen would otherwise
+ * follow the visitor onto a surface where they mean nothing.
+ */
+export function clearUiState(name) {
+    if (name === undefined)
+        explicit.clear();
+    else
+        explicit.delete(clean(name));
+}
+/**
+ * The state signature for the interaction happening RIGHT NOW.
+ *
+ * Read synchronously inside the event handler, never reconstructed afterwards: by the time a menu has
+ * closed, the DOM no longer knows it was open when the click landed.
+ */
+/**
+ * DEVELOPMENT OVERLAYS ARE NOT THE PRODUCT.
+ *
+ * Measured on a real app: 59 of 60 captured keyframes reported exactly one state dimension, and it
+ * was `nextjs-dev-tools-menu` — the framework's own dev-tools button, the only element on the page
+ * exposing `aria-expanded` with an id. So the entire state lane was describing a development tool
+ * while the app's own drawer went unrecorded.
+ *
+ * WHY IT HAS TO BE EXCLUDED AT CAPTURE rather than filtered later. A dimension is part of the state
+ * KEY: `sidebar:closed` and `nextjs-dev-tools-menu:closed;sidebar:closed` are two different states,
+ * so leaving it in fragments every count. It also spends the 96-character budget — 28 of it — and
+ * sorts before most real names, so a page with several dimensions could lose a real one to make room
+ * for a dev tool.
+ *
+ * DELIBERATELY A PREFIX LIST, not a heuristic. Matching on class names or visibility was rejected
+ * elsewhere in this file for inventing states; the same objection applies to guessing at what is
+ * "probably a dev tool". These are exact, published names owned by the frameworks that inject them.
+ */
+const DEV_OVERLAY = /^(nextjs-|__next|vercel-live)/;
+/**
+ * A GENERATED ID IS NOT A NAME — it is a new dimension on every page load.
+ *
+ * Measured on production (joint web, 30 days): alongside `sidebar:open|closed`, the catalogue
+ * carried `headlessui-popover-button-v-0:closed;headlessui-popover-button-v-10:closed`. Those
+ * numbers are allocated by the component library in mount order, so the SAME control is a different
+ * dimension after a route change, a re-render, or one extra popover appearing earlier in the tree.
+ *
+ * The damage is not cosmetic. A dimension is part of the state KEY, so a wandering name fragments
+ * one control's counts across many states that each look real and none of which can be filtered on
+ * usefully — and it spends the 96-character budget while doing it. It then reaches the operator's
+ * state picker as a row named after a library's internal counter.
+ *
+ * SKIPPED, NOT RENAMED. There is no honest way to recover what that control is from the id, and
+ * inventing a name here is the same error this file rejects everywhere else. An app that wants the
+ * dimension names it instead — `data-scalebun-state` has always been the first thing read, and
+ * `data-testid` is now read before the id so the common case needs no new markup at all.
+ *
+ * `aria-label` is deliberately NOT a fallback. It is the control's visible, LOCALISED text, so the
+ * same control would be `القائمة` to one visitor and `Menu` to another and the two would never
+ * reconcile. Production still carries exactly that pair from the pre-`name:value` format.
+ *
+ * A prefix/shape list, not a heuristic, for the same reason DEV_OVERLAY is one: `:r0:` is React's
+ * own useId output, the rest are the published prefixes of the libraries that generate them.
+ */
+const GENERATED_ID = /^(headlessui-|radix-|mui-|:r[0-9a-z]*:|react-aria)/;
+export function uiStateSignature() {
+    const dims = new Map();
+    document.querySelectorAll('[aria-expanded],dialog').forEach((e) => {
+        const x = e.getAttribute('aria-expanded');
+        const v = x === 'true' || (x === null && e.hasAttribute('open')) ? 'open' : 'closed';
+        // `aria-controls` names the thing being controlled — the dimension — rather than the control
+        // doing the controlling. A dimension with no stable name is skipped: a generated one would
+        // fragment the same state across every page load.
+        /* FIRST CANDIDATE THAT YIELDS A USABLE NAME — a candidate that cleans away, or that is a
+           library-generated id, falls through to the next rather than aborting the element. Two bugs
+           were caught here by heatmap:statekey rather than by reading: `||` over RAW values let a
+           whitespace-only data-scalebun-state win and then clean away to nothing, losing the id that
+           would have named it; and testing GENERATED_ID after clean() cannot work, because clean
+           strips `:` and React's `:r7:` arrives as `r7`, which no honest pattern separates from a
+           dimension genuinely called `r7`. */
+        let n = '';
+        for (const r of [
+            e.getAttribute('data-scalebun-state'),
+            e.getAttribute('data-testid'),
+            e.getAttribute('aria-controls'),
+            e.id,
+        ]) {
+            if (r && !GENERATED_ID.test(r) && (n = clean(r)))
+                break;
+        }
+        if (n && !DEV_OVERLAY.test(n))
+            dims.set(n, v);
+    });
+    for (const [k, v] of explicit)
+        dims.set(k, v);
+    if (!dims.size)
+        return undefined;
+    /* SORTED, or the same surface produces different signatures depending on DOM order and every
+       count fragments into several that mean nothing. */
+    const pairs = [...dims.keys()]
+        .sort()
+        .map((k) => `${k}:${dims.get(k)}`);
+    let signature = '';
+    for (const pair of pairs) {
+        const next = signature ? `${signature};${pair}` : pair;
+        if (next.length > 96)
+            break;
+        signature = next;
+    }
+    return signature || undefined;
+}
+//# sourceMappingURL=uiState.js.map

package/dist/features/journey/uiState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uiState.js","sourceRoot":"","sources":["../../../src/features/journey/uiState.ts"],"names":[],"mappings":"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"}

package/dist/features/manifest.d.ts

@@ -0,0 +1,41 @@
+import type { IFeature } from '@scalebun/sdk-contracts';
+import type { Capabilities } from '../core/capabilities.js';
+/**
+ * The feature registry source. Each capture feature vertical (errors, network, webVitals, replay,
+ * …) appends its instance here — this is the append-only seam from WEB-SDK-PLAN.md §1. Bootstrap
+ * only registers a feature when config.features[name] !== false (replay is off by default).
+ */
+export declare const FEATURES: IFeature[];
+/**
+ * P5a — features that are OFF BY DEFAULT, loaded only when a host turns one on.
+ *
+ * WHY THESE FIVE AND NOT OTHERS: `resolveConfig` defaults `replay`, `inbox`, `profiler`, `watchdog`
+ * and `inapp2` to `false`. Every other feature defaults to `true`, so lazy-loading it would trade
+ * eager bytes for a round trip on the path virtually every site takes — a bad exchange. These five are
+ * the only ones the typical site never uses, and they were nonetheless constructed and bundled into
+ * the eager core on every page load.
+ *
+ * MEASURED: removing their shells takes the eager core from 33,602 B to 32,219 B gzipped — **1,383 B**,
+ * which is 7× the headroom that existed before this change (190 B). That budget is what a minimal
+ * eager keyframe needs, and it did not exist until now.
+ *
+ * A dynamic `import()` here is what actually moves the bytes; a `() => new X()` factory would not,
+ * because the static import would still pull the module into the eager chunk.
+ *
+ * The cost is one round trip when a host opts in, paid during `activate()` before `setupAll` — so an
+ * enabled feature still sets up before the pipeline starts, exactly as an eager one does. The ordering
+ * F-VIT depends on is unchanged.
+ */
+export declare const OPTIONAL_FEATURES: Record<string, () => Promise<IFeature>>;
+/**
+ * The MINIMAL capability each feature fundamentally needs — bootstrap skips a feature whose required
+ * capabilities are absent in the current runtime (e.g. DOM features on the edge). CONSERVATIVE by
+ * design: gate on the core capability only, so a browser missing an optional API (say
+ * IntersectionObserver) still registers DOM features (they degrade internally) — browser behavior never
+ * changes. Only edge/worker runtimes (no DOM) filter the DOM features out. `network`-only features
+ * (analytics, config) are the edge-eligible surface. See core/capabilities.ts.
+ */
+export declare const FEATURE_CAPS: Record<string, Array<keyof Capabilities>>;
+/** A feature's required capabilities. Unmapped (future) features default to DOM — browser-only, conservative. */
+export declare function featureRequirements(name: string): Array<keyof Capabilities>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/features/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/features/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAezD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,EAc9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,CAMrE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,YAAY,CAAC,CAmBlE,CAAC;AAEF,iHAAiH;AACjH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,YAAY,CAAC,CAE3E"}

package/dist/features/manifest.js

@@ -0,0 +1,93 @@
+import { AnalyticsFeature } from './analytics/AnalyticsFeature.js';
+import { ConfigFeature } from './config/ConfigFeature.js';
+import { ErrorsFeature } from './errors/ErrorsFeature.js';
+import { NetworkFeature } from './network/NetworkFeature.js';
+import { WebVitalsFeature } from './webVitals/WebVitalsFeature.js';
+import { PerformanceFeature } from './performance/PerformanceFeature.js';
+import { JourneyFeature } from './journey/JourneyFeature.js';
+import { ConsoleFeature } from './console/ConsoleFeature.js';
+import { BugReportFeature } from './bugreport/BugReportFeature.js';
+import { CrashFeature } from './crash/CrashFeature.js';
+import { EngageFeature } from './engage/EngageFeature.js';
+import { WebPerfFeature } from './webperf/WebPerfFeature.js';
+import { ExitIntentFeature } from './exit-intent/ExitIntentFeature.js';
+/**
+ * The feature registry source. Each capture feature vertical (errors, network, webVitals, replay,
+ * …) appends its instance here — this is the append-only seam from WEB-SDK-PLAN.md §1. Bootstrap
+ * only registers a feature when config.features[name] !== false (replay is off by default).
+ */
+export const FEATURES = [
+    new ConfigFeature(), // F-CFG flags/config/rollouts/experiments (early: cache loads sync in setup)
+    new AnalyticsFeature(), // F-ANL product-analytics + revenue lane → POST /batch (Event)
+    new ErrorsFeature(), // F-ERR
+    new NetworkFeature(), // F-NET
+    new WebVitalsFeature(), // F-VIT
+    new WebPerfFeature(), // web RUM: page-load + FPS + LoAF (F-PERFWEB)
+    new PerformanceFeature(), // performance traces (F-PERF)
+    new JourneyFeature(), // F-JRN
+    new ConsoleFeature(), // console breadcrumbs (F-CON)
+    new BugReportFeature(), // bug-report widget (F-BUG)
+    new CrashFeature(), // crash detection: ReportingObserver + session-liveness recovery (F-CRASH)
+    new EngageFeature(), // surveys/NPS — shell in core, runtime lazy-loaded when a campaign is active (F-ENG)
+    new ExitIntentFeature(), // exit-intent CRO detector → $exit_intent + signal (F-EXIT, opt-in)
+];
+/**
+ * P5a — features that are OFF BY DEFAULT, loaded only when a host turns one on.
+ *
+ * WHY THESE FIVE AND NOT OTHERS: `resolveConfig` defaults `replay`, `inbox`, `profiler`, `watchdog`
+ * and `inapp2` to `false`. Every other feature defaults to `true`, so lazy-loading it would trade
+ * eager bytes for a round trip on the path virtually every site takes — a bad exchange. These five are
+ * the only ones the typical site never uses, and they were nonetheless constructed and bundled into
+ * the eager core on every page load.
+ *
+ * MEASURED: removing their shells takes the eager core from 33,602 B to 32,219 B gzipped — **1,383 B**,
+ * which is 7× the headroom that existed before this change (190 B). That budget is what a minimal
+ * eager keyframe needs, and it did not exist until now.
+ *
+ * A dynamic `import()` here is what actually moves the bytes; a `() => new X()` factory would not,
+ * because the static import would still pull the module into the eager chunk.
+ *
+ * The cost is one round trip when a host opts in, paid during `activate()` before `setupAll` — so an
+ * enabled feature still sets up before the pipeline starts, exactly as an eager one does. The ordering
+ * F-VIT depends on is unchanged.
+ */
+export const OPTIONAL_FEATURES = {
+    replay: async () => new (await import('./replay/ReplayFeature.js')).ReplayFeature(),
+    inbox: async () => new (await import('./inbox/InboxFeature.js')).InboxFeature(),
+    profiler: async () => new (await import('./profiler/ProfilerFeature.js')).ProfilerFeature(),
+    watchdog: async () => new (await import('./watchdog/WatchdogFeature.js')).WatchdogFeature(),
+    inapp2: async () => new (await import('./inapp/InApp2Feature.js')).InApp2Feature(),
+};
+/**
+ * The MINIMAL capability each feature fundamentally needs — bootstrap skips a feature whose required
+ * capabilities are absent in the current runtime (e.g. DOM features on the edge). CONSERVATIVE by
+ * design: gate on the core capability only, so a browser missing an optional API (say
+ * IntersectionObserver) still registers DOM features (they degrade internally) — browser behavior never
+ * changes. Only edge/worker runtimes (no DOM) filter the DOM features out. `network`-only features
+ * (analytics, config) are the edge-eligible surface. See core/capabilities.ts.
+ */
+export const FEATURE_CAPS = {
+    config: ['network'],
+    analytics: ['network'],
+    errors: ['dom'],
+    network: ['dom'],
+    webVitals: ['performanceObserver'],
+    webPerf: ['performanceObserver'],
+    performance: ['performance'],
+    journey: ['dom'],
+    console: ['dom'],
+    bugReport: ['dom'],
+    crash: ['dom'],
+    engage: ['dom'],
+    inbox: ['dom'],
+    profiler: ['dom'],
+    watchdog: ['performanceObserver'],
+    exitIntent: ['dom'],
+    inapp2: ['dom'],
+    replay: ['dom'],
+};
+/** A feature's required capabilities. Unmapped (future) features default to DOM — browser-only, conservative. */
+export function featureRequirements(name) {
+    return FEATURE_CAPS[name] ?? ['dom'];
+}
+//# sourceMappingURL=manifest.js.map

package/dist/features/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/features/manifest.ts"],"names":[],"mappings":"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"}

package/dist/features/network/NetworkFeature.d.ts

@@ -0,0 +1,60 @@
+/**
+ * F-NET — captures fetch + XHR (+ WebSocket/SSE/beacon) requests and emits contract `network` items
+ * onto the unified pipeline. Metadata by default (method/url/status/duration/sizes + N0 failure
+ * taxonomy/slow/route); bodies/headers are off by default (privacy) and an opt-in (N4). Self-excludes
+ * the SDK's own ingestion traffic. Thin shell: interceptors + normalize + stats.
+ */
+import type { IFeature, FeatureContext } from '@scalebun/sdk-contracts';
+import type { NetProtocol, NetFailure } from './types.js';
+/** Self-observability snapshot (N5) — the SDK's own network-capture health. */
+export interface NetworkStats {
+    /** emitted to the pipeline */
+    captured: number;
+    /** count per protocol */
+    byProtocol: Record<NetProtocol, number>;
+    /** count per failure class (successful requests aren't counted here) */
+    byFailure: Record<NetFailure, number>;
+    /** dropped by third-party filter / denyUrls / sampling / beforeSend(null) */
+    dropped: number;
+    /** of `dropped`, how many were known telemetry beacons -- so the filter is observable */
+    droppedThirdParty: number;
+    /** kept by the success-sampler (failed/slow are always kept, counted in `captured`) */
+    sampledIn: number;
+    /** how many emitted items carried captured bodies */
+    bodiesCaptured: number;
+}
+export declare class NetworkFeature implements IFeature {
+    readonly name = "network";
+    private active;
+    private uninstalls;
+    private slowMs;
+    private sampleRate;
+    private dedupMs;
+    private deduper?;
+    private denyUrls;
+    private keepThirdParty;
+    private thirdPartyHosts;
+    private beforeSend?;
+    private readonly timingIndex;
+    private timingOn;
+    /** N4 — resolved body-capture options when `captureBodies` is on; undefined ⇒ bodies off. */
+    private bodyOpts?;
+    private readonly counters;
+    /** Self-observability — the SDK's own network-capture health. */
+    stats(): NetworkStats;
+    get isActive(): boolean;
+    setup(ctx: FeatureContext): void;
+    /** Normalize → third-party/denyUrls gate → beforeSend → emit. The single emit point. */
+    private handle;
+    private finalize;
+    /** Tiny core-side gate: only the cheapest signals, so the GraphQL chunk loads on demand. */
+    private maybeGraphql;
+    private emit;
+    /** Final emit. With dedup on (opt-in), a burst of identical requests collapses into one trailing
+     *  `repeat` item (see {@link Deduper}); the first of the burst still emits immediately. */
+    private emitItem;
+    /** Update self-observability counters from an item about to be emitted. */
+    private record;
+    teardown(): void;
+}
+//# sourceMappingURL=NetworkFeature.d.ts.map

package/dist/features/network/NetworkFeature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NetworkFeature.d.ts","sourceRoot":"","sources":["../../../src/features/network/NetworkFeature.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAWxE,OAAO,KAAK,EAAc,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEnE,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACxC,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACtC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,yFAAyF;IACzF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;CACxB;AAMD,qBAAa,cAAe,YAAW,QAAQ;IAC7C,QAAQ,CAAC,IAAI,aAAa;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,UAAU,CAAC,CAA4C;IAC/D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAS;IACzB,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,CAA2D;IAC5E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAQvB;IAEF,iEAAiE;IACjE,KAAK,IAAI,YAAY;IAYrB,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAwFhC,wFAAwF;IACxF,OAAO,CAAC,MAAM;IAwCd,OAAO,CAAC,QAAQ;IAmBhB,4FAA4F;IAC5F,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,IAAI;IAiCZ;+FAC2F;IAC3F,OAAO,CAAC,QAAQ;IAShB,2EAA2E;IAC3E,OAAO,CAAC,MAAM;IASd,QAAQ,IAAI,IAAI;CASjB"}

package/dist/features/network/NetworkFeature.js

@@ -0,0 +1,260 @@
+/**
+ * F-NET — captures fetch + XHR (+ WebSocket/SSE/beacon) requests and emits contract `network` items
+ * onto the unified pipeline. Metadata by default (method/url/status/duration/sizes + N0 failure
+ * taxonomy/slow/route); bodies/headers are off by default (privacy) and an opt-in (N4). Self-excludes
+ * the SDK's own ingestion traffic. Thin shell: interceptors + normalize + stats.
+ */
+import { installFetch } from './fetchInterceptor.js';
+import { installXhr } from './xhrInterceptor.js';
+import { toNetworkItem } from './normalize.js';
+import { makeTraceInjector } from './tracing.js';
+import { DEFAULT_SLOW_MS } from './classify.js';
+import { ResourceTimingIndex } from './timing.js';
+import { shouldKeep } from './sampler.js';
+import { Deduper } from './dedup.js';
+import { isThirdPartyBeacon } from './thirdParty.js';
+function matchUrl(pat, url) {
+    return typeof pat === 'string' ? url.includes(pat) : pat.test(url);
+}
+export class NetworkFeature {
+    constructor() {
+        this.name = 'network';
+        this.active = false;
+        this.uninstalls = [];
+        this.slowMs = DEFAULT_SLOW_MS;
+        this.sampleRate = 1;
+        this.dedupMs = 0; // opt-in (network.dedupWindowMs); 0 = off
+        this.denyUrls = [];
+        this.keepThirdParty = false;
+        this.timingIndex = new ResourceTimingIndex();
+        this.timingOn = false;
+        this.counters = {
+            captured: 0,
+            byProtocol: { http: 0, ws: 0, sse: 0, beacon: 0 },
+            byFailure: { http_4xx: 0, http_5xx: 0, network_error: 0, timeout: 0, cors: 0, abort: 0 },
+            dropped: 0,
+            droppedThirdParty: 0,
+            sampledIn: 0,
+            bodiesCaptured: 0,
+        };
+    }
+    /** Self-observability — the SDK's own network-capture health. */
+    stats() {
+        return {
+            captured: this.counters.captured,
+            byProtocol: { ...this.counters.byProtocol },
+            byFailure: { ...this.counters.byFailure },
+            dropped: this.counters.dropped,
+            droppedThirdParty: this.counters.droppedThirdParty,
+            sampledIn: this.counters.sampledIn,
+            bodiesCaptured: this.counters.bodiesCaptured,
+        };
+    }
+    get isActive() {
+        return this.active;
+    }
+    setup(ctx) {
+        if (typeof window === 'undefined')
+            return;
+        const opts = ctx.networkOptions ?? {};
+        this.slowMs = opts.slowRequestMs ?? DEFAULT_SLOW_MS;
+        this.sampleRate = typeof opts.sampleRate === 'number' ? opts.sampleRate : 1;
+        // dedup is opt-in; read defensively so it works before the contract type formally lists it.
+        const dw = opts.dedupWindowMs;
+        this.dedupMs = typeof dw === 'number' && dw > 0 ? dw : 0;
+        if (this.dedupMs > 0) {
+            this.deduper = new Deduper(this.dedupMs, (item) => {
+                this.record(item);
+                ctx.emit(item);
+            }, () => {
+                this.counters.dropped++;
+            });
+        }
+        this.denyUrls = opts.denyUrls ?? [];
+        // Opt OUT, not in: the default is the useful one, and a team that genuinely wants to watch
+        // its own pixels can say so. `thirdPartyHosts` replaces the built-in list wholesale when set.
+        this.keepThirdParty = opts.captureThirdParty === true;
+        this.thirdPartyHosts = opts.thirdPartyHosts;
+        this.beforeSend = opts.beforeSend;
+        // N4 — body capture is opt-in (privacy). Resolve the cap/allowlist once; the heavy redaction +
+        // read logic lives in the lazy chunk. Cap is ceiling-enforced there too.
+        if (opts.captureBodies) {
+            this.bodyOpts = {
+                bodyMaxBytes: Math.min(Math.max(0, opts.bodyMaxBytes ?? 8192), 64 * 1024),
+                contentTypeAllowlist: opts.contentTypeAllowlist && opts.contentTypeAllowlist.length
+                    ? opts.contentTypeAllowlist
+                    : ['application/json', 'text/plain'],
+            };
+        }
+        // N1 — buffered ResourceTiming observer (DNS/TCP/TLS/TTFB/transferSize). Graceful no-op where
+        // the API is missing. The entry lands AFTER the response settles, so the merge is deferred.
+        this.timingOn = this.timingIndex.install();
+        const base = ctx.apiBaseUrl;
+        const isOwnUrl = (url) => !!base && url.startsWith(base);
+        const onRecord = (c) => this.handle(ctx, c);
+        // P4.3 — W3C traceparent injection for the allowlisted origins (FE→BE correlation handoff).
+        // ctx.traceOrigins is the resolved allowlist (same-origin by default; empty = tracing off).
+        //
+        // N5 cross-vertical seam (trace handoff): today Network MINTS a fresh trace per request (the
+        // makeTrace() inside makeTraceInjector). The end state is that when a Perf/RUM transaction is
+        // OPEN, the request joins THAT transaction's trace (one traceId across FE txn ↔ FE request ↔ BE
+        // span) and falls back to a per-request mint when none is open. The accessor shape the Perf
+        // engineer should expose (read-only, no Network→Perf import):
+        //
+        //   FeatureContext.getActiveTrace?: () => { traceId: string; parentSpanId: string } | null
+        //
+        // When present and non-null, makeTraceInjector should build the traceparent from it
+        // (`00-${traceId}-${childSpanId}-01`, a fresh child spanId) instead of minting a new traceId.
+        // Until that accessor lands, we KEEP the per-request mint (no behavior change).
+        // TODO(perf-seam): consume ctx.getActiveTrace() here once Perf provides it.
+        const injectTrace = makeTraceInjector(ctx.traceOrigins ?? []) ?? undefined;
+        this.uninstalls.push(installFetch(window, onRecord, isOwnUrl, injectTrace));
+        this.uninstalls.push(installXhr(window, onRecord, isOwnUrl, injectTrace));
+        // N3/N6 — WebSocket + SSE lifecycle + sendBeacon, all in ONE LAZY chunk (feature-detection +
+        // wiring live there, so core stays light). Default on; patched as soon as the chunk resolves.
+        const flags = {
+            ws: opts.trackWebSocket !== false,
+            sse: opts.trackSse !== false,
+            beacon: true,
+        };
+        const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+        void import('./intercept/streams.js')
+            .then((m) => {
+            if (this.active)
+                this.uninstalls.push(...m.installStreams(window, nav, onRecord, isOwnUrl, flags));
+        })
+            .catch(() => {
+            /* chunk failed to load — WS/SSE/beacon simply not tracked */
+        });
+        this.active = true;
+    }
+    /** Normalize → third-party/denyUrls gate → beforeSend → emit. The single emit point. */
+    handle(ctx, c) {
+        /**
+         * Telemetry never reaches the pipeline: anything sent with sendBeacon (whoever sent it — no
+         * response, nothing to score), and the known tracker hosts. These are about half of all web
+         * requests, so dropping them here saves the visitor the upload.
+         *
+         * The FULL rule — framework page payloads, static assets, non-web schemes too (requestKind in
+         * thirdParty.ts) — is applied by the backend at ingest, for every SDK version. It is not applied
+         * here on purpose: its patterns cost ~300 B of eager bundle (measured 2026-09-22), and what it
+         * would add over this subset is only upload bandwidth, never what is stored.
+         * Set `captureThirdParty: true` to keep everything.
+         */
+        if (!this.keepThirdParty &&
+            (c.protocol === 'beacon' || isThirdPartyBeacon(c.url, this.thirdPartyHosts))) {
+            this.counters.dropped++;
+            this.counters.droppedThirdParty++;
+            return;
+        }
+        if (this.denyUrls.some((p) => matchUrl(p, c.url))) {
+            this.counters.dropped++;
+            return;
+        }
+        // N1 — ResourceTiming lands just after settle. For http captures, defer one macrotask so the
+        // entry is available, then merge DNS/TCP/TLS/TTFB/transferSize. WS/SSE/beacon have no entry.
+        const proto = c.protocol ?? 'http';
+        if (this.timingOn && proto === 'http' && c.timing === undefined) {
+            setTimeout(() => {
+                if (!this.active)
+                    return;
+                const merged = this.timingIndex.match(c.url, c.startedAt);
+                if (merged.timing)
+                    c.timing = merged.timing;
+                if (merged.transferSize !== undefined && c.transferSize === undefined)
+                    c.transferSize = merged.transferSize;
+                this.finalize(ctx, c);
+            }, 0);
+            return;
+        }
+        this.finalize(ctx, c);
+    }
+    finalize(ctx, c) {
+        // N2/N4 — http captures may need GraphQL op-awareness and/or body capture, both in the LAZY
+        // chunk (a single pass reads the one-shot response clone once). Cheap inline gates the import so
+        // ordinary REST traffic with bodies off never loads it.
+        const proto = c.protocol ?? 'http';
+        const wantGraphql = proto === 'http' && c.graphql === undefined && this.maybeGraphql(c);
+        const wantBody = !!this.bodyOpts && proto === 'http';
+        if (wantGraphql || wantBody) {
+            import('./lazy.js')
+                .then((m) => m.enrichHttpCapture(c, { graphql: wantGraphql, body: wantBody ? this.bodyOpts : undefined }))
+                .catch(() => { })
+                .finally(() => {
+                if (this.active)
+                    this.emit(ctx, c);
+            });
+            return;
+        }
+        this.emit(ctx, c);
+    }
+    /** Tiny core-side gate: only the cheapest signals, so the GraphQL chunk loads on demand. */
+    maybeGraphql(c) {
+        if (c.method !== 'POST')
+            return false;
+        return /graphql/i.test(c.url) || (!!c.reqBody && c.reqBody.includes('query'));
+    }
+    emit(ctx, c) {
+        let item = toNetworkItem(c, { slowMs: this.slowMs });
+        // N5 — adaptive sampling: always keep failed/slow, deterministically thin successful requests to
+        // the base rate. Sampled-out items are dropped (counted), never emitted.
+        if (this.sampleRate < 1) {
+            const kept = shouldKeep({ failed: !!item.failure, slow: !!item.slow, key: `${c.url}|${c.startedAt}` }, this.sampleRate);
+            if (!kept) {
+                this.counters.dropped++;
+                return;
+            }
+            this.counters.sampledIn++;
+        }
+        if (this.beforeSend) {
+            try {
+                const out = this.beforeSend(item);
+                if (out == null) {
+                    this.counters.dropped++;
+                    return;
+                }
+                item = out;
+            }
+            catch {
+                /* a throwing host hook keeps the original item — never lose the capture */
+            }
+        }
+        // E1 (engage) — nudge the capture-signal bus on a genuine request failure (not a user-abort) so a
+        // `network_error`-triggered campaign can fire. Fire-and-forget; the signaller isolates listener throws.
+        if (item.failure && item.failure !== 'abort')
+            ctx.signal('network_error');
+        this.emitItem(ctx, item);
+    }
+    /** Final emit. With dedup on (opt-in), a burst of identical requests collapses into one trailing
+     *  `repeat` item (see {@link Deduper}); the first of the burst still emits immediately. */
+    emitItem(ctx, item) {
+        if (this.deduper) {
+            this.deduper.push(item); // record + ctx.emit happen via the Deduper's emit callback
+            return;
+        }
+        this.record(item);
+        ctx.emit(item);
+    }
+    /** Update self-observability counters from an item about to be emitted. */
+    record(item) {
+        this.counters.captured++;
+        const proto = item.protocol ?? 'http';
+        this.counters.byProtocol[proto]++;
+        const failure = item.failure;
+        if (failure)
+            this.counters.byFailure[failure]++;
+        if (item.request || item.response)
+            this.counters.bodiesCaptured++;
+    }
+    teardown() {
+        for (const u of this.uninstalls)
+            u();
+        this.uninstalls = [];
+        this.deduper?.dispose();
+        this.deduper = undefined;
+        this.timingIndex.teardown();
+        this.timingOn = false;
+        this.active = false;
+    }
+}
+//# sourceMappingURL=NetworkFeature.js.map