---
name: dictum-sdk-integration
description: Add, review, or update browser and web-app integrations with the headless Dictum SDK for speech-to-text. Use when Codex needs to wire createSession, choose DOM versus custom targets, connect host-owned UI controls, handle public session events/results/errors, or enforce Dictum SDK security and transport boundaries in app code.
---

# Dictum SDK Integration

Use this skill to integrate Dictum SDK without adding SDK-owned UI, DOM scanning, hidden transport behavior, or leaked secrets.

## Workflow

1. Inspect the host app first: framework, text target ownership, auth flow, cleanup lifecycle, and where UI state is rendered.
2. Choose the insertion boundary:
   - DOM input, textarea, HTMLElement, or contenteditable when the browser owns the editable value.
   - Custom insertion adapter for React-controlled fields, rich editors, mobile webviews, native wrappers, or any host-owned text state.
3. Create the session with `createSession(config)` and bind `target` there. Do not pass a target to `start()`.
4. Wire host-owned buttons to `start`, `pause`, `resume`, `stop`, `retry`, and `destroy`.
5. Render state from `statechange`; handle final transcript from `insert` or `session.result`.
6. Handle dedicated errors and the general `error` event. Do not invent unsupported public events.
7. Keep identity signing server-side. Never expose project secrets, signed-token secrets, transcripts, or raw audio in logs.

## References

- Read `references/browser-integration.md` when implementing app code, React examples, cleanup, or UI command wiring.
- Read `references/public-event-contract.md` when handling states, events, results, or error payloads.

## Hard Rules

- The SDK is headless: no generated microphone buttons, overlays, CSS injection, debug panels, or script-tag bootstrap contract.
- `data-stt` attributes, script URL query params, and HTML attributes are not Dictum SDK configuration.
- WebSocket is the default first-attempt transport. POST+SSE is used only with `transport: "sse"`.
- Public code must not depend on raw WebSocket frames, SSE lines, or `ack` frames.
- Raw audio must never be logged or copied into debugging output.