Skip to content

The five interaction verbs #6

Closed

Description

@omesser

Depends on: #1, #3

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

  1. omesser commented on Aug 29, 2026

    @omesser
    OwnerAuthor

    #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.rs at the Grab branch. A
    held 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::Grab writes position directly
    rather than going through physics.

  2. omesser commented on Aug 29, 2026

    @omesser
    OwnerAuthor

    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

    • Grab, Throw, Poke, and the Shell input path that produces them.
    • The hit-test suspension. A held Grab keeps the mouse wherever the cursor goes, so a drag that outruns the art does not hand the button to the application underneath.
    • Poke plays react. Engine::reacting_ms draws it over whatever the sprite is doing, and a second Poke restarts it.
    • Verbs come from polling 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:

    • Pressing and holding still picks the sprite up, rather than requiring movement first.
    • A release throws only above a threshold speed. Nobody holds a mouse still, and testing for zero movement made every release a fling.

    Left

    Acceptance criteria still open

    • Right-clicking the sprite and clicking the tray icon open the same menu.
    • Each verb produces its expected State or output, for the two verbs that do not exist yet.

    Everything else in the list is met and tested.

  3. omesser commented on Sep 2, 2026

    @omesser
    OwnerAuthor

    Shipped across #49 (Grab, Throw, Poke) and #170 (Menu). Checked against the leftover comment and the acceptance list:

    • Grab, Throw, and Poke produce their State; Grab overrides any State; a fast release Throws and a still one falls; a drag that outruns the art keeps hold.
    • Same-tick verbs resolve deterministically; a proposal during a Grab never yanks the sprite.
    • Poke plays react. Click-through still holds when no verb is in flight.
    • Menu is the right-click: Verb::Menu opens the shared menu::describe popup. The tray icon (Tray and settings #18) will reuse that description; there is no tray yet to click.
    • Summon is the double-click: the verb is accepted and shows nothing. Opening chat is Chat surface #17.
  4. added this to the V1 milestone on Sep 6, 2026
  5. added 3 commits that reference this issue on Oct 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestready-for-agentFully specified, ready for an AFK agent

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions