@solidrt/core 0.0.66 → 0.0.67

package/agents/performance.md

@@ -151,27 +151,29 @@ Rules, in order of leverage:
    snapshot instead of re-rasterizing. A window shader's output is invisible
    to get_snapshot and every other MCP tool; `bun run sol render` is the only
    way to see it (see @solidrt/cli AGENTS.md).
-8. `flux:wasm` runs a pure interpreter (wasmi, no JIT), so temper browser
-   expectations - but do not write it off for compute. A genuinely numeric
-   kernel (typed-array math, tight inner loops, no host calls inside the
-   loop) compiled from a systems language can come out a real multiple
-   faster than the same loop in interpreted JavaScript, and when profiling
-   shows such a kernel is what the app is spending its time on, that
-   multiple is worth having: measure the JS loop, port the kernel, measure
-   again, keep whichever wins. What wasm does not do is speed up
-   render-path work (rules 1-3 are that leverage), and every host call
-   costs marshalling, so batch at the boundary - one call over a byte
-   buffer, not a call per element. It is also the way to ship one compiled
-   module across every target with no native toolchain, and it pairs with
-   an isolate when a call runs long enough to block.
-9. `flux:ffi` (dlopen of a native library) is a binding tool, not a
-   performance tool. It needs a shared library compiled per platform and
-   architecture and shipped under each target's packing rules (Android
-   loads only what arrives inside the APK as a lib*.so), so reaching for
-   it "to make something fast" buys a build-and-packaging problem on every
-   platform the app targets. Use it when the app must call a native
-   library that already exists and already ships for those targets; for
-   speed, everything above comes first.
+8. `flux:wasm` compiles a module to machine code on devices that allow it
+   (`Flux.capabilities` lists `wasm-native`: desktop, 64-bit Android) and
+   interprets it elsewhere (iOS, 32-bit Android). Both lanes are the fast
+   lane for compute: measured on a desktop, an arm64 tablet and a 32-bit
+   TV, a numeric kernel (typed-array math, tight inner loops, no host calls
+   inside the loop) runs 18x to 960x faster than the same loop in
+   JavaScript when compiled and 4x to 88x when interpreted, float at the low
+   end, integer and SIMD-shaped loops at the high end. So when profiling
+   shows such a kernel is where the app spends its time, port it: measure
+   the JS loop, port the kernel, measure again, keep whichever wins. The
+   boundary is the cost, not the code: a host call out of the module costs
+   3x to 7x a plain JavaScript call, two to three hundred iterations of a
+   tight loop, so batch at the boundary - one call per frame over a byte
+   buffer, never a call per element. What wasm does not do is speed up
+   render-path work (rules 1-3 are that leverage). It is also the way to
+   ship one compiled module across every target with no native toolchain,
+   and it pairs with an isolate when a call runs long enough to block.
+9. There is no native-library route from app code. A shared library is
+   compiled per platform, so it cannot travel in a portable app payload,
+   and Android loads only what arrived inside the APK. Binding one is a
+   custom runtime build: the runtime crates with the library registered
+   beside the built-in modules. For speed, everything above comes first;
+   for a proven library that has a wasm build, rule 8.
 10. Text costs shaping, once per word per style, through a shared word cache;
    line breaking is arithmetic over the shaped words. So re-breaking text
    every frame with prepareText + layoutNextLine (a shape that breathes, an
@@ -188,7 +190,7 @@ Rules, in order of leverage:
 ## Isolates: heavy work off the JS thread
 
 A long synchronous computation (a big parse, a simulation step, a blocking
-`flux:ffi`/`flux:wasm` call) freezes rendering and input for its duration.
+`flux:wasm` call) freezes rendering and input for its duration.
 Move it into an isolate module: a file whose first statement is the
 `"use isolate"` directive runs in a second runtime on its own thread, and
 main calls its exports as async functions.

package/docs/index.md

@@ -91,9 +91,13 @@ ancestor with `position="relative"`.
 ## Input
 
 Pointer, wheel, and key events are props on any element:
