@fixback/sdk 0.1.0 → 0.2.0

package/README.md

@@ -62,6 +62,8 @@ global:
 | `reporterId`     | `string`      | —                          | The handle returned when a reporter redeems an invite.                  |
 | `anonymousId`    | `string`      | a persisted per-browser id | A stable first-party id for an anonymous reporter.                      |
 | `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. |
 
 None of the identity fields is a trust tier — Fixback derives trust on the
 server and never honours a self-declared tier.
@@ -72,6 +74,24 @@ const fixback = await init({ key: "pk_live_..." });
 fixback.destroy();
 ```
 
+## The launcher
+
+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.
+- **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
+  slide/fade transitions. The launcher also honours the visitor's OS-level
+  `prefers-reduced-motion: reduce` on its own, with no configuration.
+
+All of this chrome lives inside the launcher's Shadow DOM, so it never adds a
+global style or touches the host page's markup.
+
 ## The launch event
 
 Activating the launcher opens the SDK's own report overlay. It also dispatches a
@@ -86,6 +106,57 @@ document.addEventListener(LAUNCH_EVENT, () => {
 });
 ```
 
+## Automatic error capture
+
+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
+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.
+
+- **Deduped & rate-limited.** The same error reported many times collapses to one
+  Feedback with a rising occurrence count. A token-bucket burst limiter and a
+  per-session cap keep a runaway error loop from flooding the queue; the excess is
+  dropped and kept only as a local count. On a `429` + `Retry-After` from ingest,
+  auto-reporting backs off until the window clears.
+- **Gated like a manual report.** Auto-capture only runs where a submission would
+  be accepted (boot's `canSubmit`), so a public visitor's crash is tracked at their
+  server-derived tier — never auto-shipped. `console.error` is **not** promoted to a
+  report; it stays breadcrumb-only Evidence.
+- **Private-by-default.** Every auto-report passes through the same client-side
+  `beforeSend` scrub choke point as a manual one — input values and request/response
+  bodies never leave the browser, and your hook can drop an auto-report entirely.
+
+## Invite redemption
+
+An invited tester needs no account and no setup. When a page loads with an invite
+token in its URL (`?fixback_invite=<token>`), `init` reads the invite's status and
+renders the SDK's own **onboarding modal** — the site you were invited to, the
+**access tier** the redemption grants (server-derived, never guessed on the
+client), a private-by-default note, and a "Continue as" name / email:
+
+```ts
+init({ key: "pk_live_..." }); // auto-detects ?fixback_invite= on the page
+```
+
+On confirm the SDK redeems the invite, persists the returned `reporterId` in
+`localStorage` (scoped to your publishable key), strips the token from the URL
+(one-time consumption), and mounts the launcher. On later visits `init` presents
+that stored `reporterId`, so a returning tester is recognised at their correct
+tier without re-onboarding — and on an **Invited** or **Internal** Gate the
+launcher appears only after redemption, while an **Open** Gate shows it to anyone.
+
+The name / email are **self-provided display fields** — never a trust signal; the
+tier is always the server's to derive. If the token reaches the page some way
+other than the URL, redeem it explicitly:
+
+```ts
+import { redeem } from "@fixback/sdk";
+
+redeem({ key: "pk_live_...", token: "the-invite-token" });
+```
+
 ## How the boot gate works
 
 On `init`, the SDK `POST`s to `${apiUrl}/api/ingest/boot` with your key (the

package/dist/annotation.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The Annotation & vector-marks model (spec 0003 §B/§D).
+ *
+ * An Annotation is everything a Reporter marked on the page, as three
+ * **composable, optional** layers over one full masked screenshot: the picked
+ * `element` (from the element-picker), a drag-captured `region`, and vector
+ * `marks` — arrow / box / pen / text. Marks live in the **screenshot's coordinate
+ * space** (the full viewport the screenshot is rasterised at), never baked into
+ * the PNG: the dashboard composites them at view time (#91).
+ *
+ * This module is the marks' single home — the pure types and geometry used by the
+ * region-capture and draw controllers and by the overlay's Send assembly. Like the
+ * rest of the SDK's wire types it is vendored (no `@fixback/shared` import); keep
+ * `Annotation` in lock-step with the server's ingest contract (spec §D/§H).
+ */
+import type { SelectedElement } from "./report";
+/** A point in screenshot (viewport) coordinate space. */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** A rectangle in screenshot coordinates — the same shape as an element's rect. */
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** The draw tools the overlay offers, in toolbar order (spec §B, prototype). */
+export type DrawTool = "arrow" | "box" | "pen" | "text";
+/** Fields shared by every vector mark. */
+interface MarkBase {
+    /** Stroke/fill colour, as a CSS colour string. */
+    readonly color: string;
+}
+/** A directional arrow from `(x0,y0)` to its tip at `(x1,y1)`. */
+export interface ArrowMark extends MarkBase {
+    readonly type: "arrow";
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+}
+/** A rectangle spanning the drag from `(x0,y0)` to `(x1,y1)`. */
+export interface BoxMark extends MarkBase {
+    readonly type: "box";
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+}
+/** A freehand polyline through `points` (in order). */
+export interface PenMark extends MarkBase {
+    readonly type: "pen";
+    readonly points: ReadonlyArray<Point>;
+}
+/** A text label anchored at `(x,y)` (its baseline-left, as SVG text). */
+export interface TextMark extends MarkBase {
+    readonly type: "text";
+    readonly x: number;
+    readonly y: number;
+    readonly text: string;
+}
+/** A single vector mark, in screenshot coordinates. */
+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).
+ */
+export interface Annotation {
+    readonly element?: SelectedElement;
+    readonly region?: Rect;
+    readonly marks?: ReadonlyArray<Mark>;
+}
+/**
+ * The default mark colour — Signal's danger red, matching the frozen Reporter
+ * prototype's draw layer (`docs/design/Fixback Reporter.dc.html`).
+ */
+export declare const MARK_COLOR = "#e5484d";
+/**
+ * Normalise a drag from a start to an end point into a positive-extent rect
+ * (top-left origin, non-negative width/height), rounded to whole pixels — the
+ * screenshot is a pixel raster, so sub-pixel extents carry no meaning. Shared by
+ * region-capture and the box mark.
+ */
+export declare function normalizeRect(x0: number, y0: number, x1: number, y1: number): Rect;
+/**
+ * The three points of an arrow's head, given its line `(x0,y0)→(x1,y1)` and a head
+ * length: the tip, then the two barbs splayed ±30° behind it. Pure geometry the
+ * draw surface renders as a filled triangle at the arrow's tip.
+ */
+export declare function arrowHeadPoints(x0: number, y0: number, x1: number, y1: number, size?: number): [Point, Point, Point];
+/**
+ * Assemble the structured Annotation from whatever a Reporter marked, dropping
+ * empty layers: no element, no region, and an empty marks list are omitted, so the
+ * result is `undefined` when nothing was marked. Marks are copied into a plain,
+ * independent array so the annotation is a serialisable snapshot decoupled from the
+ * live draw state.
+ */
+export declare function assembleAnnotation(parts: {
+    readonly element?: SelectedElement | null;
+    readonly region?: Rect | null;
+    readonly marks?: ReadonlyArray<Mark> | null;
+}): Annotation | undefined;
+export {};

package/dist/auto-report-backoff.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Client-side backpressure for **automatic** error reports (spec 0003 §E/§H,
+ * ticket #89). When ingest sheds `source: auto` load it answers `429` with a
+ * `Retry-After`; the SDK honours it by holding a pause window during which further
+ * `source: auto` reports are dropped without touching the network. **Manual**
+ * reports — a human clicking Send — never consult this gate.
+ *
+ * This is the transport's counterpart to the server's per-Project token bucket
+ * (`apps/api/src/ingest/auto-report-rate-limiter.ts`): one shared window per page,
+ * so a 429 from one auto-report shed applies to the auto-reports that follow it.
+ * The clock is injectable so the window is unit-tested deterministically, never on
+ * wall time — mirroring the server limiter's `Clock`.
+ */
+/** A source of the current time in epoch milliseconds — injectable for tests. */
+export type Clock = () => number;
+/** The hold window applied when a `429` carries no usable `Retry-After` (spec §E). */
+export declare const DEFAULT_RETRY_AFTER_SECONDS = 60;
+/**
+ * Parse a `Retry-After` header into whole seconds to hold for. Handles both HTTP
+ * forms — a delta-seconds integer and an HTTP-date (measured from `now`, rounded up
+ * and clamped at zero) — and falls back to {@link DEFAULT_RETRY_AFTER_SECONDS} when
+ * the header is absent, blank, or unparseable. Ingest sends the delta-seconds form;
+ * the date form is handled for spec-completeness.
+ */
+export declare function parseRetryAfter(header: string | null | undefined, now: number): number;
+/**
+ * A single pause window for `source: auto` reports. `hold` opens (or extends) it
+ * from a `429`'s `Retry-After`; `isPaused` reports whether it is still open. The
+ * default instance in `submit.ts` is shared across a page's reports so the hold
+ * persists across successive auto submissions.
+ */
+export declare class AutoReportBackoff {
+    private readonly now;
+    /** Epoch ms until which `source: auto` reports are held; `0` when clear. */
+    private pausedUntil;
+    constructor(now?: Clock);
+    /** Is the `source: auto` pause window currently open? */
+    isPaused(): boolean;
+    /** Whole seconds remaining in the pause window (`0` when clear). */
+    retryAfterSeconds(): number;
+    /**
+     * Open (or extend) the window from a `429`'s `Retry-After` value, returning the
+     * seconds it will hold for. The window only ever grows — a shorter later hold
+     * never clips a longer one already in effect.
+     */
+    hold(retryAfterHeader: string | null | undefined): number;
+}

package/dist/breadcrumbs.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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" | "ui.click" | "ui.input" | "error";
+/**
+ * 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;
+}
+/** One entry in the trace buffer. */
+export interface Breadcrumb {
+    readonly category: BreadcrumbCategory;
+    readonly message?: string;
+    readonly level?: BreadcrumbLevel;
+    /** Epoch milliseconds when the crumb was recorded. */
+    readonly timestamp: number;
+    readonly data?: BreadcrumbData;
+}
+/** 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). */
+export declare const DEFAULT_CONSOLE_LEVELS: readonly BreadcrumbLevel[];
+/** 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. */
+    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`. */
+    readonly now?: () => number;
+}
+/** A live trace buffer. */
+export interface BreadcrumbBuffer {
+    /** Record a crumb (subject to `beforeBreadcrumb`, size, and age trimming). */
+    add(crumb: Breadcrumb): void;
+    /** The current crumbs, oldest first — a fresh array, safe to keep. */
+    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.
+ */
+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. */
+export declare function navigationCrumb(from: string, to: string, timestamp: number): Breadcrumb;
+/** A `fetch` crumb: method + scrubbed URL + status only. No body, ever. */
+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. */
+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. */
+export declare function errorCrumb(error: unknown, timestamp: number): 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;
+    open(method: string, url: string | URL, ...rest: unknown[]): void;
+    send(body?: unknown): void;
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+interface XhrConstructor {
+    new (): XhrInstance;
+    prototype: XhrInstance;
+}
+/** The structural window surface the instrumentation reaches into. */
+export interface InstrumentWindow {
+    fetch?: FetchFn;
+    history?: HistoryLike;
+    location?: {
+        href: string;
+    };
+    XMLHttpRequest?: XhrConstructor;
+    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;
+}
+/** 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.
+ */
+export declare function instrumentFetch(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => 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.
+ */
+export declare function instrumentXhr(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/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;