# @mhosaic/feedback

Embeddable feedback + bug-report widget. Preact + Shadow DOM (renders inside any host app without leaking styles), opt-in modules for session replay, Web Vitals, and automatic error capture.

The fastest way to integrate is the guided Claude Code skill — it walks you through both halves (operator provisioning + consumer install), framework-aware, with a live smoke test that confirms a report lands in admin before declaring done.

## The 30-second install (guided)

```bash
# 1. One-time: drop the skill into ~/.claude/skills/
npx @mhosaic/feedback-cli@latest install-skill

# 2. In any project where you want the widget:
cd ~/path/to/your-app
claude
```

Inside Claude Code:

```
/integrate-feedback
```

The skill asks one question (operator / consumer / both) and drives the rest: framework detection, env files, provider wiring, `identify()` recipe for your auth provider, smoke test in Chrome. Full docs: [`docs/INTEGRATING.md`](https://github.com/mhosaic-technologies/feedback-tool-mhosaic/blob/main/docs/INTEGRATING.md) in the source repo.

## Manual install

```bash
npm install @mhosaic/feedback
```

```typescript
import { createFeedback } from '@mhosaic/feedback'
import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
import { withReplay } from '@mhosaic/feedback/replay'
import { withWebVitals } from '@mhosaic/feedback/webvitals'

const fb = withErrorTracking(
  withReplay(
    withWebVitals(createFeedback({
      apiKey: 'pk_proj_…',
      endpoint: 'https://your-feedback-backend.example.com',
      env: 'prod',
    }))
  )
)

// Call identify() once auth resolves; FAB stays hidden until then.
fb.identify({ id: 'user-id', email: 'user@example.com', name: 'User' })
```

Or via CDN with pinned SRI:

```html
<script
  src="https://cdn.jsdelivr.net/npm/@mhosaic/feedback@0.15.4/dist/embed.min.js"
  integrity="sha384-…"
  crossorigin="anonymous"
  data-key="pk_proj_…"
  data-endpoint="https://your-feedback-backend.example.com"
  data-env="prod"
  defer
></script>
```

Pin the exact version + integrity hash — `@latest` breaks SRI. Hash is published in each GitHub Release.

## React provider

For React hosts, `@mhosaic/feedback/react` exposes `<FeedbackProvider>` + `useFeedback()`:

```tsx
import { FeedbackProvider } from '@mhosaic/feedback/react'

<FeedbackProvider apiKey={…} endpoint={…} env="prod">
  <App />
</FeedbackProvider>
```

The CLI auto-wires this for Vite + React apps on `init`. For Next/Remix/Vue/SvelteKit/Astro/Nuxt, see the framework-specific reference docs at `packages/cli/skills/integrate-feedback/references/` (or `~/.claude/skills/integrate-feedback/references/` after `install-skill`).

## Opt-in modules

| Subpath | What it does | Approx gzip |
|---|---|---|
| `@mhosaic/feedback/replay` | rrweb session replay (last N seconds) | ~15 KiB |
| `@mhosaic/feedback/webvitals` | Core Web Vitals capture | ~3 KiB |
| `@mhosaic/feedback/error-tracking` | Auto-files synthetic reports on `window.error` + `unhandledrejection` | ~2 KiB |

All three are middleware wrappers — chain them around `createFeedback()`. See the install snippet above.

## Backend

The widget POSTs to your `mhosaic-feedback` Django backend at `/api/feedback/v1/reports/`. The backend is multi-tenant (Company → Project → Report) and authenticates the widget by `pk_proj_…` Bearer key + origin allow-list. Source + deployment: <https://github.com/mhosaic-technologies/feedback-tool-mhosaic>.

## Links

- **Source code + issues:** <https://github.com/mhosaic-technologies/feedback-tool-mhosaic>
- **Design spec:** [`docs/superpowers/specs/2026-04-21-feedback-plugin-design.md`](https://github.com/mhosaic-technologies/feedback-tool-mhosaic/blob/main/docs/superpowers/specs/2026-04-21-feedback-plugin-design.md)
- **CLI:** [`@mhosaic/feedback-cli`](https://www.npmjs.com/package/@mhosaic/feedback-cli)