@mushi-mushi/core 0.9.0 → 1.1.0

package/CONTRIBUTING.md

@@ -91,6 +91,33 @@ pnpm changeset
 
 Select the affected packages, the semver bump type, and write a summary. The changeset file gets committed with your PR.
 
+## Release flow
+
+Releases are fully automated. Maintainers don't run `npm publish` by hand.
+
+1. PRs land on `master` with one or more changeset files in `.changeset/`.
+2. `release.yml` runs on every push to `master`. It opens (or updates) a `chore: version packages` PR that bumps every affected `package.json`, rolls up the changelogs, and deletes the consumed changesets.
+3. Merging that "Version Packages" PR re-fires `release.yml`. The publish step authenticates to npm via **OpenID Connect (OIDC) Trusted Publishers** — no long-lived `NPM_TOKEN` is exchanged — and every tarball ships with a **Sigstore provenance attestation** uploaded to the public transparency log.
+
+If GitHub's anti-loop protection suppresses the auto re-fire (the squash merge can be attributed to `github-actions[bot]`), trigger the workflow manually: **Actions → release → Run workflow → master**.
+
+### Adding a brand-new publishable package
+
+Trusted Publisher bindings are configured **per package** on `npmjs.com` and require the package to already exist on the registry. New packages therefore need a one-time bootstrap before OIDC can take over.
+
+1. Add the package under `packages/<name>/` with a real `version`, `files`, `publishConfig.access: "public"`, `LICENSE`, and the standard fields enforced by `pnpm check:publish-readiness`.
+2. Build it locally: `pnpm install && pnpm -r build`.
+3. Mint a short-lived granular access token at `https://www.npmjs.com/settings/<your-user>/tokens/granular-access-tokens/new` — **Bypass 2FA: ON**, **Read and write: All packages**, **Expiration: 7 days**.
+4. Bootstrap-publish:
+   ```bash
+   NPM_TOKEN=npm_xxx pnpm bootstrap:new-package
+   ```
+   The script auto-detects which workspace packages are missing on npm and publishes them via `pnpm publish --no-provenance` (so `workspace:^` specifiers get rewritten to real semver in the tarball).
+5. The script prints one URL per freshly-published package. Open each, click **GitHub Actions** under "Trusted Publisher", confirm the auto-filled fields (`<owner>` / `<repo>` / `release.yml`), and tap your security key.
+6. Revoke the bootstrap token at `https://www.npmjs.com/settings/<your-user>/tokens`.
+
+From the next changeset bump onward, that package publishes through the normal `release.yml` flow with full OIDC provenance — same as the rest.
+
 ## Code Style
 
 - **TypeScript strict mode** — no `any` unless absolutely necessary

package/README.md

@@ -10,10 +10,12 @@ Core types, API client, and utilities for the Mushi Mushi SDK.
 - **API Client**: Fetch-based HTTP client with retry and exponential backoff. Tags every internal request with `X-Mushi-Internal: <kind>` so framework SDKs can filter their own traffic out of network capture and `apiCascade`. Ships HMAC-signed reporter helpers (`getLatestSdkVersion`, `listReporterReports`, `listReporterComments`, `replyToReporterReport`) for the two-way reply pipeline, plus `postDiscoveryEvent` (v2.1) for the passive inventory channel
 - **Pre-Filter**: On-device Stage 0 spam/gibberish filter (runs client-side, zero server cost)
 - **Offline Queue**: IndexedDB-backed queue with auto-sync on reconnect
-- **Environment Capture**: Browser/device snapshot (viewport, user agent, connection info)
+- **Environment Capture**: Browser/device snapshot — viewport, user agent (with **User-Agent Client Hints** when supported), connection info, screen + DPR, accessibility prefs (`prefers-reduced-motion`, `prefers-color-scheme`, `prefers-contrast`), online/displayMode/title, and a one-shot **page load timing** read from `PerformanceNavigationTiming` (TTFB, DOMContentLoaded, FCP, LCP)
 - **Reporter Token**: Anonymous persistent identity for report attribution
 - **Session ID**: Tab-scoped session correlation
 - **Rate Limiter**: Token bucket self-throttle to prevent API flooding
