@fixback/sdk 0.3.0 → 0.5.0

package/README.md

@@ -8,9 +8,9 @@ launcher **only when it would**. Nothing renders when the origin isn't
 allowlisted or the Gate turns the visitor away, and if Fixback can't be reached
 the SDK stays completely silent — it never throws into the host page.
 
-Activating the launcher opens the **report overlay**: the Reporter picks a
-**Kind** (bug / improve / idea), writes a comment, optionally **points at the
-element** they mean, and hits **Send** — which captures a **masked screenshot**
+Activating the launcher opens the **report overlay**: the Reporter writes a
+comment, optionally **points at the element** they mean, and hits **Send** —
+which captures a **masked screenshot**
 of the current view, assembles the annotation, and submits it to Fixback. A
 successful send shows a confirmation; a refusal or an unreachable Fixback fails
 quietly, leaving the host page untouched.
@@ -79,11 +79,12 @@ fixback.destroy();
 
 The launcher is a bottom-right **Feedback** pill, and it stays out of the way:
 
-- **Hover-peek & tuck-away** — the pill's caret tucks it off-screen behind a
-  small edge nub. Hovering the bottom-right corner (or the nub) peeks it back;
-  clicking the nub — or pressing Enter/Space on it — brings it fully back, which
-  also covers pointers that can't hover (touch, keyboard). A brief hint appears
-  the first time it's tucked, pointing at the corner.
+- **Hover-peek & tuck-away** — the pill's chevron tucks it off-screen to the
+  right behind a small edge nub, pointing **right** to tuck away and flipping to
+  point **left** while tucked. Hovering the bottom-right corner (or the nub)
+  peeks it back, where clicking that same chevron — or the nub, or pressing
+  Enter/Space on the nub — restores the launcher, which also covers pointers that
+  can't hover (touch, keyboard).
 - **First-visit welcome** — a one-time toast greets a new visitor, drawing the
   eye with a gentle pulse. It shows once per publishable key per browser.
 - **Reduce motion** — pass `reduceMotion: true` to still the pulse and the
@@ -111,8 +112,8 @@ document.addEventListener(LAUNCH_EVENT, () => {
 
 The SDK's signature capability: **errors report themselves, with no prompt.** Two
 capture-phase global handlers (`error` + `unhandledrejection`) turn uncaught
-exceptions and unhandled promise rejections into `source: auto`, `Kind = bug`
-Feedback for the current session's reporter — carrying the same masked screenshot
+exceptions and unhandled promise rejections into `source: auto` Feedback
+(classified `Kind = bug` server-side) for the current session's reporter — carrying the same masked screenshot
 and trace buffer a manual report does, plus a per-session fingerprint. It is
 **on by default across every Gate**; pass `autoCapture: false` to turn it off.
 

package/dist/annotation.d.ts

@@ -1,78 +1,16 @@
 /**
- * The Annotation & vector-marks model (spec 0003 §B/§D).
+ * The Annotation & vector-marks geometry (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).
+ * The Annotation **wire types** (`Annotation`, `Mark` and friends, `Point`,
+ * `Rect`, `SelectedElement`) live in `@fixback/sdk-core` (ADR-0028) so every
+ * surface shares one shape; this module re-exports them and holds the browser's
+ * pure geometry and Send-assembly used by the region-capture and draw controllers
+ * and the overlay. 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).
  */
-export interface Annotation {
-    readonly element?: SelectedElement;
-    readonly region?: Rect;
-    readonly marks?: ReadonlyArray<Mark>;
-}
+import { type Annotation, type ArrowMark, type BoxMark, type DrawTool, type Mark, type PenMark, type Point, type Rect, type SelectedElement, type TextMark } from "@fixback/sdk-core";
+export type { Annotation, ArrowMark, BoxMark, DrawTool, Mark, PenMark, Point, Rect, TextMark, };
 /**
  * The default mark colour — Signal's danger red, matching the frozen Reporter
  * prototype's draw layer (`docs/design/Fixback Reporter.dc.html`).
@@ -103,4 +41,3 @@ export declare function assembleAnnotation(parts: {
     readonly region?: Rect | null;
     readonly marks?: ReadonlyArray<Mark> | null;
 }): Annotation | undefined;
-export {};

package/dist/boot.d.ts

@@ -37,6 +37,12 @@ export interface BootRequest extends IdentityInputs {
 export interface CaptureConfig {
     readonly console: boolean;
     readonly network: boolean;
+    /**
+     * The Project's session-replay toggle (issue #189, ADR-0024). Optional on the
+     * wire: a server predating replay omits it, which — like the other streams —
+     * means **capture on**.
+     */
+    readonly replay?: boolean;
 }
 /**
  * The boot answer: whether this origin is allowlisted, the Project's Gate, the

package/dist/breadcrumbs.d.ts

@@ -18,128 +18,8 @@
  * 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;
-}
+import { type Breadcrumb, type BreadcrumbCategory, type BreadcrumbData, type BreadcrumbLevel, type ConsoleArg, type ConsoleArgType, type NetworkApi, type NetworkOutcome, type SourceLocation } from "@fixback/sdk-core";
+export type { Breadcrumb, BreadcrumbCategory, BreadcrumbData, BreadcrumbLevel, ConsoleArg, ConsoleArgType, NetworkApi, NetworkOutcome, SourceLocation, };
 /**
  * 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
@@ -445,4 +325,3 @@ export declare function instrumentUiEvents(buffer: BreadcrumbBuffer, doc: Docume
  * never blocks the others, and none can throw into the host page.
  */
 export declare function instrumentBreadcrumbs(buffer: BreadcrumbBuffer, options?: InstrumentOptions): Teardown;
-export {};

package/dist/error-capture.d.ts

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