Dictation

Root holds the dictation state for the field below it. With the service it opens the microphone, picks the mode from the config's capabilities (live when it can, record then transcribe when it has file only) and keeps one recording for a retry. With enabled="optional" and no service, it renders its children and nothing else.

Source: @slices.sh/transcription/src/headless/dictation-root.tsx

The field being dictated into, which somebody may also type in. It wraps any text input: give it the input as `render` (a `Composer.Input`, an address input, a plain textarea) and it takes over four props of it: `value` and `onChange`, through which recognised words land at the caret, `aria-busy`, true while listening or finalizing, which is the whole of its link to a form, and `onKeyDown`, where Escape cancels. It knows nothing about forms or messages. Without a transcription service it renders its input untouched. It is a part rather than the pattern's own textarea so the text lives in the root: what a person types and what dictation writes are the same value, and two owners of it would disagree the first time both happened at once. It also owns the caret, in both directions. Where it is goes up, because dictation starts there. Where it belongs comes back down as arithmetic rather than as a number from anybody: a controlled textarea whose value changed puts the caret at the end, and every committed segment changes the value — so on a change this element did not make, the caret goes to the end of what changed, which is exactly the end of the dictated run.

Source: @slices.sh/transcription/src/headless/field.tsx

The field's text again, with the span dictation just wrote singled out. A textarea cannot colour a range of its own value. The only way to point at the words that have just arrived is a second element behind it with the same metrics, holding the same text invisibly and marking the run — so the eye finds the new text and the field was never anything but a textarea, with its own caret, its own selection and its own spellcheck. The three pieces are handed over rather than drawn, because which of them is marked is this layer's and what a mark looks like is not. → docs/rules/words-in-copy-looks-in-skin.md

Source: @slices.sh/transcription/src/headless/marks.tsx

The one button: starts when idle, finishes when listening. One control rather than two, because that is what everybody expects from a microphone, and because a separate stop button spends most of its life disabled beside it.

Source: @slices.sh/transcription/src/headless/mic-button.tsx

How loud it is, as a real `<meter>`. Read from the local analyser rather than from anything the provider sends, so it follows the voice rather than the network. Rendered only while listening: a meter at zero next to an idle button says nothing. `Dictation.Level` is the same number without the element, for a skin that draws its own.

Source: @slices.sh/transcription/src/headless/mic-level.tsx

How loud it is, as a number somebody else draws. `Dictation.MicLevel` is a real `<meter>`, which is the right answer when a meter is what is wanted. This is for the other one: twelve bars, a ring, a blob that breathes — a skin that is given 0–1 and decides. Neither belongs in the other, because an element the browser styles and an element a designer draws are different things. Rendered only while listening: a level of zero beside an idle button says nothing.

Source: @slices.sh/transcription/src/headless/level.tsx

The voice itself, handed to whatever draws it. The one part here that gives out an object with functions on it rather than a number, and deliberately: a waveform wants a fresh reading every frame, and a part that put those numbers into React state would re-render the field somebody is dictating into sixty times a second. What goes across is the analyser; the drawing loop belongs to the skin, and it reads from its own `requestAnimationFrame` without this layer hearing about any of it. → services/transcription/signal.ts `mode` is what the drawing is of rather than what it looks like: a voice arriving, a pass being waited on, or a microphone that is not open. Which of those is a fact about the dictation, and the only one this layer is entitled to state.

Source: @slices.sh/transcription/src/headless/signal.tsx

The last couple of seconds of voice, oldest first, for a skin to draw as it likes. A history rather than a spectrum. A bar per frequency band is a picture of the sound; a bar per moment is a picture of the *speaking*, and it is the second one people read — which is also why it scrolls, since a shape that only rises and falls in place cannot show a pause. The list is handed over whole and is never drawn here. What it looks like is the skin's, and drawing anything at all would put a decision in the headless layer that belongs one level up. → docs/rules/words-in-copy-looks-in-skin.md

Source: @slices.sh/transcription/src/headless/waveform.tsx

Somebody is talking, rather than the room merely being on. Not the same as `Dictation.Listening`, which is about the microphone: an open microphone in a quiet room is listening and nobody is speaking. The difference is what a screen needs to say "go on, I'm getting this" without saying it into silence. The timing that makes it watchable — a syllable turns it on, a pause between words does not turn it off — is in `hooks/transcription/level.ts`.

Source: @slices.sh/transcription/src/headless/speaking.tsx

The hypothesis being revised, which never goes into the field. Shown beside it instead, so a person watching their own words appear is not also watching them rewrite themselves inside something they might be about to edit. Split at the last word, because that is the one that is about to be rewritten and a hypothesis that looks as settled as the text beside it is a hypothesis nobody reads as one. Which word is the unstable one is a fact; drawing it lighter is a look. → docs/rules/words-in-copy-looks-in-skin.md