+- **Breadcrumb Buffer** (1.0+ — `createBreadcrumbBuffer`): 50-entry ring of `{timestamp, category, level, message, data?}` rows; framework SDKs auto-capture route changes, `console.error/warn`, `[data-testid]` clicks, and SDK lifecycle events. Snapshot is attached to every `MushiReport` (server promotes it to a dedicated `reports.breadcrumbs` jsonb column for GIN-indexed filtering)
+- **Exception Normaliser** (1.0+ — `normaliseThrown`): turns any thrown value (`Error`, string, plain object, `null`, `undefined`) into a stable `{ name, message, stack?, cause? }` shape with truncated stacks and cyclic-cause guards. Powers `Mushi.captureException()` in `@mushi-mushi/web`
 
 ## Public types added in 0.7 → 0.11
 
@@ -31,6 +33,10 @@ Core types, API client, and utilities for the Mushi Mushi SDK.
 | `MushiReporterComment`     | Reporter-facing comment row (HMAC-authed) tagged `author_kind: 'admin' \| 'reporter'`.        |
 | `MushiDiscoverInventoryConfig` | Mushi v2.1 — fine-grained controls for `capture.discoverInventory` (`enabled`, `throttleMs`, `routeTemplates`, `userIdSource`, `captureDomSummary`). Pass `true` for defaults. |
 | `MushiDiscoveryEventPayload`   | Mushi v2.1 — wire shape for `POST /v1/sdk/discovery`. Mirrored server-side by `_shared/schemas.ts::discoveryEventSchema`; route + page title + testids + network paths + query-param **keys only** + sha256 user id hash. |
+| `MushiBreadcrumb`              | 1.0+ — `{ timestamp, category, level: 'debug' \| 'info' \| 'warning' \| 'error' \| 'critical', message, data? }`. Mirrors the Sentry breadcrumb shape so the admin can interleave Mushi + Sentry breadcrumbs on one timeline. |
+| `MushiSentryContext`           | 1.0+ — rich Sentry handshake the SDK captures via `@sentry/browser` v7/v8/v9: `eventId`, `replayId`, `traceId`, `spanId`, `transaction`, `release`, `environment`, `user`, `tags`, `breadcrumbs`, `issueUrl`, `mushiReportId` (bidirectional). |
+| `MushiCaptureExceptionOptions` | 1.0+ — options for `Mushi.captureException(err, opts)`: `level`, `tags`, `extras`, `category`, `userIntent` overrides for the structured report. |
+| `NormalisedException`          | 1.0+ — return type of `normaliseThrown(err)` (`{ name, message, stack?, cause? }`); used internally by `captureException` and exposed for adapters that want to ship their own thin wrappers. |
 
 Constants: `MUSHI_INTERNAL_HEADER` (`'X-Mushi-Internal'`),
 `MUSHI_INTERNAL_INIT_MARKER`, and the `MushiInternalRequestKind` literal union

package/SECURITY.md

@@ -19,15 +19,59 @@ If you discover a security vulnerability, please report it responsibly.
 
 **Do NOT open a public GitHub issue.**
 
-Instead, email: **kensaurus@gmail.com**
+Use either channel below:
+
+1. **GitHub Private Vulnerability Reporting** — strongly preferred.
+   <https://github.com/kensaurus/mushi-mushi/security/advisories/new>
+   Routes the report into a private advisory with built-in CVE issuance,
+   patch coordination, and contributor-credit workflow.
+2. **Email** — `kensaurus@gmail.com`, subject prefix `[mushi-security]`.
+   PGP welcome but not required.
 
 Include:
 - Description of the vulnerability
-- Steps to reproduce
-- Impact assessment
+- Steps to reproduce (smallest reproducer wins)
+- Impact assessment (what an attacker gains)
 - Suggested fix (if any)
+- Whether you want public credit (and how to spell your name)
+
+### Coordinated-disclosure timeline
+
+| Day | Action |
+|-----|--------|
+| 0 | Report received |
+| ≤ 2 | Acknowledgment + assigned a tracking ID |
+| ≤ 7 | Triage complete: severity assigned (CVSS 3.1) and target patch date communicated |
+| ≤ 30 | Patch released for critical / high (CVSS ≥ 7.0); ≤ 60 days for medium; best-effort for low |
+| Patch + 7 | Public advisory + CVE published; reporter credited unless they declined |
+| Patch + 90 | Embargo expires regardless; if upstream is unresponsive, the reporter is free to publish |
+
+### Safe harbor
+
+Good-faith security research on Mushi Mushi is welcome. If you stay
+within the rules below, we will not pursue legal action, will not ask
+your hosting provider to take you offline, and will publicly credit your
+work:
+
+- Test only against your own self-hosted instance, the public demo at
+  <https://kensaur.us/mushi-mushi/admin/>, or accounts you own.
+- Do not access, exfiltrate, or modify data belonging to other users.
+- Do not run automated scanning that affects availability for others
+  (rate-limit your tooling, exclude `/health`).
+- Disclose privately first (channels above); do not publish before the
+  embargo above expires.
+- Do not intentionally exploit a finding to escalate beyond proving it
+  exists.
+
+If a finding requires touching production data to confirm, **stop and
+ask first** — describe what you'd need to do and we'll spin up a sandbox.
+
+### Hall of fame
 
