@fixback/sdk 0.4.0 → 0.6.0

package/dist/overlay.d.ts

@@ -1,31 +1,40 @@
-import type { IdentityInputs, ProjectGate, ReporterTier } from "./boot";
-import type { Breadcrumb } from "./breadcrumbs";
-import type { ReporterDisplay } from "./invite";
-import { type ElementPicker, type ElementPickerOptions } from "./element-picker";
+/**
+ * The report **overlay** — the on-page panel a Reporter files a report from, built
+ * to the frozen Signal Reporter prototype (`docs/design/Fixback Reporter.dc.html`).
+ *
+ * This module is the wiring: it mounts the view lazily inside its own Shadow DOM
+ * (isolated from the host page, and marked so the replay recorder and
+ * element-picker skip it), opens on the launcher's `fixback:launch` seam, and joins
+ * the three parts that do the work:
+ *
+ * - `./overlay/view` builds the markup and hands back typed refs;
+ * - `./overlay/marking` runs the three composable marking layers (element-pick,
+ *   region-capture, draw) and owns what has been marked;
+ * - `./overlay/send` assembles, scrubs, and submits.
+ *
+ * What is left here is the panel's own state: open/closed, the compose → sending →
+ * sent phase, the status line, and the confirmation's auto-close. The marks are
+ * viewport-space vectors composited at view time (spec §D), never baked into an
+ * image; the still they annotate is a frame of the buffered rrweb window
+ * (reconstructed downstream since ADR-0027), so the SDK rasterises nothing.
+ */
+import type { BeforeSend, IdentityInputs, ProjectGate, ReporterIdentity } from "@fixback/sdk-core";
+import { type StartPickerFn } from "./overlay/marking";
+import { type BreadcrumbSource, type SubmitReportFn } from "./overlay/send";
 import type { ReplaySource } from "./replay";
-import { type BeforeSend } from "./scrub";
-import { type Capture, type CaptureOptions } from "./screenshot";
-import { type SubmitInput, type SubmitResult } from "./submit";
-/** Marks the overlay's host element in the light DOM (skipped by capture/picker). */
-export declare const OVERLAY_ATTRIBUTE = "data-fixback-overlay";
-type CaptureViewFn = (options?: CaptureOptions) => Promise<Capture | null>;
-type SubmitReportFn = (apiUrl: string, input: SubmitInput, fetchImpl?: typeof fetch) => Promise<SubmitResult>;
-type StartPickerFn = (options: ElementPickerOptions) => ElementPicker;
+export { OVERLAY_ATTRIBUTE } from "./overlay/dom";
+export type { BreadcrumbSource } from "./overlay/send";
 /** Injectable collaborators, defaulted to the real implementations. */
 export interface OverlayDeps {
-    readonly captureView: CaptureViewFn;
     readonly submitReport: SubmitReportFn;
     readonly startElementPicker: StartPickerFn;
 }
