Skip to content

docs: holistic touch interaction spec and design (gesture dispatcher + left rail) - #4736

Closed
btli wants to merge 7 commits into
omnigent-ai:mainfrom
btli:pollux/touch-interaction-spec
Closed

docs: holistic touch interaction spec and design (gesture dispatcher + left rail)#4736
btli wants to merge 7 commits into
omnigent-ai:mainfrom
btli:pollux/touch-interaction-spec

Conversation

@btli

@btli btli commented Aug 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Part of #4790

Related issue

Closes #

Summary

ELI5: the app keeps guessing "is this a phone?" by screen width and lets five different pieces of code fight over every finger-drag. The spec says: detect touch directly, give each surface one referee for gestures, and give mobile one navigation rail — built in that order.

Phase 2   Left rail (single mobile nav surface)
             │ consumes
Phase 1   Gesture dispatcher (one owner per surface)
             │ consumes
Phase 0   Input capability + pointer-event foundation

Test Plan

Docs-only change; no code paths affected. Verified all file/line and commit citations against main (ce6dba9c8) and the abandoned branches (feature/mobile-slide-actions-v2, train/polly/session-row-gesture-fix) during a three-vendor codebase investigation. pre-commit hooks ran clean on commit.

Demo

N/A (docs only).

Type of change

  • Bug fix
  • Feature
  • UI / frontend change
  • Refactor / chore
  • Docs
  • Test / CI
  • Breaking change

Test coverage

  • Unit tests added / updated
  • Integration tests added / updated
  • E2E tests added / updated
  • Manual verification completed
  • Existing tests cover this change
  • Not applicable

Coverage notes

Documentation-only PR; no executable behavior to test. Citations were manually verified against the repository at the referenced commits.

@btli
docs: add holistic touch interaction spec and design
3087efa 
Captures the requirements mined from the touch PR train (omnigent-ai#3154/omnigent-ai#3985 swipe
actions, omnigent-ai#4057/omnigent-ai#4060/omnigent-ai#4065 row gestures, omnigent-ai#3589/omnigent-ai#4551 contested strip,
omnigent-ai#1395 mobile shells, omnigent-ai#4723 safe-area) into one specification (TR-1..29)
and a three-phase design: input-capability foundation, unified gesture
dispatcher (resurrecting the abandoned useRowGesture work), and a gated
left-rail mobile navigation phase.

Signed-off-by: Bryan Li <bryan.li@gmail.com>
@github-actions github-actions Bot added the size/L Pull request size: L label Aug 13, 2026
btli added 2 commits August 13, 2026 10:01
@btli
docs: address tribunal round-1 findings on touch spec/design
20c3bdb 
pointerType-based recognition replacing capability gating; normative
threshold, edge-ownership/back-dismissal, gesture-parity, and
touch-action tables; corrected railTabs destination set (Browser kept,
Sessions/Settings as extensions); TableBubbleMenu inventory; hover-
affordance fallback requirement; testable perf gates; RTL logical
directions; corrected Android bridge breakpoint claim; resize
robustness outcomes; dispatcher scoped away from uncontended handles.

Signed-off-by: Bryan Li <bryan.li@gmail.com>
@btli
docs: address tribunal round-2 findings on touch spec/design
f68a076 
Replace invalid geometric disjointness with first-crossed-wins precedence
(HOLD_DRIFT_PX corrected to the train's 20px, provenance fixed); split
Android back vs browser back with History-API layer participation; remove
nonexistent iOS edge dismissal from TR-24; preserve pinch-zoom on rows and
rail edge with second-pointer yield; pin the perf gate to a named device
and scripted benchmark; universal 24px handle hit targets incl. pen; fix
TR-20 cross-reference; invariants dominate tuning ranges.

Signed-off-by: Bryan Li <bryan.li@gmail.com>
@github-actions github-actions Bot added size/XL Pull request size: XL and removed size/L Pull request size: L labels Aug 13, 2026
github-actions Bot pushed a commit to btli/omnigent that referenced this pull request Aug 13, 2026
omnigent-staging
staging: merge PR omnigent-ai#4736 (pollux/touch-interaction-spec @ f…
37f6be8 
…68a076)
github-actions Bot pushed a commit to btli/omnigent that referenced this pull request Aug 13, 2026
omnigent-staging
staging: merge PR omnigent-ai#4736 (pollux/touch-interaction-spec @ f…
461451c 
…68a076)
@btli
docs: address tribunal round-3 findings on touch spec/design
b56a1c6 
- Add SCROLL_ACTIVATION_PX to the TR-11 threshold table; TR-13 and the
  design state machine reference it
