@mushi-mushi/web 0.8.0 → 0.9.0

package/README.md

@@ -26,6 +26,7 @@ Browser SDK for Mushi Mushi — embeddable bug reporting widget with Shadow DOM
 - **Privacy controls** (0.9.1+) — `privacy.maskSelectors`, `privacy.blockSelectors`, `privacy.allowUserRemoveScreenshot` for selector-level screenshot redaction and a one-tap "Remove screenshot" button in the panel
 - **Repro timeline** (0.10+) — auto-captures route changes, clicks, and SDK lifecycle into a normalised `MushiReport.timeline`; pair with `Mushi.setScreen({ name, route, feature })` for screen-level grouping in the admin
 - **Two-way replies** (0.11+) — the panel ships a "Your reports" view that polls comments authored by the dev team and lets the reporter reply, all signed with HMAC against the public API key (no auth user required)
+- **Passive inventory discovery** (0.12+) — opt-in `capture.discoverInventory` ships throttled, PII-free observations (route template, page title, `[data-testid]` values, recent fetch paths, query-param **keys** only, sha256 of user/session id) to `POST /v1/sdk/discovery`. The Mushi server aggregates them into a 30-day `discovery_observed_inventory` view and Claude Sonnet drafts a first-pass `inventory.yaml` proposal you can accept on `/inventory ▸ Discovery`. See `MushiDiscoverInventoryConfig` in [`@mushi-mushi/core`](../core)
 - **SDK identity & freshness** (0.8+) — every report ships `sdkPackage` + `sdkVersion`; the widget polls `/v1/sdk/latest-version` and surfaces an outdated banner (configurable via `widget.outdatedBanner`)
 - **Self-noise filters** (0.7.1+) — internal Mushi requests are tagged with `X-Mushi-Internal` and excluded from network capture + `apiCascade`; configurable `capture.ignoreUrls` and `proactive.apiCascade.ignoreUrls` for host-app endpoints you also don't want counted
 - **`Mushi.diagnose()`** (0.7.1+) — one-call CSP / runtime-config / capture / widget health check (also runs without an init for pre-install smoke tests)
@@ -283,6 +284,47 @@ The DB-side `report_comments_fanout_to_reporter` trigger creates a
 `reporter_notifications` row whenever a `visible_to_reporter` admin comment
 lands, so the unread count stays in sync without polling.
 
+### Passive inventory discovery (v2.1)
+
+```typescript
+Mushi.init({
+  projectId: 'proj_xxx',
+  apiKey: 'mushi_xxx',
+  capture: {
+    // `true` enables defaults (60s per-route throttle, heuristic
+    // route normalisation). Pass an object for fine-grained control.
+    discoverInventory: {
+      enabled: true,
+      throttleMs: 60_000,
+      // Optional — your framework's known route templates so we don't
+      // have to guess `/practice/abc-123` → `/practice/[id]`.
+      routeTemplates: ['/practice/[id]', '/lessons/[slug]'],
+    },
+  },
+});
+```
+
+Each emission is one row on `POST /v1/sdk/discovery`:
+
+```jsonc
+{
+  "route": "/practice/[id]",
+  "page_title": "Practice — Glot.it",
+  "dom_summary": "…≤200 chars…",
+  "testids": ["practice-submit", "practice-hint"],
+  "network_paths": ["/api/practice/run", "/rest/v1/answers"],
+  "query_param_keys": ["lang"],
+  "user_id_hash": "sha256(…)",
+  "observed_at": "2026-05-04T12:00:00Z"
+}
+```
+
+Open `/inventory ▸ Discovery` in the admin to watch routes accumulate,
+hit **Generate proposal**, then **Accept** to write the LLM-drafted
+`inventory.yaml` into the project. Nothing else changes about the SDK —
+the discovery channel is independent of the bug-report widget and stays
+quiet under `prefers-reduced-motion` / when the tab is hidden.
+
 ## Test utilities (`./test-utils`)
 
 Deterministic Playwright / jsdom helpers, published as a separate

package/dist/index.cjs

