The Gap Between Intent and Effect

"You captured the target perfectly. Then you waited. That wait is where everything can go wrong."

The Capture Was Elegant — Here's Its Edge

Track 3 made capturing the target feel solved: read the focused element, the selected text, the range, done. It was clean. But that whole capture happens at the strike — and then Flint has to wait for the brain to think. Inference takes real time, often seconds. The elegant snapshot you took is a photograph of a moment that is now in the past by the time you have an answer to insert. The edge of the capture is exactly here: it told you the truth about intent-time, and says nothing about effect-time.

What Happens During the Wait

The wait is not dead time; it's a window in which the user's world keeps moving. They glance at another window and focus drifts. They click, and the selection collapses. A notification steals focus. They close the tab, or switch apps entirely. The selected text gets edited by something else. Any of these turns your snapshot stale — the app, element, or selection you captured is no longer what's in front of the cursor. And Flint is about to replace text, so acting on a stale snapshot doesn't just insert in the wrong place; it can overwrite the wrong content, irreversibly.

t0  STRIKE   capture { app, pid, element, selection, range }
        |
        |   <-- THE GAP: inference runs (seconds).
        |       focus may drift / selection may change /
        |       window may close / app may switch.
        |
 t1 ANSWER   transformed text is ready
        |
        v   before inserting: is the snapshot STILL true?
            yes -> replace exactly the captured selection
            no  -> do NOT overwrite a target you can't prove; clipboard

The Snapshot Is a Claim, Not a Fact

So the mental shift is this: the snapshot Flint took is not a fact you can act on — it's a claim about the world that was true once and must be re-checked before you trust it again. Treat the captured target as 'what the user meant,' and treat the world at insertion time as a separate thing that may or may not still agree. Insertion's entire job is to compare the two and only act when they match. This is why insertion, not capture, is the riskiest layer: capture reads; insertion writes, across a gap where the truth can expire.

Any operation with a delay between intent and effect must re-verify its target at effect-time. This is the general law behind the whole track. A scheduled send, a deferred write, an async replace — all of them capture an intent and act later, and in the interval the world can change. Binding the action to the target you found at effect-time is the bug; binding it to the target you captured at intent-time and re-proving that target still holds is the fix. Capture the intent, verify at the effect.

Flint's stakes are higher than a plain insert, and that shapes the rest of the track. A dictation app inserts text at a cursor; Flint replaces a selection. If the snapshot is stale, a plain insert lands in the wrong place (annoying, recoverable), but a replace can overwrite whatever is selected now (potentially destructive). That extra danger is why the next lessons demand a stronger proof — matching the range, re-copying to compare — than merely checking which app is frontmost.

Code

The guarded insertion, in one shape·swift

func place(_ result: String, into snapshot: TargetSnapshot) {
    // The snapshot was true at the strike. Is it STILL true now?
    switch prove(snapshot) {
    case .stillValid(let target):
        replaceSelection(with: result, in: target)   // exactly the captured spot
    case .changed, .unprovable:
        copyToClipboardAndNotify(result)             // never overwrite a guess
    }
}

// 'prove' re-reads the world and compares it to the snapshot. Everything
// interesting in this track is how 'prove' is implemented for native vs
// opaque targets, and what it refuses to do when it can't be sure.

Exercise

List everything that can change about the target during the inference wait, and for each, say whether a plain insert-at-cursor tool and a replace-the-selection tool like Flint would be harmed the same way or differently. Then state, in one sentence, why 'the target you find at effect-time' is never a safe substitute for 'the target you captured at intent-time.'

Hint

Focus drift, selection collapse, window close, app switch, and external edits can all occur. An insert-at-cursor tool mostly risks landing in the wrong place (recoverable); a replace tool additionally risks overwriting whatever is now selected (possibly irreversible). The one-sentence law: the effect-time target reflects wherever the world drifted, not what the user meant, so acting on it substitutes coincidence for intent.

The Gap Between Intent and Effect

The Capture Was Elegant — Here's Its Edge

What Happens During the Wait

The Snapshot Is a Claim, Not a Fact

Code

External links

Exercise

Progress

Comments 0