- Define the multi-pointer rule for awarded sequences (first pointer
  wins), not just undecided ones
- TR-14: close-path reconciliation — non-popstate dismissals consume
  their layer's history entry so back never no-ops on an orphan
- TR-19: state the 44px drop-target size directly instead of citing
  handle-only TR-7
- Raise HOLD_DRIFT_PX tuning floor to 16 so the wobble defect fixed in
  c21fec9 cannot be re-admitted by a legal retune
- Design doc: propagate round-2 fixes (drop disjoint-region wording,
  correct iOS edge-pan to open-only, drop stray coarse-pointer
  qualifier)

Signed-off-by: Bryan Li <bryan.li@gmail.com>
github-actions Bot pushed a commit to btli/omnigent that referenced this pull request Aug 13, 2026
omnigent-staging
staging: merge PR omnigent-ai#4736 (pollux/touch-interaction-spec @ b…
545ebfa 
…56a1c6)
btli added 3 commits August 13, 2026 17:35
@btli
docs(touch): tribunal round 4 — two-radius model, swipe-to-close rail…
83a8ee5 
…, multi-pointer note consistency

- TR-11: replace single-radius hold eligibility with the train's two-radius
  model (c21fec9): activation radii govern motion-trending surfaces only;
  the HOLD_DRIFT_PX circle governs hold-offering surfaces, so wobble can no
  longer demote a forming hold to scroll and HOLD_DRIFT_PX is reachable.
  Invariant: HOLD_DRIFT_PX > max(SCROLL_ACTIVATION_PX, SWIPE_ACTIVATION_PX).
- TR-14/15/23/24 + design doc: normative swipe-to-close for the open rail —
  on-surface start-directed swipe, all platforms including iOS, dispatcher-
  owned, consumes the layer's history entry; parity via scrim/close/Escape.
- TR-28: table notes now defer to TR-11's undecided/awarded multi-pointer
  split; add touch-action row for the open rail overlay + scrim.

Signed-off-by: Bryan Li <bryan.li@gmail.com>
@btli
docs(touch): tribunal round 5 — circle-exit fallback/tie-break, nativ…
43f4840 
…e pan-y caveat, award wording

- TR-11: horizontal-first circle exit on a surface with no swipe intent
  releases to native scroll (no award); |dx| == |dy| ties resolve
  vertical-first; propagated to the design state machine.
- TR-11: the hold-circle bound covers the dispatcher's own arbitration
  only — restore c21fec9's caveat that a native pan-y pointercancel
  releases to scroll earlier; suppressing native pan is forbidden per
  TR-16(a).
- TR-11 + table: 'nothing awards' corrected to 'no motion-based award'
  (TR-12's time-based arming/menu and post-arm drag proceed inside the
  circle).

Signed-off-by: Bryan Li <bryan.li@gmail.com>
@btli
docs(touch): tribunal round 6 — cite TR-28 (not TR-16(a)) for the nat…
83ae944 
…ive-pan suppression prohibition

Signed-off-by: Bryan Li <bryan.li@gmail.com>
@btli

btli commented Aug 14, 2026

Copy link
Copy Markdown
Contributor Author

Tribunal verdict: CLEAN ✅

Both blocking review engines attested CLEAN on the final artifact 83ae944ef.