-`onPointerDown`, `onPointerMove`, `onPointerUp`, `onPointerEnter`,
-`onPointerLeave`, `onWheel`, `onKeyDown`, `onKeyUp`. Events travel from the
-hit leaf up to the root, and `stopPropagation()` ends the walk. Key events
+`onPointerDown`, `onPointerMove`, `onPointerUp`, `onPointerCancel`,
+`onPointerEnter`, `onPointerLeave`, `onWheel`, `onKeyDown`, `onKeyUp`.
+Events travel from the hit leaf up to the root, and `stopPropagation()`
+ends the walk. A pointer ends with an up or a cancel, never both: the
+cancel is the system taking the touch away (a back swipe, palm rejection),
+delivered along the pressed path with the pointer's last position, so a
+press ends without firing and a drag ends without a fling. Key events
 bubble the same way, starting at the focused node - or at the window root
 when nothing is focused, so `onKeyDown` on the window is where app-global
 shortcuts live.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.66",
+  "version": "0.0.67",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -33,8 +33,8 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.66",
-    "@solidrt/test": "0.0.66"
+    "@solidrt/flux-types": "0.0.67",
+    "@solidrt/test": "0.0.67"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.13",

package/src/core.ts

@@ -8,8 +8,9 @@ let handlers = new Map<number, Map<string, Function>>()
 // Pointer-handler presence mirrored into the render tree, so the runtime can
 // skip building deliveries that would reach nobody (moves over static content
 // are the flood case). Bits match alloy's EventInterest (rendertree/hit.rs);
-// keep the two in sync. Down/up are recorded but the runtime never gates
-// them: focus and gesture side effects hang off them regardless of handlers.
+// keep the two in sync. Down, up and cancel are recorded but the runtime
+// never gates them: focus and gesture side effects hang off them regardless
+// of handlers.
 const MOVE_BIT = 1
 const POINTER_INTEREST: Record<string, number> = {
   onPointerMove: MOVE_BIT,
@@ -18,6 +19,7 @@ const POINTER_INTEREST: Record<string, number> = {
   onPointerEnter: 8,
   onPointerLeave: 16,
   onWheel: 32,
+  onPointerCancel: 64,
 }
 
 let interests = new Map<number, number>()

package/src/double-tap.ts

@@ -48,8 +48,8 @@ export interface TapSequenceOptions {
 }
 
 /** The tap bookkeeping under a double-tap: one first tap at a time,
- * decided by the second down, by travel, by a long hold, by the window
- * timer or by cancel(). */
+ * decided by the second down, by travel, by a long hold, by a cancelled
+ * pointer, by the window timer or by cancel(). */
 export function createTapSequence(options: TapSequenceOptions) {
   let first: { id: number; at: PointerPoint; downAt: number; upAt: number | null } | null = null
   let timer: ReturnType<typeof setTimeout> | null = null
@@ -99,6 +99,9 @@ export function createTapSequence(options: TapSequenceOptions) {
         settle(false)
       }, DOUBLE_TAP_MS)
     },
+    cancelled(e: PointerEvent) {
+      if (first && first.id === e.pointerId) settle(false)
+    },
     cancel: () => settle(false),
   }
 }
@@ -145,6 +148,10 @@ export function createDoubleTap(options: DoubleTapOptions) {
       if (second === e.pointerId) release()
       taps.up(e)
     },
+    onPointerCancel: (e: PointerEvent) => {
+      if (second === e.pointerId) release()
+      taps.cancelled(e)
+    },
   }
   return { handlers, cancel }
 }

package/src/input-pointer.ts

@@ -133,6 +133,7 @@ export interface PointerFeed extends InputDevice {
     onPointerDown(event: PointerEvent): void
     onPointerMove(event: PointerEvent): void
     onPointerUp(event: PointerEvent): void
+    onPointerCancel(event: PointerEvent): void
     onPointerLeave(event: PointerEvent): void
     onWheel(event: WheelEvent): void
   }
@@ -481,6 +482,17 @@ export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed
           opening = null
         }
       },
