Snapshot the Target First

"By the time you have the words, the cursor may have moved. So remember where it was."

Capture Before the Pause

Insertion's first job happens before a single word is transcribed. The moment the hotkey goes down — before any overlay appears — Firekeeper snapshots the target: the frontmost app's bundle id and process id, the focused Accessibility element, the selected text and range if any, and a classification of the target (browser, editor, terminal, chat, email, password field, unknown). The overlay is non-activating on purpose, so showing it doesn't steal focus from the field you meant to type into.

Why the Snapshot Matters

Between hotkey-down and insertion, seconds pass — STT runs, cleanup runs. In that window, focus can drift: you glance at another window, an app raises a dialog, a notification steals focus. If insertion just typed into "whatever is frontmost now," your dictation could land in the wrong app entirely — worst case, posted into a chat you didn't mean to. The snapshot is the fixed target: insert into the app you were in when you started talking, not wherever focus wandered to.

hotkey down  -> snapshot { app, pid, element, selection, category }
  ... STT ... cleanup ...   (focus may drift here!)
insert       -> is frontmost app still snapshot.app?
                 yes -> insert into the captured target
                 no  -> DON'T type into the wrong app; clipboard + notify

The Wrong-App Guard

The guard is a simple comparison with a strict consequence. At insertion time, check whether the frontmost app still matches the snapshot. If it changed, Firekeeper refuses to paste — it copies the text to the clipboard and notifies you instead. "Insert into the right app or don't insert" is the rule; typing into the wrong app is worse than not typing at all, because you can always paste manually but you can't un-post a message. This one comparison prevents the single most alarming failure a dictation app can have.

Bind the action to the target you captured, not the target you find. Any operation with a delay between intent and effect must remember its target at intent-time and verify it at effect-time. The current state of the world at effect-time is not a safe substitute for the state you actually meant — especially when the effect is irreversible, like posting text into a live app.

Never read a secure text field. Part of the snapshot is detecting whether the focused element is a secure/password field. If it is, Firekeeper reads no context from it and treats it as off-limits. A voice tool that inspected password fields would be a catastrophe; the capture step is where that boundary is first enforced.

Code

The target snapshot, taken at hotkey-down·swift

struct TargetSnapshot {
    let appBundleID: String
    let pid: pid_t
    let focusedElement: AXUIElement?
    let selection: String?
    let category: TargetCategory   // browser / editor / terminal / chat / secure / unknown
    let isSecureField: Bool
}

// At insertion time, verify the world hasn't changed under us.
func canInsert(into snapshot: TargetSnapshot) -> Bool {
    guard let front = NSWorkspace.shared.frontmostApplication else { return false }
    return front.bundleIdentifier == snapshot.appBundleID   // wrong-app guard
}
// If this returns false: clipboard + notify, never paste into the wrong app.

Exercise

Describe an operation in some app that has a gap between when you start it and when it takes effect (a scheduled send, a delayed paste, a background upload). What would go wrong if it used 'the current target' at effect-time instead of 'the target captured at start-time'? Sketch the guard that would prevent it.

Hint

The failure is always: the world changed during the gap, and the effect landed on the wrong thing. The guard is: capture the intended target up front, and at effect-time compare the current target to the captured one — if they differ, refuse and surface a safe fallback rather than acting on the wrong target.

Capture Before the Pause

Why the Snapshot Matters

The Wrong-App Guard

Code

External links

Exercise

Progress

Comments 0