Interim & final result handling

​

The committedText / interimText model

• committedText: text already inserted into the document and visible to the user.
• interimText: the current interim preview, shown outside the document or in a preview layer.

• If isFinal: false: replace interimText with the new segment (after applying boundary spacing). Keep only the newest interim for the current unfinished span.
• If isFinal: true: append the final segment to committedText and clear interimText.

interface DictationState {
  /** Text already committed to the document. */
  committedText: string;
  /** Current interim preview, replaced on each new interim. */
  interimText: string;
  /** End time of the most recently finalized transcript. */
  lastFinalEnd: number;
}

/**
 * Process an incoming transcript message.
 * Apply boundary spacing with buildInsertion() before replacing or
 * committing text — see Transcript Text Handling for the rules.
 */
function handleTranscript(
  state: DictationState,
  text: string,
  isFinal: boolean,
  end: number,
): DictationState {
  if (!isFinal) {
    // Replace the active interim with the newest preview.
    return { ...state, interimText: text };
  }

  // Final: commit into the document, clear the interim buffer.
  return {
    committedText: state.committedText + state.interimText + text,
    interimText: "",
    lastFinalEnd: end,
  };
}

/**
 * Clear the interim preview when a command is recognized.
 * Call this BEFORE dispatching the command action, not after.
 */
function clearInterimForCommand(state: DictationState): DictationState {
  return { ...state, interimText: "" };
}

​

Dedicated preview area (recommended starting point)

​

Clear interim before command dispatch

function onCommand(command: string) {
  // Clear the interim preview first.
  state = clearInterimForCommand(state);
  // Then dispatch the command.
  dispatchCommand(command);
}

​

Out-of-order messages after stop/flush

• start is the primary identity key.
• end is the secondary stale-overlap check during stop/flush races.

interface StaleGuardState {
  /** End time of the most recently finalized transcript. */
  lastFinalEnd: number;
  /** Time spans of recognized commands. */
  commandSpans: Array<{ start: number; end: number }>;
}

/**
 * Returns true if an interim is stale and should be skipped.
 * Uses data.start / data.end as identity keys.
 */
function isStaleInterim(
  state: StaleGuardState,
  interimStart: number,
  interimEnd: number,
): boolean {
  // Skip interims that overlap a recognized command — the command
  // handler already cleared the preview.
  for (const span of state.commandSpans) {
    if (interimStart < span.end && interimEnd > span.start) {
      return true;
    }
  }

  // Skip interims that predate a finalized transcript — an
  // out-of-order message from a stop/flush race.
  if (interimEnd <= state.lastFinalEnd) {
    return true;
  }

  return false;
}

​

Cursor movement during active dictation

• Clear the interim span.
• Send a flush message so remaining buffered audio returns transcripts promptly, then continue dictation in the new location. The API responds with type: "flushed" when done returning text from audio received before the flush message was sent.

​

Inline at caret position (advanced)

​

Editor-agnostic principles

• Overlay, not DOM injection. Do not pollute the editor’s document state or undo history with temporary text. Render the interim as a sibling element positioned over the editor. The editor’s content is only modified when a final transcript is committed.
• Mirror the insert target. The overlay position and the actual insert must resolve to the same logical location. If your adapter clamps to end-of-content when focus is outside the editor, the overlay must use the same clamped position.
• Stale interim guards. Track the command’s start/end time span and the most recently finalized transcript’s end time. Skip any interim whose time span overlaps a command (the command handler already cleared the preview) or whose end predates a finalized transcript. These guards use transcript message fields (data.start, data.end), not DOM APIs.
• Clear interim before command dispatch. Clear the preview the instant a command is recognized, before any dispatch or action execution. Clearing after dispatch or conditionally on whether the command was handled causes the command phrase to linger.
• Performance. Throttle caret measurements (coalesce bursts via requestAnimationFrame or equivalent). Cache style reads (padding, line-height) instead of reading them on every measurement. Skip measurement when the selection or focus change is outside the editor.

​

Caret coordinate resolution by editor type

• Textarea / input. The caret’s pixel position is not directly accessible. Use a mirror-div technique: a hidden <div> with identical font, padding, and width; render the text up to the caret offset and measure the resulting span’s bounding rect.
• Contenteditable (raw DOM). Create a collapsed Range at the caret point and call getClientRects(). Do not use getBoundingClientRect(); it returns zeros for collapsed ranges. At <br> or wrapping boundaries, getClientRects() returns multiple rects; pick the one with the smallest left (the start of the next line where new text will land).
• Rich editors (Tiptap, Lexical, ProseMirror). Use the editor’s coordinate API directly (e.g. Tiptap’s view.coordsAtPos(), ProseMirror’s coordsAtPos()). These return reliable pixel coordinates without Range API workarounds.
• Native controls (Windows, macOS). Use the platform’s accessibility API or caret-rect query. Coordinate systems differ from web.

​

Contenteditable-specific implementation notes

• Structural trailing <br>. Every contenteditable has one (leftover from the empty editor’s <div><br></div>). It must be excluded from trailing-break counting because it never moves the caret to a new line; every insert goes before it.
• Half-leading compensation. The overlay span inherits the editor’s line-height (e.g. 22.75px) but the caret rect is the font’s em-box (e.g. 17px). The line-box is taller by half-leading on each side, so anchoring at the caret’s top places the overlay’s glyphs below the caret’s. Lift the overlay by (lineHeight - caretRect.height) / 2.
• Empty text node anchoring after trailing <br>. Chrome paints a caret anchored after an element node (<br>) one visual line too high, a well-known contenteditable quirk. Anchor the caret in an empty text node after the <br> instead; the empty node contributes nothing to textContent, so text-offset-based models are unaffected.