+      onPointerCancel(e) {
+        if (!downs.has(e.pointerId)) return
+        // The brackets close with no velocity and no swipe: the pointer
+        // ended without its lift.
+        transform.handlers.onPointerCancel(e)
+        released = null
+        lifted(e)
+        hold.cancelled(e)
+        taps.cancelled(e)
+        if (opening && opening.id === e.pointerId) opening = null
+      },
       onPointerLeave() {},
       onWheel(e) {
         if (e.deltaY === 0) return

package/src/long-press.ts

@@ -36,7 +36,8 @@ export interface HoldTimerOptions {
 }
 
 /** The arm / slop / timer machine under a long-press: one pointer at a
- * time, disarmed by travel, by a lift, by a second pointer or by cancel(). */
+ * time, disarmed by travel, by a lift, by a cancelled pointer, by a second
+ * pointer or by cancel(). */
 export function createHoldTimer(options: HoldTimerOptions) {
   let armed: { id: number; at: PointerPoint; mods: { shiftKey: boolean; ctrlKey: boolean; altKey: boolean; metaKey: boolean; button?: number } } | null = null
   let timer: ReturnType<typeof setTimeout> | null = null
@@ -69,6 +70,9 @@ export function createHoldTimer(options: HoldTimerOptions) {
     up(e: PointerEvent) {
       if (armed && armed.id === e.pointerId) disarm()
     },
+    cancelled(e: PointerEvent) {
+      if (armed && armed.id === e.pointerId) disarm()
+    },
     cancel: disarm,
   }
 }
@@ -84,6 +88,10 @@ export interface LongPressOptions {
   onLongPressMove?: (dx: number, dy: number) => void
   /** The lift after a fire. */
   onLongPressEnd?: () => void
+  /** A fired long press ended without its lift: the system cancelled the
+   * pointer (onPointerCancel), or another recognizer took it in the
+   * arena. Fired instead of onLongPressEnd. */
+  onLongPressCancel?: () => void
 }
 
 export function createLongPress(options: LongPressOptions) {
@@ -99,16 +107,26 @@ export function createLongPress(options: LongPressOptions) {
       options.onLongPress?.(at)
     },
   })
-  let cancel = () => {
-    hold.cancel()
+  let release = () => {
     if (fired !== null) {
       arena.release(fired, owner)
       fired = null
       last = null
     }
   }
+  // The press ends without its lift, whatever took the pointer: the arena
+  // (cancel) or the system (onPointerCancel). An unmount releases alone.
+  let cancel = () => {
+    hold.cancel()
+    let won = fired !== null
+    release()
+    if (won) options.onLongPressCancel?.()
+  }
   let owner: ArenaOwner = { cancel }
-  onSettled(() => cancel)
+  onSettled(() => () => {
+    hold.cancel()
+    release()
+  })
 
   let handlers = {
     onPointerDown: (e: PointerEvent) => {
@@ -126,12 +144,16 @@ export function createLongPress(options: LongPressOptions) {
     },
     onPointerUp: (e: PointerEvent) => {
       if (fired === e.pointerId) {
-        cancel()
+        release()
         options.onLongPressEnd?.()
         return
       }
       hold.up(e)
     },
+    onPointerCancel: (e: PointerEvent) => {
+      if (fired === e.pointerId) cancel()
+      else hold.cancelled(e)
+    },
   }
   return { handlers, cancel }
 }

package/src/pan.ts

@@ -35,6 +35,13 @@ export interface PanOptions {
    * finger rested before lifting or moved under FLING_MIN_VELOCITY.
    */
   onPanEnd?: (velocity: Velocity) => void
+  /**
+   * The pan ended without its result: the system cancelled the pointer
+   * (onPointerCancel), or another recognizer took it in the arena. Fired
+   * instead of onPanEnd, only after onPanStart; whoever animates on
+   * settles here, nothing flings.
+   */
+  onPanCancel?: () => void
 }
 
 // The pan recognizer: turns a drag into a movement-delta stream. On a down it
@@ -49,8 +56,9 @@ export interface PanOptions {
 // fling minimum) for momentum. Moves and the up arrive on the frozen down
 // path, so an active pan keeps streaming when the pointer leaves the node
 // or the window.
-// cancel() is the external-cancel hook; it ends an active pan without
-// onPanEnd. Options are read at event time. Single-pointer by design; for
+// cancel() is the external-cancel hook, the arena's; it and a pointer cancel
+// end an active pan with onPanCancel instead of onPanEnd. Options are read
+// at event time. Single-pointer by design; for
 // multi-pointer pinch/rotate compose createTransform instead.
 //
 // Frames: the slop is finger travel, so it is measured in window pixels
@@ -87,7 +95,13 @@ export function createPan(options: PanOptions) {
     armed = null
     origin = null
   }
-  let cancel = reset
+  // The pan ends without its result, whatever took the pointer: the arena
+  // (cancel) or the system (onPointerCancel). An unmount resets alone.
+  let cancel = () => {
+    let started = active != null
+    reset()
+    if (started) options.onPanCancel?.()
+  }
   let owner = { cancel }
 
   // An unmount mid-drag must not leave a resolved claim behind.
@@ -134,6 +148,10 @@ export function createPan(options: PanOptions) {
         reset()
       }
     },
+    onPointerCancel: (e: PointerEvent) => {
+      if (active === e.pointerId) cancel()
+      else if (armed === e.pointerId) reset()
+    },
   }
 
   return { handlers, cancel }