-We will acknowledge receipt within 48 hours and aim to release a patch within 7 days for critical issues.
+Researchers who report a confirmed vulnerability are credited in the
+release notes for the patched version and added to
+[`docs/SECURITY_HALL_OF_FAME.md`](./docs/SECURITY_HALL_OF_FAME.md) (with
+permission).
 
 ## Scope
 
@@ -48,6 +92,125 @@ We will acknowledge receipt within 48 hours and aim to release a patch within 7
 - **Rotate API keys** regularly via the admin console
 - **Enable SSO** for team projects (Enterprise tier)
 - **Review audit logs** periodically for suspicious activity
+- **Verify SDK integrity** with `npm audit signatures` after install
+- **Set `Content-Security-Policy`** on any page embedding the Mushi widget;
+  the widget itself ships with `script-src 'self'` and does not load
+  remote scripts.
+
+## Threat model
+
+What we treat as in-scope attacker capabilities, and what we don't.
+
+| Capability | In scope | Notes |
+|-----------|----------|-------|
+| Unauthenticated network attacker hitting public endpoints | ✅ | Rate-limit + HMAC + replay protection on every webhook endpoint (`packages/server/supabase/functions/_shared/webhook-middleware.ts`). |
+| Authenticated user trying to read another tenant's data | ✅ | Postgres RLS on every `public.*` table; advisor lints reviewed monthly. |
+| Authenticated user trying to escalate to super-admin | ✅ | Role lives in `auth.users.raw_app_meta_data.role`; cannot be self-edited via PostgREST. |
+| Compromised dependency (npm supply-chain attack) | ✅ | 7-day cooldown + provenance + Harden-Runner + pinned SHAs (see "Supply-chain hardening" below). |
+| Stolen API key | ✅ | Per-key scopes (`api_key_has_scope`), revocation via admin console, audit log of every use. |
+| User pasting a Stripe / OpenAI / GitHub PAT into a bug report | ✅ | PII scrubber redacts ~15 vendor token formats client-side before the report leaves the device. Mirrors `packages/core/src/pii-scrubber.ts` across iOS, Android, Flutter, React Native. |
+| Stolen end-user device with the SDK installed | ⚠️ partial | Offline queue is AsyncStorage / Keychain / SharedPreferences — no app-level encryption beyond the OS default. Reports waiting to flush are vulnerable to a forensic attacker. |
+| Compromised Supabase service-role key | ❌ | Treated as a tier-0 incident; would require key rotation and audit-log forensics. Not defendable in software. |
+| Compromise of `kensaurus@gmail.com` | ❌ | Treated as a project-fork event; downstream consumers should pin to the last known-good version and follow the new release channel. |
+| Physical / OS-level attacker on an end-user device | ❌ | Out of scope. |
+| Malicious fork using the Mushi name to ship malware | ❌ (technical) ✅ (legal) | The MIT/BSL grant lets the fork exist; the trademark policy (`TRADEMARK.md`) makes shipping it under the Mushi name an infringement we will pursue. |
+
+## Data handling and PII
+
+### What the SDK collects by default
+
+| Field | Scope | PII risk |
+|-------|-------|----------|
+| URL / route the user was on | Always | Low — strip query strings if your routes encode user IDs. |
+| Browser / OS / device | Always | None |
+| Console errors (last 50) | Opt-in via `captureConsole: true` | Medium — can include user data your code logs. |
+| Network failures (URL + status) | Opt-in via `captureNetwork: true` | Medium — query params logged as-is unless you redact in-app. |
+| User id / email / role | Only if you call `setUser()` | High — only set what you need; we do not auto-discover. |
+| Session replay frames | Off by default | High — handled by the masking layer; passwords / cards / opted-out elements never leave the page. |
+| Free-text bug description | Always | Medium — passed through the PII scrubber (see below). |
+
+### What the PII scrubber redacts before send
+
+Implemented identically across `@mushi-mushi/core`, the iOS, Android,
+Flutter, and React Native SDKs. Defaults are below — every category can
+be toggled off, but `secretTokens` is on by default and we recommend
+keeping it that way.
+
+| Category | Default | Patterns |
+|----------|---------|----------|
+| `ssns` | on | `123-45-6789` |
+| `creditCards` | on | 12–19 digit Luhn-shaped sequences with optional separators |
+| `secretTokens` | on | AWS access key (`AKIA…` / `ASIA…`), AWS secret (`aws_secret_access_key=…`), Stripe (`sk_live_…`, `sk_test_…`, `rk_…`, `pk_…`), Slack (`xox[abpor]-…`), GitHub PAT (`ghp_…`, `github_pat_…`), OpenAI (`sk-…`, `sk-proj-…`), Anthropic (`sk-ant-…`), Google API (`AIza…`), JWT (`eyJ…` 3-segment) |
+| `emails` | on | RFC-5322 lite |
+| `phones` | on | E.164 with optional country code |
+| `ipAddresses` | off | IPv4 (off because internal IPs are usually not PII and noise hurts triage) |
+| `ipv6` | off | Same |
+
+The fields scrubbed are:
+
+- `description` — primary free-text field of every bug report
+- `summary` — short summary, in the same composer
+- `breadcrumbs[].message` — auto-captured user-action trail (clicks, route changes, console messages)
+
+Structured fields you set explicitly (`metadata.userEmail`,
+`metadata.userId`, etc.) are intentionally **not** scrubbed — those are
+opt-in attribution data, and silently rewriting them would break
+support workflows.
+
+### Where data lives
+
+- **Reports & telemetry** — Supabase Postgres in the `us-west-1` region.
+- **Session replays** — Supabase Storage, same region. Lifecycle policy
+  trims replays older than 30 days unless explicitly retained from the
+  admin console.
+- **Inbound webhook bodies** — only a SHA-256 hash + `delivery_id` of
+  the body is persisted (`webhook_audit_log`). The full body is
+  processed in memory and discarded.
+- **Outbound integrations** (Slack, Jira, …) — Mushi is a sender only;
+  the receiving system's retention applies.
+
+### Encryption
+
+| Surface | At rest | In transit |
+|---------|---------|------------|
+| Postgres (Supabase) | AES-256 (Supabase default) | TLS 1.2+ |
+| Supabase Storage (replays) | AES-256 | TLS 1.2+ |
+| Edge Function ↔ Postgres | — | TLS via the Supavisor pooler |
+| SDK ↔ ingest endpoint | — | TLS 1.2+ enforced; HSTS preload on `kensaur.us` |
+| Inbound webhooks | — | TLS terminated at CloudFront / Supabase edge |
+| Audit log integrity | append-only by RLS; no in-row signing | — |
+
+### Cryptographic primitives
+
+| Use | Algorithm | Implementation |
+|-----|-----------|---------------|
+| Webhook HMAC verification (Sentry, GitHub, Datadog, Honeycomb, Grafana, Bugsnag, Rollbar, Crashlytics) | HMAC-SHA256, constant-time compare | Web Crypto in Deno; `crypto.subtle.timingSafeEqual` analogue |
+| AWS SNS subscription confirmation | RSA-SHA1 / RSA-SHA256 | Deno `crypto.subtle.verify` with the cert from `SigningCertURL` (URL allow-listed to `*.sns.*.amazonaws.com`) |
+| Opsgenie JWT shared-token | HS256 with `aud` claim verification | `jose` (Deno-compatible) |
+| API-key hashing (database) | SHA-256 prefix + bcrypt secret half | `pgcrypto` |
+| Provenance attestations (npm) | Sigstore (Fulcio + Rekor) | `npm publish --provenance` |
+
+We deliberately do not roll our own crypto. If you find an algorithm or
+library above that has been deprecated, please file a security advisory.
+
+### Operator security checklist
+
+When you provision a new self-hosted Mushi instance:
+
+- [ ] Set `auth_leaked_password_protection = true` in Supabase Auth
+      (HaveIBeenPwned blocklist; flagged as `auth_leaked_password_protection`
+      in the security advisor).
+- [ ] Enable at least two MFA factors in Supabase Auth (`auth_insufficient_mfa_options`).
+- [ ] Rotate the service-role key on day 1, then quarterly.
+- [ ] Restrict Postgres direct connections to your CI / migration runners
+      via Supabase network restrictions.
+- [ ] Run `pnpm dlx supabase advisors --project-ref <ref>` after every
+      migration; aim for zero ERROR-level findings.
+- [ ] Configure a Supabase log drain to your SIEM if you are subject to
+      SOC 2 / ISO 27001.
+- [ ] Set CSP `frame-ancestors` on the host page if you embed the Mushi
+      widget (the widget is iframe-friendly but does not enforce
+      framing constraints itself).
 
 ## Supply-chain hardening (how this package is protected)
 

