Repository navigation
Description
Why
The verb set is fixed at five because every verb is a tax on every Character that will
ever exist. Fixing it now prevents the required animation set from growing later.
Nothing produces a verb today. The Engine handles Grab, Throw and Poke and has
tests for each, but WorldSnapshot.verbs is empty on every real tick — snapshot.rs
says so outright: "Verbs arrive with Grab (#6) and proposals with the Director (#12).
Nothing produces either yet." So the sprite cannot be touched at all.
Scope
The verbs
| Input | Verb | Result |
|---|---|---|
| press and move | Grab | sprite follows the cursor, State dragged |
| release with velocity | Throw | ballistic arc until it lands |
| click | Poke | reaction animation, optionally dialogue |
| right-click | Menu | the same menu the tray opens |
| double-click | Summon | opens the chat surface |
Verbs enter the Engine on the snapshot. Additions wait for v2.
Delivering them from the Shell
The half that does not exist. The overlay is click-through except where the cursor is
over drawn pixels (#1's alpha hit-test), so the webview receives mouse events only while
the cursor is on the sprite. It forwards them, and the frame loop turns them into verbs
on the snapshot.
Velocity for a Throw is measured here. Verb::Throw carries it, and the Engine only
flies it.
A held Grab has to suspend the hit-test. main.rs sets ignore = !over_sprite every
tick, unconditionally. Move the cursor faster than the sprite follows, the cursor leaves
the drawn pixels, click-through returns mid-gesture, the webview stops receiving
mousemove, and the drag dies in the user's hand. While a Grab is held the overlay keeps
the mouse wherever the cursor goes; releasing restores the hit-test.
A held sprite may be dragged over reserved screen strips — the Dock, the menu bar. That
was decided in #39 and is recorded at the Grab branch in engine.rs: the cursor may go
there, so the sprite may too, and letting go settles it because a release becomes a fall.
Poke's reaction
react is one of the eight required Animations and ships in the placeholder Character,
and nothing selects it: animation_for maps States, and reacting is an event rather than
a State. Today Verb::Poke only wakes a sleeping sprite and resets the idle timer.
Playing an event Animation is #8's machinery. Whichever of the two lands second wires
Poke to react.
The Menu
One menu definition, two entry points: right-clicking the sprite opens exactly what the
tray icon opens, so the two cannot drift apart. #18 owns that definition.
Characters ▸
Instances ▸
Director [on]
Hide rules ▸
────────────────────────
Memory…
Settings…
Quit ai-buddy
This sequences the Menu behind #18, which waits on #12 and #13. The other four verbs do
not wait. Grab, Throw and Poke need none of it, and are the ones that make the sprite
feel touchable — ship them first rather than holding the whole verb set behind a settings
window.
Summon
Opens the chat surface, which is #17. Until that exists the verb is accepted and does
nothing visible.
Acceptance criteria
- Each verb produces its expected State or output.
- Grab overrides any State.
- Releasing a Grab with velocity enters Throw; without velocity, it falls.
- A drag that outruns the sprite keeps hold of it, and releasing anywhere — including
over the Dock — drops it onto the usable floor. - Verbs arriving in the same tick resolve deterministically.
- A Director proposal arriving during a Grab is deferred or dropped, never yanking the
sprite. - Poke plays
react. - Right-clicking the sprite and clicking the tray icon open the same menu.
- Click-through still works when no verb is in flight: clicks off the sprite pass
underneath, as they do today.
Tests
Engine tests per verb, plus the same-tick collision case and the proposal-during-Grab
case. The mapping from a mouse event to a verb is arithmetic and is unit tested, per
docs/SPEC.md: "Arithmetic is never exempt, wherever it lives."
The hit-test suspension needs a real window server and a real drag, so it goes on the
manual checklist in README.md rather than into cargo test. Synthesising the drag in
scripts/verify-overlay.sh would mean posting CGEvents, which needs Accessibility —
a permission v1 does not ask for.
Spec: docs/SPEC.md · migrated from docs/issues/0006-interaction-verbs.md
Activity
omesser commentedon Aug 29, 2026
#39 left one decision for whoever implements Grab, since the geometry does not
imply it: may a Grabbed sprite be held below the usable floor?
Decided yes, and recorded in
crates/core/src/engine.rsat the Grab branch. Aheld sprite goes where the cursor goes. The cursor can move over the Dock, and
stopping the sprite short of a strip the user can plainly see it over would
fight the hand rather than help it.
Letting go settles it somewhere legal on its own — a release becomes a fall, and
a fall ends on the usable floor like any other. So a reserved strip is somewhere
the sprite can be put and not somewhere it can come to rest, which needs no
clamping code in the Grab path.
Worth knowing because it is the one place
Verb::Grabwrites position directlyrather than going through physics.
Catch the sprite in gaps between displays
Catch the sprite in gaps between displays
omesser commentedon Aug 29, 2026
Three of the five verbs landed in #49. This records what is left, so the issue body no longer reads as though none of it exists.
Done
react.Engine::reacting_msdraws it over whatever the sprite is doing, and a second Poke restarts it.CGEventSourceButtonState, not from webview events. A state query rather than an event tap, so it needs no Accessibility grant. Routing through the webview would have failed exactly where this issue warned: the overlay is click-through wherever the sprite is not drawn.Two behaviours went in beyond the table in this issue, both one constant each and easy to remove:
Left
Verbvariant was added for it: nothing produces or consumes one yet.Acceptance criteria still open
Everything else in the list is met and tested.
omesser commentedon Sep 2, 2026
Shipped across #49 (Grab, Throw, Poke) and #170 (Menu). Checked against the leftover comment and the acceptance list:
react. Click-through still holds when no verb is in flight.Verb::Menuopens the sharedmenu::describepopup. The tray icon (Tray and settings #18) will reuse that description; there is no tray yet to click.fix(settings): Implement all soft requirements from Architect review
fix(#1391): Include painted in RegionParams; latch QM handoff across …
fix(#1391): Include painted in RegionParams; latch QM handoff across …
fix(#1391): Include painted in RegionParams; latch QM handoff across …