@fixback/sdk 0.1.0 → 0.3.0

package/dist/screenshot.d.ts

@@ -1,15 +1,24 @@
 /**
- * Client-side masked screenshot capture (spec MVP §E; ticket #54).
+ * Client-side masked screenshot capture (spec MVP §E; ticket #54; ADR-0014).
  *
- * The capture is **private-by-default**: input values are masked and the SDK's
- * own UI is removed from a *clone* of the view **before** anything is rasterised,
- * so no unmasked text and none of Fixback's chrome ever reaches the image. The
- * approach is dependency-free — the cloned, masked DOM is serialised into an SVG
- * `<foreignObject>` and drawn onto a `<canvas>` — honouring the SDK's "no runtime
- * dependencies / no host-page disturbance" constraints. The raster step is
- * injectable so the pipeline (and the masking-before-capture guarantee) is
- * testable without a real canvas, and it fails quietly: any problem resolves to
- * `null` and the report is simply sent without a screenshot.
+ * The capture is **private-by-default**: input values are masked and the SDK's own
+ * UI is excluded from a *clone* of the view **before** anything is rasterised, so no
+ * unmasked text and none of Fixback's chrome ever reaches the image.
+ *
+ * The rasterisation itself is delegated to `modern-screenshot` (ADR-0014): it clones
+ * the target, inlines the page's real styles **and** its fonts and images as data
+ * URIs, then draws the result through an SVG `<foreignObject>` onto a `<canvas>`.
+ * That closes the fidelity gap a hand-rolled `<foreignObject>` left open — external
+ * stylesheets, web fonts, and same-origin images now render — so the shot matches
+ * what the Reporter saw and lines up with the annotation's viewport-space marks.
+ *
+ * We keep the privacy guarantee by driving it through two of its hooks: `filter`
+ * drops Fixback's own host elements, and `onCloneNode` masks the clone's inputs —
+ * both run on the library's internal clone, before it embeds or serialises anything,
+ * so the live page is never touched and no real value reaches the raster. The backend
+ * is injectable so the pipeline (and the masking-before-capture guarantee) is testable
+ * without a real canvas, and it fails quietly: any problem resolves to `null` and the
+ * report is simply sent without a screenshot.
  */
 /** The character private input content is replaced with. */
 export declare const MASK_CHAR = "\u2022";
@@ -27,12 +36,21 @@ export interface Capture {
     readonly height: number;
     readonly type: string;
 }
