@mushi-mushi/web 0.3.0 → 0.4.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,51 @@
+<!--
+  AUTO-SYNCED from repo root by scripts/sync-community-files.mjs.
+  Do not edit here — edit the canonical file at the repository root and
+  re-run `node scripts/sync-community-files.mjs` (pre-commit hook does this
+  automatically).
+-->
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team at **security@mushimushi.dev**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

package/CONTRIBUTING.md

@@ -0,0 +1,122 @@
+<!--
+  AUTO-SYNCED from repo root by scripts/sync-community-files.mjs.
+  Do not edit here — edit the canonical file at the repository root and
+  re-run `node scripts/sync-community-files.mjs` (pre-commit hook does this
+  automatically).
+-->
+
+# Contributing to Mushi Mushi
+
+Thanks for wanting to help. Here's everything you need to get started.
+
+## Prerequisites
+
+- **Node.js >= 22** (see `.node-version`)
+- **pnpm >= 10** — install with `corepack enable`
+
+## Setup
+
+```bash
+git clone https://github.com/kensaurus/mushi-mushi.git
+cd mushi-mushi
+pnpm install
+pnpm build
+```
+
+## Development
+
+```bash
+pnpm dev          # Start all dev servers (admin on :6464)
+pnpm test         # Run Vitest across all packages
+pnpm typecheck    # TypeScript checks
+pnpm lint         # ESLint
+pnpm format       # Prettier
+```
+
+### Working on a single package
+
+```bash
+cd packages/core
+pnpm dev          # Watch mode
+pnpm test         # Tests for this package only
+```
+
+## Project Structure
+
+```
+packages/
+  core/          Types, API client, offline queue (MIT)
+  web/           Browser SDK — widget, capture (MIT)
+  react/         React bindings (MIT)
+  vue/           Vue 3 plugin (MIT)
+  svelte/        Svelte SDK (MIT)
+  angular/       Angular SDK (MIT)
+  react-native/  React Native SDK (MIT)
+  cli/           CLI tool (MIT)
+  mcp/           MCP server for coding agents (MIT)
+  server/        Supabase Edge Functions (BSL)
+  agents/        Agentic fix pipeline (BSL)
+  verify/        Fix verification (BSL)
+apps/
+  admin/         Admin dashboard (React + Tailwind)
+  docs/          Documentation site (planned)
+tooling/
+  eslint-config/ Shared ESLint flat config
+  tsconfig/      Shared TypeScript configs
+```
+
+## Making Changes
+
+1. Create a feature branch from `master`
+2. Make your changes
+3. Add tests for new functionality
+4. Run `pnpm typecheck && pnpm lint && pnpm test` to verify
+5. Create a changeset if your change affects published packages:
+   ```bash
+   pnpm changeset
+   ```
+6. Open a pull request
+
+## Changesets
+
+We use [Changesets](https://github.com/changesets/changesets) for versioning. If your PR modifies a published package (`core`, `web`, `react`, `vue`, `svelte`, `angular`, `react-native`, `cli`, `mcp`), add a changeset:
+
+```bash
+pnpm changeset
+```
+
+Select the affected packages, the semver bump type, and write a summary. The changeset file gets committed with your PR.
+
+## Code Style
+
+- **TypeScript strict mode** — no `any` unless absolutely necessary
+- **Prettier** formats everything — run `pnpm format` before committing
+- **ESLint** catches bugs — `pnpm lint` must pass
+- **No default exports** in library packages — use named exports
+- **Dual ESM/CJS** builds via tsup for all SDK packages
+
+## Commit Messages
+
+Use conventional commits:
+
+```
+feat(core): add batch report submission
+fix(web): prevent widget from opening during screenshot
+docs(react): update provider usage example
+chore: bump dependencies
+```
+
+## Tests
+
+- **Framework:** Vitest
+- **Location:** Co-located with source (`src/foo.test.ts`)
+- **Coverage:** Required for `core`, `web`, `react` — encouraged for all packages
+
+## License
+
+- SDK packages are MIT — your contributions will be MIT-licensed
+- Server/agents/verify are BSL 1.1 — contributions to those packages fall under BSL
+
+## Questions?
+
+Open an issue or start a discussion. We're happy to help.

package/README.md

@@ -46,7 +46,7 @@ Each trigger respects its config flag — set `rageClick: false` to disable rage
 
 ## Bundle Size
 
-~6 KB brotli (limit: 30 KB). Requires `@mushi-mushi/core` as a dependency (not bundled inline).
+~6 KB brotli, enforced at **15 KB gzipped** via `size-limit` in CI. Requires `@mushi-mushi/core` as a dependency (not bundled inline). The `./test-utils` entry is a separate artifact and is never pulled into production bundles.
 
 ## Quick Start
 
@@ -99,6 +99,28 @@ setupProactiveTriggers({
 });
 ```
 
+## Test utilities (`./test-utils`)
+
+Deterministic Playwright / jsdom helpers, published as a separate
+entry-point so production bundles pay nothing for them:
+
+```ts
+import { triggerBug, openReport, waitForQueueDrain } from '@mushi-mushi/web/test-utils';
+```
+
+| Export              | Purpose                                                                 |
+|---------------------|-------------------------------------------------------------------------|
+| `triggerBug(opts?)` | Submit a report bypassing the widget. Returns the server-assigned id.   |
+| `openReport(cat?)`  | Open the widget programmatically without submitting.                    |
+| `waitForQueueDrain` | Resolve once the offline queue is empty (number remaining at timeout).  |
+
+Every helper no-ops when `Mushi.getInstance()` returns `null`, so
+conditional-wiring tests (e.g. cloud vs local targets) don't need to
+branch. For browser-context use in Playwright's `page.evaluate`, import
+the SDK via the app's own bundle (`window.__mushi__` in dev builds) or
+POST to `/v1/reports` directly — `page.evaluate` has no npm resolver in
+the browser context.
+
 ## License
 
 MIT

package/SECURITY.md

@@ -0,0 +1,50 @@
+<!--
+  AUTO-SYNCED from repo root by scripts/sync-community-files.mjs.
+  Do not edit here — edit the canonical file at the repository root and
+  re-run `node scripts/sync-community-files.mjs` (pre-commit hook does this
+  automatically).
+-->
+
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.x     | Yes       |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly.
+
+**Do NOT open a public GitHub issue.**
+
+Instead, email: **security@mushimushi.dev**
+
+Include:
+- Description of the vulnerability
+- Steps to reproduce
+- Impact assessment
+- Suggested fix (if any)
+
+We will acknowledge receipt within 48 hours and aim to release a patch within 7 days for critical issues.
+
+## Scope
+
+- All `@mushi-mushi/*` npm packages
+- Supabase Edge Functions (server-side)
+- Admin console application
+- CLI tool
+
+## Out of Scope
+
+- Self-hosted deployments configured by the user
+- Third-party integrations (Jira, Linear, PagerDuty)
+- Vulnerabilities requiring physical access
+
+## Security Best Practices for Users
+
+- **Never commit your API keys** — use environment variables
+- **Rotate API keys** regularly via the admin console
+- **Enable SSO** for team projects (Enterprise tier)
+- **Review audit logs** periodically for suspicious activity

package/dist/test-utils.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+require('@mushi-mushi/core');
+
+// src/mushi.ts
+
+// src/test-utils.ts
+async function triggerBug(opts = {}) {
+  return null;
+}
+function openReport(category) {
+  return;
+}
+async function waitForQueueDrain(options = {}) {
+  return 0;
+}
+
+exports.openReport = openReport;
+exports.triggerBug = triggerBug;
+exports.waitForQueueDrain = waitForQueueDrain;
+//# sourceMappingURL=test-utils.cjs.map
+//# sourceMappingURL=test-utils.cjs.map

package/dist/test-utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/test-utils.ts"],"names":[],"mappings":";;;;;;;AAsDA,eAAsB,UAAA,CAAW,IAAA,GAA0B,EAAC,EAA2B;AAErF,EAAU,OAAO,IAAA;AAqBnB;AAOO,SAAS,WAAW,QAAA,EAAsC;AAE/D,EAAU;AAEZ;AAOA,eAAsB,iBAAA,CAAkB,OAAA,GAAkC,EAAC,EAAoB;AAE7F,EAAU,OAAO,CAAA;AAenB","file":"test-utils.cjs","sourcesContent":["/**\n * @mushi-mushi/web/test-utils\n *\n * Playwright / jsdom helpers for deterministic SDK tests. This module is\n * published as a separate entry-point so production bundles never pay the\n * cost — import it via `import { triggerBug, openReport } from\n * '@mushi-mushi/web/test-utils'`.\n *\n * Design goals:\n *   1. Zero production footprint. Nothing here is imported from `./mushi`,\n *      `./widget`, or any runtime module. We reach for the live SDK via\n *      `Mushi.getInstance()` so the test process sees exactly what the app\n *      bootstrapped — no duplicate SDK singletons, no double-init races.\n *   2. Safe in a test harness even when Mushi is disabled. Every helper\n *      no-ops when `Mushi.getInstance()` returns `null`, so Playwright\n *      specs that conditionally wire Mushi (e.g. cloud vs local targets)\n *      don't have to branch.\n *   3. Flat surface. Tests want 3 verbs: \"open the widget\", \"submit a\n *      report programmatically\", \"wait until the SDK confirms the POST\n *      landed\". Anything beyond that belongs in the app under test.\n */\n\nimport { Mushi } from './mushi';\nimport type {\n  MushiReportCategory,\n  MushiSDKInstance,\n} from '@mushi-mushi/core';\n\n/** Options accepted by `triggerBug`. Mirrors the core report contract but\n *  keeps every field optional so a Playwright test can say\n *  `triggerBug({ description: 'button dead' })` without a category. */\nexport interface TriggerBugOptions {\n  /** Short free-text description of the issue. Defaults to a marker\n   *  string so tests that forget to pass a description still produce a\n   *  distinguishable report in the admin console. */\n  description?: string;\n  /** Severity-free category tag. */\n  category?: MushiReportCategory;\n  /** Arbitrary metadata the test wants to round-trip. Merged on top of\n   *  whatever `setMetadata` has already stored. */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Submit a report bypassing the widget UI. Returns the server-assigned\n * `reportId` when the POST lands, or `null` if Mushi isn't initialised in\n * this test context (or the submit failed — the SDK swallows network\n * errors silently by design).\n *\n * Use this from Playwright `page.evaluate(...)` calls to round-trip a\n * report into the backend without needing to drive the widget's DOM. It's\n * the fastest way to assert \"a bug report made it from the browser into\n * reports/ in Supabase\".\n */\nexport async function triggerBug(opts: TriggerBugOptions = {}): Promise<string | null> {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return null;\n\n  const description = opts.description\n    ?? `[test-utils] triggerBug marker ${new Date().toISOString()}`;\n\n  if (opts.metadata) {\n    for (const [k, v] of Object.entries(opts.metadata)) {\n      try { sdk.setMetadata(k, v); } catch { /* ignore */ }\n    }\n  }\n\n  // `captureEvent` is the documented programmatic-submit API since 0.3.0\n  // — it bypasses the widget, resolves with the server-assigned report\n  // id, and participates in the same offline queue / pre-filter pipeline\n  // as a widget submission.\n  return await sdk.captureEvent({\n    description,\n    source: 'test-utils',\n    ...(opts.category ? { category: opts.category } : {}),\n    ...(opts.metadata ? { metadata: opts.metadata } : {}),\n  });\n}\n\n/**\n * Programmatically open the Mushi widget without submitting anything. Use\n * for interaction tests that want to assert \"the widget is mounted and\n * reachable\" or to drive a user-like flow via Playwright selectors.\n */\nexport function openReport(category?: MushiReportCategory): void {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return;\n  sdk.report(category ? { category } : undefined);\n}\n\n/**\n * Wait until the offline queue drains — useful after `triggerBug` in tests\n * that submit while offline then assert the report eventually syncs.\n * Resolves with the number of queued items remaining (0 = fully drained).\n */\nexport async function waitForQueueDrain(options: { timeoutMs?: number } = {}): Promise<number> {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return 0;\n  const timeoutMs = options.timeoutMs ?? 5_000;\n  const started = Date.now();\n  // The SDK instance doesn't publicly expose the queue, but `getQueueSize`\n  // has been in the contract since 0.2.x. We tolerate its absence so\n  // upgrading doesn't break tests that only need triggerBug/openReport.\n  const getQueueSize = (sdk as MushiSDKInstance & { getQueueSize?: () => number }).getQueueSize;\n  if (typeof getQueueSize !== 'function') return 0;\n\n  while (Date.now() - started < timeoutMs) {\n    const remaining = getQueueSize.call(sdk);\n    if (remaining === 0) return 0;\n    await new Promise((r) => setTimeout(r, 100));\n  }\n  return getQueueSize.call(sdk);\n}\n"]}

package/dist/test-utils.d.cts

@@ -0,0 +1,66 @@
+import { MushiReportCategory } from '@mushi-mushi/core';
+
+/**
+ * @mushi-mushi/web/test-utils
+ *
+ * Playwright / jsdom helpers for deterministic SDK tests. This module is
+ * published as a separate entry-point so production bundles never pay the
+ * cost — import it via `import { triggerBug, openReport } from
+ * '@mushi-mushi/web/test-utils'`.
+ *
+ * Design goals:
+ *   1. Zero production footprint. Nothing here is imported from `./mushi`,
+ *      `./widget`, or any runtime module. We reach for the live SDK via
+ *      `Mushi.getInstance()` so the test process sees exactly what the app
+ *      bootstrapped — no duplicate SDK singletons, no double-init races.
+ *   2. Safe in a test harness even when Mushi is disabled. Every helper
+ *      no-ops when `Mushi.getInstance()` returns `null`, so Playwright
+ *      specs that conditionally wire Mushi (e.g. cloud vs local targets)
+ *      don't have to branch.
+ *   3. Flat surface. Tests want 3 verbs: "open the widget", "submit a
+ *      report programmatically", "wait until the SDK confirms the POST
+ *      landed". Anything beyond that belongs in the app under test.
+ */
+
+/** Options accepted by `triggerBug`. Mirrors the core report contract but
+ *  keeps every field optional so a Playwright test can say
+ *  `triggerBug({ description: 'button dead' })` without a category. */
+interface TriggerBugOptions {
+    /** Short free-text description of the issue. Defaults to a marker
+     *  string so tests that forget to pass a description still produce a
+     *  distinguishable report in the admin console. */
+    description?: string;
+    /** Severity-free category tag. */
+    category?: MushiReportCategory;
+    /** Arbitrary metadata the test wants to round-trip. Merged on top of
+     *  whatever `setMetadata` has already stored. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Submit a report bypassing the widget UI. Returns the server-assigned
+ * `reportId` when the POST lands, or `null` if Mushi isn't initialised in
+ * this test context (or the submit failed — the SDK swallows network
+ * errors silently by design).
+ *
+ * Use this from Playwright `page.evaluate(...)` calls to round-trip a
+ * report into the backend without needing to drive the widget's DOM. It's
+ * the fastest way to assert "a bug report made it from the browser into
+ * reports/ in Supabase".
+ */
+declare function triggerBug(opts?: TriggerBugOptions): Promise<string | null>;
+/**
+ * Programmatically open the Mushi widget without submitting anything. Use
+ * for interaction tests that want to assert "the widget is mounted and
+ * reachable" or to drive a user-like flow via Playwright selectors.
+ */
+declare function openReport(category?: MushiReportCategory): void;
+/**
+ * Wait until the offline queue drains — useful after `triggerBug` in tests
+ * that submit while offline then assert the report eventually syncs.
+ * Resolves with the number of queued items remaining (0 = fully drained).
+ */
+declare function waitForQueueDrain(options?: {
+    timeoutMs?: number;
+}): Promise<number>;
+
+export { type TriggerBugOptions, openReport, triggerBug, waitForQueueDrain };

package/dist/test-utils.d.ts

@@ -0,0 +1,66 @@
+import { MushiReportCategory } from '@mushi-mushi/core';
+
+/**
+ * @mushi-mushi/web/test-utils
+ *
+ * Playwright / jsdom helpers for deterministic SDK tests. This module is
+ * published as a separate entry-point so production bundles never pay the
+ * cost — import it via `import { triggerBug, openReport } from
+ * '@mushi-mushi/web/test-utils'`.
+ *
+ * Design goals:
+ *   1. Zero production footprint. Nothing here is imported from `./mushi`,
+ *      `./widget`, or any runtime module. We reach for the live SDK via
+ *      `Mushi.getInstance()` so the test process sees exactly what the app
+ *      bootstrapped — no duplicate SDK singletons, no double-init races.
+ *   2. Safe in a test harness even when Mushi is disabled. Every helper
+ *      no-ops when `Mushi.getInstance()` returns `null`, so Playwright
+ *      specs that conditionally wire Mushi (e.g. cloud vs local targets)
+ *      don't have to branch.
+ *   3. Flat surface. Tests want 3 verbs: "open the widget", "submit a
+ *      report programmatically", "wait until the SDK confirms the POST
+ *      landed". Anything beyond that belongs in the app under test.
+ */
+
+/** Options accepted by `triggerBug`. Mirrors the core report contract but
+ *  keeps every field optional so a Playwright test can say
+ *  `triggerBug({ description: 'button dead' })` without a category. */
+interface TriggerBugOptions {
+    /** Short free-text description of the issue. Defaults to a marker
+     *  string so tests that forget to pass a description still produce a
+     *  distinguishable report in the admin console. */
+    description?: string;
+    /** Severity-free category tag. */
+    category?: MushiReportCategory;
+    /** Arbitrary metadata the test wants to round-trip. Merged on top of
+     *  whatever `setMetadata` has already stored. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Submit a report bypassing the widget UI. Returns the server-assigned
+ * `reportId` when the POST lands, or `null` if Mushi isn't initialised in
+ * this test context (or the submit failed — the SDK swallows network
+ * errors silently by design).
+ *
+ * Use this from Playwright `page.evaluate(...)` calls to round-trip a
+ * report into the backend without needing to drive the widget's DOM. It's
+ * the fastest way to assert "a bug report made it from the browser into
+ * reports/ in Supabase".
+ */
+declare function triggerBug(opts?: TriggerBugOptions): Promise<string | null>;
+/**
+ * Programmatically open the Mushi widget without submitting anything. Use
+ * for interaction tests that want to assert "the widget is mounted and
+ * reachable" or to drive a user-like flow via Playwright selectors.
+ */
+declare function openReport(category?: MushiReportCategory): void;
+/**
+ * Wait until the offline queue drains — useful after `triggerBug` in tests
+ * that submit while offline then assert the report eventually syncs.
+ * Resolves with the number of queued items remaining (0 = fully drained).
+ */
+declare function waitForQueueDrain(options?: {
+    timeoutMs?: number;
+}): Promise<number>;
+
+export { type TriggerBugOptions, openReport, triggerBug, waitForQueueDrain };

package/dist/test-utils.js

@@ -0,0 +1,18 @@
+import '@mushi-mushi/core';
+
+// src/mushi.ts
+
+// src/test-utils.ts
+async function triggerBug(opts = {}) {
+  return null;
+}
+function openReport(category) {
+  return;
+}
+async function waitForQueueDrain(options = {}) {
+  return 0;
+}
+
+export { openReport, triggerBug, waitForQueueDrain };
+//# sourceMappingURL=test-utils.js.map
+//# sourceMappingURL=test-utils.js.map

package/dist/test-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/test-utils.ts"],"names":[],"mappings":";;;;;AAsDA,eAAsB,UAAA,CAAW,IAAA,GAA0B,EAAC,EAA2B;AAErF,EAAU,OAAO,IAAA;AAqBnB;AAOO,SAAS,WAAW,QAAA,EAAsC;AAE/D,EAAU;AAEZ;AAOA,eAAsB,iBAAA,CAAkB,OAAA,GAAkC,EAAC,EAAoB;AAE7F,EAAU,OAAO,CAAA;AAenB","file":"test-utils.js","sourcesContent":["/**\n * @mushi-mushi/web/test-utils\n *\n * Playwright / jsdom helpers for deterministic SDK tests. This module is\n * published as a separate entry-point so production bundles never pay the\n * cost — import it via `import { triggerBug, openReport } from\n * '@mushi-mushi/web/test-utils'`.\n *\n * Design goals:\n *   1. Zero production footprint. Nothing here is imported from `./mushi`,\n *      `./widget`, or any runtime module. We reach for the live SDK via\n *      `Mushi.getInstance()` so the test process sees exactly what the app\n *      bootstrapped — no duplicate SDK singletons, no double-init races.\n *   2. Safe in a test harness even when Mushi is disabled. Every helper\n *      no-ops when `Mushi.getInstance()` returns `null`, so Playwright\n *      specs that conditionally wire Mushi (e.g. cloud vs local targets)\n *      don't have to branch.\n *   3. Flat surface. Tests want 3 verbs: \"open the widget\", \"submit a\n *      report programmatically\", \"wait until the SDK confirms the POST\n *      landed\". Anything beyond that belongs in the app under test.\n */\n\nimport { Mushi } from './mushi';\nimport type {\n  MushiReportCategory,\n  MushiSDKInstance,\n} from '@mushi-mushi/core';\n\n/** Options accepted by `triggerBug`. Mirrors the core report contract but\n *  keeps every field optional so a Playwright test can say\n *  `triggerBug({ description: 'button dead' })` without a category. */\nexport interface TriggerBugOptions {\n  /** Short free-text description of the issue. Defaults to a marker\n   *  string so tests that forget to pass a description still produce a\n   *  distinguishable report in the admin console. */\n  description?: string;\n  /** Severity-free category tag. */\n  category?: MushiReportCategory;\n  /** Arbitrary metadata the test wants to round-trip. Merged on top of\n   *  whatever `setMetadata` has already stored. */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Submit a report bypassing the widget UI. Returns the server-assigned\n * `reportId` when the POST lands, or `null` if Mushi isn't initialised in\n * this test context (or the submit failed — the SDK swallows network\n * errors silently by design).\n *\n * Use this from Playwright `page.evaluate(...)` calls to round-trip a\n * report into the backend without needing to drive the widget's DOM. It's\n * the fastest way to assert \"a bug report made it from the browser into\n * reports/ in Supabase\".\n */\nexport async function triggerBug(opts: TriggerBugOptions = {}): Promise<string | null> {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return null;\n\n  const description = opts.description\n    ?? `[test-utils] triggerBug marker ${new Date().toISOString()}`;\n\n  if (opts.metadata) {\n    for (const [k, v] of Object.entries(opts.metadata)) {\n      try { sdk.setMetadata(k, v); } catch { /* ignore */ }\n    }\n  }\n\n  // `captureEvent` is the documented programmatic-submit API since 0.3.0\n  // — it bypasses the widget, resolves with the server-assigned report\n  // id, and participates in the same offline queue / pre-filter pipeline\n  // as a widget submission.\n  return await sdk.captureEvent({\n    description,\n    source: 'test-utils',\n    ...(opts.category ? { category: opts.category } : {}),\n    ...(opts.metadata ? { metadata: opts.metadata } : {}),\n  });\n}\n\n/**\n * Programmatically open the Mushi widget without submitting anything. Use\n * for interaction tests that want to assert \"the widget is mounted and\n * reachable\" or to drive a user-like flow via Playwright selectors.\n */\nexport function openReport(category?: MushiReportCategory): void {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return;\n  sdk.report(category ? { category } : undefined);\n}\n\n/**\n * Wait until the offline queue drains — useful after `triggerBug` in tests\n * that submit while offline then assert the report eventually syncs.\n * Resolves with the number of queued items remaining (0 = fully drained).\n */\nexport async function waitForQueueDrain(options: { timeoutMs?: number } = {}): Promise<number> {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return 0;\n  const timeoutMs = options.timeoutMs ?? 5_000;\n  const started = Date.now();\n  // The SDK instance doesn't publicly expose the queue, but `getQueueSize`\n  // has been in the contract since 0.2.x. We tolerate its absence so\n  // upgrading doesn't break tests that only need triggerBug/openReport.\n  const getQueueSize = (sdk as MushiSDKInstance & { getQueueSize?: () => number }).getQueueSize;\n  if (typeof getQueueSize !== 'function') return 0;\n\n  while (Date.now() - started < timeoutMs) {\n    const remaining = getQueueSize.call(sdk);\n    if (remaining === 0) return 0;\n    await new Promise((r) => setTimeout(r, 100));\n  }\n  return getQueueSize.call(sdk);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/web",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Mushi Mushi browser SDK — embeddable bug reporting widget with Shadow DOM isolation",
   "license": "MIT",
   "type": "module",
@@ -17,12 +17,25 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./test-utils": {
+      "import": {
+        "types": "./dist/test-utils.d.ts",
+        "default": "./dist/test-utils.js"
+      },
+      "require": {
+        "types": "./dist/test-utils.d.cts",
+        "default": "./dist/test-utils.cjs"
+      }
     }
   },
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md"
   ],
   "repository": {
     "type": "git",
@@ -53,17 +66,25 @@
     "sdk"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "sideEffects": false,
   "size-limit": [
     {
+      "name": "Core SDK bundle (minified + gzipped)",
       "path": "dist/index.js",
-      "limit": "30 KB"
+      "limit": "15 KB",
+      "gzip": true
+    },
+    {
+      "name": "Core SDK bundle (uncompressed)",
+      "path": "dist/index.js",
+      "limit": "60 KB"
     }
   ],
   "dependencies": {
-    "@mushi-mushi/core": "^0.3.0"
+    "@mushi-mushi/core": "^0.4.0"
   },
   "devDependencies": {
     "@size-limit/file": "^12.1.0",
@@ -77,6 +98,9 @@
     "@mushi-mushi/tsconfig": "0.0.0"
   },
   "author": "Kenji Sakuramoto",
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",