@@ -2052,6 +2052,17 @@ function createElementSelector() {
   let active = false;
   let overlay = null;
   let resolvePromise = null;
+  function findNearestTestid(el) {
+    let cur = el;
+    let hops = 0;
+    while (cur && hops < 20) {
+      const tid = cur.getAttribute?.("data-testid");
+      if (tid) return tid;
+      cur = cur.parentElement;
+      hops++;
+    }
+    return null;
+  }
   function getXPath(el) {
     const parts = [];
     let current = el;
@@ -2081,7 +2092,13 @@ function createElementSelector() {
         y: Math.round(rect.y),
         width: Math.round(rect.width),
         height: Math.round(rect.height)
-      }
+      },
+      // v2 (whitepaper §4.7): the closest ancestor's `data-testid` lets the
+      // server map this report → an Action node in the inventory graph
+      // without a fuzzy NLP guess. We walk to the body so a deeply nested
+      // span inside a button-with-testid still resolves correctly.
+      nearestTestid: findNearestTestid(el) || void 0,
+      route: typeof window !== "undefined" ? window.location.pathname : void 0
     };
   }
   function createOverlay() {
@@ -2260,6 +2277,194 @@ function textSnippet(el) {
   return text ? text.slice(0, 80) : void 0;
 }
 
+// src/capture/discovery.ts
+var DEFAULT_THROTTLE_MS = 6e4;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var HEX24_RE = /^[0-9a-f]{20,}$/i;
+var NUMERIC_RE = /^\d+$/;
+var SLUG_HASHY_RE = /^[a-z0-9]{16,}$/i;
+function normalizeSegment(seg) {
+  if (seg.length === 0) return seg;
+  if (UUID_RE.test(seg)) return "[id]";
+  if (HEX24_RE.test(seg)) return "[id]";
+  if (NUMERIC_RE.test(seg)) return "[id]";
+  if (SLUG_HASHY_RE.test(seg) && /\d/.test(seg)) return "[id]";
+  return seg;
+}
+function normalizeRoute(pathname, templates) {
+  const clean = pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+  if (templates?.length) {
+    const matched = matchTemplate(clean, templates);
+    if (matched) return matched;
+  }
+  return "/" + clean.split("/").filter((s) => s.length > 0).map(normalizeSegment).join("/");
+}
+function matchTemplate(pathname, templates) {
+  const segs = pathname.split("/").filter((s) => s.length > 0);
+  const sorted = [...templates].sort(
+    (a, b) => b.split("/").length - a.split("/").length
+  );
+  for (const tpl of sorted) {
+    const tplSegs = tpl.split("/").filter((s) => s.length > 0);
+    if (tplSegs.length !== segs.length) continue;
+    let ok = true;
+    for (let i = 0; i < tplSegs.length; i++) {
+      const t = tplSegs[i];
+      const s = segs[i];
+      if (t.startsWith("[") && t.endsWith("]")) continue;
+      if (t.startsWith(":")) continue;
+      if (t === s) continue;
+      ok = false;
+      break;
+    }
+    if (ok) return "/" + tplSegs.join("/");
+  }
+  return null;
+}
+function readTestids() {
+  if (typeof document === "undefined") return [];
+  const out = /* @__PURE__ */ new Set();
+  const els = document.querySelectorAll("[data-testid]");
+  for (const el of Array.from(els)) {
+    const v = el.getAttribute("data-testid");
+    if (v && v.length > 0 && v.length < 120) out.add(v);
+  }
+  return Array.from(out).sort();
+}
+function readQueryParamKeys() {
+  if (typeof window === "undefined") return [];
+  try {
+    const params = new URLSearchParams(window.location.search);
+    const out = /* @__PURE__ */ new Set();
+    params.forEach((_, key) => out.add(key));
+    return Array.from(out).sort();
+  } catch {
+    return [];
+  }
+}
+function readDomSummary() {
+  if (typeof document === "undefined") return null;
+  const trim = (s) => (s ?? "").replace(/\s+/g, " ").trim().slice(0, 200);
+  const h1 = trim(document.querySelector("h1")?.textContent);
+  if (h1) return h1;
+  const title = trim(document.title);
+  if (title) return title;
+  const main = trim(document.querySelector("main")?.textContent);
+  return main || null;
+}
+async function hashUserId(input) {
+  if (!input || typeof crypto === "undefined" || !crypto.subtle) return null;
+  try {
+    const data = new TextEncoder().encode(input);
+    const buf = await crypto.subtle.digest("SHA-256", data);
+    const bytes = new Uint8Array(buf);
+    let hex = "";
+    for (let i = 0; i < bytes.length; i++) {
+      hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+  } catch {
+    return null;
+  }
+}
+function createDiscoveryCapture(opts) {
+  const {
+    config,
+    getRecentNetworkPaths,
+    getUserId,
+    getSessionId: getSessionId2,
+    onEvent
+  } = opts;
+  const throttleMs = config.throttleMs ?? DEFAULT_THROTTLE_MS;
+  const captureSummary = config.captureDomSummary !== false;
+  const userIdSource = config.userIdSource ?? "auto";
+  const lastEmittedAt = /* @__PURE__ */ new Map();
+  let lastPath = null;
+  let pendingTimer = null;
+  async function emitForCurrent() {
+    if (typeof window === "undefined") return;
+    const route = normalizeRoute(window.location.pathname, config.routeTemplates);
+    const now = Date.now();
+    const last = lastEmittedAt.get(route) ?? 0;
+    if (now - last < throttleMs) return;
+    lastEmittedAt.set(route, now);
+    let userIdInput = null;
+    if (userIdSource === "auto") {
+      userIdInput = getUserId() ?? getSessionId2();
+    } else if (userIdSource === "session-only") {
+      userIdInput = getSessionId2();
+    }
+    const event = {
+      route,
+      page_title: typeof document !== "undefined" ? (document.title || "").slice(0, 300) || null : null,
+      dom_summary: captureSummary ? readDomSummary() : null,
+      testids: readTestids(),
+      network_paths: getRecentNetworkPaths().slice(-50),
+      query_param_keys: readQueryParamKeys(),
+      user_id_hash: await hashUserId(userIdInput),
+      observed_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    onEvent(event);
+  }
+  function scheduleEmit() {
+    if (pendingTimer) return;
+    pendingTimer = setTimeout(() => {
+      pendingTimer = null;
+      void emitForCurrent();
+    }, 100);
+  }
+  function onMaybeNavigation() {
+    if (typeof window === "undefined") return;
+    const path = window.location.pathname + window.location.search;
+    if (path === lastPath) return;
+    lastPath = path;
+    scheduleEmit();
+  }
+  if (typeof window === "undefined") {
+    return {
+      destroy: () => void 0,
+      flushNow: () => void 0
+    };
+  }
+  const originalPush = window.history.pushState.bind(window.history);
+  const originalReplace = window.history.replaceState.bind(window.history);
+  const patchedPush = function patched(...args) {
+    const out = originalPush(...args);
+    onMaybeNavigation();
+    return out;
+  };
+  const patchedReplace = function patched(...args) {
+    const out = originalReplace(...args);
+    onMaybeNavigation();
+    return out;
+  };
+  window.history.pushState = patchedPush;
+  window.history.replaceState = patchedReplace;
+  const onPop = () => onMaybeNavigation();
+  window.addEventListener("popstate", onPop);
+  scheduleEmit();
+  return {
+    destroy() {
+      window.removeEventListener("popstate", onPop);
+      if (window.history.pushState === patchedPush) {
+        window.history.pushState = originalPush;
+      }
+      if (window.history.replaceState === patchedReplace) {
+        window.history.replaceState = originalReplace;
+      }
+      if (pendingTimer) {
+        clearTimeout(pendingTimer);
+        pendingTimer = null;
+      }
+      lastEmittedAt.clear();
+    },
+    flushNow() {
+      lastEmittedAt.clear();
+      void emitForCurrent();
+    }
+  };
+}
+
 // src/sentry.ts
 function getSentryGlobal() {
   try {
@@ -2475,7 +2680,7 @@ function createProactiveManager(config = {}) {
 
 // src/version.ts
 var MUSHI_SDK_PACKAGE = "@mushi-mushi/web";
-var MUSHI_SDK_VERSION = "0.8.0" ;
+var MUSHI_SDK_VERSION = "0.9.0" ;
 
 // src/mushi.ts
 var instance = null;
@@ -2528,6 +2733,7 @@ function createInstance(config) {
   let perfCap = null;
   let screenshotCap = null;
   let elementSelector = null;
+  let discoveryCap = null;
   const timelineCap = createTimelineCapture();
   let widget;
   function syncCaptureModules() {
@@ -2576,6 +2782,40 @@ function createInstance(config) {
       elementSelector = null;
       pendingElement = null;
     }
+    const discoveryRaw = activeConfig.capture?.discoverInventory;
+    const discoveryConfig = discoveryRaw === true ? {} : discoveryRaw && typeof discoveryRaw === "object" ? discoveryRaw : null;
+    const discoveryEnabled = discoveryConfig != null && discoveryConfig.enabled !== false;
+    if (discoveryEnabled) {
+      discoveryCap?.destroy();
+      discoveryCap = createDiscoveryCapture({
+        config: discoveryConfig,
+        getRecentNetworkPaths: () => {
+          if (!networkCap) return [];
+          return networkCap.getEntries().map((e) => {
+            try {
+              const u = new URL(e.url, typeof window !== "undefined" ? window.location.href : "http://localhost");
+              if (u.host && typeof window !== "undefined" && u.host !== window.location.host) return null;
+              return u.pathname;
+            } catch {
+              return null;
+            }
+          }).filter((p) => p != null && p.length > 0 && p.length < 200);
+        },
+        getUserId: () => userInfo?.id ?? null,
+        getSessionId: core.getSessionId,
+        onEvent: (event) => {
+          void apiClient.postDiscoveryEvent({
+            ...event,
+            sdk_version: MUSHI_SDK_VERSION
+          }).catch((err) => {
+            log.debug("discovery emit failed", { err: String(err) });
+          });
+        }
+      });
+    } else {
+      discoveryCap?.destroy();
+      discoveryCap = null;
+    }
   }
   const listeners = /* @__PURE__ */ new Map();
   function emit(type, data) {
@@ -2922,6 +3162,8 @@ function createInstance(config) {
       perfCap?.destroy();
       elementSelector?.deactivate();
       timelineCap.destroy();
+      discoveryCap?.destroy();
+      discoveryCap = null;
       offlineQueue.stopAutoSync();
       listeners.clear();
       instance = null;