Process: 3-vendor adversarial debate on the approach (dispatcher+rail vs dispatcher-only vs rail-only), then 7 adversarial review rounds across two independent engines (Codex / Claude). 35 findings raised → 35 fixed, 0 dismissed (19 → 9 → 8 → 3 → 3 → 1 → 0). No finding ever challenged the architecture; all were spec-precision items.

Highlights hardened through review:

  • Two-radius gesture arbitration model (recovered from the abandoned train's c21fec929), with jointly-consistent thresholds, invariants that dominate tuning ranges, native pan-y caveat, no-swipe fallback and axis tie-break
  • Full edge/back ownership matrix incl. browser-history close-path reconciliation (no orphaned history entries)
  • Normative swipe-to-close for the rail on all platforms incl. iOS
  • Pointer-capability detection replacing 5 drifting viewport-width encodings; all 5 mouse-only resize hooks get pointer-event migration
  • Per-surface touch-action policy, accessibility parity matrix, measurable scroll-perf gate

Advisory seats (kimi/agy/cursor) were unavailable this run; shipped on the blocking pair per doctrine — no advisory escalations outstanding.

Review ledger: .pollux/review-ledger.md (rounds 1–7).

github-actions Bot pushed a commit to btli/omnigent that referenced this pull request Aug 14, 2026
omnigent-staging
staging: merge PR omnigent-ai#4736 (pollux/touch-interaction-spec @ 8…
dab9310 
…3ae944)
@btli
btli marked this pull request as ready for review August 14, 2026 01:16
@github-actions
github-actions Bot requested a review from PattaraS August 14, 2026 01:17
@btli btli mentioned this pull request Aug 14, 2026
Closed
20 tasks
github-actions Bot pushed a commit to btli/omnigent that referenced this pull request Aug 14, 2026
omnigent-staging
staging: merge PR omnigent-ai#4736 (pollux/touch-interaction-spec @ 8…
40f08d0 
…3ae944)
@btli btli mentioned this pull request Aug 14, 2026
Open
github-actions Bot pushed a commit to btli/omnigent that referenced this pull request Aug 14, 2026
omnigent-staging
staging: merge PR omnigent-ai#4736 (pollux/touch-interaction-spec @ 8…
d5e5ee3 
…3ae944)
github-actions Bot pushed a commit to btli/omnigent that referenced this pull request Aug 14, 2026
omnigent-staging
staging: merge PR omnigent-ai#4736 (pollux/touch-interaction-spec @ 8…
78c8604 
…3ae944)
github-actions Bot pushed a commit to btli/omnigent that referenced this pull request Aug 14, 2026
omnigent-staging
staging: merge PR omnigent-ai#4736 (pollux/touch-interaction-spec @ 8…
727b9e9 
…3ae944)
btli pushed a commit to btli/omnigent that referenced this pull request Aug 14, 2026
omnigent-staging
staging: merge PR omnigent-ai#4736 (pollux/touch-interaction-spec @ 8…
db36d71 
…3ae944)
@btli

btli commented Aug 14, 2026

Copy link
Copy Markdown
Contributor Author

Closing per maintainer/author direction: planning/spec documents don't belong in the repository. The spec and design doc (tribunal-reviewed, final at 83ae944ef) now live here: https://gist.github.com/btli/77feb3881658835716fc1e9e87852d04 — tracked from umbrella issue #4790. The six implementation PRs (#4780 #4781 #4782 #4784 #4785 #4786) are unaffected.

@btli btli closed this Aug 14, 2026
@github-actions

github-actions Bot commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Closed. If you want to pick this back up, comment /reopen. GitHub only lets maintainers press the Reopen button, so this command does it for you. It needs the source branch to still exist.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@PattaraS PattaraS Awaiting requested review from PattaraS

Assignees

@PattaraS PattaraS

Labels

size/XL Pull request size: XL waiting-for-review

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@btli @PattaraS