Capability: live, partials

Source: @slices.sh/transcription/src/headless/partial.tsx

How long it has been listening, as m:ss.

Source: @slices.sh/transcription/src/headless/elapsed.tsx

Who is transcribing, and on which model. A dictation that fell back to the browser's own recogniser looked exactly like one on a provider until the words came out wrong; this is where it says which it is. Hidden until the instance has answered, and wherever it never does. → docs/rules/capability-honesty.md

Source: @slices.sh/transcription/src/headless/engine.tsx

How many seconds of quiet are left before it stops itself. Rendered only while something is counting, because that is the only time it is true — and it is worth saying out loud rather than only acting on: a dictation that ends in the middle of a thought reads as one that broke, and somebody who is pausing to think has no way to know a word would cancel it. → hooks/transcription/use-silence.ts

Source: @slices.sh/transcription/src/headless/countdown.tsx

Nothing is happening: no microphone open, nothing waiting to be decided. Where a hint about how to start belongs. It is a gate rather than the absence of the others because "idle" is four of the seven states, and a pattern that wrote the negation itself would be a pattern reading the state. → docs/rules/states-gate-themselves.md

Source: @slices.sh/transcription/src/headless/idle.tsx

A microphone is open.

Source: @slices.sh/transcription/src/headless/listening.tsx

Stopped, and waiting for the definitive text. Its own state because the wait is real and worth showing: without `live` it is the whole transcription, and a button that looked idle here would be pressed again.

Source: @slices.sh/transcription/src/headless/finalizing.tsx

The definitive text disagrees with what is in the field. Only reached when somebody typed while it was listening — otherwise the better text is simply taken and nobody sees this. Here, they choose. → hooks/transcription/types.ts `diff` is what changed, word by word, because the alternative is asking somebody to read two sentences and spot the difference — which for the correction this usually is, one name in the middle of a line they have already read, is the whole decision hidden. What a removed or an added word looks like is the skin's. → hooks/transcription/word-diff.ts

Capability: live, file

Source: @slices.sh/transcription/src/headless/revised.tsx

Takes the machine's version.

Capability: live, file

Source: @slices.sh/transcription/src/headless/accept-revision.tsx

Keeps what is in the field.

Capability: live, file

Source: @slices.sh/transcription/src/headless/keep-mine.tsx

Gives up and puts the field back. Not the same as the microphone button: that one finishes and waits for the text, this one throws it away. A dictation needs both. → services/transcription/ports.ts

Source: @slices.sh/transcription/src/headless/cancel-dictation.tsx

Sends the kept recording again. Rendered only where there is one. A live session's words arrived as text or not at all, so on that path there is nothing behind this button and it is not drawn — which is the difference between offering a retry and offering a shape. → hooks/transcription/use-dictation.ts

Source: @slices.sh/transcription/src/headless/retry-dictation.tsx

Throws the kept recording away, and with it the offer to send it again.

Source: @slices.sh/transcription/src/headless/discard-recording.tsx

Removes what dictation wrote, and nothing anybody typed.

Source: @slices.sh/transcription/src/headless/undo-dictation.tsx

The browser will not give this page a microphone. Three refusals rather than one, because only one of them is a setting: no device, an insecure page or a browser without `getUserMedia` is nobody's to grant; a refusal can be taken back in the address bar; and a microphone another application is holding needs nothing changed at all, only the other application closed. Which one it was is read from the rejection `getUserMedia` threw, not from the Permissions API — Firefox has no `microphone` name and Safari's answer is unreliable, so a gate that waited for that one never appeared outside Chrome. → services/transcription/microphone.ts

Source: @slices.sh/transcription/src/headless/mic-denied.tsx

Which microphone to listen to. A `<select>`, which is the one control that is already the right thing on both ends: a menu beside a pointer and the operating system's own wheel or sheet on a phone, with its keyboard, its type-ahead and its screen-reader behaviour already correct. A popover built out of buttons would be a worse version of all of that on the smaller screen. The list is handed over and the options are drawn one level up, because an `<option>` is a host element and this layer renders none. What the labels say is the browser's — they are data rather than words, and are empty until permission has been given once, which is it declining to be a fingerprint rather than a bug. Three things a picker has to be honest about: - Before that first permission it is also the request. There is one device to list and no names for it, so it is shown anyway and opening it is what asks; the names arrive when the browser has said yes. Hiding it until then meant the first press always used the default, whatever somebody had meant to pick. - While listening it shows the microphone that is actually open, which is not always the one that was chosen, and it is disabled: a change then would be a choice that nothing acts on until the next press, and a select that looks live and is not is worse than one that says so. - Otherwise it is rendered only where there is a choice to make: one microphone and a picker beside it is a control that cannot do anything.

Source: @slices.sh/transcription/src/headless/mic-devices.tsx