-/** Turns a serialised SVG of the view into image bytes (injectable for tests). */
-export type Rasterize = (svg: string, meta: {
+/** The screenshot filename extension for a {@link Capture}'s content type (defaults to `png`). */
+export declare function extensionFor(type: string): string;
+/** How the SDK prepares a capture: exclude Fixback's UI, mask the clone's inputs. */
+interface CaptureHooks {
+    /** Keep a node in the shot? Returns `false` for Fixback's own host elements. */
+    readonly filter: (node: Node) => boolean;
+    /** Mask private input content on the library's internal clone, pre-raster. */
+    readonly onCloneNode: (clone: Node) => void;
+}
+/** Turns a DOM subtree into image bytes at a given size (injectable for tests). */
+export type CaptureBackend = (target: Element, meta: {
     width: number;
     height: number;
     type: string;
-}) => Promise<Blob | null>;
+} & CaptureHooks) => Promise<Blob | null>;
 /** Options for {@link captureView}. */
 export interface CaptureOptions {
     /** The element to capture. Defaults to the document element (the full view). */
@@ -41,12 +59,15 @@ export interface CaptureOptions {
     readonly win?: Window;
     /** Output content type. Defaults to `image/png`. */
     readonly type?: string;
-    /** Override the raster step (the default draws via an SVG + `<canvas>`). */
-    readonly rasterize?: Rasterize;
+    /** Override the raster backend (the default is `modern-screenshot`). */
+    readonly capture?: CaptureBackend;
 }
 /**
- * Capture the current view as a masked screenshot. Clones the target, removes the
- * SDK's own UI, masks input values — **all before** serialising and rasterising —
- * then returns the image bytes, or `null` if capture wasn't possible.
+ * Capture the current view as a masked screenshot. Delegates the raster to the
+ * backend ({@link captureViaModernScreenshot} by default), which excludes the SDK's
+ * own UI and masks input values on its internal clone — **before** it embeds or
+ * serialises anything — then returns the image bytes, or `null` if capture wasn't
+ * possible.
  */
 export declare function captureView(options?: CaptureOptions): Promise<Capture | null>;
+export {};

package/dist/scrub.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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, a token-bearing
+ * fragment (one that carries `key=value`), and PII (emails, long digit runs) in
+ * the **path segments** (#139). Plain hash routes (`#/checkout`) are kept. Works
+ * on absolute and relative URLs alike, with no dependency and no throw. The host
+ * (authority) is never redacted — only the path and any surviving fragment route.
+ */
+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;

package/dist/styles.d.ts

@@ -6,5 +6,15 @@
  * token values are **vendored** Signal design tokens — copied from
  * `packages/ui/src/tokens.css` rather than imported, because the SDK must not
  * depend on `@fixback/ui` at runtime (ticket #47). Keep them in sync by value.
+ *
+ * The launcher is the prototype's polished pill (spec 0003 §A): a bottom-right
+ * **Feedback** pill that **hover-peeks**, can be **tucked away** (sliding off
+ * behind an edge nub, with a corner hover-zone to bring it back), a first-visit
+ * **welcome toast**, and a **reduce-motion** mode that stills the pulse. Every
+ * piece — pill, nub, corner zone, toasts — lives in this one Shadow DOM.
+ *
+ * Motion is driven by two host-element attributes the mount toggles:
+ * `data-fb-hidden` (tucked away) and `data-fb-peeking` (peeked back on hover);
+ * `data-fb-reduce-motion` (or the OS `prefers-reduced-motion`) stills it all.
  */
-export declare const LAUNCHER_STYLES = "\n:host {\n  /* Vendored Signal tokens (packages/ui/src/tokens.css). */\n  --fb-color-accent: #2f6fed;\n  --fb-color-accent-hover: #245fd0;\n  --fb-color-on-emphasis: #ffffff;\n  --fb-color-text: #0f1720;\n  --fb-font-sans: \"IBM Plex Sans\", system-ui, -apple-system, \"Segoe UI\", Roboto,\n    Helvetica, Arial, sans-serif;\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.4;\n  -webkit-font-smoothing: antialiased;\n}\n\n.fb-launcher {\n  display: inline-flex;\n  align-items: center;\n  gap: 8px;\n  box-sizing: border-box;\n  height: 40px;\n  margin: 0;\n  padding: 0 16px;\n  border: 0;\n  border-radius: 999px;\n  background: var(--fb-color-accent);\n  color: var(--fb-color-on-emphasis);\n  font-family: inherit;\n  font-size: 13px;\n  font-weight: 600;\n  letter-spacing: 0.01em;\n  cursor: pointer;\n  box-shadow:\n    0 6px 18px rgba(15, 23, 32, 0.16),\n    0 1px 2px rgba(15, 23, 32, 0.12);\n  transition:\n    background-color 120ms ease,\n    transform 120ms ease;\n}\n\n.fb-launcher:hover {\n  background: var(--fb-color-accent-hover);\n}\n\n.fb-launcher:active {\n  transform: translateY(1px);\n}\n\n.fb-launcher:focus-visible {\n  outline: 2px solid var(--fb-color-accent);\n  outline-offset: 2px;\n}\n\n.fb-launcher__icon {\n  display: block;\n  flex: none;\n  width: 16px;\n  height: 16px;\n}\n\n.fb-launcher__label {\n  white-space: nowrap;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .fb-launcher {\n    transition: none;\n  }\n}\n";
+export declare const LAUNCHER_STYLES = "\n:host {\n  /* Vendored Signal tokens (packages/ui/src/tokens.css). */\n  --fb-color-accent: #2f6fed;\n  --fb-color-accent-hover: #245fd0;\n  --fb-color-on-emphasis: #ffffff;\n  --fb-color-text: #0f1720;\n  /* Inverse (dark) surface for the toasts \u2014 Signal --fb-ink-900. */\n  --fb-color-surface-inverse: #0f1720;\n  --fb-font-sans: \"IBM Plex Sans\", system-ui, -apple-system, \"Segoe UI\", Roboto,\n    Helvetica, Arial, sans-serif;\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.4;\n  -webkit-font-smoothing: antialiased;\n}\n\n/* The pill: Feedback button + divider + tuck control, anchored bottom-right. */\n.fb-launcher {\n  position: fixed;\n  right: 20px;\n  bottom: 20px;\n  z-index: 2;\n  display: inline-flex;\n  align-items: stretch;\n  box-sizing: border-box;\n  height: 40px;\n  margin: 0;\n  border-radius: 999px;\n  background: var(--fb-color-accent);\n  box-shadow:\n    0 6px 18px rgba(15, 23, 32, 0.16),\n    0 1px 2px rgba(15, 23, 32, 0.12);\n  transform: translateX(0);\n  transition:\n    transform 340ms cubic-bezier(0.2, 0.8, 0.3, 1),\n    background-color 120ms ease;\n}\n\n.fb-launcher:hover {\n  background: var(--fb-color-accent-hover);\n}\n\n.fb-launcher__button {\n  display: inline-flex;\n  align-items: center;\n  gap: 8px;\n  box-sizing: border-box;\n  height: 100%;\n  margin: 0;\n  padding: 0 6px 0 16px;\n  border: 0;\n  background: transparent;\n  color: var(--fb-color-on-emphasis);\n  font-family: inherit;\n  font-size: 13px;\n  font-weight: 600;\n  letter-spacing: 0.01em;\n  cursor: pointer;\n}\n\n.fb-launcher__button:focus-visible,\n.fb-launcher__tuck:focus-visible {\n  outline: 2px solid var(--fb-color-on-emphasis);\n  outline-offset: -3px;\n  border-radius: 999px;\n}\n\n.fb-launcher__icon {\n  display: block;\n  flex: none;\n  width: 16px;\n  height: 16px;\n}\n\n.fb-launcher__label {\n  white-space: nowrap;\n}\n\n.fb-launcher__divider {\n  width: 1px;\n  margin: 9px 0;\n  flex: none;\n  background: rgba(255, 255, 255, 0.28);\n}\n\n.fb-launcher__tuck {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  box-sizing: border-box;\n  width: 32px;\n  height: 100%;\n  padding: 0;\n  border: 0;\n  background: transparent;\n  color: rgba(255, 255, 255, 0.82);\n  cursor: pointer;\n}\n\n.fb-launcher__tuck:hover {\n  color: var(--fb-color-on-emphasis);\n}\n\n.fb-launcher__tuck-icon {\n  display: block;\n  width: 14px;\n  height: 14px;\n}\n\n/* The corner hover-zone that peeks a tucked launcher back \u2014 inert until tucked,\n * so it never swallows the host page's own bottom-right clicks. */\n.fb-launcher__peekzone {\n  position: fixed;\n  right: 0;\n  bottom: 0;\n  z-index: 1;\n  width: 160px;\n  height: 160px;\n  pointer-events: none;\n}\n\n/* The edge nub: the visible re-reveal affordance, hidden until tucked. */\n.fb-launcher__nub {\n  position: fixed;\n  right: 0;\n  bottom: 22px;\n  z-index: 2;\n  width: 13px;\n  height: 42px;\n  border-radius: 9px 0 0 9px;\n  background: var(--fb-color-accent);\n  box-shadow: -6px 5px 18px rgba(47, 111, 237, 0.4);\n  cursor: pointer;\n  opacity: 0;\n  transform: translateX(10px);\n  pointer-events: none;\n  transition:\n    opacity 220ms ease,\n    transform 220ms ease;\n}\n\n/* Tucked and not peeking: slide the pill off, reveal the nub, arm the zone. */\n:host([data-fb-hidden]:not([data-fb-peeking])) .fb-launcher {\n  transform: translateX(calc(100% + 30px));\n}\n\n:host([data-fb-hidden]:not([data-fb-peeking])) .fb-launcher__nub {\n  opacity: 1;\n  transform: none;\n  pointer-events: auto;\n}\n\n:host([data-fb-hidden]) .fb-launcher__peekzone {\n  pointer-events: auto;\n}\n\n/* Toasts: the first-visit welcome (above the pill) and the tuck-away hint. */\n.fb-launcher__welcome,\n.fb-launcher__hint {\n  position: fixed;\n  right: 20px;\n  z-index: 5;\n  box-sizing: border-box;\n  color: #fff;\n  font-size: 12px;\n  line-height: 1.45;\n  background: var(--fb-color-surface-inverse);\n  border-radius: 10px;\n  box-shadow: 0 12px 30px rgba(15, 40, 70, 0.32);\n  animation: fbToast 300ms ease both;\n}\n\n.fb-launcher__welcome {\n  bottom: 70px;\n  max-width: 210px;\n  padding: 9px 13px;\n}\n\n.fb-launcher__welcome strong {\n  color: #8fc0ff;\n  font-weight: 600;\n}\n\n.fb-launcher__hint {\n  bottom: 20px;\n  max-width: 232px;\n  padding: 10px 13px;\n}\n\n/* The pulse that draws the eye while the welcome shows. */\n.fb-launcher--pulse {\n  animation: fbPulse 1.8s ease-in-out 2;\n}\n\n@keyframes fbPulse {\n  0%,\n  100% {\n    box-shadow:\n      0 6px 18px rgba(15, 23, 32, 0.16),\n      0 0 0 0 rgba(47, 111, 237, 0.45);\n  }\n  50% {\n    box-shadow:\n      0 6px 18px rgba(15, 23, 32, 0.16),\n      0 0 0 12px rgba(47, 111, 237, 0);\n  }\n}\n\n@keyframes fbToast {\n  from {\n    opacity: 0;\n    transform: translateY(14px);\n  }\n  to {\n    opacity: 1;\n    transform: none;\n  }\n}\n\n/* Reduce motion \u2014 the explicit opt-in and the OS setting both still it all. */\n:host([data-fb-reduce-motion]) .fb-launcher,\n:host([data-fb-reduce-motion]) .fb-launcher__nub {\n  transition: none;\n}\n\n:host([data-fb-reduce-motion]) .fb-launcher--pulse,\n:host([data-fb-reduce-motion]) .fb-launcher__welcome,\n:host([data-fb-reduce-motion]) .fb-launcher__hint {\n  animation: none;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .fb-launcher,\n  .fb-launcher__nub {\n    transition: none;\n  }\n  .fb-launcher--pulse,\n  .fb-launcher__welcome,\n  .fb-launcher__hint {\n    animation: none;\n  }\n}\n";

package/dist/submit.d.ts

@@ -1,3 +1,4 @@
+import { AutoReportBackoff } from "./auto-report-backoff";
 import type { IdentityInputs, ReporterTier } from "./boot";
 import type { ReportContent } from "./report";
 /** What ingest returns for an accepted submission (vendored server shape). */
@@ -27,13 +28,30 @@ export type SubmitResult = {
     readonly ok: false;
     readonly reason: "unreachable" | "refused";
     readonly status?: number;
+} | {
+    /**
+     * A `source: auto` 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.
+     */
+    readonly ok: false;
+    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;
 /**
  * Submit a report to ingest. Assembles the `payload` JSON (key + identity +
- * content) and the optional `screenshot` file into a `FormData`, posts it, and
- * resolves to the recorded Feedback on success or a named failure otherwise. The
- * `fetchImpl` seam exists purely so the call is testable.
+ * 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.
+ *
+ * A `source: auto` 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.
  */
-export declare function submitReport(apiUrl: string, input: SubmitInput, fetchImpl?: typeof fetch): Promise<SubmitResult>;
+export declare function submitReport(apiUrl: string, input: SubmitInput, fetchImpl?: typeof fetch, backoff?: AutoReportBackoff): Promise<SubmitResult>;

package/dist/version.d.ts

@@ -1,7 +1,13 @@
 /**
  * The SDK's own version string, reported to ingest as `environment.sdkVersion`
- * (spec MVP §B/§E). Kept as a hand-maintained constant rather than imported from
- * `package.json`, so the bundle stays a single self-contained file with no JSON
- * import — keep it in step with `package.json` and the Changesets bump.
+ * (spec MVP §B/§E). Kept as an inlined constant rather than a runtime `package.json`
+ * import, so the published bundle stays a single self-contained file.
+ *
+ * It must equal `package.json`'s `version`. Two things keep it there: the Changesets
+ * `version` step syncs it automatically (`scripts/sync-sdk-version.mjs`, wired into
+ * `version-packages`), and `version.test.ts` fails the build if the two ever drift —
+ * so a stale dogfood version (the SDK reporting an old number on our own dashboard)
+ * can't slip through. Do not hand-edit this line to a value other than
+ * `package.json`'s version.
  */
-export declare const SDK_VERSION = "0.1.0";
+export declare const SDK_VERSION = "0.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fixback/sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The Fixback capture SDK — a boot-gated, self-isolating on-page feedback launcher.",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "modern-screenshot": "^4.7.0"
+  },
   "devDependencies": {
     "jsdom": "^30.0.1",
     "typescript": "5.9.3",