# VoiceChart Widget

An **embeddable** version of VoiceChart's dictation panel — built to drop into the
odontOS "Quick Note" card (and any future odontOS tenant), with **zero changes to the
host app**. The host embeds one `<script>` and gets dictation that writes structured,
per-tooth notes back via a small callback.

This folder is self-contained. It **reuses the proven dictation engine verbatim** from the
standalone app (`../app/src/main.js`) — the Whisper background worker, Web Speech engine,
auto-fallback, hallucination filter, dental homophone fixes, and voice-command parser —
so accuracy matches the live app. Only the UI is compact and a `postMessage` bridge is added.

> **We do not modify `odontos.io`.** The widget is a separate artifact. The demo here is a
> *copy* of the Quick Note context, not the real dashboard.

## Files

| File | What |
|------|------|
| `app/index.html` | The widget itself — self-contained (engine + compact UI + postMessage API). Runs as an iframe. |
| `voicechart-widget.js` | Embed loader — injects the iframe (with mic permission) and exposes `VoiceChart.mount()`. |
| `demo/index.html` | A copy of the odontOS Quick Note card with the widget mounted, showing notes flowing back to the host. |

## Embed (one line)

```html
<div id="quicknote"></div>
<script src="https://widget.voicechart.io/voicechart-widget.js"></script>
<script>
  const vc = VoiceChart.mount('#quicknote', {
    patient: 'Isabella Moreau', patNum: '10428', provider: 'Dr. Baruch Tetri',
    theme: { accent: '#8fb4ff', field: '#0f1828' },     // match host design tokens
    onNote: ({ plainText, sections }) => {
      // write to the patient chart / Commlog
      myTextarea.value = plainText;
    },
  });
</script>
```

`mount(target, opts)` returns an API: `vc.start()`, `vc.stop()`, `vc.clear()`,
`vc.config({...})`, `vc.getNote()`, `vc.on('note', cb)`, `vc.destroy()`.

### Options

| opt | meaning |
|-----|---------|
| `patient`, `patNum`, `provider` | echoed back on every note payload |
| `theme` | CSS-token overrides: `accent`, `accentInk`, `accent2`, `text`, `text2`, `text3`, `field`, `border`, `bg`, `font`, `radius` |
| `engine` | `'whisper'` (default, on-device/private) or `'webspeech'` |
| `model` | Whisper model id (default `Xenova/whisper-tiny.en` — fastest first-load) |
| `height` | iframe height (default `340px`) |
| `src` | override the widget app URL (defaults next to the loader script) |
| `onNote`, `onReady` | callbacks |

### `onNote` payload

```js
{
  type: 'voicechart:note',
  plainText: 'Tooth 5: mesial occlusal caries.\n\nPeriodontal: 4mm pocket distal.',
  sections: [ { label: 'Tooth 5', tooth: 5, text: 'mesial occlusal caries.' }, … ],
  patient: 'Isabella Moreau', patNum: '10428', durationSec: 41.2, ts: 1750000000000
}
```

## Voice commands (same as the app)

“start patient note” · “tooth 5” · “next tooth” · “section perio” · “scratch that” ·
“new line” / “new paragraph” · “period” / “comma” / “question mark” · “end patient note”.

## Integrating into the real odontOS demo (when ready)

In a **copy** of `odontos.io/TetriSmile_Odontos.html`, the Quick Note card is built around
the `note.innerHTML = …` block (search for `Quick Note`). Replace the `<textarea>` with a
mount point and add the loader:

```js
// was: <textarea placeholder="Type a note, or dictate with VoiceChart…">…</textarea>
note.innerHTML = `<h3><span class="ico">${svg('note')}</span> Quick Note</h3>
  <div id="vc-quicknote"></div>`;
right.appendChild(note);
// once, after the dashboard mounts:
VoiceChart.mount('#vc-quicknote', { patient: currentPatient.name, patNum: currentPatient.num,
  theme: { accent:'var(--accent)', field:'var(--field)' },
  onNote: ({ plainText }) => savePatientNote(currentPatient, plainText) });
```

…and add `<script src="https://widget.voicechart.io/voicechart-widget.js"></script>` once.

## Hosting

Deployed on its own origin, isolated from the app: **`https://widget.voicechart.io/`**
(loader at `/voicechart-widget.js`, iframe app at `/app/`, this demo at `/demo/`).
Mic permission is granted to the iframe via `allow="microphone"` (the loader sets it).
On-device dictation keeps all audio local — a clean privacy boundary for PHI; the
cross-origin iframe is an extra isolation layer between the host (odontOS) and the engine.