-/** A read-only view of the trace buffer the overlay attaches to a report. */
-export interface BreadcrumbSource {
-    snapshot(): readonly Breadcrumb[];
-}
 /** Configuration for {@link createOverlay}. */
 export interface OverlayConfig {
     readonly apiUrl: string;
     readonly key: string;
-    readonly identity?: IdentityInputs;
+    /** Identity evidence, read **live** at send time (ADR-0032) — see {@link MountContext}. */
+    readonly getIdentity?: () => IdentityInputs;
     /**
      * The Project's Gate, forwarded verbatim from the boot answer. Reserved for
      * Gate-aware launcher / redemption behaviour (spec §A/§F); the overlay itself
@@ -33,21 +42,20 @@ export interface OverlayConfig {
      */
     readonly gate?: ProjectGate;
     /**
-     * The Reporter's **server-derived** trust tier from the boot answer, or `null`
-     * when a presented identity was refused. Rendered as a **display-only** chip in
-     * the overlay header (spec §G) — never a trust signal, never read for a decision,
-     * and never sent back to the server. When `null`/absent no tier is asserted.
+     * The current Reporter identity — anonymous, or a connected Account with its
+     * server-derived tier — rendered in the header's identity chip (ADR-0032). Updated in
+     * place via {@link OverlayController.setIdentity} after a Connect or sign-out.
      */
-    readonly tier?: ReporterTier | null;
+    readonly reporterIdentity: ReporterIdentity;
+    /** Start a Connect from the chip's **Sign in** (ADR-0032). */
+    readonly onSignIn: () => void;
+    /** Clear the Reporter session from the chip's **Sign out** (ADR-0032). */
+    readonly onSignOut: () => void;
     readonly sdkVersion?: string;
     /** The host app's Release (#117, ADR-0024), validated by `init`; rides in the environment. */
     readonly release?: string;
-    /**
-     * The Reporter's self-provided display name / email (spec §F), when the SDK holds
-     * them (from a redemption in this session or a prior one). They ride along with the
-     * report so a Member sees who filed it — display only, never a trust signal.
-     */
-    readonly display?: ReporterDisplay;
+    /** The deploy environment (`production` / `staging` / …), stamped on every report. */
+    readonly deployEnvironment?: string;
     /** Where to mount the overlay host. Defaults to `document.body`. */
     readonly target?: HTMLElement;
     readonly doc?: Document;
@@ -67,20 +75,9 @@ export interface OverlayController {
     open(): void;
     close(): void;
     destroy(): void;
+    /** Update the identity chip in place after a Connect or sign-out (ADR-0032). */
+    setIdentity(identity: ReporterIdentity): void;
     readonly isOpen: boolean;
 }
-/**
- * Create the report overlay — the on-page panel a Reporter files a report from,
- * built to the frozen Signal Reporter prototype (`docs/design/Fixback Reporter.dc.html`).
- * It mounts lazily inside its own Shadow DOM (isolated from the host page, and
- * marked so the screenshot and element-picker skip it), opens on the launcher's
- * `fixback:launch` seam, and offers three **composable, optional** marking layers
- * over one full masked screenshot (spec §B): **element-pick**, **region-capture**
- * (drag), and **draw** (arrow / box / pen / text, with undo / cancel / attach). On
- * Send it captures the masked screenshot, assembles the structured Annotation
- * (`{ element?, region?, marks? }`, spec §D — marks stay vector, never baked into
- * the PNG), and submits to ingest — showing a confirmation on success and failing
- * quietly otherwise.
- */
+/** Create the report overlay. See the module doc. */
 export declare function createOverlay(config: OverlayConfig): OverlayController;
-export {};

package/dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/report.d.ts

@@ -1,113 +1,20 @@
 /**
- * The ingest **feedback** content wire-contract, vendored, plus the helpers that
- * assemble it from what a Reporter composed in the overlay.
+ * Assembling the ingest **feedback** content from what a Reporter composed in the
+ * overlay, plus the browser-side environment capture and Release validation.
  *
- * Like `boot.ts`, the SDK does not import `@fixback/shared`; the slice of the
- * submission shape it needs is copied here. Keep it in lock-step with the server:
- * the JSON `payload` part accepted by `POST /api/ingest/feedback`
- * (`apps/api/src/ingest/ingest.controller.ts` — `feedbackContentBody`) and the
- * `SubmissionContent` it parses (`apps/api/src/ingest/reporter-identity.ts`).
- */
-import { type Annotation, type Mark, type Rect } from "./annotation";
-import type { Breadcrumb } from "./breadcrumbs";
-/**
- * Where a Feedback came from — a human in the overlay (`reporter`, the default) or
- * the SDK's automatic error capture (`auto`). Mirrors the server's `FEEDBACK_SOURCES`;
- * the server derives trust independently and ignores anything else the client claims.
- */
-export type FeedbackSource = "reporter" | "auto";
-/** The picked element's viewport rectangle, as the server's annotation `rect`. */
-export interface ElementRect {
-    readonly x: number;
-    readonly y: number;
-    readonly width: number;
-    readonly height: number;
-}
-/**
- * The picked element — the `element` layer of an {@link Annotation}: a stable CSS
- * selector, a readable DOM path, the tag, and the bounding rect. Exactly the
- * server's annotation `element` object shape.
- */
-export interface SelectedElement {
-    readonly selector: string;
-    readonly domPath: string;
-    readonly tag: string;
-    readonly rect: ElementRect;
-}
-/** The capture environment recorded alongside a report. */
-export interface CaptureEnvironment {
-    readonly viewportWidth?: number;
-    readonly viewportHeight?: number;
-    readonly browser?: string;
-    readonly sdkVersion?: string;
-    /**
-     * The host app's **Release** — the build identifier the builder configured at
-     * `init` (#117, ADR-0024). Uploaded sourcemaps are keyed by it, so the server
-     * can symbolicate this session's stack traces against the exact build that
-     * produced them. Omitted when the Project doesn't set one.
-     */
-    readonly release?: string;
-}
-/**
- * One structured frame of a captured stack trace (#117, ADR-0024), top of stack
- * first — the server's `errorFrames` wire shape (mirrors `@fixback/shared`'s
- * `CapturedStackFrame` by value, per this file's vendoring rule). `file` is the
- * scrubbed script URL; `line`/`column` are 1-based as browsers report them.
- */
-export interface CapturedFrame {
-    readonly file: string;
-    readonly line: number;
-    readonly column: number | null;
-    readonly function: string | null;
-}
-/**
- * Validate + trim a builder-supplied release (#117, ADR-0024), mirroring the
- * server's rules by value: 1–100 visible characters, no whitespace, control
- * characters, or path separators, and not a reserved name. Returns `undefined`
- * for an invalid value — the SDK drops it (with a warning at `init`) rather than
- * shipping a value the server would discard.
- */
-export declare function normaliseRelease(value: string): string | undefined;
-/**
- * The JSON content of a feedback submission — the object serialised into the
- * multipart `payload` part next to the `key` and identity evidence. Every field
- * is optional: none of it feeds the server's trust decision, so a submission may
- * carry any subset. `annotation` is the structured `{ element?, region?, marks? }`
- * (spec §D); the screenshot is a separate binary part, never part of this JSON.
- */
-export interface ReportContent {
-    readonly comment?: string;
-    /**
-     * The Reporter's self-provided display **name / email** (spec §F), captured in the
-     * invite onboarding step and riding along with every submission so a Member sees
-     * who reported an Issue. **Display only, never a trust signal** — the server derives
-     * the tier from identity evidence alone and ignores these. Omitted when the Reporter
-     * gave none (a Public/anonymous visitor).
-     */
-    readonly reporterName?: string;
-    readonly reporterEmail?: string;
-    readonly url?: string;
-    readonly environment?: CaptureEnvironment;
-    readonly annotation?: Annotation;
-    /** The masked breadcrumb trace buffer that rode on this report (spec §C). */
-    readonly trace?: readonly Breadcrumb[];
-    /**
-     * Provenance (spec §D/§E). Omitted for a manual report — the transport stamps the
-     * `reporter` default on the wire; set to `auto` by the SDK's error capture.
-     */
-    readonly source?: FeedbackSource;
-    /** For `source: auto` only — the SDK's per-session error fingerprint (spec §E). */
-    readonly errorSignature?: string;
-    /** For `source: auto` only — the running occurrence count within the session (spec §E). */
-    readonly occurrences?: number;
-    /**
-     * For `source: auto` only — the captured error's parsed stack frames (#117,
-     * ADR-0024), top of stack first, capped client-side. The analysis worker
-     * matches them against the release's uploaded sourcemaps to write the Issue's
-     * Code-area pointer.
-     */
-    readonly errorFrames?: readonly CapturedFrame[];
-}
+ * The shared wire shapes it produces — `ReportContent`, `CaptureEnvironment`,
+ * `CapturedFrame`, `SelectedElement`, `ElementRect`, `FeedbackSource` — live in
+ * `@fixback/sdk-core` (ADR-0028), so the browser and backend SDKs speak the same
+ * shape; this module re-exports them for the SDK's public surface and holds only
+ * the browser-specific assembly (`assembleContent`, `collectEnvironment`) and the
+ * `release` validation. Keep the shapes in lock-step with the server: the JSON
+ * `payload` accepted by `POST /api/ingest/feedback`
+ * (`apps/api/src/ingest/ingest.controller.ts`).
+ */
+import { type Breadcrumb, type CaptureEnvironment, type CapturedFrame, type ElementRect, type FeedbackSource, normaliseRelease, type ReportContent, type SelectedElement } from "@fixback/sdk-core";
+import { type Mark, type Rect } from "./annotation";
+export type { CaptureEnvironment, CapturedFrame, ElementRect, FeedbackSource, ReportContent, SelectedElement, };
+export { normaliseRelease };
 /**
  * What the overlay hands to {@link assembleContent} when the Reporter sends. The
  * three marking layers arrive flat (`element` / `region` / `marks`); `assembleContent`
@@ -121,9 +28,13 @@ export interface ReportDraft {
     readonly url?: string;
     readonly environment?: CaptureEnvironment;
     readonly trace?: readonly Breadcrumb[];
-    /** The Reporter's self-provided display name / email (spec §F), if the SDK holds them. */
-    readonly reporterName?: string;
-    readonly reporterEmail?: string;
+    /**
+     * The deploy **Environment** the SDK was configured with (ADR-0025) —
+     * `production` / `staging` / … — distinct from the build `release` in
+     * {@link CaptureEnvironment}. Named apart from `environment` (the capture bag)
+     * to avoid the collision, exactly as the wire does.
+     */
+    readonly deployEnvironment?: string;
 }
 /**
  * Read the capture environment off a window: the viewport size, the browser's

package/dist/reporter-session-store.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The browser's **Reporter session** store (ADR-0032) — the storage binding only.
+ *
+ * After a Connect the SDK holds a compact signed token per origin and forwards it on
+ * every boot; the boot answer hands back a refreshed one (30-day sliding). The token
+ * lives in `localStorage` under a key **scoped by publishable key** (so two Projects on
+ * one origin keep separate sessions), the key format shared with every SDK
+ * (`@fixback/sdk-core`). Persistence is best-effort: a blocked or absent `localStorage`
+ * (private mode) simply means no stored session — the SDK falls back to anonymous
+ * rather than throwing, so it never disturbs the host page.
+ */
+/** Read the stored Reporter session token for this Project, or `null`. */
+export declare function readReporterSession(publishableKey: string): string | null;
+/** Persist a Reporter session token for this Project. Best-effort. */
+export declare function writeReporterSession(publishableKey: string, token: string): void;
+/** Clear the stored Reporter session token for this Project (sign out). Best-effort. */
+export declare function clearReporterSession(publishableKey: string): void;

