@fixback/sdk 0.1.0 → 0.3.0

package/dist/breadcrumbs.d.ts

@@ -0,0 +1,448 @@
+/**
+ * The thin trace **breadcrumb ring buffer** and its capture instrumentation
+ * (spec 0003 §C; research `sentry-error-capture-findings.md` §7.5).
+ *
+ * A fixed-size FIFO buffer of the most recent activity — console, navigation,
+ * network metadata, masked user actions, and the failing error — that rides on a
+ * report as Evidence. It is trimmed exactly like Sentry (`crumbs.slice(-N)`),
+ * defaults to a deliberately thin `N ≈ 30` because it ships on **every** payload,
+ * and takes an optional age cap. A `beforeBreadcrumb(crumb) => crumb | null`
+ * filter lets a Project mute or edit crumbs before they enter the buffer.
+ *
+ * Everything private is kept out **at the source**: `ui.input` records that an
+ * input changed, never its value; `fetch`/`xhr` crumbs carry method + URL +
+ * status only, **never** bodies; URLs are scrubbed as the crumb is built. The
+ * `beforeSend` choke point (`scrub.ts`) is the final gate over the whole report.
+ *
+ * The SDK stays dependency-free and must never throw into the host page, so every
+ * instrumentation hook is wrapped: a capture failure is swallowed and the original
+ * behaviour (the real `console`, `fetch`, navigation) always runs.
+ */
+/** 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" | "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.
+ */
+export interface BreadcrumbData {
+    readonly url?: string;
+    readonly method?: string;
+    readonly status?: number;
+    /** A masked CSS selector for a `ui.*` target — never its text or value. */
+    readonly target?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly errorType?: string;
+}
+/**
+ * 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;
+}
+/**
+ * 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 {
+    /**
+     * 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;
+    /** 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`, id/mono stamping, size, and age trimming). */
+    add(crumb: Breadcrumb): void;
+    /** The current crumbs, merged across streams and ordered in time — a fresh array. */
+    snapshot(): Breadcrumb[];
+    /** Drop every crumb. */
+    clear(): void;
+}
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+/** 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;
+/**
+ * A `ui.input` crumb: records **that** an input changed and which field, never
+ * 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. 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;
+type ConsoleLike = Partial<Record<BreadcrumbLevel, AnyFn>>;
+type FetchFn = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+interface HistoryLike {
+    pushState(data: unknown, unused: string, url?: string | URL | null): void;
+    replaceState(data: unknown, unused: string, url?: string | URL | null): void;
+}
+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;
+}
+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;
+    history?: HistoryLike;
+    location?: {
+        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;
+}
+/** Options for {@link instrumentBreadcrumbs} and the individual installers. */
+export interface InstrumentOptions {
+    readonly win?: InstrumentWindow;
+    readonly doc?: Document;
+    readonly consoleObj?: ConsoleLike;
+    readonly consoleLevels?: readonly BreadcrumbLevel[];
+    /** 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 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 instrumentXhr(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number, mono?: () => number): Teardown;
+/**
+ * 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 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. */
+export declare function instrumentUiEvents(buffer: BreadcrumbBuffer, doc: Document, now: () => number): Teardown;
+/**
+ * Install every capture hook onto a window/document and return a single teardown
+ * that removes them all. Each hook is independent and defensive: a failure in one
+ * never blocks the others, and none can throw into the host page.
+ */
+export declare function instrumentBreadcrumbs(buffer: BreadcrumbBuffer, options?: InstrumentOptions): Teardown;
+export {};

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/draw-surface.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The draw surface — arrow / box / pen / text marking over the captured frame
+ * (spec 0003 §B, the Reporter prototype's draw toolbar). It is the interactive
+ * editor behind the overlay's draw mode: a tool, a live preview, a committed list
+ * of {@link Mark}s with undo, and an SVG it renders into. Marks are recorded in
+ * **screenshot (viewport) coordinates** so they compose over the full masked
+ * screenshot; the overlay reads {@link DrawSurface.marks} when the Reporter
+ * attaches.
+ *
+ * Pointer listeners are capture-phase on the document, so a stroke is intercepted
+ * before the host page; a stroke that begins on interactive chrome (the toolbar,
+ * the label input) is ignored so the toolbar stays clickable. The surface draws
+ * nothing into the host page — only into the SVG the overlay hands it inside its
+ * own Shadow DOM.
+ */
+import { type DrawTool, type Mark } from "./annotation";
+/** Options for {@link startDrawSurface}. */
+export interface DrawSurfaceOptions {
+    /** Document to attach to. Defaults to the global `document`. */
+    readonly doc?: Document;
+    /** The (viewport-filling) SVG the surface renders committed marks + preview into. */
+    readonly svg: SVGSVGElement;
+    /** The inline label input the text tool shows, positions, and reads. */
+    readonly textInput: HTMLInputElement;
+    /** Mark colour. Defaults to {@link MARK_COLOR}. */
+    readonly color?: string;
+    /** Marks to seed from, so re-entering draw continues an existing annotation. */
+    readonly initialMarks?: ReadonlyArray<Mark>;
+    /** Notified with a fresh snapshot whenever the committed marks change. */
+    readonly onChange?: (marks: ReadonlyArray<Mark>) => void;
+}
+/** A running draw surface. */
+export interface DrawSurface {
+    /** Switch the active tool. */
+    setTool(tool: DrawTool): void;
+    /** The active tool. */
+    getTool(): DrawTool;
+    /** Remove the most recently committed mark. */
+    undo(): void;
+    /** A snapshot of the committed marks, in screenshot coordinates. */
+    marks(): ReadonlyArray<Mark>;
+    /** Detach all listeners and hide the label input. */
+    stop(): void;
+}
+/**
+ * Begin drawing. The returned surface tracks a tool, a live preview stroke, and the
+ * committed marks; `marks()` snapshots them for the overlay's Send assembly. Text
+ * labels are entered through the provided input (Enter commits, Escape/blur-empty
+ * discards). `stop()` detaches everything.
+ */
+export declare function startDrawSurface(options: DrawSurfaceOptions): DrawSurface;

package/dist/error-capture.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Automatic error capture — the SDK's signature capability: **errors report
+ * themselves, no prompt** (spec 0003 §E, ADR-0011; research
+ * `sentry-error-capture-findings.md` §7.1–7.3, §7.6).
+ *
+ * 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
+ * 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
+ * shipped through the same transport (which honours ingest's `429` / `Retry-After`
+ * backpressure, ticket #89). `console.error` is **not** promoted — it stays
+ * breadcrumb-only Evidence.
+ *
+ * Per-firing order (research §7.1): **`canSubmit`/Gate → dedup → rate-limit/cap →
+ * `beforeSend` scrub → enqueue Feedback**. The Gate is honoured by construction:
+ * `init` installs this only when boot returned `canSubmit`, so an auto-error is
+ * never filed where a manual report would be refused, and it inherits the session
+ * Reporter's server-derived tier.
+ *
+ * The whole module is defensive — every handler is wrapped so a Fixback problem
+ * (or an error thrown while capturing an error) never surfaces on the host page.
+ * The fingerprint/`normalize` shape and the limiter numbers are **starting points**
+ * from research (ticket #92), exposed as config — tunable, not frozen.
+ */
+import type { IdentityInputs } from "./boot";
+import { type BreadcrumbBuffer, type Teardown } from "./breadcrumbs";
+import { type BeforeSend } from "./scrub";
+import { type Capture, type CaptureOptions } from "./screenshot";
+import { type SubmitInput, type SubmitResult } from "./submit";
+export type { Teardown };
+/** Burst limiter capacity — how many auto-reports may fire back-to-back (§E). */
+export declare const DEFAULT_BURST_CAPACITY = 5;
+/** Burst limiter refill — one token returns every this-many ms (§E). */
+export declare const DEFAULT_BURST_REFILL_MS = 2000;
+/** Per-session ceiling on distinct auto-Feedback; beyond it, only a dropped-count (§E). */
+export declare const DEFAULT_MAX_DISTINCT_AUTO = 20;
+/**
+ * Collapse the volatile parts of an error message so a changing string doesn't
+ * split one bug: UUIDs, URLs, `0x…` and long hex runs, and long digit runs are
+ * replaced with stable placeholders. Short numbers and stable text are kept so
+ * genuinely distinct bugs stay distinct. A small, dependency-free regex set —
+ * tunable per ticket #92, never a frozen magic set.
+ */
+export declare function normalize(value: string): string;
+/**
+ * A dependency-free FNV-1a hash rendered in base-36. It only has to be stable and
+ * well-distributed within one session (the client key is a flood guard; the server
+ * does canonical cross-session clustering), so a non-cryptographic hash is right.
+ */
+export declare function hashString(input: string): string;
+/**
+ * Extract a compact, stable signature of the top in-app frames of a stack: up to
+ * {@link FINGERPRINT_FRAME_LIMIT} frames as `function@basename:line:col`, origin
+ * and cache-busting query stripped so a per-deploy asset hash doesn't matter within
+ * a session. Returns `""` when there is no usable stack (message-only fallback).
+ */
+export declare function extractTopFrames(stack: string | undefined, limit?: number): string;
+/**
+ * The per-session fingerprint (research §7.2):
+ * `hash(errorType + "|" + normalize(value) + "|" + topFrames)`. Stack frames
+ * dominate when present; otherwise it falls back to type + normalized value.
+ */
+export declare function computeFingerprint(type: string, value: string, stack?: string): string;
+/** Configuration for {@link TokenBucket}. */
+export interface TokenBucketOptions {
+    readonly capacity: number;
+    readonly refillIntervalMs: number;
+    /** Clock source, injectable for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * A token bucket: starts full at `capacity`, refills one token every
+ * `refillIntervalMs`, and refuses (`take() === false`) when empty. So a fast error
+ * loop that dodges dedup with distinct fingerprints still can't machine-gun ingest.
+ * The clock is injectable so the window is unit-tested deterministically.
+ */
+export declare class TokenBucket {
+    private readonly options;
+    private tokens;
+    private last;
+    private readonly now;
+    constructor(options: TokenBucketOptions);
+    /** Consume a token if one is available (refilling first), else refuse. */
+    take(): boolean;
+}
+/** Injectable collaborators, defaulted to the real implementations. */
+export interface AutoCaptureDeps {
+    readonly captureView: (options?: CaptureOptions) => Promise<Capture | null>;
+    readonly submitReport: (apiUrl: string, input: SubmitInput, fetchImpl?: typeof fetch) => Promise<SubmitResult>;
+}
+/** Configuration for {@link installErrorCapture}. */
+export interface AutoCaptureConfig {
+    readonly apiUrl: string;
+    readonly key: string;
+    readonly identity?: IdentityInputs;
+    /** 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 shared trace buffer; the failing error is added to it before filing. */
+    readonly buffer?: BreadcrumbBuffer | 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). */
+    readonly scrub?: boolean;
+    readonly deps?: Partial<AutoCaptureDeps>;
+    /** Burst limiter capacity. Defaults to {@link DEFAULT_BURST_CAPACITY}. */
+    readonly burstCapacity?: number;
+    /** Burst limiter refill interval (ms). Defaults to {@link DEFAULT_BURST_REFILL_MS}. */
+    readonly burstRefillMs?: number;
+    /** Per-session distinct-Feedback cap. Defaults to {@link DEFAULT_MAX_DISTINCT_AUTO}. */
+    readonly maxDistinct?: number;
+    /** Clock source, injectable for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/** A running auto-capture: its teardown, plus the local dropped-count (spec §E). */
+export interface AutoCaptureHandle {
+    /** Remove the two global handlers and the flush hooks. Safe to call repeatedly. */
+    readonly destroy: Teardown;
+    /**
+     * Distinct auto-Feedback dropped by the burst limiter or the per-session cap —
+     * the "keep only a local dropped-count" fallback beyond the guardrails (spec §E).
+     */
+    droppedCount(): number;
+}
+/**
+ * Install automatic error capture on a window and return a handle whose `destroy`
+ * removes every listener it added (the two global handlers plus the flush hooks).
+ * The caller (`init`) installs this only after boot returned `canSubmit`, so the
+ * Gate is respected and the auto-error inherits the session Reporter's tier.
+ */
+export declare function installErrorCapture(config: AutoCaptureConfig): AutoCaptureHandle;