package/dist/index.cjs

@@ -147,6 +147,53 @@ function createApiClient(options) {
         reporterToken,
         { body }
       );
+    },
+    // ─── Rewards program (P1) ──────────────────────────────────
+    async submitActivity(userId, events, opts) {
+      return request(
+        "POST",
+        "/v1/sdk/activity",
+        {
+          user_id: userId,
+          user_traits: opts?.userTraits,
+          opted_in: opts?.optedIn,
+          reporter_token_hash: opts?.reporterTokenHash,
+          // P2: JWT for monetary verification; omitted when null
+          ...opts?.hostJwt ? { host_jwt: opts.hostJwt } : {},
+          events
+        },
+        1,
+        // best-effort, 1 retry
+        "discovery"
+      );
+    },
+    async getMyPoints(userId) {
+      return request(
+        "GET",
+        `/v1/sdk/me/points?userId=${encodeURIComponent(userId)}`,
+        void 0,
+        1,
+        "reporter-poll"
+      );
+    },
+    async getMyTier(userId) {
+      return request(
+        "GET",
+        `/v1/sdk/me/tier?userId=${encodeURIComponent(userId)}`,
+        void 0,
+        1,
+        "reporter-poll"
+      );
+    },
+    async getMyHistory(userId, opts) {
+      const qs = new URLSearchParams({ userId, ...opts?.limit ? { limit: String(opts.limit) } : {} });
+      return request(
+        "GET",
+        `/v1/sdk/me/history?${qs}`,
+        void 0,
+        1,
+        "reporter-poll"
+      );
     }
   };
 }
