@fixback/sdk 0.3.0 → 0.4.0

package/README.md

@@ -8,9 +8,9 @@ launcher **only when it would**. Nothing renders when the origin isn't
 allowlisted or the Gate turns the visitor away, and if Fixback can't be reached
 the SDK stays completely silent — it never throws into the host page.
 
-Activating the launcher opens the **report overlay**: the Reporter picks a
-**Kind** (bug / improve / idea), writes a comment, optionally **points at the
-element** they mean, and hits **Send** — which captures a **masked screenshot**
+Activating the launcher opens the **report overlay**: the Reporter writes a
+comment, optionally **points at the element** they mean, and hits **Send** —
+which captures a **masked screenshot**
 of the current view, assembles the annotation, and submits it to Fixback. A
 successful send shows a confirmation; a refusal or an unreachable Fixback fails
 quietly, leaving the host page untouched.
@@ -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

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

package/dist/boot.d.ts

@@ -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/error-capture.d.ts

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