@fixback/sdk-core 0.2.0

package/src/annotation.ts

@@ -0,0 +1,104 @@
+/**
+ * The Annotation & vector-marks **wire types** (spec 0003 §B/§D) — the shared,
+ * runtime-agnostic shapes that ride on a report's content (ADR-0028).
+ *
+ * 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**, never baked into the PNG: the dashboard composites them at view time.
+ *
+ * This module carries only the pure value types; the SDK's geometry and assembly
+ * helpers (`normalizeRect`, `arrowHeadPoints`, `assembleAnnotation`) live in the
+ * consuming SDK. Keep these in lock-step with the server's ingest contract
+ * (spec §D/§H).
+ */
+
+/** 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 picked element's viewport rectangle, as the server's annotation `rect`. */
+export interface ElementRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The picked element — the `element` layer of an {@link Annotation}: a stable CSS
+ * selector, a readable DOM path, the tag, and the bounding rect. Exactly the
+ * server's annotation `element` object shape.
+ */
+export interface SelectedElement {
+  readonly selector: string;
+  readonly domPath: string;
+  readonly tag: string;
+  readonly rect: ElementRect;
+}
+
+/** The 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 comment is a valid Send).
+ */
+export interface Annotation {
+  readonly element?: SelectedElement;
+  readonly region?: Rect;
+  readonly marks?: ReadonlyArray<Mark>;
+}

package/src/backoff.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  AutoReportBackoff,
+  DEFAULT_RETRY_AFTER_SECONDS,
+  parseRetryAfter,
+} from "./backoff";
+
+describe("parseRetryAfter", () => {
+  const NOW = 1_000_000;
+
+  it("reads the delta-seconds form", () => {
+    expect(parseRetryAfter("30", NOW)).toBe(30);
+    expect(parseRetryAfter("  0 ", NOW)).toBe(0);
+  });
+
+  it("reads the HTTP-date form as whole seconds from now (rounded up)", () => {
+    // toUTCString carries whole seconds only, so the header parses to NOW + 45_000.
+    const when = new Date(NOW + 45_000).toUTCString();
+    expect(parseRetryAfter(when, NOW)).toBe(45);
+    // A sub-second remainder rounds up: from NOW - 500 the gap is 45_500 ms.
+    expect(parseRetryAfter(when, NOW - 500)).toBe(46);
+  });
+
+  it("clamps a past HTTP-date to zero", () => {
+    const when = new Date(NOW - 10_000).toUTCString();
+    expect(parseRetryAfter(when, NOW)).toBe(0);
+  });
+
+  it("falls back to the default when the header is absent, blank, or unparseable", () => {
+    expect(parseRetryAfter(null, NOW)).toBe(DEFAULT_RETRY_AFTER_SECONDS);
+    expect(parseRetryAfter(undefined, NOW)).toBe(DEFAULT_RETRY_AFTER_SECONDS);
+    expect(parseRetryAfter("", NOW)).toBe(DEFAULT_RETRY_AFTER_SECONDS);
+    expect(parseRetryAfter("   ", NOW)).toBe(DEFAULT_RETRY_AFTER_SECONDS);
+    expect(parseRetryAfter("soon", NOW)).toBe(DEFAULT_RETRY_AFTER_SECONDS);
+  });
+
+  it("defaults to 60 seconds", () => {
+    expect(DEFAULT_RETRY_AFTER_SECONDS).toBe(60);
+  });
+});
+
+describe("AutoReportBackoff", () => {
+  function at(t: number): { clock: { t: number }; backoff: AutoReportBackoff } {
+    const clock = { t };
+    return { clock, backoff: new AutoReportBackoff(() => clock.t) };
+  }
+
+  it("starts clear", () => {
+    const { backoff } = at(1_000);
+    expect(backoff.isPaused()).toBe(false);
+    expect(backoff.retryAfterSeconds()).toBe(0);
+  });
+
+  it("opens a window from a Retry-After value and clears when it elapses", () => {
+    const { clock, backoff } = at(1_000);
+
+    expect(backoff.hold("30")).toBe(30);
+    expect(backoff.isPaused()).toBe(true);
+    expect(backoff.retryAfterSeconds()).toBe(30);
+
+    clock.t = 1_000 + 29_000;
+    expect(backoff.isPaused()).toBe(true);
+
+    clock.t = 1_000 + 30_000;
+    expect(backoff.isPaused()).toBe(false);
+    expect(backoff.retryAfterSeconds()).toBe(0);
+  });
+
+  it("defaults to 60 seconds when the header is absent", () => {
+    const { clock, backoff } = at(1_000);
+
+    expect(backoff.hold(null)).toBe(60);
+    clock.t = 1_000 + 59_000;
+    expect(backoff.isPaused()).toBe(true);
+    clock.t = 1_000 + 60_000;
+    expect(backoff.isPaused()).toBe(false);
+  });
+
+  it("extends the window but never shrinks it", () => {
+    const { clock, backoff } = at(1_000);
+
+    backoff.hold("60"); // until 61_000
+    clock.t = 1_000 + 10_000; // t = 11_000
+    backoff.hold("5"); // would end at 16_000 — earlier than 61_000, so ignored
+    clock.t = 1_000 + 20_000; // t = 21_000, still inside the original window
+    expect(backoff.isPaused()).toBe(true);
+
+    clock.t = 1_000 + 10_000; // back inside; extend past the original
+    backoff.hold("120"); // until 71_000
+    clock.t = 1_000 + 65_000; // t = 66_000 — past the original 61_000
+    expect(backoff.isPaused()).toBe(true);
+  });
+});