package/dist/session.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The **session flow** behind `init` (ADR-0032): recognise the Reporter through the
+ * Reporter session token it holds, ask ingest what it may do, and mount only when a
+ * submission would be accepted — while exposing `signIn` / `signOut` / `identity`.
+ *
+ * On boot the SDK forwards its stored **Reporter session** token (from a prior Connect,
+ * scoped per publishable key) and swaps in the refreshed one boot hands back (30-day
+ * sliding). It also detects a one-time code arriving on the `?fixback=` query parameter
+ * — the connect page's redirect fallback, and Fixback-issued links (ticket #250) — and
+ * exchanges it for a session before booting.
+ *
+ * **Connect** binds an Account to the site: `signIn` opens the platform's connect page
+ * (popup, or a full redirect when it is blocked), exchanges the returned code, and
+ * re-boots — so an Open-gated visitor's launcher gains the Account, and a gated
+ * Project's launcher **mounts** once the Account is eligible. The launcher mounts only
+ * when boot returns `canSubmit`, so a gated Project shows nothing to a signed-out
+ * visitor. Everything is wrapped so a Fixback problem resolves to a no-op and never
+ * surfaces on the host page.
+ */
+import type { FixbackInstance, InitOptions } from "./init";
+/** A running SDK that mounted nothing — every failure path resolves to this. */
+export declare const NOOP_INSTANCE: FixbackInstance;
+/**
+ * Run one session: recognise the Reporter, boot, and mount when accepted — exchanging a
+ * `?fixback=` return code first, and exposing Connect (`signIn` / `signOut` / `identity`).
+ */
+export declare function runSession(options: InitOptions, apiUrl: string): Promise<FixbackInstance>;

