Clarity

A browser dictation host — one mic follows your active field, speech merges into the DOM, optional LLM finish cleans the session chunk, and explicit send tears down the voice session.

Not always listening Finish ≠ Send No block text cache High-quality STT core

Session lifecycle

Idle Mic off until click or ⌘⇧M
→
Listening STT appends to locked field
→
Finish Stop + optional LLM cleanup — field stays open
→
Send Host submits; session + memory cleared

Architecture

HOST createClarityHost — focus tracking, mic placement, shortcuts, send reset
SESSION dictation-session — frozenPrefix + sessionText + interimText merge
STT stt-capture — Web Speech API uses OS speech engine
FINISH stt-finish — transcript, prompt, or meeting-summary cleanup at injected stops

Field value model

On mic start, existing typed text becomes the frozen prefix. New speech appends after it.

frozenPrefix
sessionText
interim
Prior field value Finalized speech this session Live partial transcript

Mic states

Idle Red — ready
Listening Green glow
Finishing Dimmed, wait

Placement

follow-field

One shared mic reparents to the focused field's host — COO ideas blocks, generic tabs.

fixed-anchor

Mic stays on a command bar — dal-ide pattern with #command-input.

static dock

Per-field toolbar inside .clarity-field-wrap — clarity-notes (mic + proofread) or meeting-summary (mic + summarize).

Finish modes

  • Raw — browser STT only
  • Transcript — punctuation, fillers removed, wording kept
  • Prompt — directive-style cleanup for AI / dev prompts
  • Meeting summary — structured markdown notes from dialogue

Voice commands (opt-in): clarity finish stops; clarity send submits.

Presets & auto-detect

Clarity.auto() fingerprints the DOM and picks a preset config.

clarity-notes Shipped

Note-taking apps with static dock per field. Mic + proofread. BLACKPAD / Prodify Central.

@langmark/clarity/presets/clarity-notes

meeting-summary Shipped

Voice console with mic + summarize. Transcript → formal meeting notes. TeamLead AI.

@langmark/clarity/presets/meeting-summary

generic Shipped

Greenfield apps with data-clarity-field, panels, and context blocks.

@langmark/clarity/presets/generic

coo / dal-ide Reference

Field maps for existing hosts. COO and dal-ide keep their own implementations today.

presets/coo.js · presets/dal-ide.js

Distribution (same core)

1
npm SDK

Embed in your app — createClarityHost + preset + your finish API.

2
Browser extension planned

Shadow DOM mic on any site; pin mode for arbitrary text boxes.

3
api.clarity.app planned

Auth, metered finish, billing for extension with mobile keyboard surface.

Design principles

  • Host-native — adapts to your DOM; no text snapshots in storage
  • Explicit opt-in — mic click or shortcut arms STT
  • Append / resume — re-start reads field.value as prefix
  • Finish ≠ send — cleanup without submitting the form
  • Parity bar — same STT/finish modules across Clarity integrations