package/src/backoff.ts

@@ -0,0 +1,83 @@
+/**
+ * Client-side backpressure for **automatic** error reports (spec 0003 §E/§H,
+ * ticket #89) — the pure, runtime-agnostic backoff every SDK shares (ADR-0028).
+ * When ingest sheds `source: error` load it answers `429` with a `Retry-After`;
+ * the SDK honours it by holding a pause window during which further automatic
+ * reports are dropped without touching the network. **Manual** reports — a human
+ * clicking Send — never consult this gate.
+ *
+ * This is the transport's counterpart to the server's per-Project token bucket
+ * (`apps/api/src/ingest/auto-report-rate-limiter.ts`): one shared window per page,
+ * so a 429 from one auto-report shed applies to the auto-reports that follow it.
+ * The clock is injectable so the window is unit-tested deterministically, never on
+ * wall time — mirroring the server limiter's `Clock`.
+ */
+
+/** A source of the current time in epoch milliseconds — injectable for tests. */
+export type Clock = () => number;
+
+/** The hold window applied when a `429` carries no usable `Retry-After` (spec §E). */
+export const DEFAULT_RETRY_AFTER_SECONDS = 60;
+
+/**
+ * Parse a `Retry-After` header into whole seconds to hold for. Handles both HTTP
+ * forms — a delta-seconds integer and an HTTP-date (measured from `now`, rounded up
+ * and clamped at zero) — and falls back to {@link DEFAULT_RETRY_AFTER_SECONDS} when
+ * the header is absent, blank, or unparseable. Ingest sends the delta-seconds form;
+ * the date form is handled for spec-completeness.
+ */
+export function parseRetryAfter(
+  header: string | null | undefined,
+  now: number,
+): number {
+  if (header == null) return DEFAULT_RETRY_AFTER_SECONDS;
+  const value = header.trim();
+  if (value === "") return DEFAULT_RETRY_AFTER_SECONDS;
+
+  if (/^\d+$/.test(value)) {
+    return Number(value);
+  }
+
+  const when = Date.parse(value);
+  if (!Number.isNaN(when)) {
+    return Math.max(0, Math.ceil((when - now) / 1000));
+  }
+
+  return DEFAULT_RETRY_AFTER_SECONDS;
+}
+
+/**
+ * A single pause window for automatic (`source: error`) reports. `hold` opens (or
+ * extends) it from a `429`'s `Retry-After`; `isPaused` reports whether it is still
+ * open. The default instance in the SDK's transport is shared across a page's
+ * reports so the hold persists across successive automatic submissions.
+ */
+export class AutoReportBackoff {
+  /** Epoch ms until which automatic reports are held; `0` when clear. */
+  private pausedUntil = 0;
+
+  constructor(private readonly now: Clock = Date.now) {}
+
+  /** Is the automatic-report pause window currently open? */
+  isPaused(): boolean {
+    return this.now() < this.pausedUntil;
+  }
+
+  /** Whole seconds remaining in the pause window (`0` when clear). */
+  retryAfterSeconds(): number {
+    return Math.max(0, Math.ceil((this.pausedUntil - this.now()) / 1000));
+  }
+
+  /**
+   * Open (or extend) the window from a `429`'s `Retry-After` value, returning the
+   * seconds it will hold for. The window only ever grows — a shorter later hold
+   * never clips a longer one already in effect.
+   */
+  hold(retryAfterHeader: string | null | undefined): number {
+    const now = this.now();
+    const seconds = parseRetryAfter(retryAfterHeader, now);
+    const until = now + seconds * 1000;
+    if (until > this.pausedUntil) this.pausedUntil = until;
+    return seconds;
+  }
+}