@@ -785,6 +832,8 @@ function captureEnvironment() {
   const nav = typeof navigator !== "undefined" ? navigator : void 0;
   const win = typeof window !== "undefined" ? window : void 0;
   const doc = typeof document !== "undefined" ? document : void 0;
+  const scr = typeof screen !== "undefined" ? screen : void 0;
+  void kickOffUserAgentData(nav);
   const connection = nav && "connection" in nav ? nav.connection : void 0;
   return {
     userAgent: nav?.userAgent ?? "unknown",
@@ -806,7 +855,19 @@ function captureEnvironment() {
     deviceMemory: nav?.deviceMemory,
     hardwareConcurrency: nav?.hardwareConcurrency,
     route: win?.location?.pathname,
-    nearestTestid: findNearestTestidFromActive(doc)
+    nearestTestid: findNearestTestidFromActive(doc),
+    userAgentData: captureUserAgentData(nav),
+    screen: captureScreen(scr, win),
+    prefersColorScheme: matchScheme(win),
+    prefersReducedMotion: matchMedia(win, "(prefers-reduced-motion: reduce)"),
+    prefersReducedData: matchMedia(win, "(prefers-reduced-data: reduce)"),
+    prefersContrast: matchContrast(win),
+    forcedColors: matchMedia(win, "(forced-colors: active)"),
+    online: typeof nav?.onLine === "boolean" ? nav.onLine : void 0,
+    displayMode: matchDisplayMode(win),
+    documentTitle: doc?.title?.slice(0, 200),
+    buildId: readBuildIdMeta(doc),
+    pageLoadTiming: capturePageLoadTiming(win)
   };
 }
 function findNearestTestidFromActive(doc) {
@@ -821,6 +882,117 @@ function findNearestTestidFromActive(doc) {
   }
   return void 0;
 }
+var cachedHighEntropy = null;
+var highEntropyKickedOff = false;
+function kickOffUserAgentData(nav) {
+  if (highEntropyKickedOff) return;
+  const ua = nav?.userAgentData;
+  if (!ua?.getHighEntropyValues) return;
+  highEntropyKickedOff = true;
+  ua.getHighEntropyValues([
+    "architecture",
+    "bitness",
+    "model",
+    "platformVersion",
+    "uaFullVersion",
+    "fullVersionList"
+  ]).then((v) => {
+    cachedHighEntropy = v;
+  }).catch(() => {
+  });
+}
+function pickBrand(brands) {
+  if (!brands?.length) return void 0;
+  const real = brands.filter((b) => !/not.?a.?brand/i.test(b.brand));
+  if (real.length === 0) return void 0;
+  const named = real.find((b) => !/chromium|google chrome/i.test(b.brand));
+  return named ?? real[0];
+}
+function captureUserAgentData(nav) {
+  const low = nav?.userAgentData;
+  if (!low && !cachedHighEntropy) return void 0;
+  const fullList = cachedHighEntropy?.fullVersionList;
+  const brand = pickBrand(fullList ?? low?.brands);
+  const out = {};
+  if (brand) {
+    out.browser = brand.brand;
+    out.browserVersion = brand.version;
+  }
+  if (low?.platform) out.os = low.platform;
+  if (cachedHighEntropy?.platformVersion) out.osVersion = cachedHighEntropy.platformVersion;
+  if (typeof low?.mobile === "boolean") out.mobile = low.mobile;
+  if (cachedHighEntropy?.model) out.model = cachedHighEntropy.model;
+  if (cachedHighEntropy?.architecture) out.architecture = cachedHighEntropy.architecture;
+  if (cachedHighEntropy?.bitness) out.bitness = cachedHighEntropy.bitness;
+  return Object.keys(out).length === 0 ? void 0 : out;
+}
+function captureScreen(scr, win) {
+  if (!scr && !win) return void 0;
+  const out = {};
+  if (typeof scr?.width === "number") out.width = scr.width;
+  if (typeof scr?.height === "number") out.height = scr.height;
+  if (typeof win?.devicePixelRatio === "number") out.devicePixelRatio = win.devicePixelRatio;
+  if (typeof scr?.colorDepth === "number") out.colorDepth = scr.colorDepth;
+  const orientationType = scr?.orientation?.type;
+  if (orientationType) out.orientation = orientationType;
+  return Object.keys(out).length === 0 ? void 0 : out;
+}
+function matchMedia(win, query) {
+  if (!win?.matchMedia) return void 0;
+  try {
+    return win.matchMedia(query).matches;
+  } catch {
+    return void 0;
+  }
+}
+function matchScheme(win) {
+  if (!win?.matchMedia) return void 0;
+  if (matchMedia(win, "(prefers-color-scheme: dark)")) return "dark";
+  if (matchMedia(win, "(prefers-color-scheme: light)")) return "light";
+  return "no-preference";
+}
+function matchContrast(win) {
+  if (!win?.matchMedia) return void 0;
+  if (matchMedia(win, "(prefers-contrast: more)")) return "more";
+  if (matchMedia(win, "(prefers-contrast: less)")) return "less";
+  if (matchMedia(win, "(prefers-contrast: custom)")) return "custom";
+  return "no-preference";
+}
+function matchDisplayMode(win) {
+  if (!win?.matchMedia) return void 0;
+  if (matchMedia(win, "(display-mode: fullscreen)")) return "fullscreen";
+  if (matchMedia(win, "(display-mode: standalone)")) return "standalone";
+  if (matchMedia(win, "(display-mode: minimal-ui)")) return "minimal-ui";
+  if (matchMedia(win, "(display-mode: browser)")) return "browser";
+  return void 0;
+}
+function readBuildIdMeta(doc) {
+  if (!doc) return void 0;
+  const el = doc.querySelector?.('meta[name="mushi:build"]');
+  const v = el?.content?.trim();
+  if (!v) return void 0;
+  return v.slice(0, 64);
+}
+function capturePageLoadTiming(win) {
+  const perf = win?.performance;
+  if (!perf?.getEntriesByType) return void 0;
+  let entry;
+  try {
+    const entries = perf.getEntriesByType("navigation");
+    entry = entries[0];
+  } catch {
+    return void 0;
+  }
+  if (!entry) return void 0;
+  const start = entry.startTime ?? 0;
+  const out = {};
+  if (entry.domContentLoadedEventEnd > 0)
+    out.domContentLoadedMs = Math.round(entry.domContentLoadedEventEnd - start);
+  if (entry.loadEventEnd > 0) out.loadCompleteMs = Math.round(entry.loadEventEnd - start);
+  if (entry.responseStart > 0) out.timeToFirstByteMs = Math.round(entry.responseStart - start);
+  if (typeof entry.type === "string") out.navigationType = entry.type;
+  return Object.keys(out).length === 0 ? void 0 : out;
+}
 
 // src/reporter-token.ts
 var STORAGE_KEY = "mushi_reporter_token";
@@ -1028,12 +1200,82 @@ function scrubPii(text, config) {
   return createPiiScrubber(config).scrub(text);
 }
 
+// src/breadcrumbs.ts
+var DEFAULT_MAX = 50;
+var DEFAULT_MAX_MESSAGE = 500;
+function createBreadcrumbBuffer(options = {}) {
+  const max = Math.max(1, options.max ?? DEFAULT_MAX);
+  const maxMsg = Math.max(50, options.maxMessageLength ?? DEFAULT_MAX_MESSAGE);
+  let entries = [];
+  return {
+    add(input) {
+      const ts = typeof input.timestamp === "number" ? input.timestamp : Date.now();
+      const message = typeof input.message === "string" && input.message.length > maxMsg ? `${input.message.slice(0, maxMsg)}\u2026` : input.message;
+      const crumb = {
+        timestamp: ts,
+        category: input.category,
+        level: input.level ?? "info",
+        message: message ?? "",
+        ...input.data ? { data: input.data } : {}
+      };
+      entries.push(crumb);
+      while (entries.length > max) entries.shift();
+    },
+    getAll() {
+      return entries.slice();
+    },
+    clear() {
+      entries = [];
+    },
+    size() {
+      return entries.length;
+    }
+  };
+}
+
+// src/exception-normaliser.ts
+var STACK_LIMIT = 8 * 1024;
+var FALLBACK_JSON_LIMIT = 1e3;
+function normaliseThrown(thrown) {
+  if (thrown instanceof Error) {
+    const name = thrown.name || "Error";
+    const message = thrown.message || String(thrown);
+    const stack = typeof thrown.stack === "string" && thrown.stack.length > 0 ? thrown.stack.slice(0, STACK_LIMIT) : void 0;
+    const cause = thrown.cause;
+    return {
+      name,
+      message,
+      ...stack ? { stack } : {},
+      ...cause !== void 0 ? { cause: cause instanceof Error ? cause.message : cause } : {}
+    };
+  }
+  if (typeof thrown === "string") {
+    return { name: "Error", message: thrown };
+  }
+  if (thrown && typeof thrown === "object") {
+    const obj = thrown;
+    const name = typeof obj.name === "string" ? obj.name : "Error";
+    const message = typeof obj.message === "string" ? obj.message : (() => {
+      try {
+        return JSON.stringify(obj).slice(0, FALLBACK_JSON_LIMIT);
+      } catch {
+        return String(obj);
+      }
+    })();
+    const stack = typeof obj.stack === "string" ? obj.stack.slice(0, STACK_LIMIT) : void 0;
+    return { name, message, ...stack ? { stack } : {} };
+  }
+  if (thrown === void 0) return { name: "Error", message: "unknown" };
+  return { name: "Error", message: String(thrown) };
+}
+
 exports.DEFAULT_API_ENDPOINT = DEFAULT_API_ENDPOINT;
 exports.MUSHI_INTERNAL_HEADER = MUSHI_INTERNAL_HEADER;
 exports.MUSHI_INTERNAL_INIT_MARKER = MUSHI_INTERNAL_INIT_MARKER;
 exports.REGION_ENDPOINTS = REGION_ENDPOINTS;
 exports.captureEnvironment = captureEnvironment;
 exports.createApiClient = createApiClient;
+exports.createBreadcrumbBuffer = createBreadcrumbBuffer;
 exports.createLogger = createLogger;
 exports.createOfflineQueue = createOfflineQueue;
 exports.createPiiScrubber = createPiiScrubber;
@@ -1043,6 +1285,7 @@ exports.getDeviceFingerprintHash = getDeviceFingerprintHash;
 exports.getReporterToken = getReporterToken;
 exports.getSessionId = getSessionId;
 exports.noopLogger = noopLogger;
+exports.normaliseThrown = normaliseThrown;
 exports.resolveRegionEndpoint = resolveRegionEndpoint;
 exports.scrubPii = scrubPii;
 //# sourceMappingURL=index.cjs.map