package/src/runtime-modules.d.ts

@@ -26,7 +26,8 @@ declare module "*.frag" {
 
 // Binary asset imports: `import data from "./pic.png" with { type: "binary" }`.
 // The bundler inlines the file's bytes as a Uint8Array (see packages/cli
-// bundler `inlineImport`); feed it straight into createImage/decodeImage.
+// bundler `inlineImport`); feed it straight into createImage/decodeImage, or a
+// `.wasm` into `new Module` from flux:wasm.
 declare module "*.png" {
   const bytes: Uint8Array
   export default bytes
@@ -55,6 +56,10 @@ declare module "*.sol3m" {
   const bytes: Uint8Array
   export default bytes
 }
+declare module "*.wasm" {
+  const bytes: Uint8Array
+  export default bytes
+}
 
 // UI event bus (lattice), provided by the runtime as a builtin module.
 // on/once return an unsubscribe function. Notable events: the routed pointer

package/src/swipe.ts

@@ -67,6 +67,10 @@ export interface SwipeOptions {
   onSwipe?: (direction: SwipeDirection, velocity: Velocity) => void
   /** Every lift of an active swipe, qualified or not. */
   onSwipeEnd?: (velocity: Velocity) => void
+  /** An active swipe ended without its lift: the system cancelled the
+   * pointer (onPointerCancel), or another recognizer took it in the
+   * arena. Fired instead of onSwipe and onSwipeEnd. */
+  onSwipeCancel?: () => void
 }
 
 export function createSwipe(options: SwipeOptions) {
@@ -97,6 +101,11 @@ export function createSwipe(options: SwipeOptions) {
       if (direction) options.onSwipe?.(direction, velocity)
       options.onSwipeEnd?.(velocity)
     },
+    onPanCancel: () => {
+      down = null
+      lift = null
+      options.onSwipeCancel?.()
+    },
   })
 
   let handlers = {
@@ -120,6 +129,13 @@ export function createSwipe(options: SwipeOptions) {
         lift = null
       }
     },
+    onPointerCancel: (e: PointerEvent) => {
+      pan.handlers.onPointerCancel(e)
+      if (down && down.id === e.pointerId) {
+        down = null
+        lift = null
+      }
+    },
   }
   let cancel = () => {
     pan.cancel()

package/src/transform.ts

@@ -59,6 +59,10 @@ export interface TransformOptions {
    * parent-frame pixels per second (velocity.ts; zero after a rest or
    * under the fling minimum). */
   onTransformEnd?: (velocity: Velocity) => void
+  /** The gesture ended without its result: the system cancelled a finger
+   * (onPointerCancel), or another recognizer took the pointers in the
+   * arena. Fired instead of onTransformEnd, only after onTransformStart. */
+  onTransformCancel?: () => void
 }
 
 // The merged transform recognizer: pan + pinch + rotate as ONE gesture over
@@ -116,7 +120,8 @@ export interface TransformOptions {
 // configuration, so the change itself never emits a jump delta. The gesture
 // ends when the last finger lifts. Moves and ups arrive on the frozen down
 // path, so an active transform survives leaving the node or the window.
-// cancel() is the external-cancel hook; it ends an active gesture without
+// cancel() is the external-cancel hook, the arena's; it and a cancelled
+// finger end an active gesture with onTransformCancel instead of
 // onTransformEnd. Options are read at event time.
 //
 // Frames: the slop, the span filter and its rate gates are finger-travel
@@ -206,7 +211,11 @@ export function createTransform(options: TransformOptions) {
     rebase = false
     tracker.reset()
   }
-  let cancel = reset
+  let cancel = () => {
+    let started = active
+    reset()
+    if (started) options.onTransformCancel?.()
+  }
   let owner: ArenaOwner = { cancel }
 
   // The per-frame measure point: runs at the pointerFrame terminator, when
@@ -355,6 +364,17 @@ export function createTransform(options: TransformOptions) {
       pointers.delete(e.pointerId)
       ref = pointers.size > 0 ? measure() : null
     },
+    onPointerCancel: (e: PointerEvent) => {
+      if (!pointers.has(e.pointerId)) return
+      // The system cancels the gesture, not a finger: every platform
+      // cancels all of them together, so the whole gesture ends.
+      if (active) {
+        cancel()
+        return
+      }
+      pointers.delete(e.pointerId)
+      ref = pointers.size > 0 ? measure() : null
+    },
   }
 
   return { handlers, cancel }

package/src/types.d.ts

@@ -278,7 +278,8 @@ export interface TransformProps {
 
 // Window-relative pointer coordinates are reported as clientX/clientY (matching
 // the DOM MouseEvent). pointerType distinguishes mouse from touch; button is the
-// pressed button on down/up (0 = primary); the modifier flags mirror the DOM.
+// pressed button on down/up (0 = primary) and absent on a cancel; the modifier
+// flags mirror the DOM.
 export interface PointerEvent {
   /**
    * When the event happened, in milliseconds. Every input event carries one,
@@ -408,6 +409,15 @@ export interface NodeProps {
 export interface PointerProps extends NodeProps {
   onPointerDown?: (event: PointerEvent) => void
   onPointerUp?: (event: PointerEvent) => void
+  /**
+   * The system took the pointer away: a system gesture (the back swipe,
+   * the notification shade), palm rejection, the window losing the touch.
+   * The last event for that pointer, and no up follows it, so a press
+   * ends without firing and a drag ends without a fling. Routed along the
+   * pressed path like an up, with the pointer's last known position and
+   * no `button`.
+   */
+  onPointerCancel?: (event: PointerEvent) => void
   onPointerMove?: (event: PointerEvent) => void
   onPointerEnter?: (event: PointerEvent) => void
   onPointerLeave?: (event: PointerEvent) => void

package/src/window.ts

@@ -553,6 +553,7 @@ export function attachWindow(nodeId: number) {
   let unsubscribe: () => void = null!
   let unsubDown: () => void = null!
   let unsubUp: () => void = null!
+  let unsubCancel: () => void = null!
   let unsubMove: () => void = null!
   let unsubEnter: () => void = null!
   let unsubLeave: () => void = null!
@@ -664,6 +665,10 @@ export function attachWindow(nodeId: number) {
       bubble(raw, "onPointerUp")
     })
 
+    unsubCancel = on("pointerCancel", (raw: RawPointer) => {
+      bubble(raw, "onPointerCancel")
+    })
+
     unsubMove = on("pointerMove", (raw: RawPointer) => {
       bubble(raw, "onPointerMove")
     })
@@ -761,6 +766,7 @@ export function attachWindow(nodeId: number) {
     if (unsubscribe) unsubscribe()
     if (unsubDown) unsubDown()
     if (unsubUp) unsubUp()
+    if (unsubCancel) unsubCancel()
     if (unsubMove) unsubMove()
     if (unsubEnter) unsubEnter()
     if (unsubLeave) unsubLeave()