@fixback/sdk 0.1.0 → 0.2.0

package/dist/init.d.ts

@@ -1,10 +1,28 @@
 import { type IdentityInputs } from "./boot";
+import { type BeforeBreadcrumb, type BreadcrumbLevel } from "./breadcrumbs";
+import type { BeforeSend } from "./scrub";
 /**
  * The hosted Fixback API origin the SDK talks to by default. A self-hosted or
  * local deployment overrides it with `apiUrl` (the dashboard's install snippet
  * pre-fills the right value for the Project).
  */
 export declare const DEFAULT_API_URL = "https://api.fixback.dev";
+/**
+ * Trace buffer tuning (spec §C). These are configurable **starting points** from
+ * research (N ≈ 30, `warn`/`error`/`assert`, optional ~60 s age cap) — never
+ * frozen magic numbers. Pass `false` for {@link InitOptions.trace} to disable
+ * capture entirely.
+ */
+export interface TraceOptions {
+    /** Keep at most this many crumbs (oldest drop). Defaults to 30. */
+    readonly maxBreadcrumbs?: number;
+    /** Optional age cap in ms (e.g. `60000`); off by default. */
+    readonly maxAgeMs?: number;
+    /** Console levels captured. Defaults to `warn`/`error`/`assert`. */
+    readonly consoleLevels?: readonly BreadcrumbLevel[];
+    /** Per-crumb filter: mute a category, edit a crumb, or drop it (`null`). */
+    readonly beforeBreadcrumb?: BeforeBreadcrumb;
+}
 /** Options for {@link init}. Only `key` is required. */
 export interface InitOptions extends IdentityInputs {
     /** The Project's **publishable** key — an identifier that ships in the page. */
@@ -13,6 +31,39 @@ export interface InitOptions extends IdentityInputs {
     readonly apiUrl?: string;
     /** Where to mount the launcher. Defaults to `document.body`. */
     readonly target?: HTMLElement;
+    /**
+     * Still the launcher's pulse and motion. An explicit opt-in that complements
+     * the visitor's OS-level `prefers-reduced-motion`, which the launcher already
+     * honours on its own.
+     */
+    readonly reduceMotion?: boolean;
+    /**
+     * The synchronous, network-free client scrub hook every report passes through
+     * before transport (spec §C). Mutate the draft to scrub further, or return
+     * `null` to drop the report. Runs after the default scrubbers.
+     */
+    readonly beforeSend?: BeforeSend;
+    /** Run the built-in default scrubbers. Defaults to `true` (private-by-default). */
+    readonly scrub?: boolean;
+    /** Trace buffer tuning, or `false` to turn the buffer off entirely. */
+    readonly trace?: TraceOptions | false;
+    /**
+     * Automatic error capture — the SDK files uncaught exceptions / unhandled
+     * rejections as `source: auto` Feedback with no prompt (spec §E, ADR-0011).
+     * **Default-on across all Gates**; set `false` for the per-project toggle that
+     * turns it off. It is gated by boot's `canSubmit` either way, so an auto-error is
+     * never filed where a manual report would be refused.
+     */
+    readonly autoCapture?: boolean;
+}
+/**
+ * Options for {@link redeem} — the explicit form of the `?fixback_invite=` URL
+ * detection {@link init} performs. Identical to {@link InitOptions} plus the
+ * `token` to redeem (the value the invite link carried).
+ */
+export interface RedeemOptions extends InitOptions {
+    /** The invite token to redeem — the `?fixback_invite=` value from the link. */
+    readonly token: string;
 }
 /** A running SDK instance. */
 export interface FixbackInstance {
@@ -23,12 +74,20 @@ export interface FixbackInstance {
  * Boot the SDK and mount the launcher when — and only when — a submission would
  * be accepted for this key, origin, and Gate.
  *
- * On load the SDK calls the ingest boot endpoint; it mounts the launcher solely
- * when the answer's `canSubmit` is true, so a Reporter is never shown a launcher
- * a submission would be refused (origin off the allowlist, or the Gate turns their
- * tier away). Activating the launcher opens the report overlay (ticket #54) — wired
- * to the launcher's `fixback:launch` seam — from which a Reporter files a complete
- * report. Everything is wrapped so a Fixback problem — unreachable, refused, or an
- * unexpected error — resolves to a no-op instance and never surfaces on the host page.
+ * On load the SDK first checks the page URL for an invite token
+ * (`?fixback_invite=`, spec §F); when one is present and live it renders the
+ * onboarding modal and defers the launcher until the tester redeems. Otherwise it
+ * calls the ingest boot endpoint and mounts the launcher solely when the answer's
+ * `canSubmit` is true — so a Reporter is never shown a launcher a submission would
+ * be refused, and on an Invited / Internal Gate the launcher stays absent until
+ * redemption. Everything is wrapped so a Fixback problem — unreachable, refused,
+ * or an unexpected error — resolves to a no-op instance.
  */
 export declare function init(options: InitOptions): Promise<FixbackInstance>;
+/**
+ * Redeem an invite token explicitly, the programmatic equivalent of landing on a
+ * page with `?fixback_invite=<token>`. Renders the onboarding modal, and on
+ * confirm redeems, persists the `reporterId`, and mounts the launcher (spec §F).
+ * Use it when the token reaches the page some way other than the URL.
+ */
+export declare function redeem(options: RedeemOptions): Promise<FixbackInstance>;

package/dist/invite.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Invite redemption & reporter identity (spec §F).
+ *
+ * The zero-integration path for an invited tester: detect an invite token on the
+ * page (`?fixback_invite=<token>`) or an explicit `redeem()` call, read the
+ * Invite's public status, and — on confirmation — redeem it into a persisted
+ * `reporterId` the SDK thereafter presents as an identity input.
+ *
+ * This module is the wire + storage half (pure enough to unit-test directly): the
+ * two invite endpoints, the localStorage persistence scoped by publishable key,
+ * and the URL token detection / one-time consumption. The onboarding modal is
+ * `onboarding.ts`; `init` wires the two together.
+ *
+ * Like `boot.ts`, the wire types are a **vendored** slice of the server contract
+ * (`apps/api/src/invites/invite-redemption.controller.ts`) — the SDK never imports
+ * the private server package. Keep them in lock-step with that controller.
+ */
+import type { ReporterTier } from "./boot";
+/** The Invite's shape. Mirrors the server's `InviteKind`. */
+export type InviteKind = "targeted" | "shared";
+/** The dead/unknown states a status or redeem read can resolve to. */
+export type InviteDeadStatus = "revoked" | "expired" | "exhausted" | "not_found";
+/**
+ * The public status of an Invite (`GET /api/invites/:token`). A live (`pending`)
+ * Invite reveals the minimal facts the onboarding modal needs — the Project, the
+ * Invite's shape, and the **server-derived** tier the redemption would grant; a
+ * dead or unknown token reveals only its state.
+ */
+export type InviteStatusAnswer = {
+    readonly status: "pending";
+    readonly projectId: string;
+    readonly kind: InviteKind;
+    readonly tier: ReporterTier;
+} | {
+    readonly status: InviteDeadStatus;
+};
+/**
+ * The result of redeeming an Invite (`POST /api/invites/:token/redeem`): the
+ * minted Reporter (its handle + server-derived tier + Project), or why it was
+ * refused.
+ */
+export type RedeemAnswer = {
+    readonly status: "redeemed";
+    readonly reporterId: string;
+    readonly tier: ReporterTier;
+    readonly projectId: string;
+} | {
+    readonly status: InviteDeadStatus;
+};
+/**
+ * The self-provided display fields captured in the onboarding modal. They ride
+ * along as a Reporter's chosen name / email — **never** a trust signal (the tier
+ * is always server-derived, spec §F).
+ */
+export interface ReporterDisplay {
+    readonly name?: string;
+    readonly email?: string;
+}
+/** A persisted redeemed Reporter: the server handle plus the display fields. */
+export interface StoredReporter extends ReporterDisplay {
+    readonly reporterId: string;
+}
+/** The URL query parameter that carries an invite token. */
+export declare const INVITE_QUERY_PARAM = "fixback_invite";
+/**
+ * Read the invite token from a page URL's `?fixback_invite=` param. Returns the
+ * token, or `null` when absent, empty, or the URL cannot be parsed — never throws.
+ */
+export declare function readInviteToken(href: string): string | null;
+/**
+ * Strip the invite token from the address bar (one-time consumption, spec §F) via
+ * `history.replaceState`, so a reload or a shared link cannot re-trigger — or
+ * re-consume — an already-redeemed Invite. Other params, the path, and the hash
+ * are preserved. Best-effort: it never throws into the host page.
+ */
+export declare function stripInviteToken(win: Window): void;
+/**
+ * Persist a redeemed Reporter for `key`. The `reporterId` is the identity the SDK
+ * presents on later boots; the display name / email ride along as chosen fields.
+ * Best-effort — storage being unavailable (private mode) is never fatal.
+ */
+export declare function persistReporter(key: string, reporter: StoredReporter, store?: Storage | null): void;
+/**
+ * Read the redeemed Reporter persisted for `key`, or `null` when none is stored,
+ * the record is malformed, or it carries no `reporterId`. Never throws.
+ */
+export declare function readStoredReporter(key: string, store?: Storage | null): StoredReporter | null;
+/** Join an API base URL with the invite status path, tolerating a trailing slash. */
+export declare function inviteStatusEndpoint(apiUrl: string, token: string): string;
+/** Join an API base URL with the redeem path for a token. */
+export declare function redeemEndpoint(apiUrl: string, token: string): string;
+/**
+ * Read an Invite's public status. Resolves to the answer, or `null` when Fixback
+ * could not be reached or the body was not a recognised answer. The endpoint
+ * answers 200 for a live or dead Invite and 404 (with a JSON body) for an unknown
+ * token, so the body — not the HTTP status — is what the caller narrows on. Never
+ * throws: an outage stays invisible to the host page.
+ */
+export declare function fetchInviteStatus(apiUrl: string, token: string, fetchImpl?: typeof fetch): Promise<InviteStatusAnswer | null>;
+/**
+ * Redeem an Invite by token, minting and returning a Reporter. Resolves to the
+ * answer, or `null` on an unreachable API or an unrecognised body. Never throws.
+ */
+export declare function redeemInviteToken(apiUrl: string, token: string, fetchImpl?: typeof fetch): Promise<RedeemAnswer | null>;

package/dist/launcher.d.ts

@@ -2,22 +2,42 @@
 export declare const ROOT_ATTRIBUTE = "data-fixback-root";
 /**
  * Dispatched from the host element when the launcher is activated. The report
- * overlay this opens is a later ticket (#54); for now the launcher is the mounted
- * entry point, and this event is the seam the overlay will hang off. It is
- * `composed` so host-page listeners outside the Shadow DOM can hear it.
+ * overlay this opens is wired in `init`; this event is the seam it hangs off. It
+ * is `composed` so host-page listeners outside the Shadow DOM can hear it.
  */
 export declare const LAUNCH_EVENT = "fixback:launch";
+/** Options that shape a mounted launcher. */
+export interface LauncherOptions {
+    /**
+     * The Project's publishable key. Scopes the first-visit welcome flag so the
+     * welcome greets once per key per browser.
+     */
+    readonly key?: string;
+    /**
+     * Still the pulse and motion. An explicit opt-in that complements the OS-level
+     * `prefers-reduced-motion` (which the styles already honour on their own).
+     */
+    readonly reduceMotion?: boolean;
+}
 /** A mounted launcher and the handle needed to remove it again. */
 export interface Launcher {
     readonly host: HTMLElement;
+    /** Clears the launcher's pending timers. Called by {@link unmountLauncher}. */
+    readonly dispose: () => void;
 }
 /**
- * Mount the launcher into `target` (typically `document.body`). The visible
- * button lives inside an open Shadow DOM so its styles are fully isolated from
- * the host page and vice-versa; the host element itself is fixed-positioned and
- * out of flow, so mounting never shifts the host page's layout. Only one launcher
- * can exist at a time — an earlier one is removed first.
+ * Mount the launcher into `target` (typically `document.body`). Everything the
+ * launcher draws — the **Feedback** pill, its **tuck** control, the edge **nub**
+ * and corner **hover-zone** that peek it back, and the first-visit **welcome**
+ * and tuck-away **hint** toasts — lives inside one open Shadow DOM, so its styles
+ * are fully isolated from the host page and vice-versa. The host element is
+ * fixed-positioned and out of flow, so mounting never shifts the host page's
+ * layout. Only one launcher can exist at a time — an earlier one is removed first.
+ *
+ * Tuck/peek state is expressed as `data-fb-hidden` / `data-fb-peeking` attributes
+ * on the host, which the Shadow DOM stylesheet animates; `reduceMotion` sets
+ * `data-fb-reduce-motion`, which (with the OS `prefers-reduced-motion`) stills it.
  */
-export declare function mountLauncher(target: HTMLElement): Launcher;
+export declare function mountLauncher(target: HTMLElement, options?: LauncherOptions): Launcher;
 /** Remove a mounted launcher. Safe to call more than once. */
 export declare function unmountLauncher(launcher: Launcher): void;

package/dist/onboarding-styles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Styles for the invite onboarding modal (spec §F) — the Signal look of the
+ * frozen Reporter prototype (`docs/design/Fixback Reporter.dc.html`), scoped to
+ * the modal's own Shadow DOM so the host page is never touched and never touches
+ * it. Tokens mirror `overlay-styles.ts` so launcher, overlay, and modal read as
+ * one system.
+ */
+export declare const ONBOARDING_STYLES = "\n:host {\n  --fb-color-accent: #2f6fed;\n  --fb-color-accent-hover: #245fd0;\n  --fb-color-on-emphasis: #ffffff;\n  --fb-color-ink: #0f1720;\n  --fb-color-text: #1a2530;\n  --fb-color-muted: #5a6875;\n  --fb-color-faint: #9aa7b2;\n  --fb-color-hint: #b7c1cb;\n  --fb-color-border: #dce3ea;\n  --fb-color-border-soft: #e6ebf0;\n  --fb-color-surface: #ffffff;\n  --fb-color-card: #f6f8fa;\n  --fb-color-accent-bg: #eaf1fe;\n  --fb-color-success: #2f9e5b;\n  --fb-font-sans: \"IBM Plex Sans\", system-ui, -apple-system, \"Segoe UI\", Roboto,\n    Helvetica, Arial, sans-serif;\n  --fb-font-mono: \"IBM Plex Mono\", ui-monospace, \"SFMono-Regular\", Menlo, Consolas,\n    monospace;\n  all: initial;\n}\n\n*, *::before, *::after { box-sizing: border-box; }\n\n.fb-ob-backdrop {\n  position: fixed;\n  inset: 0;\n  z-index: 2147483010;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  padding: 24px;\n  background: rgba(15, 23, 32, 0.55);\n  backdrop-filter: blur(3px);\n  font-family: var(--fb-font-sans);\n  color: var(--fb-color-text);\n  animation: fb-ob-fade 0.25s ease both;\n}\n\n.fb-ob-panel {\n  width: 400px;\n  max-width: 100%;\n  background: var(--fb-color-surface);\n  border-radius: 16px;\n  box-shadow: 0 30px 70px rgba(15, 40, 70, 0.4);\n  overflow: hidden;\n  animation: fb-ob-pop 0.32s cubic-bezier(0.2, 0.8, 0.3, 1) both;\n}\n\n.fb-ob-head {\n  padding: 22px 24px 0;\n  display: flex;\n  align-items: center;\n  gap: 10px;\n}\n.fb-ob-mark {\n  width: 22px;\n  height: 22px;\n  border-radius: 6px;\n  background: var(--fb-color-accent);\n  flex: none;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n}\n.fb-ob-mark::after {\n  content: \"\";\n  width: 7px;\n  height: 7px;\n  border-radius: 2px;\n  background: #fff;\n}\n.fb-ob-brand { font-size: 15px; font-weight: 600; color: var(--fb-color-ink); }\n.fb-ob-chip {\n  margin-left: auto;\n  font-family: var(--fb-font-mono);\n  font-size: 10px;\n  color: #8a97a3;\n  border: 1px solid var(--fb-color-border-soft);\n  border-radius: 6px;\n  padding: 2px 7px;\n}\n\n.fb-ob-body { padding: 16px 24px 8px; }\n.fb-ob-title {\n  font-size: 19px;\n  font-weight: 700;\n  color: var(--fb-color-ink);\n  letter-spacing: -0.01em;\n}\n.fb-ob-lede {\n  font-size: 13.5px;\n  color: var(--fb-color-muted);\n  line-height: 1.5;\n  margin: 7px 0 0;\n}\n.fb-ob-lede strong { color: var(--fb-color-text); }\n\n.fb-ob-card {\n  margin: 16px 0;\n  padding: 13px 14px;\n  background: var(--fb-color-card);\n  border: 1px solid var(--fb-color-border-soft);\n  border-radius: 10px;\n  display: flex;\n  flex-direction: column;\n  gap: 10px;\n}\n.fb-ob-row { display: flex; align-items: center; gap: 10px; }\n.fb-ob-row + .fb-ob-row {\n  border-top: 1px solid #eef2f6;\n  padding-top: 10px;\n}\n.fb-ob-rowlabel {\n  font-family: var(--fb-font-mono);\n  font-size: 10px;\n  color: var(--fb-color-faint);\n  width: 70px;\n  flex: none;\n}\n.fb-ob-site { font-size: 13px; color: var(--fb-color-text); font-weight: 500; }\n.fb-ob-tier {\n  font-size: 11px;\n  font-weight: 600;\n  color: var(--fb-color-accent);\n  background: var(--fb-color-accent-bg);\n  padding: 3px 9px;\n  border-radius: 6px;\n}\n.fb-ob-tiernote { font-size: 11.5px; color: #8a97a3; }\n\n.fb-ob-fieldlabel {\n  display: block;\n  font-family: var(--fb-font-mono);\n  font-size: 10px;\n  letter-spacing: 0.05em;\n  text-transform: uppercase;\n  color: var(--fb-color-faint);\n  margin-bottom: 6px;\n}\n.fb-ob-fields { display: flex; gap: 8px; }\n.fb-ob-input {\n  height: 38px;\n  padding: 0 12px;\n  border: 1px solid var(--fb-color-border);\n  border-radius: 9px;\n  font-family: inherit;\n  font-size: 13px;\n  color: var(--fb-color-text);\n  outline: none;\n  min-width: 0;\n}\n.fb-ob-input:focus { border-color: var(--fb-color-accent); }\n.fb-ob-name { flex: 1; }\n.fb-ob-email { flex: 1.3; font-family: var(--fb-font-mono); font-size: 12.5px; color: var(--fb-color-muted); }\n\n.fb-ob-privacy {\n  display: flex;\n  align-items: flex-start;\n  gap: 8px;\n  margin-top: 14px;\n  font-size: 11.5px;\n  color: #8a97a3;\n  line-height: 1.5;\n}\n.fb-ob-privacy svg { flex: none; margin-top: 1px; }\n.fb-ob-privacy strong { color: var(--fb-color-muted); }\n\n.fb-ob-foot { padding: 16px 24px 22px; }\n.fb-ob-confirm {\n  width: 100%;\n  height: 44px;\n  border: 0;\n  border-radius: 11px;\n  background: var(--fb-color-accent);\n  color: var(--fb-color-on-emphasis);\n  font-family: inherit;\n  font-size: 14px;\n  font-weight: 600;\n  cursor: pointer;\n}\n.fb-ob-confirm:hover { background: var(--fb-color-accent-hover); }\n.fb-ob-confirm:disabled { opacity: 0.6; cursor: default; }\n\n@keyframes fb-ob-fade { from { opacity: 0; } to { opacity: 1; } }\n@keyframes fb-ob-pop {\n  from { opacity: 0; transform: translateY(8px) scale(0.98); }\n  to { opacity: 1; transform: none; }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .fb-ob-backdrop, .fb-ob-panel { animation: none; }\n}\n";

package/dist/onboarding.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The invite onboarding modal (spec §F) — the SDK-rendered redemption screen an
+ * invited tester sees when a page carries an invite token. It shows the site
+ * they were invited to, the **server-derived** access tier the redemption grants,
+ * a private-by-default note, and a "Continue as" name / email, then confirms.
+ *
+ * Built to the frozen Signal Reporter prototype
+ * (`docs/design/Fixback Reporter.dc.html`). It mounts lazily inside its own open
+ * Shadow DOM so the host page is fully isolated, and — like the launcher and
+ * overlay — never throws into the host page. It renders only data the SDK
+ * truthfully holds: the site's own origin and the server-derived tier. The name /
+ * email are **self-provided display fields**, never a trust signal (§F).
+ */
+import type { ReporterTier } from "./boot";
+import type { ReporterDisplay } from "./invite";
+/** Marks the modal's host element in the light DOM, so it is findable and unique. */
+export declare const ONBOARDING_ATTRIBUTE = "data-fixback-onboard";
+/** Configuration for {@link createOnboardingModal}. */
+export interface OnboardingConfig {
+    /** The site the tester was invited to — its origin (`window.location.host`). */
+    readonly origin: string;
+    /** The **server-derived** tier the redemption grants (from the invite status). */
+    readonly tier: ReporterTier;
+    /** Prefill the Continue-as fields from a previously stored display identity. */
+    readonly defaults?: ReporterDisplay;
+    /** Called with the self-provided display fields when the tester confirms. */
+    readonly onConfirm: (display: ReporterDisplay) => void;
+    /** Where to mount the modal host. Defaults to `document.body`. */
+    readonly target?: HTMLElement;
+    /** The document to build in. Defaults to the target's owner document. */
+    readonly doc?: Document;
+}
+/** A mounted onboarding modal. */
+export interface OnboardingModal {
+    destroy(): void;
+    readonly host: HTMLElement;
+}
+/**
+ * Render the onboarding modal into `target` (default `document.body`) and return a
+ * handle to remove it. Confirming reads the name / email, fires `onConfirm` once
+ * (further clicks are ignored while the caller redeems), and leaves teardown to
+ * the caller so it can strip the token and mount the launcher first.
+ */
+export declare function createOnboardingModal(config: OnboardingConfig): OnboardingModal;

package/dist/overlay-styles.d.ts

@@ -6,4 +6,4 @@
  * vendored Signal tokens (copied from `packages/ui/src/tokens.css`, not imported —
  * the SDK must not depend on `@fixback/ui` at runtime). Keep them in sync by value.
  */
-export declare const OVERLAY_STYLES = "\n:host {\n  --fb-color-accent: #2f6fed;\n  --fb-color-accent-hover: #245fd0;\n  --fb-color-on-emphasis: #ffffff;\n  --fb-color-ink: #0f1720;\n  --fb-color-text: #1a2530;\n  --fb-color-muted: #5a6875;\n  --fb-color-faint: #9aa7b2;\n  --fb-color-border: #e0e6ec;\n  --fb-color-border-soft: #e6ebf0;\n  --fb-color-surface: #ffffff;\n  --fb-color-bug: #e5484d;\n  --fb-color-bug-bg: #fdecec;\n  --fb-color-impr: #2f6fed;\n  --fb-color-impr-bg: #eaf1fe;\n  --fb-color-idea: #8b5cf6;\n  --fb-color-idea-bg: #f2ecfe;\n  --fb-color-success: #2f9e5b;\n  --fb-font-sans: \"IBM Plex Sans\", system-ui, -apple-system, \"Segoe UI\", Roboto,\n    Helvetica, Arial, sans-serif;\n  --fb-font-mono: \"IBM Plex Mono\", ui-monospace, \"SFMono-Regular\", Menlo, Consolas,\n    monospace;\n\n  display: block;\n  color: var(--fb-color-text);\n  font-family: var(--fb-font-sans);\n  font-size: 13px;\n  line-height: 1.45;\n  -webkit-font-smoothing: antialiased;\n}\n\n* { box-sizing: border-box; }\n\n.fb-ov-panel {\n  width: 300px;\n  max-width: calc(100vw - 40px);\n  background: var(--fb-color-surface);\n  border: 1px solid var(--fb-color-border);\n  border-radius: 13px;\n  box-shadow: 0 18px 44px rgba(20, 40, 70, 0.2);\n  overflow: hidden;\n}\n\n.fb-ov-head {\n  display: flex;\n  align-items: center;\n  gap: 9px;\n  padding: 12px 14px;\n  border-bottom: 1px solid var(--fb-color-border-soft);\n}\n.fb-ov-mark-sq {\n  width: 13px;\n  height: 13px;\n  border-radius: 4px;\n  background: var(--fb-color-accent);\n  flex: none;\n}\n.fb-ov-brand { font-size: 14px; font-weight: 600; color: var(--fb-color-ink); }\n.fb-ov-close {\n  margin-left: auto;\n  border: 0;\n  background: none;\n  color: var(--fb-color-faint);\n  font-size: 16px;\n  line-height: 1;\n  padding: 2px 4px;\n  cursor: pointer;\n  border-radius: 6px;\n}\n.fb-ov-close:hover { color: var(--fb-color-muted); background: #f4f7fa; }\n\n.fb-ov-tabs { display: flex; gap: 6px; padding: 12px 14px 6px; }\n.fb-ov-tab {\n  flex: 1;\n  text-align: center;\n  font-size: 11px;\n  font-weight: 600;\n  padding: 6px;\n  border-radius: 7px;\n  border: 1px solid var(--fb-color-border);\n  background: var(--fb-color-surface);\n  color: var(--fb-color-muted);\n  cursor: pointer;\n  font-family: inherit;\n}\n.fb-ov-tab:hover { border-color: #cfd8e2; }\n.fb-ov-tab.is-active[data-kind=\"bug\"] {\n  background: var(--fb-color-bug-bg); color: var(--fb-color-bug); border-color: transparent;\n}\n.fb-ov-tab.is-active[data-kind=\"improvement\"] {\n  background: var(--fb-color-impr-bg); color: var(--fb-color-impr); border-color: transparent;\n}\n.fb-ov-tab.is-active[data-kind=\"idea\"] {\n  background: var(--fb-color-idea-bg); color: var(--fb-color-idea); border-color: transparent;\n}\n\n.fb-ov-mark {\n  margin: 10px 14px;\n  min-height: 52px;\n  border-radius: 9px;\n  border: 1px solid var(--fb-color-border-soft);\n  background: repeating-linear-gradient(135deg, #f4f7fa, #f4f7fa 7px, #eaeff4 7px, #eaeff4 14px);\n  display: flex;\n  flex-direction: column;\n  align-items: flex-start;\n  justify-content: center;\n  gap: 6px;\n  padding: 10px 12px;\n}\n.fb-ov-selector {\n  display: none;\n  max-width: 100%;\n  font-family: var(--fb-font-mono);\n  font-size: 10px;\n  color: var(--fb-color-on-emphasis);\n  background: var(--fb-color-accent);\n  padding: 3px 8px;\n  border-radius: 5px;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n.fb-ov-mark.has-element .fb-ov-selector { display: inline-block; }\n.fb-ov-mark-caption { font-size: 10px; color: var(--fb-color-faint); font-family: var(--fb-font-mono); }\n\n.fb-ov-comment {\n  display: block;\n  width: calc(100% - 28px);\n  margin: 0 14px 10px;\n  min-height: 62px;\n  resize: vertical;\n  font-family: inherit;\n  font-size: 13px;\n  color: var(--fb-color-text);\n  border: 1px solid var(--fb-color-border-soft);\n  border-radius: 9px;\n  padding: 10px 11px;\n}\n.fb-ov-comment::placeholder { color: var(--fb-color-faint); }\n.fb-ov-comment:focus-visible { outline: 2px solid var(--fb-color-accent); outline-offset: 1px; }\n\n.fb-ov-status { padding: 0 14px; font-size: 11px; min-height: 0; }\n.fb-ov-status.is-error { color: var(--fb-color-bug); }\n\n.fb-ov-tools { display: flex; align-items: center; gap: 8px; padding: 8px 14px 14px; }\n.fb-ov-pickbtn {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  font-family: inherit;\n  font-size: 12px;\n  color: var(--fb-color-muted);\n  background: var(--fb-color-surface);\n  border: 1px solid var(--fb-color-border);\n  border-radius: 8px;\n  padding: 8px 11px;\n  cursor: pointer;\n}\n.fb-ov-pickbtn:hover { border-color: #cfd8e2; }\n.fb-ov-pickbtn.is-active {\n  color: var(--fb-color-accent);\n  border-color: var(--fb-color-accent);\n  background: var(--fb-color-impr-bg);\n}\n.fb-ov-pickbtn__glyph { font-size: 14px; line-height: 1; }\n\n.fb-ov-send {\n  margin-left: auto;\n  font-family: inherit;\n  font-size: 13px;\n  font-weight: 600;\n  color: var(--fb-color-on-emphasis);\n  background: var(--fb-color-accent);\n  border: 0;\n  border-radius: 8px;\n  padding: 9px 18px;\n  cursor: pointer;\n}\n.fb-ov-send:hover { background: var(--fb-color-accent-hover); }\n.fb-ov-send:disabled { opacity: 0.6; cursor: default; }\n\n.fb-ov-done { display: none; padding: 24px 18px; text-align: center; }\n.fb-ov-panel.is-sent .fb-ov-form { display: none; }\n.fb-ov-panel.is-sent .fb-ov-done { display: block; }\n.fb-ov-done__check {\n  width: 40px; height: 40px; margin: 0 auto 12px;\n  border-radius: 50%;\n  background: #e7f6ee; color: var(--fb-color-success);\n  display: flex; align-items: center; justify-content: center;\n  font-size: 20px; font-weight: 700;\n}\n.fb-ov-done__title { font-size: 15px; font-weight: 600; color: var(--fb-color-ink); }\n.fb-ov-done__sub { font-size: 12px; color: var(--fb-color-muted); margin-top: 4px; }\n\n.fb-ov-pick { position: fixed; inset: 0; pointer-events: none; z-index: 2147483002; display: none; }\n.fb-ov-panel.is-picking + .fb-ov-pick { display: block; }\n.fb-ov-panel.is-picking { visibility: hidden; }\n.fb-ov-highlight {\n  position: absolute;\n  border: 2px dashed var(--fb-color-accent);\n  border-radius: 6px;\n  box-shadow: 0 0 0 3px rgba(47, 111, 237, 0.14);\n  transition: all 60ms ease;\n}\n.fb-ov-hint {\n  position: absolute;\n  top: 16px;\n  left: 50%;\n  transform: translateX(-50%);\n  font-family: var(--fb-font-mono);\n  font-size: 11px;\n  color: var(--fb-color-on-emphasis);\n  background: var(--fb-color-ink);\n  padding: 6px 12px;\n  border-radius: 7px;\n  box-shadow: 0 8px 20px rgba(20, 40, 70, 0.25);\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .fb-ov-highlight { transition: none; }\n}\n";
+export declare const OVERLAY_STYLES = "\n:host {\n  --fb-color-accent: #2f6fed;\n  --fb-color-accent-hover: #245fd0;\n  --fb-color-on-emphasis: #ffffff;\n  --fb-color-ink: #0f1720;\n  --fb-color-text: #1a2530;\n  --fb-color-muted: #5a6875;\n  --fb-color-faint: #9aa7b2;\n  --fb-color-border: #e0e6ec;\n  --fb-color-border-soft: #e6ebf0;\n  --fb-color-surface: #ffffff;\n  --fb-color-bug: #e5484d;\n  --fb-color-bug-bg: #fdecec;\n  --fb-color-impr: #2f6fed;\n  --fb-color-impr-bg: #eaf1fe;\n  --fb-color-idea: #8b5cf6;\n  --fb-color-idea-bg: #f2ecfe;\n  --fb-color-success: #2f9e5b;\n  --fb-font-sans: \"IBM Plex Sans\", system-ui, -apple-system, \"Segoe UI\", Roboto,\n    Helvetica, Arial, sans-serif;\n  --fb-font-mono: \"IBM Plex Mono\", ui-monospace, \"SFMono-Regular\", Menlo, Consolas,\n    monospace;\n\n  display: block;\n  color: var(--fb-color-text);\n  font-family: var(--fb-font-sans);\n  font-size: 13px;\n  line-height: 1.45;\n  -webkit-font-smoothing: antialiased;\n}\n\n* { box-sizing: border-box; }\n\n.fb-ov-panel {\n  width: 300px;\n  max-width: calc(100vw - 40px);\n  background: var(--fb-color-surface);\n  border: 1px solid var(--fb-color-border);\n  border-radius: 13px;\n  box-shadow: 0 18px 44px rgba(20, 40, 70, 0.2);\n  overflow: hidden;\n}\n\n.fb-ov-head {\n  display: flex;\n  align-items: center;\n  gap: 9px;\n  padding: 12px 14px;\n  border-bottom: 1px solid var(--fb-color-border-soft);\n}\n.fb-ov-mark-sq {\n  width: 13px;\n  height: 13px;\n  border-radius: 4px;\n  background: var(--fb-color-accent);\n  flex: none;\n}\n.fb-ov-brand { font-size: 14px; font-weight: 600; color: var(--fb-color-ink); }\n.fb-ov-tier {\n  flex: none;\n  font-family: var(--fb-font-mono);\n  font-size: 9.5px;\n  color: var(--fb-color-faint);\n  border: 1px solid var(--fb-color-border-soft);\n  border-radius: 5px;\n  padding: 1px 6px;\n}\n.fb-ov-close {\n  margin-left: auto;\n  border: 0;\n  background: none;\n  color: var(--fb-color-faint);\n  font-size: 16px;\n  line-height: 1;\n  padding: 2px 4px;\n  cursor: pointer;\n  border-radius: 6px;\n}\n.fb-ov-close:hover { color: var(--fb-color-muted); background: #f4f7fa; }\n\n.fb-ov-tabs { display: flex; gap: 6px; padding: 12px 14px 6px; }\n.fb-ov-tab {\n  flex: 1;\n  text-align: center;\n  font-size: 11px;\n  font-weight: 600;\n  padding: 6px;\n  border-radius: 7px;\n  border: 1px solid var(--fb-color-border);\n  background: var(--fb-color-surface);\n  color: var(--fb-color-muted);\n  cursor: pointer;\n  font-family: inherit;\n}\n.fb-ov-tab:hover { border-color: #cfd8e2; }\n.fb-ov-tab.is-active[data-kind=\"bug\"] {\n  background: var(--fb-color-bug-bg); color: var(--fb-color-bug); border-color: transparent;\n}\n.fb-ov-tab.is-active[data-kind=\"improvement\"] {\n  background: var(--fb-color-impr-bg); color: var(--fb-color-impr); border-color: transparent;\n}\n.fb-ov-tab.is-active[data-kind=\"idea\"] {\n  background: var(--fb-color-idea-bg); color: var(--fb-color-idea); border-color: transparent;\n}\n\n.fb-ov-mark {\n  margin: 10px 14px;\n  min-height: 52px;\n  border-radius: 9px;\n  border: 1px solid var(--fb-color-border-soft);\n  background: repeating-linear-gradient(135deg, #f4f7fa, #f4f7fa 7px, #eaeff4 7px, #eaeff4 14px);\n  display: flex;\n  flex-direction: column;\n  align-items: flex-start;\n  justify-content: center;\n  gap: 6px;\n  padding: 10px 12px;\n}\n.fb-ov-selector {\n  display: none;\n  max-width: 100%;\n  font-family: var(--fb-font-mono);\n  font-size: 10px;\n  color: var(--fb-color-on-emphasis);\n  background: var(--fb-color-accent);\n  padding: 3px 8px;\n  border-radius: 5px;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n.fb-ov-mark.has-element .fb-ov-selector { display: inline-block; }\n.fb-ov-mark-caption { font-size: 10px; color: var(--fb-color-faint); font-family: var(--fb-font-mono); }\n\n.fb-ov-comment {\n  display: block;\n  width: calc(100% - 28px);\n  margin: 0 14px 10px;\n  min-height: 62px;\n  resize: vertical;\n  font-family: inherit;\n  font-size: 13px;\n  color: var(--fb-color-text);\n  border: 1px solid var(--fb-color-border-soft);\n  border-radius: 9px;\n  padding: 10px 11px;\n}\n.fb-ov-comment::placeholder { color: var(--fb-color-faint); }\n.fb-ov-comment:focus-visible { outline: 2px solid var(--fb-color-accent); outline-offset: 1px; }\n\n.fb-ov-status { padding: 0 14px; font-size: 11px; min-height: 0; }\n.fb-ov-status.is-error { color: var(--fb-color-bug); }\n\n.fb-ov-tools { display: flex; align-items: center; gap: 7px; padding: 8px 14px 14px; }\n.fb-ov-pickbtn,\n.fb-ov-capturebtn {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  font-family: inherit;\n  font-size: 12px;\n  color: var(--fb-color-muted);\n  background: var(--fb-color-surface);\n  border: 1px solid var(--fb-color-border);\n  border-radius: 8px;\n  padding: 8px 11px;\n  cursor: pointer;\n}\n.fb-ov-capturebtn { padding: 8px 9px; }\n.fb-ov-pickbtn:hover,\n.fb-ov-capturebtn:hover { border-color: #cfd8e2; }\n.fb-ov-pickbtn.is-active,\n.fb-ov-capturebtn.is-active,\n.fb-ov-capturebtn.is-attached {\n  color: var(--fb-color-accent);\n  border-color: var(--fb-color-accent);\n  background: var(--fb-color-impr-bg);\n}\n.fb-ov-pickbtn__glyph { font-size: 14px; line-height: 1; }\n.fb-ov-icon { display: block; }\n\n.fb-ov-send {\n  margin-left: auto;\n  font-family: inherit;\n  font-size: 13px;\n  font-weight: 600;\n  color: var(--fb-color-on-emphasis);\n  background: var(--fb-color-accent);\n  border: 0;\n  border-radius: 8px;\n  padding: 9px 18px;\n  cursor: pointer;\n}\n.fb-ov-send:hover { background: var(--fb-color-accent-hover); }\n.fb-ov-send:disabled { opacity: 0.6; cursor: default; }\n\n.fb-ov-done { display: none; padding: 24px 18px; text-align: center; }\n.fb-ov-panel.is-sent .fb-ov-form { display: none; }\n.fb-ov-panel.is-sent .fb-ov-done { display: block; }\n.fb-ov-done__check {\n  width: 40px; height: 40px; margin: 0 auto 12px;\n  border-radius: 50%;\n  background: #e7f6ee; color: var(--fb-color-success);\n  display: flex; align-items: center; justify-content: center;\n  font-size: 20px; font-weight: 700;\n}\n.fb-ov-done__title { font-size: 15px; font-weight: 600; color: var(--fb-color-ink); }\n.fb-ov-done__sub { font-size: 12px; color: var(--fb-color-muted); margin-top: 4px; }\n\n/* The panel is hidden while any full-screen marking layer is active. */\n.fb-ov-panel.is-marking { visibility: hidden; }\n\n.fb-ov-pick,\n.fb-ov-capture,\n.fb-ov-draw { position: fixed; inset: 0; z-index: 2147483002; display: none; }\n.fb-ov-pick.is-visible,\n.fb-ov-capture.is-visible,\n.fb-ov-draw.is-visible { display: block; }\n\n/* Element-pick highlight layer \u2014 visual only, never intercepts host events. */\n.fb-ov-pick { pointer-events: none; }\n.fb-ov-highlight {\n  position: absolute;\n  border: 2px dashed var(--fb-color-accent);\n  border-radius: 6px;\n  box-shadow: 0 0 0 3px rgba(47, 111, 237, 0.14);\n  transition: all 60ms ease;\n}\n.fb-ov-hint {\n  position: absolute;\n  top: 16px;\n  left: 50%;\n  transform: translateX(-50%);\n  font-family: var(--fb-font-mono);\n  font-size: 11px;\n  color: var(--fb-color-on-emphasis);\n  background: var(--fb-color-ink);\n  padding: 6px 12px;\n  border-radius: 7px;\n  box-shadow: 0 8px 20px rgba(20, 40, 70, 0.25);\n}\n\n/* Region-capture layer \u2014 a dim wash with a live selection box. */\n.fb-ov-capture { cursor: crosshair; }\n.fb-ov-capture-dim { position: absolute; inset: 0; background: rgba(15, 23, 32, 0.28); }\n.fb-ov-capture-sel {\n  position: absolute;\n  border: 2px solid var(--fb-color-accent);\n  border-radius: 4px;\n  box-shadow: 0 0 0 100vmax rgba(15, 23, 32, 0.32);\n}\n\n/* Draw layer \u2014 the mark SVG, the region frame, the label input, and the toolbar. */\n.fb-ov-draw-svg { position: absolute; inset: 0; width: 100%; height: 100%; overflow: visible; pointer-events: none; }\n.fb-ov-draw-frame {\n  position: absolute;\n  border: 1px solid rgba(47, 111, 237, 0.5);\n  border-radius: 4px;\n  box-shadow: 0 0 0 100vmax rgba(15, 23, 32, 0.18);\n  pointer-events: none;\n}\n.fb-ov-draw-text {\n  position: absolute;\n  display: none;\n  font-family: var(--fb-font-sans);\n  font-size: 15px;\n  font-weight: 600;\n  color: var(--fb-color-bug);\n  background: rgba(255, 255, 255, 0.92);\n  border: 1px dashed var(--fb-color-bug);\n  border-radius: 4px;\n  padding: 2px 6px;\n  outline: none;\n  z-index: 3;\n}\n.fb-ov-draw-toolbar {\n  position: fixed;\n  left: 50%;\n  bottom: 26px;\n  transform: translateX(-50%);\n  display: flex;\n  align-items: center;\n  gap: 5px;\n  background: var(--fb-color-ink);\n  border-radius: 12px;\n  padding: 7px;\n  box-shadow: 0 16px 40px rgba(15, 40, 70, 0.4);\n}\n.fb-ov-drawtool {\n  width: 34px;\n  height: 34px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  border: 0;\n  border-radius: 8px;\n  background: transparent;\n  color: #c4ccd4;\n  cursor: pointer;\n  font-family: inherit;\n}\n.fb-ov-drawtool:hover { background: rgba(255, 255, 255, 0.08); color: #fff; }\n.fb-ov-drawtool.is-active { background: var(--fb-color-accent); color: var(--fb-color-on-emphasis); }\n.fb-ov-drawtool__t { font-weight: 700; font-size: 14px; line-height: 1; }\n.fb-ov-draw-divider { width: 1px; height: 22px; background: #2a343e; margin: 0 3px; }\n.fb-ov-draw-undo {\n  width: 34px;\n  height: 34px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  border: 0;\n  border-radius: 8px;\n  background: transparent;\n  color: #c4ccd4;\n  cursor: pointer;\n}\n.fb-ov-draw-undo:hover:not(:disabled) { background: rgba(255, 255, 255, 0.08); color: #fff; }\n.fb-ov-draw-undo:disabled { opacity: 0.4; cursor: default; }\n.fb-ov-draw-cancel {\n  height: 34px;\n  padding: 0 12px;\n  border: 0;\n  border-radius: 8px;\n  background: transparent;\n  color: var(--fb-color-faint);\n  font-family: inherit;\n  font-size: 12.5px;\n  cursor: pointer;\n}\n.fb-ov-draw-cancel:hover { color: #fff; }\n.fb-ov-draw-attach {\n  height: 34px;\n  padding: 0 15px;\n  border: 0;\n  border-radius: 8px;\n  background: var(--fb-color-accent);\n  color: var(--fb-color-on-emphasis);\n  font-family: inherit;\n  font-size: 12.5px;\n  font-weight: 600;\n  cursor: pointer;\n}\n.fb-ov-draw-attach:hover { background: var(--fb-color-accent-hover); }\n\n@media (prefers-reduced-motion: reduce) {\n  .fb-ov-highlight { transition: none; }\n}\n";

package/dist/overlay.d.ts

@@ -1,5 +1,7 @@
-import type { IdentityInputs } from "./boot";
+import type { IdentityInputs, ProjectGate, ReporterTier } from "./boot";
+import type { Breadcrumb } from "./breadcrumbs";
 import { type ElementPicker, type ElementPickerOptions } from "./element-picker";
+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). */
@@ -13,17 +15,40 @@ export interface OverlayDeps {
     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;
+    /**
+     * The Project's Gate, forwarded verbatim from the boot answer. Reserved for
+     * Gate-aware launcher / redemption behaviour (spec §A/§F); the overlay itself
+     * does not read it yet, but `init` plumbs it through here (ticket #85 / §G).
+     */
+    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.
+     */
+    readonly tier?: ReporterTier | null;
     readonly sdkVersion?: string;
     /** Where to mount the overlay host. Defaults to `document.body`. */
     readonly target?: HTMLElement;
     readonly doc?: Document;
     readonly win?: Window;
     readonly deps?: Partial<OverlayDeps>;
+    /** The trace buffer whose snapshot rides on each report (spec §C). */
+    readonly buffer?: BreadcrumbSource | null;
+    /** Per-project client scrub hook, run at the `beforeSend` choke point. */
+    readonly beforeSend?: BeforeSend;
+    /** Run the built-in default scrubbers. Defaults to `true` (private-by-default). */
+    readonly scrub?: boolean;
 }
 /** A mounted overlay the launcher opens. */
 export interface OverlayController {
@@ -34,11 +59,16 @@ export interface OverlayController {
 }
 /**
  * Create the report overlay — the on-page panel a Reporter files a report from,
- * built to the frozen Signal overlay (`1d`). 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 on
- * Send captures a masked screenshot, assembles the Annotation, and submits to
- * ingest — showing a confirmation on success and failing quietly otherwise.
+ * 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.
  */
 export declare function createOverlay(config: OverlayConfig): OverlayController;
 export {};

package/dist/region-capture.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Region-capture — drag a rectangle over the page to focus the report on one area
+ * (spec 0003 §B, the Reporter prototype's capture layer). It produces a `region`
+ * rect in screenshot (viewport) coordinates; Escape or a too-small drag abandons
+ * it. One of the overlay's three composable, optional marking layers, alongside
+ * element-pick and draw.
+ *
+ * Listeners are attached in the **capture phase** so the drag is intercepted before
+ * any host-page handler sees it. It is armed deliberately — the overlay lays a
+ * full-screen capture layer over the page (and hides the panel) while it runs — so
+ * it captures whatever the Reporter drags, its own layer included. Purely a producer
+ * of a `Rect`: it draws nothing; the overlay renders the live selection box from
+ * `onProgress`.
+ */
+import { type Rect } from "./annotation";
+/** Options for {@link startRegionCapture}. */
+export interface RegionCaptureOptions {
+    /** Document to attach to. Defaults to the global `document`. */
+    readonly doc?: Document;
+    /** Called on each drag update with the current rect (to draw a selection box). */
+    readonly onProgress?: (rect: Rect) => void;
+    /** Called with the captured rect when the drag ends large enough to keep. */
+    readonly onComplete: (rect: Rect) => void;
+    /** Called when the capture is abandoned (Escape, or a drag below the floor). */
+    readonly onCancel?: () => void;
+    /** Minimum width and height, in px, to count as a capture. Defaults to 12. */
+    readonly minSize?: number;
+}
+/** A running region-capture; call {@link RegionCapture.stop} to detach it. */
+export interface RegionCapture {
+    stop(): void;
+}
+/**
+ * Enter region-capture mode: the next drag on the host page draws out a rectangle,
+ * reported live through `onProgress` and committed through `onComplete` on release
+ * (when it clears the size floor). Escape, or a drag too small to be meaningful,
+ * calls `onCancel`. `stop()` (called automatically on complete/cancel) detaches all
+ * listeners.
+ */
+export declare function startRegionCapture(options: RegionCaptureOptions): RegionCapture;

package/dist/report.d.ts

@@ -8,8 +8,16 @@
  * (`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";
 /** The Kind a Reporter tags a report with. Mirrors the server's `ISSUE_KINDS`. */
 export type IssueKind = "bug" | "improvement" | "idea";
+/**
+ * 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;
@@ -18,9 +26,9 @@ export interface ElementRect {
     readonly height: number;
 }
 /**
- * The Annotation — the element a Reporter pointed at: a stable CSS selector, a
- * readable DOM path, the tag, and the bounding rect. Exactly the server's
- * `annotation` object shape.
+ * 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;
@@ -39,23 +47,41 @@ export interface CaptureEnvironment {
  * 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 selected element; the screenshot is a
- * separate binary part, never part of this JSON.
+ * 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;
     readonly kind?: IssueKind;
     readonly url?: string;
     readonly environment?: CaptureEnvironment;
-    readonly annotation?: SelectedElement;
+    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;
 }
-/** What the overlay hands to {@link assembleContent} when the Reporter sends. */
+/**
+ * What the overlay hands to {@link assembleContent} when the Reporter sends. The
+ * three marking layers arrive flat (`element` / `region` / `marks`); `assembleContent`
+ * folds whatever is present into the structured {@link Annotation}.
+ */
 export interface ReportDraft {
     readonly kind?: IssueKind;
     readonly comment?: string;
     readonly element?: SelectedElement;
+    readonly region?: Rect;
+    readonly marks?: ReadonlyArray<Mark>;
     readonly url?: string;
     readonly environment?: CaptureEnvironment;
+    readonly trace?: readonly Breadcrumb[];
 }
 /**
  * Read the capture environment off a window: the viewport size, the browser's

package/dist/screenshot.d.ts

@@ -27,6 +27,8 @@ export interface Capture {
     readonly height: number;
     readonly type: string;
 }
+/** The screenshot filename extension for a {@link Capture}'s content type (defaults to `png`). */
+export declare function extensionFor(type: string): string;
 /** Turns a serialised SVG of the view into image bytes (injectable for tests). */
 export type Rasterize = (svg: string, meta: {
     width: number;

package/dist/scrub.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The single client-side **scrub choke point** every report passes through
+ * before transport (spec 0003 §C; research `sentry-error-capture-findings.md`
+ * §7.4) — the SDK's `beforeSend` equivalent.
+ *
+ * Masking is the SDK's job, done in the browser before anything leaves the page.
+ * The screenshot is masked at capture, and breadcrumbs never record a value or a
+ * body at the source; `runBeforeSend` is the **last** gate over the assembled
+ * report. Its default scrubbers are **on**: they strip credentials, query
+ * strings, and bearer tokens from URLs, and redact obvious PII (emails, long
+ * digit runs, bearer tokens) from crumb and error text. The result is then handed
+ * to an optional per-project hook that can mutate it further or drop the whole
+ * report by returning `null`.
+ *
+ * The hook is **synchronous and network-free** by contract, and both manual
+ * (overlay) and automatic (error-capture) reports run through the very same
+ * choke point. A project relaxes the defaults with `scrub: false`, or reshapes
+ * the draft in its own hook — never a silent raw send.
+ */
+import type { ReportContent } from "./report";
+/** The per-project client scrub hook. Return `null` to drop the whole report. */
+export type BeforeSend = (draft: ReportContent) => ReportContent | null;
+/** Options for {@link runBeforeSend}. */
+export interface BeforeSendOptions {
+    /** The per-project hook, run **after** the default scrubbers. */
+    readonly hook?: BeforeSend | null;
+    /** Run the built-in default scrubbers first. Defaults to `true`. */
+    readonly scrub?: boolean;
+}
+/**
+ * Redact obvious PII from free text: email addresses, `Bearer <token>` /
+ * `token <value>` pairs, and long digit runs. Conservative by design — it keeps
+ * the shape of the message readable while removing the sensitive spans.
+ */
+export declare function redactPii(text: string): string;
+/**
+ * Strip the sensitive parts of a URL: userinfo credentials
+ * (`scheme://user:pass@host`), the entire query string, and a token-bearing
+ * fragment (one that carries `key=value`). Plain hash routes (`#/checkout`) are
+ * kept. Works on absolute and relative URLs alike, with no dependency and no
+ * throw.
+ */
+export declare function scrubUrl(url: string): string;
+/**
+ * Apply the built-in default scrubbers to a report draft: strip the page URL,
+ * and scrub every crumb's URLs and redact PII from its text. The Reporter's own
+ * `comment` is intentionally left untouched — it is authored on purpose, not
+ * scraped. The screenshot and input values are masked elsewhere (at capture and
+ * at crumb creation); this is the final URL/PII sweep.
+ */
+export declare function applyDefaultScrub(draft: ReportContent): ReportContent;
+/**
+ * Run the report draft through the client scrub choke point: the default
+ * scrubbers first (unless `scrub` is `false`), then the optional per-project
+ * hook. Returns the scrubbed (and possibly hook-mutated) draft, or `null` when
+ * the hook drops the report. A hook that throws is treated as a no-op — the
+ * already-scrubbed draft is kept, so a buggy hook never breaks the report path
+ * nor leaks unscrubbed data.
+ */
+export declare function runBeforeSend(draft: ReportContent, options?: BeforeSendOptions): ReportContent | null;