package/dist/submit.d.ts

@@ -1,6 +1,36 @@
-import { AutoReportBackoff } from "./auto-report-backoff";
-import type { IdentityInputs, ReporterTier } from "./boot";
-import type { ReportContent } from "./report";
+/**
+ * The multipart feedback submission — the transport half of the capture loop.
+ *
+ * `POST /api/ingest/feedback` (spec MVP §C; tickets #50/#53) is a multipart
+ * request: a single text part `payload` carrying the JSON (publishable key +
+ * identity evidence + content) and an optional binary `replay` part — the buffered
+ * rrweb window (ADR-0024), from which the annotated still is reconstructed downstream
+ * (ADR-0027), so the browser SDK rasterises and sends no screenshot. The content-type
+ * header is deliberately not set, so the runtime writes the `multipart/form-data`
+ * boundary itself. Like `requestBoot`, this never throws: an unreachable Fixback or a
+ * refusal is a quiet result, so a Fixback problem never breaks the host page.
+ *
+ * The endpoint, the identity compaction, and the backpressure window are the shared
+ * core's (ADR-0028); what lives here is the browser envelope — a `FormData` with a
+ * `Blob` replay part.
+ *
+ * The `payload` carries the full report content — the structured `annotation`
+ * (element + region + marks, kept vector), the masked `trace` buffer, and the
+ * `source` provenance (spec §D). Automatic reports (`source: error`) additionally
+ * honour ingest's `429` + `Retry-After` backpressure: while the hold window is open
+ * they are dropped without touching the network. Manual reports are never gated
+ * (spec §E/§H).
+ */
+import { AutoReportBackoff, feedbackEndpoint, type FetchLike, type IdentityInputs, type ReportContent, type ReporterTier } from "@fixback/sdk-core";
+export { feedbackEndpoint };
+/**
+ * How long a submission may stay in flight before it is reported as
+ * `unreachable`. A hung connection — a captive portal, a proxy that never
+ * answers — would otherwise leave a report pending forever, and with it the
+ * overlay's "Sending…" state. The abandoned request keeps running in the
+ * background harmlessly. Matches `@fixback/expo`'s and `@fixback/node`'s window.
+ */
+export declare const DEFAULT_SUBMIT_TIMEOUT_MS = 30000;
 /** What ingest returns for an accepted submission (vendored server shape). */
 export interface RecordedFeedback {
     readonly feedbackId: string;
@@ -8,11 +38,6 @@ export interface RecordedFeedback {
     readonly reporterId: string;
     readonly tier: ReporterTier;
 }
-/** The captured screenshot to attach, if any. */
-export interface SubmitScreenshot {
-    readonly blob: Blob;
-    readonly filename?: string;
-}
 /**
  * The buffered replay window to attach, if any — the rrweb events a
  * `ReplaySnapshot` holds (replay.ts). Serialized into its own binary part.
@@ -25,7 +50,6 @@ export interface SubmitInput {
     readonly key: string;
     readonly identity?: IdentityInputs;
     readonly content: ReportContent;
-    readonly screenshot?: SubmitScreenshot | null;
     readonly replay?: SubmitReplay | null;
 }
 /** The outcome of a submission — never an exception. */
@@ -38,7 +62,7 @@ export type SubmitResult = {
     readonly status?: number;
 } | {
     /**
-     * A `source: auto` report shed under ingest backpressure (spec §E/§H) — either
+     * A `source: error` report shed under ingest backpressure (spec §E/§H) — either
      * held locally because the window is still open, or answered `429` by ingest,
      * which opened/extended the window. Carries the seconds left to wait. Manual
      * reports never produce this.
@@ -47,19 +71,32 @@ export type SubmitResult = {
     readonly reason: "backpressure";
     readonly retryAfterSeconds: number;
 };
-/** Join an API base URL with the feedback path, tolerating a trailing slash. */
-export declare function feedbackEndpoint(apiUrl: string): string;
+/**
+ * Injectable transport collaborators, defaulted to the real implementations — the
+ * same deps-object shape `requestBoot` and `@fixback/expo`'s `submitReport` take.
+ */
+export interface SubmitDeps {
+    /** The `fetch` to call. Defaults to the page's global. */
+    readonly fetch?: FetchLike;
+    /**
+     * The shared `source: error` backpressure window. Defaults to the page-wide
+     * instance; tests inject their own to isolate the clock.
+     */
+    readonly backoff?: AutoReportBackoff;
+    /** Overall request timeout in ms; `0` disables. Defaults to {@link DEFAULT_SUBMIT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+}
 /**
  * Submit a report to ingest. Assembles the `payload` JSON (key + identity +
- * content, with an explicit `source` stamped) and the optional full masked
- * `screenshot` file into a `FormData`, posts it, and resolves to the recorded
- * Feedback on success or a named failure otherwise.
+ * content, with an explicit `source` stamped) and the optional `replay` window
+ * into a `FormData`, posts it, and resolves to the recorded Feedback on success
+ * or a named failure otherwise.
  *
- * A `source: auto` report first consults the shared backpressure window: while it
+ * A `source: error` report first consults the shared backpressure window: while it
  * is open the report is dropped without a request (spec §E/§H). Ingest's `429` +
  * `Retry-After` opens/extends that window (default 60 s if the header is absent).
  * Manual reports (`source: reporter`, the default) never consult the window and a
- * non-2xx for them stays a plain refusal. The `fetchImpl` and `backoff` seams exist
- * purely so the call is testable.
+ * non-2xx for them stays a plain refusal. The `deps` seams exist purely so the call
+ * is testable.
  */
-export declare function submitReport(apiUrl: string, input: SubmitInput, fetchImpl?: typeof fetch, backoff?: AutoReportBackoff): Promise<SubmitResult>;
+export declare function submitReport(apiUrl: string, input: SubmitInput, deps?: SubmitDeps): Promise<SubmitResult>;

package/dist/trace/instrument/beacon.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `navigator.sendBeacon` network hook (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.
+ */
+import { type BreadcrumbBuffer, type Teardown } from "@fixback/sdk-core";
+import { type InstrumentWindow } from "./window";
+/** Wrap `navigator.sendBeacon` to record a network crumb per beacon. See the module doc. */
+export declare function instrumentBeacon(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number): Teardown;

package/dist/trace/instrument/console.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The browser's binding for the shared **console** wrapper.
+ *
+ * `instrumentConsole` itself is `@fixback/sdk-core`'s (ADR-0028) — the browser and
+ * React Native wrap `console` identically, and the wrapper takes its target as an
+ * argument rather than reading a global. This module exists so `./trace/instrument`
+ * names every stream it installs, and so the page's `console` is resolved in one
+ * place.
+ */
+export { instrumentConsole, type ConsoleLike } from "@fixback/sdk-core";
+export { globalConsole } from "./window";

package/dist/trace/instrument/fetch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `fetch` network hook (spec #122 §D, ticket #139).
+ *
+ * Wraps the page's `fetch` to record a rich network crumb on settlement: 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.
+ */
+import { type BreadcrumbBuffer, type Teardown } from "@fixback/sdk-core";
+import { type InstrumentWindow } from "./window";
+/** Wrap `fetch` to record a rich network crumb on settlement. See the module doc. */
+export declare function instrumentFetch(buffer: BreadcrumbBuffer, win: InstrumentWindow, ignoreUrl: (url: string) => boolean, now: () => number, mono?: () => number): Teardown;

package/dist/trace/instrument/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The browser SDK's **capture instrumentation** — one hook per stream, plus the
+ * composite that installs them all (spec 0003 §C; spec #122 §A/§D).
+ *
+ * Each hook lives in its own module and takes exactly the surface it patches, so
+ * none of them needs a whole `Window`: `console` (the shared core's wrapper),
+ * `fetch`, `XMLHttpRequest`, `sendBeacon`, `history` + hash navigation, and the
+ * masked `click`/`input` listeners.
+ *
+ * Everything private is kept out **at the source**: `ui.input` records that an
+ * input changed, never its value; network crumbs carry method + URL + status only,
+ * **never** bodies; URLs are scrubbed as the crumb is built. The `beforeSend` choke
+ * point is the final gate over the whole report.
+ *
+ * The SDK stays dependency-free and must never throw into the host page, so every
+ * hook is wrapped: a capture failure is swallowed and the original behaviour (the
+ * real `console`, `fetch`, navigation) always runs.
+ */
+import { type BreadcrumbBuffer, type BreadcrumbLevel, type ConsoleLike, type Teardown } from "@fixback/sdk-core";
+import { type InstrumentWindow } from "./window";
+export { instrumentBeacon } from "./beacon";
+export { instrumentConsole } from "./console";
+export { instrumentFetch } from "./fetch";
+export { instrumentNavigation } from "./navigation";
+export { clickCrumb, inputCrumb, instrumentUiEvents } from "./ui";
+export { instrumentXhr } from "./xhr";
+export { type BeaconNavigator, type FetchFn, globalConsole, globalDocument, globalWindow, type HistoryLike, type InstrumentWindow, type XhrConstructor, type XhrInstance, } from "./window";
+/** Options for {@link instrumentBreadcrumbs} and the individual installers. */
+export interface InstrumentOptions {
+    /** The window to instrument. Defaults to the page's, when there is one. */
+    readonly win?: InstrumentWindow;
+    /** The document whose masked UI events are listened for. Defaults to the page's. */
+    readonly doc?: Document;
+    /** The console to wrap. Defaults to the page's. */
+    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`, `XHR`, and `sendBeacon`
+     * (spec #122 §L; ticket #138). Defaults to `true`; pass `false` and none is
+     * wrapped, so no network entry is ever recorded. Navigation and masked UI events
+     * are unaffected.
+     */
+    readonly captureNetwork?: boolean;
+}
+/**
+ * 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;

package/dist/trace/instrument/navigation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The navigation hook (spec #122 §A): a `navigation` crumb on every SPA route
+ * change — `pushState`, `replaceState`, `popstate`, and `hashchange`.
+ *
+ * Both `history` methods are patched rather than listened for, because neither
+ * fires an event of its own; the original is always called first and its result
+ * returned, so the host page's routing is untouched.
+ */
+import { type BreadcrumbBuffer, type Teardown } from "@fixback/sdk-core";
+import { type InstrumentWindow } from "./window";
+/** Record a `navigation` crumb on `pushState`/`replaceState`/pop/hash changes. */
+export declare function instrumentNavigation(buffer: BreadcrumbBuffer, win: InstrumentWindow, now: () => number): Teardown;

package/dist/trace/instrument/ui.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The masked **user-action** hook (spec #122 §A) and its two crumb builders.
+ *
+ * These are the browser-only crumbs: they need an `Element` to derive a masked CSS
+ * selector from, which is why they stay here rather than in the shared core with
+ * the rest of the builders. The masking is at the source and structural — a
+ * `ui.input` crumb records **that** a field changed and which one, and the shape
+ * has no slot for a value, so the typed text can never be recorded.
+ *
+ * Listeners are capture-phase and passive observers: they never call
+ * `preventDefault` or `stopPropagation`, and the SDK's own chrome (launcher,
+ * overlay, and anything inside their shadow roots) is skipped.
+ */
+import type { Breadcrumb, BreadcrumbBuffer, Teardown } from "@fixback/sdk-core";
+/** 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;
+/** Listen (capture-phase) for clicks and input changes as masked crumbs. */
+export declare function instrumentUiEvents(buffer: BreadcrumbBuffer, doc: Document, now: () => number): Teardown;

package/dist/trace/instrument/window.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The **structural browser surfaces** the trace instrumentation reaches into, and
+ * the resolvers that find them on the page.
+ *
+ * Everything the hooks touch is described as a narrow interface rather than taken
+ * from the DOM lib wholesale, so a test can build a plain object (`fakeWindow()`)
+ * instead of a whole `Window`. The shapes are deliberately written so the **real**
+ * `window` and `console` satisfy them by assignment — no `as unknown as` escape
+ * anywhere, in the SDK or in its tests.
+ */
+import type { ConsoleLike } from "@fixback/sdk-core";
+/** The `fetch` signature the network hook wraps. */
+export type FetchFn = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** The `history` slice the navigation hook patches. */
+export interface HistoryLike {
+    pushState(data: unknown, unused: string, url?: string | URL | null): void;
+    replaceState(data: unknown, unused: string, url?: string | URL | null): void;
+}
+/** The XHR instance surface the network hook touches. */
+export 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;
+}
+/** The XHR constructor whose prototype the network hook patches. */
+export interface XhrConstructor {
+    new (): XhrInstance;
+    prototype: XhrInstance;
+}
+/** The `navigator.sendBeacon` surface the beacon hook 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;
+}
+/** An installed hook's detacher — nothing installed is the no-op below. */
+export declare function noop(): void;
+/**
+ * The page's `window`, when there is one (a worker or an SSR pass has none).
+ * `Window` satisfies {@link InstrumentWindow} structurally, so this is a plain
+ * assignment rather than a cast.
+ */
+export declare function globalWindow(): InstrumentWindow | undefined;
+/** The page's `document`, when there is one. */
+export declare function globalDocument(): Document | undefined;
+/**
+ * The page's `console`, when there is one. A real `Console` satisfies
+ * {@link ConsoleLike} (its optional-method shape is bivariant in its parameters,
+ * which is what makes `console.assert`'s overloads fit), so this too is an
+ * assignment, not a cast.
+ */
+export declare function globalConsole(): ConsoleLike | undefined;