@fixback/sdk 0.2.0 → 0.4.0

package/README.md

@@ -8,9 +8,9 @@ launcher **only when it would**. Nothing renders when the origin isn't
 allowlisted or the Gate turns the visitor away, and if Fixback can't be reached
 the SDK stays completely silent — it never throws into the host page.
 
-Activating the launcher opens the **report overlay**: the Reporter picks a
-**Kind** (bug / improve / idea), writes a comment, optionally **points at the
-element** they mean, and hits **Send** — which captures a **masked screenshot**
+Activating the launcher opens the **report overlay**: the Reporter writes a
+comment, optionally **points at the element** they mean, and hits **Send** —
+which captures a **masked screenshot**
 of the current view, assembles the annotation, and submits it to Fixback. A
 successful send shows a confirmation; a refusal or an unreachable Fixback fails
 quietly, leaving the host page untouched.
@@ -64,6 +64,7 @@ global:
 | `target`         | `HTMLElement` | `document.body`            | Where to mount the launcher.                                            |
 | `reduceMotion`   | `boolean`     | `false`                    | Still the launcher's pulse and motion (see [The launcher](#the-launcher)). |
 | `autoCapture`    | `boolean`     | `true`                     | Automatic error capture — file uncaught errors with no prompt (see [Automatic error capture](#automatic-error-capture)). Set `false` to turn it off. |
+| `capture`        | `{ console?: boolean; network?: boolean }` | served per-project | Console / network Trace capture. **On by default** and normally governed per-project from the dashboard; set a stream here to override what the server serves (e.g. `{ network: false }`). A stream you leave unset follows the Project's setting. |
 
 None of the identity fields is a trust tier — Fixback derives trust on the
 server and never honours a self-declared tier.
@@ -78,11 +79,12 @@ fixback.destroy();
 
 The launcher is a bottom-right **Feedback** pill, and it stays out of the way:
 
-- **Hover-peek & tuck-away** — the pill's caret tucks it off-screen behind a
-  small edge nub. Hovering the bottom-right corner (or the nub) peeks it back;
-  clicking the nub — or pressing Enter/Space on it — brings it fully back, which
-  also covers pointers that can't hover (touch, keyboard). A brief hint appears
-  the first time it's tucked, pointing at the corner.
+- **Hover-peek & tuck-away** — the pill's chevron tucks it off-screen to the
+  right behind a small edge nub, pointing **right** to tuck away and flipping to
+  point **left** while tucked. Hovering the bottom-right corner (or the nub)
+  peeks it back, where clicking that same chevron — or the nub, or pressing
+  Enter/Space on the nub — restores the launcher, which also covers pointers that
+  can't hover (touch, keyboard).
 - **First-visit welcome** — a one-time toast greets a new visitor, drawing the
   eye with a gentle pulse. It shows once per publishable key per browser.
 - **Reduce motion** — pass `reduceMotion: true` to still the pulse and the
@@ -110,8 +112,8 @@ document.addEventListener(LAUNCH_EVENT, () => {
 
 The SDK's signature capability: **errors report themselves, with no prompt.** Two
 capture-phase global handlers (`error` + `unhandledrejection`) turn uncaught
-exceptions and unhandled promise rejections into `source: auto`, `Kind = bug`
-Feedback for the current session's reporter — carrying the same masked screenshot
+exceptions and unhandled promise rejections into `source: auto` Feedback
+(classified `Kind = bug` server-side) for the current session's reporter — carrying the same masked screenshot
 and trace buffer a manual report does, plus a per-session fingerprint. It is
 **on by default across every Gate**; pass `autoCapture: false` to turn it off.
 

package/dist/annotation.d.ts

@@ -66,7 +66,7 @@ export type Mark = ArrowMark | BoxMark | PenMark | TextMark;
 /**
  * The structured Annotation carried on a report's content (spec §D): the three
  * optional layers. Every field is optional — a report may carry any subset or
- * none (a bare Kind + comment is a valid Send).
+ * none (a bare comment is a valid Send).
  */
 export interface Annotation {
     readonly element?: SelectedElement;

package/dist/boot.d.ts

@@ -26,17 +26,37 @@ export interface IdentityInputs {
 export interface BootRequest extends IdentityInputs {
     readonly key: string;
 }
+/**
+ * The Project's effective console/network capture config, served on the boot answer
+ * (spec #122 §L; ticket #138). Each flag is the per-project master toggle ANDed with
+ * that stream's own toggle, so the SDK gates instrumentation on one boolean per
+ * stream. Optional on the wire: an older server that does not send it (or a
+ * malformed value) is treated as **capture on** — default-on, matching the server
+ * default — and `init` options override whatever is served.
+ */
+export interface CaptureConfig {
+    readonly console: boolean;
+    readonly network: boolean;
+    /**
+     * The Project's session-replay toggle (issue #189, ADR-0024). Optional on the
+     * wire: a server predating replay omits it, which — like the other streams —
+     * means **capture on**.
+     */
+    readonly replay?: boolean;
+}
 /**
  * The boot answer: whether this origin is allowlisted, the Project's Gate, the
- * caller's derived tier (`null` when a presented identity was refused), and
- * whether a submission would be accepted right now. The launcher shows only when
- * `canSubmit` is true.
+ * caller's derived tier (`null` when a presented identity was refused), whether a
+ * submission would be accepted right now, and the Project's capture config. The
+ * launcher shows only when `canSubmit` is true.
  */
 export interface BootAnswer {
     readonly originAllowed: boolean;
     readonly gate: ProjectGate;
     readonly tier: ReporterTier | null;
     readonly canSubmit: boolean;
+    /** The Project's console/network capture config; absent ⇒ default-on (#138). */
+    readonly capture?: CaptureConfig;
 }
 /** Join an API base URL with the boot path, tolerating a trailing slash. */
 export declare function bootEndpoint(apiUrl: string): string;

package/dist/breadcrumbs.d.ts

@@ -21,7 +21,20 @@
 /** Console-style severity a `console` crumb records. */
 export type BreadcrumbLevel = "log" | "info" | "warn" | "error" | "assert" | "debug";
 /** The kind of activity a crumb records. */
-export type BreadcrumbCategory = "console" | "navigation" | "fetch" | "xhr" | "ui.click" | "ui.input" | "error";
+export type BreadcrumbCategory = "console" | "navigation" | "fetch" | "xhr" | "beacon" | "ui.click" | "ui.input" | "error";
+/**
+ * Which browser API issued a captured network request (spec #122 §D, ticket #139).
+ * Every network crumb's `category` is one of these too, so a stream router and the
+ * read model agree on what is a network entry.
+ */
+export type NetworkApi = "fetch" | "xhr" | "beacon";
+/**
+ * A network request's failure classification (spec #122 §D, ticket #139). `ok` and
+ * the HTTP status classes come from a settled response; `network-error` / `timeout`
+ * / `aborted` from how a request failed; `opaque-cors` from a cross-origin response
+ * whose status is unreadable. The Network tab flags every non-`ok` outcome.
+ */
+export type NetworkOutcome = "ok" | "http-4xx" | "http-5xx" | "network-error" | "timeout" | "aborted" | "opaque-cors";
 /**
  * A crumb's structured detail. Deliberately narrow: there is **no** field for a
  * request/response body or an input value, so those can never be recorded.
@@ -36,56 +49,273 @@ export interface BreadcrumbData {
     readonly to?: string;
     readonly errorType?: string;
 }
-/** One entry in the trace buffer. */
+/**
+ * The type tag on a structured console argument (spec #122 §C, decision D7). A
+ * console call's arguments are preserved **type-tagged** rather than flattened to a
+ * string, so an object/array argument can be inspected in the Console tab rather
+ * than read as `[object Object]`: `string`/`number`/`bool`/`null` carry the value
+ * directly, `json` a depth-/byte-capped JSON-safe clone, and `error` an Error's
+ * `{ name, message, stack }`.
+ */
+export type ConsoleArgType = "string" | "number" | "bool" | "null" | "json" | "error";
+/**
+ * One structured console argument (spec #122 §C): a type tag plus a JSON-safe value.
+ * `v` is always serializable — a `json` arg is depth-, breadth-, and string-capped at
+ * assembly, and exotic values (bigint, symbol, function, circular refs) are rendered
+ * to safe text — so a console crumb can never carry an unserializable or unbounded
+ * value onto the wire.
+ */
+export interface ConsoleArg {
+    readonly t: ConsoleArgType;
+    readonly v: unknown;
+}
+/** A `file:line` source location (spec #122 §C) — where a console call was made. */
+export interface SourceLocation {
+    readonly file: string;
+    readonly line: number;
+}
+/**
+ * One entry in a trace stream. Alongside its semantic fields every entry carries a
+ * stable {@link id} and a high-res monotonic {@link mono} timestamp — both stamped
+ * by the buffer on `add` — so entries from the three independent streams order and
+ * cross-link exactly (spec #122 §B, decision D9). `timestamp` stays epoch ms.
+ */
 export interface Breadcrumb {
     readonly category: BreadcrumbCategory;
     readonly message?: string;
     readonly level?: BreadcrumbLevel;
     /** Epoch milliseconds when the crumb was recorded. */
     readonly timestamp: number;
+    /** A stable id, unique within the buffer — assigned on `add` when not already set. */
+    readonly id?: string;
+    /** A high-res monotonic timestamp (`performance.now()`) — assigned on `add`. */
+    readonly mono?: number;
     readonly data?: BreadcrumbData;
+    /**
+     * For a `console` crumb (spec #122 §C): the call's arguments preserved as
+     * structured, type-tagged values (see {@link ConsoleArg}), so the Console tab can
+     * render each argument expandably instead of a flattened string. `message` stays
+     * the one-line preview. Absent on non-console crumbs.
+     */
+    readonly args?: readonly ConsoleArg[];
+    /**
+     * For a `console` crumb (spec #122 §C): the `file:line` the call was made from,
+     * parsed best-effort from the call stack. Captured only for the levels that keep a
+     * source — `warn`/`error`/`assert` (ticket #159; see {@link SOURCE_CAPTURE_LEVELS}) —
+     * and only when the stack yields a usable location; a chatty app's `log`/`info`/`debug`
+     * omit it so the hot-page capture cost stays low. Absent on non-console crumbs.
+     */
+    readonly source?: SourceLocation;
+    /**
+     * For an auto-captured `error` crumb only (spec #122 §F): the ids of the entries
+     * immediately preceding the throw — a causal pointer into the same trace, so a
+     * machine-filed crash names its lead-up. Absent on every other crumb.
+     */
+    readonly causedBy?: readonly string[];
+    /**
+     * For a network crumb (`fetch` / `xhr` / `beacon`) — spec #122 §D, ticket #139.
+     * The rich request metadata the Network tab renders, lifted to the top level (the
+     * console-enrichment precedent) so the read model shapes each into a
+     * `NetworkTraceEntry`. **No field carries a request/response body or an arbitrary
+     * header** — `respSize` derives from the `content-length` response header only and
+     * `contentType` from `content-type`; nothing else is read. Absent on every other crumb.
+     */
+    readonly api?: NetworkApi;
+    /** The request method (network crumb) — e.g. `GET`, `POST`. */
+    readonly method?: string;
+    /** The scrubbed request URL (network crumb) — query dropped, path PII redacted. */
+    readonly url?: string;
+    /** The final HTTP status (network crumb), when one was known; absent on a network error/beacon. */
+    readonly status?: number;
+    /** The HTTP status text (network crumb), when the response carried one. */
+    readonly statusText?: string;
+    /** Wall-clock duration of the request in ms (network crumb) — a `performance.now()` delta. */
+    readonly durationMs?: number;
+    /** Request body size in bytes (network crumb) — only when trivially known (string/Blob/ArrayBuffer), never by reading a stream. */
+    readonly reqSize?: number;
+    /** Response body size in bytes (network crumb) — from the `content-length` response header only. */
+    readonly respSize?: number;
+    /** Response content type (network crumb) — the `content-type` header's media type. */
+    readonly contentType?: string;
+    /** The request's failure classification (network crumb) — see {@link NetworkOutcome}. */
+    readonly outcome?: NetworkOutcome;
 }
-/** Default ring size — thinner than Sentry's 100 (it rides on every payload). */
-export declare const DEFAULT_MAX_BREADCRUMBS = 30;
-/** Console levels captured by default (warn/error/assert first, per research). */
+/**
+ * The three independent trace streams (spec #122 §A, decision D6). Each is its own
+ * FIFO ring with its own size budget, so a chatty stream can't evict another's
+ * lead-up. Every {@link BreadcrumbCategory} maps to exactly one stream via
+ * {@link streamOf}.
+ */
+export type TraceStream = "network" | "console" | "breadcrumbs";
+/**
+ * Per-stream ring budgets — starting points from the grill (D6): network is the
+ * chattiest, breadcrumbs the sparsest. Per-project tunable, never frozen.
+ */
+export declare const DEFAULT_STREAM_BUDGETS: Readonly<Record<TraceStream, number>>;
+/**
+ * The shared age cap (spec #122 §A): entries older than this are pruned from every
+ * stream, whichever trims first. ~3 minutes and — unlike the thin buffer's
+ * off-by-default cap — **on** by default, so an idle tab never ships stale context.
+ */
+export declare const DEFAULT_MAX_AGE_MS: number;
+/**
+ * Console levels captured by default (spec #122 §C, decision D7): **all** of them, so
+ * the Console tab is a real console and not just an error log. Eviction priority (not
+ * capture) is what keeps a chatty app's `log`/`info`/`debug` from burying the signal —
+ * see {@link PINNED_CONSOLE_LEVELS}.
+ */
 export declare const DEFAULT_CONSOLE_LEVELS: readonly BreadcrumbLevel[];
+/**
+ * The console levels **pinned** against eviction (spec #122 §C, decision D7). When the
+ * console stream overflows its budget, `warn`/`error`/`assert` are retained ahead of
+ * `log`/`info`/`debug`, so an error is never evicted by a burst of chatter — the
+ * low-priority levels fill the remainder and are dropped first.
+ */
+export declare const PINNED_CONSOLE_LEVELS: readonly BreadcrumbLevel[];
+/**
+ * The console levels for which `source` (`file:line`) is captured (ticket #159).
+ *
+ * Capturing a call site constructs a `new Error()` to read its stack on **every** console
+ * call — a measurable hot-page cost when a chatty app logs in a tight loop (spec #122's
+ * "hot-page performance budget" open question, handed onward from the grill). The
+ * spec-sanctioned mitigation (decision D7) narrows source capture to the **levels that
+ * matter for debugging** — the same `warn`/`error`/`assert` that are pinned against
+ * eviction — so `log`/`info`/`debug` pay no per-call stack cost and simply omit `source`.
+ * Full-fidelity `source` is preserved exactly where it earns its keep: on warnings,
+ * errors, and failed assertions. Per-project tunability of this set is future work; today
+ * it deliberately mirrors {@link PINNED_CONSOLE_LEVELS} so "what survives eviction" and
+ * "what carries a call site" stay one idea.
+ */
+export declare const SOURCE_CAPTURE_LEVELS: readonly BreadcrumbLevel[];
+/**
+ * Which stream a crumb's category belongs to (spec #122 §A). Network APIs
+ * (`fetch` / `xhr` / `beacon`) form the network stream, `console` its own, and
+ * everything else (navigation, masked UI events, the failing error) breadcrumbs.
+ */
+export declare function streamOf(category: string): TraceStream;
 /** Filters or edits each crumb before it enters the buffer; `null` drops it. */
 export type BeforeBreadcrumb = (crumb: Breadcrumb) => Breadcrumb | null;
 /** Configuration for {@link createBreadcrumbBuffer}. All values are optional. */
 export interface BreadcrumbBufferConfig {
-    /** Keep at most this many crumbs (oldest drop). Defaults to {@link DEFAULT_MAX_BREADCRUMBS}. */
-    readonly maxBreadcrumbs?: number;
-    /** Optional age cap in ms: crumbs older than this are dropped. Off by default. */
+    /**
+     * Per-stream size budgets (oldest drop, independently per stream). Any stream
+     * omitted falls back to {@link DEFAULT_STREAM_BUDGETS}.
+     */
+    readonly budgets?: Partial<Record<TraceStream, number>>;
+    /**
+     * Shared age cap in ms: entries older than this are dropped from every stream.
+     * Defaults to {@link DEFAULT_MAX_AGE_MS} (on); pass `0` (or a non-positive value)
+     * to disable age pruning.
+     */
     readonly maxAgeMs?: number;
     /** A per-crumb filter (mute a category, edit, or drop by returning `null`). */
     readonly beforeBreadcrumb?: BeforeBreadcrumb | null;
-    /** Clock source, injectable for tests. Defaults to `Date.now`. */
+    /** Epoch clock source, injectable for tests. Defaults to `Date.now`. */
     readonly now?: () => number;
+    /** High-res monotonic clock, injectable for tests. Defaults to `performance.now`. */
+    readonly mono?: () => number;
+    /** Stable id generator, injectable for tests. Defaults to a per-buffer sequence. */
+    readonly nextId?: () => string;
 }
 /** A live trace buffer. */
 export interface BreadcrumbBuffer {
-    /** Record a crumb (subject to `beforeBreadcrumb`, size, and age trimming). */
+    /** Record a crumb (subject to `beforeBreadcrumb`, id/mono stamping, size, and age trimming). */
     add(crumb: Breadcrumb): void;
-    /** The current crumbs, oldest first — a fresh array, safe to keep. */
+    /** The current crumbs, merged across streams and ordered in time — a fresh array. */
     snapshot(): Breadcrumb[];
     /** Drop every crumb. */
     clear(): void;
 }
 /**
- * Create a FIFO ring buffer. On `add`, the crumb passes through
- * `beforeBreadcrumb`, is appended, then the buffer is trimmed to the newest
- * `maxBreadcrumbs` (`slice(-N)`) and — when an age cap is set — pruned of stale
- * crumbs. `snapshot` prunes by age again at read time so an idle tab never ships
- * stale context.
+ * Create the per-stream trace buffer (spec #122 §A/§B). It holds **three
+ * independent FIFO rings** — `network`, `console`, `breadcrumbs` — each trimmed to
+ * its own budget so a chatty stream never evicts another's lead-up, plus a shared
+ * age cap. On `add`, a crumb passes through `beforeBreadcrumb`, is stamped with a
+ * stable `id` and a high-res `mono` timestamp (and an epoch `timestamp` if it has
+ * none), routed to its stream, then that stream is pruned by age and trimmed to its
+ * budget. `snapshot` prunes by age again, then merges the three streams into one
+ * `mono`-ordered array for transport — so the wire keeps its single `trace` field.
  */
 export declare function createBreadcrumbBuffer(config?: BreadcrumbBufferConfig): BreadcrumbBuffer;
-/** A `console` crumb from a captured call's level and arguments. */
-export declare function consoleCrumb(level: BreadcrumbLevel, args: readonly unknown[], timestamp: number): Breadcrumb;
-/** A `navigation` crumb; both URLs are scrubbed as the crumb is built. */
+/**
+ * Longest scrubbed URL kept on a crumb (spec #122 §F): capped at assembly so an
+ * over-long URL is truncated, never dropped and never allowed to bloat a report.
+ */
+export declare const MAX_URL_LENGTH = 2048;
+/**
+ * Structured console argument caps (spec #122 §C/§F), all applied **at assembly** so a
+ * single console crumb can never bloat a report:
+ * - {@link MAX_ARG_DEPTH} bounds how deep a `json` argument is cloned (deeper nodes
+ *   collapse to an `[Object]`/`[Array]` marker);
+ * - {@link MAX_ARG_ITEMS} bounds how many keys/elements are kept at each level;
+ * - {@link MAX_ARG_STRING_LENGTH} truncates a single over-long string value;
+ * - {@link MAX_CONSOLE_ARGS_BYTES} bounds the serialized size of the whole args array
+ *   (trailing args are dropped to fit), kept well under ingest's per-entry byte cap.
+ */
+export declare const MAX_ARG_DEPTH = 4;
+export declare const MAX_ARG_ITEMS = 100;
+export declare const MAX_ARG_STRING_LENGTH = 1024;
+export declare const MAX_CONSOLE_ARGS_BYTES = 4096;
+/** Classify one console argument into a type-tagged {@link ConsoleArg} (spec #122 §C). */
+export declare function toConsoleArg(value: unknown): ConsoleArg;
+/**
+ * A `console` crumb from a captured call's level and arguments (spec #122 §C). The
+ * `message` is the one-line preview (flattened, truncated); `args` preserves each
+ * argument as a structured, type-tagged, size-capped value so the Console tab can
+ * render objects/errors expandably; `source` is the best-effort `file:line`, attached
+ * only when the stack yielded one. Args are omitted entirely for a no-argument call.
+ */
+export declare function consoleCrumb(level: BreadcrumbLevel, args: readonly unknown[], timestamp: number, source?: SourceLocation): Breadcrumb;
+/** A `navigation` crumb; both URLs are scrubbed and length-capped as the crumb is built. */
 export declare function navigationCrumb(from: string, to: string, timestamp: number): Breadcrumb;
-/** A `fetch` crumb: method + scrubbed URL + status only. No body, ever. */
+/**
+ * Classify an HTTP status into a {@link NetworkOutcome} (spec #122 §D). A missing or
+ * `0` status is a `network-error` (a request that never got a response); otherwise
+ * the 4xx/5xx classes flag failures and everything else is `ok`. Used both as the
+ * fallback outcome and by the thin {@link fetchCrumb} / {@link xhrCrumb} builders.
+ */
+export declare function outcomeFromStatus(status: number | undefined): NetworkOutcome;
+/**
+ * The trivially-known byte size of a request body (spec #122 §D) — a string's UTF-8
+ * length, a `Blob`'s `.size`, or an `ArrayBuffer`/typed-array `.byteLength`. Anything
+ * that would require **reading** the body (a `ReadableStream`, `FormData`, a `Request`
+ * with a stream body) returns `undefined` — the "never read the body" line holds.
+ */
+export declare function trivialBodySize(body: unknown): number | undefined;
+/** Parse a `content-length` header into a non-negative byte count, or `undefined`. */
+export declare function parseContentLength(value: string | null | undefined): number | undefined;
+/** The media type from a `content-type` header (the part before any `;` parameters). */
+export declare function contentTypeOf(value: string | null | undefined): string | undefined;
+/** The rich metadata a network crumb records (spec #122 §D) — never a body or header. */
+export interface NetworkCrumbInput {
+    readonly api: NetworkApi;
+    readonly method: string;
+    /** The raw request URL — scrubbed (query dropped, path PII redacted) as the crumb is built. */
+    readonly url: string;
+    readonly status?: number;
+    readonly statusText?: string;
+    readonly durationMs?: number;
+    readonly reqSize?: number;
+    readonly respSize?: number;
+    readonly contentType?: string;
+    readonly outcome: NetworkOutcome;
+}
+/**
+ * A network crumb (`fetch` / `xhr` / `beacon`) with the rich, metadata-only fields
+ * the Network tab renders (spec #122 §D, ticket #139): api, method, scrubbed URL,
+ * status + statusText, duration, request/response sizes, content type, and a failure
+ * outcome. The URL is scrubbed and length-capped at assembly. The shape has **no field
+ * for a request/response body or an arbitrary header**, so neither can ever be
+ * recorded; only a positive status, and fields that were actually supplied, ride along.
+ */
+export declare function networkCrumb(input: NetworkCrumbInput, timestamp: number): Breadcrumb;
+/**
+ * A thin `fetch` crumb from method + URL + status (outcome derived from the status).
+ * The instrumentation uses {@link networkCrumb} directly to carry the full metadata;
+ * this convenience builder seeds a network crumb from a status alone.
+ */
 export declare function fetchCrumb(method: string, url: string, status: number | undefined, timestamp: number): Breadcrumb;
-/** An `xhr` crumb: method + scrubbed URL + status only. No body, ever. */
+/** A thin `xhr` crumb from method + URL + status (outcome derived from the status). */
 export declare function xhrCrumb(method: string, url: string, status: number | undefined, timestamp: number): Breadcrumb;
 /** A `ui.click` crumb: a masked target selector only — no text or value. */
 export declare function clickCrumb(target: Element, timestamp: number): Breadcrumb;
@@ -94,8 +324,12 @@ export declare function clickCrumb(target: Element, timestamp: number): Breadcru
  * the value typed into it. The `target` element's `.value` is never read.
  */
 export declare function inputCrumb(target: Element, timestamp: number): Breadcrumb;
-/** An `error` crumb for the failing exception or rejection that ends the trace. */
-export declare function errorCrumb(error: unknown, timestamp: number): Breadcrumb;
+/**
+ * An `error` crumb for the failing exception or rejection that ends the trace. When
+ * `causedBy` is given (an auto-captured error), it rides on the crumb as the causal
+ * pointer to the ids of the entries immediately preceding the throw (spec #122 §F).
+ */
+export declare function errorCrumb(error: unknown, timestamp: number, causedBy?: readonly string[]): Breadcrumb;
 /** Detaches an installed instrumentation, restoring the original behaviour. */
 export type Teardown = () => void;
 type AnyFn = (...args: unknown[]) => unknown;
@@ -107,8 +341,10 @@ interface HistoryLike {
 }
 interface XhrInstance {
     status: number;
+    statusText?: string;
     open(method: string, url: string | URL, ...rest: unknown[]): void;
     send(body?: unknown): void;
+    getResponseHeader?(name: string): string | null;
     addEventListener(type: string, listener: () => void): void;
     removeEventListener(type: string, listener: () => void): void;
 }
@@ -116,6 +352,10 @@ interface XhrConstructor {
     new (): XhrInstance;
     prototype: XhrInstance;
 }
+/** The `navigator.sendBeacon` surface the beacon instrumentation wraps. */
+export interface BeaconNavigator {
+    sendBeacon?: (url: string | URL, data?: BodyInit | null) => boolean;
+}
 /** The structural window surface the instrumentation reaches into. */
 export interface InstrumentWindow {
     fetch?: FetchFn;
@@ -124,6 +364,7 @@ export interface InstrumentWindow {
         href: string;
     };
     XMLHttpRequest?: XhrConstructor;
+    navigator?: BeaconNavigator;
     addEventListener(type: string, listener: (event: Event) => void, options?: boolean | AddEventListenerOptions): void;
     removeEventListener(type: string, listener: (event: Event) => void, options?: boolean | EventListenerOptions): void;
 }
@@ -136,22 +377,64 @@ export interface InstrumentOptions {
     /** Skip URLs (e.g. the SDK's own ingest calls) so they never become crumbs. */
     readonly ignoreUrl?: (url: string) => boolean;
     readonly now?: () => number;
+    /**
+     * High-res monotonic clock (spec #122 §D) — used to measure a request's duration as
+     * a delta around the wrapped call. Defaults to `performance.now`; injectable for tests.
+     */
+    readonly mono?: () => number;
+    /**
+     * Whether to instrument the **console** stream (spec #122 §L; ticket #138).
+     * Defaults to `true`; pass `false` and `console` is never wrapped, so no console
+     * entry is ever recorded — the per-project toggle stops the stream at its source.
+     */
+    readonly captureConsole?: boolean;
+    /**
+     * Whether to instrument the **network** stream — `fetch` and `XHR` (spec #122 §L;
+     * ticket #138). Defaults to `true`; pass `false` and neither is wrapped, so no
+     * network entry is ever recorded. Navigation and masked UI events are unaffected.
+     */
+    readonly captureNetwork?: boolean;
 }
+/**
+ * The best-effort `file:line` a console call was made from (spec #122 §C). Parses the
+ * frames of a stack, skipping `skipFrames` leading (SDK-internal) frames so the source
+ * points at the host code that called `console.*`. Returns `undefined` when no frame
+ * yields a usable location — the crumb then simply omits `source`.
+ */
+export declare function sourceFromStack(stack: string | undefined, skipFrames?: number): SourceLocation | undefined;
 /** Wrap `console` methods so calls at the captured levels become crumbs. */
 export declare function instrumentConsole(buffer: BreadcrumbBuffer, consoleObj: ConsoleLike, levels: readonly BreadcrumbLevel[], now: () => number): Teardown;
 /**
- * Wrap `fetch` to record a crumb on settlement. The **original** outcome is
- * returned untouched — the response is passed through without its body being
- * read, and a rejection is re-thrown so the caller's `unhandledrejection`
- * semantics are preserved.
+ * Wrap `fetch` to record a rich network crumb on settlement (spec #122 §D, ticket
+ * #139): method, scrubbed URL, status + statusText, a `performance.now()` duration,
+ * request size (only when the body is trivially sized), response size (from the
+ * `content-length` header only), content type, and a failure outcome. The **original**
+ * outcome is returned untouched — the response is passed through **without its body
+ * being read** (only two metadata headers are inspected), and a rejection is re-thrown
+ * so the caller's `unhandledrejection` semantics are preserved.
+ */
+export declare function instrumentFetch(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number, mono?: () => number): Teardown;
+/**
+ * Patch `XMLHttpRequest` to record a rich network crumb when a request settles (spec
+ * #122 §D, ticket #139): method, scrubbed URL, status + statusText, a `performance.now()`
+ * duration, request size (only when the body is trivially sized), response size (from
+ * the `content-length` header only), content type, and a failure outcome distinguished
+ * by which terminal event fired (`error` / `timeout` / `abort` / `load`). The `send`
+ * body argument is **never read for content** — only its trivially-known size — so a body
+ * can never reach the buffer.
  */
-export declare function instrumentFetch(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number): Teardown;
+export declare function instrumentXhr(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number, mono?: () => number): Teardown;
 /**
- * Patch `XMLHttpRequest` to record a crumb when a request settles. Only the
- * method, URL, and final status are read; the `send` body argument is ignored,
- * so a body can never reach the buffer.
+ * Wrap `navigator.sendBeacon` to record a network crumb for each beacon (spec #122 §D,
+ * ticket #139). `sendBeacon` is fire-and-forget with a **synchronous boolean** return —
+ * `true` when the user agent queued the beacon, `false` when it declined — so wrapping
+ * must return that boolean unchanged: the original is called first and its result both
+ * classifies the crumb (`ok` / `network-error`) and is returned to the caller. Only the
+ * URL and the trivially-known request size are recorded (no response exists to read);
+ * capture failure is swallowed and the boolean still returned, and if the original itself
+ * throws we record best-effort and re-throw so the contract is preserved exactly.
  */
-export declare function instrumentXhr(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number): Teardown;
+export declare function instrumentBeacon(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number): Teardown;
 /** Record a `navigation` crumb on `pushState`/`replaceState`/pop/hash changes. */
 export declare function instrumentNavigation(buffer: BreadcrumbBuffer, win: InstrumentWindow, now: () => number): Teardown;
 /** Listen (capture-phase) for clicks and input changes as masked crumbs. */

package/dist/dom.d.ts

@@ -10,6 +10,13 @@
  */
 /** Marker attributes on the SDK's own host elements in the light DOM. */
 export declare const FIXBACK_HOST_MARKERS: readonly ["data-fixback-root", "data-fixback-overlay"];
+/**
+ * Is this node itself one of the SDK's own host elements (the launcher / overlay
+ * roots)? A self-only check — the screenshot's clone walk excludes a node's whole
+ * subtree once the host is matched, so catching the host is enough to keep all of
+ * Fixback's chrome (light DOM and its shadow tree) out of a capture.
+ */
+export declare function isFixbackHostElement(node: Node | null | undefined): boolean;
 /**
  * Is this node part of the SDK's own UI? Walks up parents and out through any
  * Shadow DOM boundary (via `getRootNode().host`), so a click inside the overlay's

package/dist/error-capture.d.ts

@@ -5,7 +5,7 @@
  *
  * Exactly **two capture-phase listeners** (`window` `error` +
  * `unhandledrejection`) turn uncaught exceptions and unhandled rejections into
- * `source: auto`, `Kind = bug` Feedback for the current session's Reporter — no
+ * `source: auto` Feedback (stamped `Kind = bug` server-side, ADR-0023) for the current session's Reporter — no
  * native-API monkeypatching, no library. Each firing is deduped by a per-session
  * fingerprint, rate-limited by a token-bucket burst limiter and a per-session cap,
  * scrubbed through the same `beforeSend` choke point as manual reports (§C), and
@@ -26,6 +26,9 @@
  */
 import type { IdentityInputs } from "./boot";
 import { type BreadcrumbBuffer, type Teardown } from "./breadcrumbs";
+import type { ReporterDisplay } from "./invite";
+import { type CapturedFrame } from "./report";
+import type { ReplaySource } from "./replay";
 import { type BeforeSend } from "./scrub";
 import { type Capture, type CaptureOptions } from "./screenshot";
 import { type SubmitInput, type SubmitResult } from "./submit";
@@ -57,6 +60,15 @@ export declare function hashString(input: string): string;
  * a session. Returns `""` when there is no usable stack (message-only fallback).
  */
 export declare function extractTopFrames(stack: string | undefined, limit?: number): string;
+/**
+ * Extract **structured** frames from a stack for the wire (#117, ADR-0024) —
+ * unlike {@link extractTopFrames} (a compact fingerprint signature that drops the
+ * origin), these keep the full script URL, because server-side symbolication
+ * matches it against uploaded sourcemap paths. URLs are scrubbed (query dropped,
+ * PII redacted) before they leave the page; unlocatable frames (`native`,
+ * `<anonymous>`, eval) are skipped; the count is capped.
+ */
+export declare function extractStructuredFrames(stack: string | undefined, limit?: number): CapturedFrame[];
 /**
  * The per-session fingerprint (research §7.2):
  * `hash(errorType + "|" + normalize(value) + "|" + topFrames)`. Stack frames
@@ -95,13 +107,31 @@ export interface AutoCaptureConfig {
     readonly apiUrl: string;
     readonly key: string;
     readonly identity?: IdentityInputs;
+    /**
+     * The Reporter's self-provided display name / email (spec §F). Carried on
+     * auto-captured Feedback too, so a machine-filed crash still names whose session it
+     * was — display only, never a trust signal.
+     */
+    readonly display?: ReporterDisplay;
     /** The window whose global handlers are installed. Defaults to `window`. */
     readonly win?: Window;
     /** The document used for capture + environment. Defaults to the window's. */
     readonly doc?: Document;
     readonly sdkVersion?: string;
+    /**
+     * The host app's **Release** (#117, ADR-0024) — already validated by `init`
+     * (`normaliseRelease`). Stamped into every auto report's environment so the
+     * server can symbolicate the captured frames against this build's sourcemaps.
+     */
+    readonly release?: string;
     /** The shared trace buffer; the failing error is added to it before filing. */
     readonly buffer?: BreadcrumbBuffer | null;
+    /**
+     * The shared replay recorder (ADR-0024); the buffered window rides on a rich
+     * first report — the moment before an uncaught error is exactly what replay
+     * exists to show. Light count-update flushes never re-send it.
+     */
+    readonly replay?: ReplaySource | null;
     /** Per-project client scrub hook, run at the `beforeSend` choke point (§C). */
     readonly beforeSend?: BeforeSend;
     /** Run the built-in default scrubbers. Defaults to `true` (private-by-default). */