feat(framework): browser-aligned touch events (W3C subset) over a pac…

[odex21]

Summary

Adds a small touch event dispatcher (framework/src/touch-events.ts, ~230 lines of logic). Hosts pack one u32 per event; the framework fires touchstart / touchmove / touchend / touchcancel with bubble-only propagation, implicit target capture, and multi-touch via a per-contact identifier. One hit test per contact (at its touchstart); after that, moves/ends walk the capture table, so an active drag costs zero FFI. Zero touch = zero per-frame cost (no events → no FFI, no allocation).

The four event names and the dispatch semantics (implicit capture, bubble order, per-contact identifiers) are borrowed from W3C Touch Events — which is Apple's 2007 iPhone design, later standardized in 2013. So the model here is native-grade, not web-grade: it is the same implicit-capture + parent-chain walk that iOS UITouch and the responder chain use.

This is the raw event layer only. It does not include a gesture layer (tap / long-press / pan / pinch), and this PR does not propose one.

Validated end-to-end on real hardware (two ESP32-class targets with different touch controllers): ESP32-P4 + AXS15260 (640×226) and ESP32-S3 + CST9217 (Waveshare ESP32-S3-Touch-AMOLED-1.75). Drag, tap, long-press, and slider gestures all run on these events in the demo app.

Why not an iOS-shaped API directly?

The dispatch semantics here are the same ones iOS uses (implicit capture + parent-chain walk). This layer does not provide gestures; if a Touchable-style surface is wanted later, it can sit on top of this stream rather than being blocked by it.

Wire format

One u32 per event:

• bits[1:0] phase (start/move/end/cancel)
• bits[11:2] x (logical px, 10-bit, 0..1023)
• bits[21:12] y (logical px, 10-bit, 0..1023)
• bits[27:22] dticks (ms since this contact's previous event, clamp 63)
• bits[31:28] contact identifier (0..15)

10-bit coords fix the 9-bit era's wrap: at x ≥ 512 the old snapshot truncated and wrapped x=639 → 111, teleporting dragged elements on 640-px-class panels. dticks reconstruct per-event timestamps at the frame boundary, so sub-frame down+up pairs both fire in order instead of collapsing into an empty snapshot. Note 10-bit is sized for the current target hardware (logical 640×226 and smaller); a future panel with a logical axis over 1023 would need a wider field.

Semantics (borrowed subset)

• Multi-touch (W3C §5.1): each contact carries an identifier (0..15) stable for its lifetime; contacts are tracked independently. 4 id bits cover every PocketJS touch host — PS Vita front panel (up to 8), web pointer streams (10 on touchscreen laptops); single-point controllers (ESP32-S3's CST9217) report id 0, which is fully backward compatible.
• Implicit target capture (W3C §5.2 / iOS touch.view): after touchstart, all moves/ends for that contact go to its start target regardless of position — dragging survives leaving the element.
• Bubble-only propagation (W3C §5.6, target + bubble phases only): target first, then ancestors innermost→outermost; stopPropagation works; currentTarget tracks the bubbling node.
• Hit tests that fall through to the document still dispatch, with root as target (background taps reach root listeners).
• targetTouches lists only contacts targeting the currentTarget (§5.3).
• No touchmove without movement (integer logical coords).

Deliberately not implemented:

• Spec-surface scope cuts: capture phase, passive listeners, addEventListener, and the TouchEvent constructor.
• Hardware-dependent fields the target controllers cannot report: radiusX/Y, rotationAngle, force. The AXS15260 / CST9217 report contact points with no area or pressure data, so these have no source on ESP32-class panels — a hardware boundary, not a scope choice.

Coordinate sanitization is the host's job

The framework accepts the host's sample stream as authoritative and does not filter coordinates. Sanitization belongs to the host, which owns the electrical context. An earlier draft of this branch carried a framework-side outlier guard; it was removed because it treated the wrong disease (the dragged-element jumps were a timing artifact of the old per-frame snapshot model, fixed properly by the event-stream + dticks design), it kept a single global baseline that would mis-fire on legitimate multi-touch input, and per-host filtering is the correct layering.

What ships

• framework/src/touch-events.ts — decoder, dispatcher, capture/bubble, multi-contact tracking.
• 29 contract tests (tests/touch-events.test.ts) with W3C section references: bubbling order, background-target dispatch, targetTouches per-currentTarget, stopPropagation at target, and 6 multi-touch cases (independent per-contact capture, interleaved moves, end-one-keep-one, per-contact dtick reconstruction).
• Component props onTouchstart / onTouchmove / onTouchend / onTouchcancel (vue-vapor + solid).
• host-web: pointer→touch stream keyed by pointerId (multi-touch); release deferred one frame so same-frame down+up pairs both fire.
• host-sim: 4th frame argument carries the packed stream; devtools replay neutralizes live touch.
• host-vita: touch.rs updated to the 10-bit wire (compile-checked only — no Vita hardware here).
• apps/touch-lab demo.

Known limitations (honest list)

• preventDefault() is a shape-only no-op — the framework has no default behavior to cancel; it only flips defaultPrevented for API compatibility.
• Modifier keys are hard-coded false (altKey/ctrlKey/metaKey/shiftKey) — placeholders for shape only.
• Text nodes claim hits unconditionally (claims_hit returns true for any text run, no pointer-events equivalent): any text painted after an interactive element steals its touches. Apps structure around it (the demo ball became a root-level absolute element). A hit-behavior style bit would address it — claims_hit already carries a TODO-shaped comment.
• z-index only orders siblings; a dragged element cannot be raised above an overlapping subtree from a different branch.
• host-vita updated blind (no device to verify).

Test plan

• bun test tests/touch-events.test.ts — 29/29 green.
• Demo app (separate ESP32 repo): sim-driven regression asserts a dragged ball remains hittable at its new position; real-device serial observation on ESP32-P4 shows stable 28 fps with the touch stream active, and the same gesture page runs on the ESP32-S3 AMOLED target.

[doodlewind]

I'm not fully convinced if aligning browser spec is the best practice here. There are history legacy there. I need some research to build a Touchable API surface that possibly aligns the iOS touch system more.