The recogniser dropped and is coming back. Its own gate because it is not a failure and not idleness: Chrome's recogniser ends itself after a silence even when it was told to be continuous, and a screen with only "listening" to show left somebody talking into a socket that had closed. The contract has modelled `reconnecting` from the start and nothing was reading it. → services/transcription/ports.ts

Capability: live, partials

Source: @slices.sh/transcription/src/headless/reconnecting.tsx

The one region a screen reader is told about, and the reason it is always here. A live region has to exist *before* the text arrives in it: one that mounts with its content already in place announces nothing, which is why this is not simply an `aria-live` on the hypothesis. So it renders whatever a pattern puts in it at every state, empty included, and assistive technology watches one place from the start. What it says is the committed text, never the hypothesis. A partial is rewritten three or four times a second and reading each version out loud is not dictation feedback, it is a machine talking over the person. → components/headless/transcription/partial.tsx

Source: @slices.sh/transcription/src/headless/dictation-status.tsx

The service refused, with the reason. Never a microphone: that is the gate beside this. `recorded` says whether the audio that pass was made from is still in hand, which decides whether there is anything to offer beyond an apology: a recorded pass can be sent again, and a live session's words arrived as text or not at all. → components/headless/transcription/retry-dictation.tsx `message` is the service's own words for it, `null` where it had none. Say it as written when it is there: a sentence picked from `error` alone is a guess about which refusal this was, and it was once wrong about a provider's 429.

Source: @slices.sh/transcription/src/headless/dictation-failed.tsx

This instance cannot transcribe as somebody speaks. The button still works — it records and submits at the end — so this is a note about *when* the text will appear, not a refusal. A capability that is absent removes an affordance; it never breaks the screen. → docs/rules/capability-honesty.md Only where there is an "at the end" to speak of: an instance that cannot take the recording either has no button to make one with, and this would promise a transcript.

Source: @slices.sh/transcription/src/headless/not-live.tsx

The transcription backend answered that its server lacks a key it needs. Pinned to this family's service so a screen does not repeat the scope, and so another service's missing variable is never its notice. Where the instance can do without the key — a microphone that hides itself when no engine is available — nothing is asked of this gate: the server's warning is what says so. → docs/rules/missing-configuration-is-said.md

Source: @slices.sh/transcription/src/headless/missing-configuration.tsx

Draws its children only where `Dictation.MicButton` would draw one. It exists so what surrounds the button goes with it: a wrapper left behind an absent button is an empty element that still takes its place in a row's gap. → docs/rules/capability-honesty.md

Source: @slices.sh/transcription/src/headless/available.tsx

An instance is installed and cannot take a microphone here: the browser's recogniser in a browser that has none, say. The place for a sentence saying so, because a button that is simply absent leaves somebody looking for one. Not drawn where no instance is installed at all: that screen chose not to dictate, and has nothing to explain. → docs/rules/capability-honesty.md

Source: @slices.sh/transcription/src/headless/unavailable.tsx

The dictation finished and no word came out of it. A quiet room, a microphone nobody spoke into, a session that closed with nothing said: all end `done`, and a screen that announced "inserted" over an empty field would be saying something untrue. → docs/rules/capability-honesty.md

Source: @slices.sh/transcription/src/headless/nothing-heard.tsx

Draws its children only where this instance can do the thing. The gate exists because capability belongs to the configured instance rather than to the provider: the same key with a different model has different answers, and a screen that assumed would show a speaker column full of nothing. → services/transcription/capabilities.ts

Source: @slices.sh/transcription/src/headless/supports.tsx

Draws its children only where this instance *cannot* do the thing. The other half of `Supports`, and it is not the same screen with the condition flipped: a capability that is absent usually removes an affordance silently, and the cases worth a sentence are the ones where somebody would otherwise be surprised later — a model that hears one language at a time, given a list of three. Saying it is the alternative to pretending. → docs/rules/capability-honesty.md

Source: @slices.sh/transcription/src/headless/lacks.tsx

A few bars that rise with the voice, for the places a scrolling strip will not fit. Bands rather than moments: inside a mic button there is no room for a history, so the shape is the symmetric silhouette of one instant — the lowest band in the middle, the highest at the edges — which reads as "a voice" at sixteen pixels where a waveform reads as a smudge. Written to the elements' own styles from an animation frame, never through React: there are five of them and they change sixty times a second.

Source: @slices.sh/voice-canvas/src/bar-visualizer.tsx

The last couple of seconds of voice, scrolling right to left. A history rather than a spectrum, and the difference matters: a bar per frequency band is a picture of the sound, a bar per moment is a picture of the *speaking* — and it is the second one people read, because it is the only one that can show a pause. Every number it draws comes from the signal it was handed, read inside its own animation frame. It never renders, never sets state and never opens a microphone.

Source: @slices.sh/voice-canvas/src/live-waveform.tsx