package/src/breadcrumb.ts

@@ -0,0 +1,169 @@
+/**
+ * The trace **breadcrumb wire types** (spec 0003 §C, spec #122) — the shared,
+ * runtime-agnostic shapes for one entry of a captured trace stream (ADR-0028).
+ *
+ * A breadcrumb records recent activity — console, navigation, network metadata,
+ * masked user actions, and the failing error — that rides on a report as
+ * Evidence. This module carries only the value types; the SDK's ring buffer and
+ * DOM/Node instrumentation that produce them live in the consuming SDK.
+ * Everything private is kept out **at the source** by that instrumentation:
+ * `ui.input` records that an input changed, never its value; network crumbs carry
+ * method + URL + status only, never bodies.
+ */
+
+/** 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` — and only when the stack yields a usable
+   * location; a chatty app's `log`/`info`/`debug` omit it. 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;
+}

package/src/fingerprint.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+
+import { computeFingerprint, extractTopFrames, hashString, normalize } from "./fingerprint";
+
+describe("normalize — collapsing the volatile parts of an error message", () => {
+  it("replaces UUIDs, URLs, hex, and long digit runs with stable placeholders", () => {
+    expect(normalize("failed for 550e8400-e29b-41d4-a716-446655440000")).toBe(
+      "failed for <uuid>",
+    );
+    expect(
+      normalize("GET https://api.example.com/users/42?token=abc failed"),
+    ).toContain("<url>");
+    expect(normalize("bad pointer 0xdeadbeef")).toBe("bad pointer <hex>");
+    expect(normalize("chunk 3f9a1c2e4b7d8091 missing")).toBe("chunk <hex> missing");
+    expect(normalize("order 1234567 not found")).toBe("order <n> not found");
+  });
+
+  it("keeps short numbers and stable text so distinct bugs stay distinct", () => {
+    expect(normalize("code 42 raised")).toBe("code 42 raised");
+    expect(normalize("Cannot read properties of undefined")).toBe(
+      "Cannot read properties of undefined",
+    );
+  });
+
+  it("returns an empty string for a non-string or empty input", () => {
+    expect(normalize("")).toBe("");
+    expect(normalize(undefined as unknown as string)).toBe("");
+  });
+});
+
+describe("extractTopFrames — a compact top-of-stack signature", () => {
+  it("parses V8 frames to `function@basename:line:col`, origin stripped", () => {
+    const stack = [
+      "Error: boom",
+      "    at pay (https://acme.app/assets/checkout.abc123.js:10:5)",
+      "    at onClick (https://acme.app/assets/checkout.abc123.js:20:9)",
+    ].join("\n");
+    expect(extractTopFrames(stack)).toBe(
+      "pay@checkout.abc123.js:10:5 < onClick@checkout.abc123.js:20:9",
+    );
+  });
+
+  it("parses Firefox/Safari `fn@loc` frames", () => {
+    const stack = "pay@https://acme.app/checkout.js:10:5\n@https://acme.app/x.js:1:1";
+    expect(extractTopFrames(stack)).toBe("pay@checkout.js:10:5 < @x.js:1:1");
+  });
+
+  it("caps at the frame limit and returns '' for no usable stack", () => {
+    const many = Array.from(
+      { length: 10 },
+      (_v, i) => `    at fn${i} (https://acme.app/a.js:${i}:1)`,
+    ).join("\n");
+    expect(extractTopFrames(many).split(" < ")).toHaveLength(5);
+    expect(extractTopFrames(undefined)).toBe("");
+    expect(extractTopFrames("")).toBe("");
+  });
+});
+
+describe("hashString — dependency-free FNV-1a", () => {
+  it("is deterministic and distinguishes distinct inputs", () => {
+    expect(hashString("a|b|c")).toBe(hashString("a|b|c"));
+    expect(hashString("a|b|c")).not.toBe(hashString("a|b|d"));
+  });
+});
+
+describe("computeFingerprint — the cross-surface grouping key", () => {
+  it("is stable for the same logical error", () => {
+    const stack = "    at pay (https://acme.app/checkout.js:10:5)";
+    expect(computeFingerprint("TypeError", "boom", stack)).toBe(
+      computeFingerprint("TypeError", "boom", stack),
+    );
+  });
+
+  it("ignores the volatile parts of the message (same bug, changed ids)", () => {
+    const stack = "    at pay (https://acme.app/checkout.js:10:5)";
+    expect(computeFingerprint("Error", "order 111111 failed", stack)).toBe(
+      computeFingerprint("Error", "order 999999 failed", stack),
+    );
+  });
+
+  it("separates errors with different types or frames", () => {
+    const stack = "    at pay (https://acme.app/checkout.js:10:5)";
+    expect(computeFingerprint("TypeError", "boom", stack)).not.toBe(
+      computeFingerprint("RangeError", "boom", stack),
+    );
+    expect(computeFingerprint("Error", "boom", stack)).not.toBe(
+      computeFingerprint("Error", "boom", "    at other (https://acme.app/x.js:1:1)"),
+    );
+  });
+
+  it("falls back to type + normalised message when there is no stack", () => {
+    expect(computeFingerprint("Error", "order 5 failed")).toBe(
+      computeFingerprint("Error", "order 5 failed", undefined),
+    );
+  });
+});

package/src/fingerprint.ts

@@ -0,0 +1,112 @@
+/**
+ * The cross-surface error **fingerprint** (research `sentry-error-capture-findings.md`
+ * §7.2; ADR-0027/0028) — the pure, runtime-agnostic key by which the same logical
+ * error groups together, computed the **same way** on every SDK.
+ *
+ * `computeFingerprint(type, value, stack)` hashes the error type, a normalised
+ * message, and a compact top-frames signature. It only has to be stable and
+ * well-distributed (the client key is a flood guard; the server does canonical
+ * cross-session clustering), so a dependency-free FNV-1a hash is right. The
+ * `normalize` shape and the frame limit are **starting points** from research
+ * (ticket #92), tunable — never a frozen magic set.
+ */
+
+const UUID_RE =
+  /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+const URL_RE = /\bhttps?:\/\/[^\s"')]+/gi;
+const HEX_0X_RE = /\b0x[0-9a-f]+\b/gi;
+const HEX_RUN_RE = /\b[0-9a-f]{8,}\b/gi;
+const DIGIT_RUN_RE = /\d{4,}/g;
+
+/** How many top stack frames feed the fingerprint (research §7.2). */
+const FINGERPRINT_FRAME_LIMIT = 5;
+
+/**
+ * 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.
+ */
+export function normalize(value: string): string {
+  if (typeof value !== "string" || value.length === 0) return "";
+  return value
+    .replace(UUID_RE, "<uuid>")
+    .replace(URL_RE, "<url>")
+    .replace(HEX_0X_RE, "<hex>")
+    .replace(HEX_RUN_RE, "<hex>")
+    .replace(DIGIT_RUN_RE, "<n>")
+    .trim();
+}
+
+/**
+ * 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 function hashString(input: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(36);
+}
+
+/** Reduce a frame location to `basename:line:col`, dropping origin and query. */
+function compactLocation(location: string): string {
+  const noQuery = location.replace(/\?[^:]*/, "");
+  const lastSlash = noQuery.lastIndexOf("/");
+  return lastSlash >= 0 ? noQuery.slice(lastSlash + 1) : noQuery;
+}
+
+/** Parse one stack line into a compact `function@basename:line:col` frame id. */
+function parseFrame(line: string): string | null {
+  // V8: "at fn (loc)"  |  "at loc"
+  const v8Named = line.match(/^at\s+(.+?)\s+\((.+)\)$/);
+  if (v8Named) return `${v8Named[1] ?? ""}@${compactLocation(v8Named[2] ?? "")}`;
+  const v8Bare = line.match(/^at\s+(.+)$/);
+  if (v8Bare) return `@${compactLocation(v8Bare[1] ?? "")}`;
+  // Firefox / Safari: "fn@loc"  |  "@loc"
+  const at = line.indexOf("@");
+  if (at >= 0) {
+    const fn = line.slice(0, at);
+    return `${fn}@${compactLocation(line.slice(at + 1))}`;
+  }
+  return null;
+}
+
+/**
+ * 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 function extractTopFrames(
+  stack: string | undefined,
+  limit = FINGERPRINT_FRAME_LIMIT,
+): string {
+  if (typeof stack !== "string" || stack.length === 0) return "";
+  const frames: string[] = [];
+  for (const raw of stack.split("\n")) {
+    const frame = parseFrame(raw.trim());
+    if (frame) {
+      frames.push(frame);
+      if (frames.length >= limit) break;
+    }
+  }
+  return frames.join(" < ");
+}
+
+/**
+ * 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 function computeFingerprint(
+  type: string,
+  value: string,
+  stack?: string,
+): string {
+  return hashString(`${type}|${normalize(value)}|${extractTopFrames(stack)}`);
+}