The converged foundations
These are the “build apps from this” foundations — the decisions where the Honest Cursor handoff, the original design brief, and the Seeing States spec and integration notes all converge. Each one is a load-bearing constraint: an app built on this grammar honors all ten, or it isn’t built on this grammar. Each block states the principle, why it holds, how to apply it, and where it comes from.
Propose, don’t impose — action is a co-signature.
Why.The cursor never acts unilaterally on a Claude-touched target. Every action surfaces as a proposal — a halo, a highlighted cell, a tracked change, a drafted email — and the user accepts by following, edits by diverging, vetoes by jiggling.
How to apply.Render every agent action as a withheld proposal that commits only on an explicit follow/accept gesture; never auto-apply.
HANDOFF §2 A · brief §2 A
Posture, not percentages — calibration shown in shape and motion.
Why.Confidence is legible in how the cursor looks and moves, not in a “73% sure” label. A number invites false precision; a posture is read at a glance.
How to apply.Encode each state in color, halo, arrow, badge, and easing — drop the confidence-percentage tooltip entirely.
HANDOFF §2 C · brief §2 C
The held state is the product — never degrade into plausible text.
Why.The hero is “I don’t know”: a cursor that physically holds still rather than manufacturing a confident-sounding answer. That visible withholding is the whole concept in one gesture.
How to apply.On low confidence, slow the cursor and mark it held (the “?” disc, 70% arrow) — do not fill the gap with generated prose.
HANDOFF §0 · §1
No silent failures — every failure surfaces at least a chip.
Why.Misrecognition, occlusion, stale frames, blur, lost permissions — every failure mode has a detection signal and an obligatory shown response. A failure the user never sees is a failure that quietly commits.
How to apply.Before any action commits, route every failure-table entry through at least a brief chip held for ≥ the min-dwell window (350ms).
SPEC §9
Pointer is sacred — barge-in cancels agent action within the yield window.
Why.While the agent drives (co-pilot, controlling, demo), any user-pointer event is a veto. The agent yields control and must not retry without explicit re-confirmation — the human hand always wins.
How to apply.On user-pointer during agent driving, cancel the in-flight action and fall back to sharing within pointerYieldMs (default 120ms).
SPEC §7
Quiet mode and memory ship together — a cursor that knows everything is surveillant.
Why.A cross-surface cursor with memory is a “second brain” — and a second brain that can’t be told to look away is surveillance. The ability to go quiet is the consent boundary on the ability to remember.
How to apply.Never land a memory/recall feature without its quiet-mode counterpart in the same release; sensitivity labels and focus sessions must dim or revert the cursor.
HANDOFF §10 (§5)
Selector-anchored, not pixel-anchored — markup stays glued to data-* targets.
Why.Screens swap and viewports resize. Markup pinned to pixel coordinates drifts off its element; markup referencing a stable selector stays glued through every layout change.
How to apply.Anchor each overlay to a data-markup-target attribute and recompute its bounding rect on layout and resize, never to fixed coordinates.
HANDOFF §8.3
Keyframes as data, not a bespoke state machine, for scripted flows.
Why.A scripted walkthrough is a flat array of self-contained frames. Keeping it as data — not as hand-rolled control flow — means the player just walks the array, and flows stay inspectable and editable.
How to apply.Model each scripted scenario as an ordered list of frame snapshots with per-frame durations; the player advances the index and renders whatever frame it lands on.
HANDOFF §8.4
Calibration needs a held-rate eval story — “I don’t know” must be precise or it’s noise.
Why.Calibration is a model-side problem. If Claude is poorly calibrated, the held state becomes either noise (held when it shouldn’t be) or a lie (confident when it shouldn’t be). The UI can only be as honest as the held-rate underneath it.
How to apply.Treat held-rate precision as a measured, evaluated quantity — define the eval before relying on the held state as a trust signal.
HANDOFF §10.4 (brief §11.4)
One state machine, one toolbar source, one icon set, one token root.
Why.Naïve integration spawns parallel components — three toolbars, a duplicate reducer, redrawn icons, scattered color declarations. Each fork is a place the grammar can silently diverge.
How to apply.Route all state through a single reduce(), render layout variants from one toolbar source, import one icon family, and declare tokens in one :root.
INTEGRATION §4