@solidrt/core 0.0.46 → 0.0.47

package/AGENTS.md

@@ -174,6 +174,22 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   app-global shortcut point; `stopPropagation()` ends the walk. `focusable`
   declares focus-navigation candidacy (enumerate via getFocusables()).
 
+- Gesture recognizers, shared by every package: `createPan` (single-pointer
+  drag, axis-aware slop, per-event dx/dy) and `createTransform` (merged
+  pan + pinch + rotate over the whole pointer set, Flutter-Scale style: streams
+  `{ dx, dy, scale, rotation, x, y, pointers }` once per FRAME - positions
+  update per event, but the cross-pointer measure waits for the
+  `pointerFrame` batch terminator, when every pointer is the same age; one
+  finger degrades to a plain pan, and `pointers` is how a consumer gives one-
+  and two-finger translation different meanings - dx/dy alone cannot tell
+  them apart).
+  Spread the returned `.handlers` onto the receiving element. They
+  arbitrate through the exported `arena` (ONE per app): a press claims its
+  pointer provisionally, movement evidence steals and resolves it, the loser's
+  `cancel()` retracts its feedback. Custom recognizers should join the arena
+  rather than track pointers ad hoc, or they will double-handle against
+  scrollers and pressables.
+
 - Reactivity is SolidJS 2.0 (`@solidjs/signals`), NOT Solid 1.x. `createSignal`
   is as you expect, but `createEffect` takes the 2.0 two-function shape: a
   TRACKED compute that reads signals and returns a value, then an UNTRACKED

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -27,7 +27,7 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.46"
+    "@solidrt/flux-types": "0.0.47"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-beta.31",

package/src/arena.ts

@@ -0,0 +1,60 @@
+// The gesture arena: per-pointer ownership arbitration between recognizers.
+// Raw pointer events keep bubbling along the frozen down path regardless; the
+// arena only decides which recognizer's gesture a pointer belongs to. It lives
+// in core beside that routing (window.ts) because arbitration only works with
+// exactly ONE claims map per app: recognizers from every package (components'
+// press and pan, 3d's orbit transform, future runtime-level recognizers) must
+// see each other's claims, and two arenas cannot arbitrate against each other.
+//
+// Two claim strengths mirror how gestures resolve. A press claims its pointer
+// provisionally on the down: it is the presumed winner (innermost-wins falls
+// out of leaf-to-root dispatch, first claim sticks) but a later recognizer
+// with positive evidence of a different gesture (a pan crossing its movement
+// slop) may steal the pointer, cancelling the press. A steal resolves the
+// arena: the pointer is won outright and cannot be stolen again, so e.g. the
+// outer axis of two nested scrollers cannot take a drag the inner one already
+// owns. Plain state on purpose: claims must be visible across recognizers
+// within one synchronous bubble dispatch, before any signal flush.
+
+export type ArenaOwner = {
+  /** Retract the gesture without firing; invoked when the pointer is stolen. */
+  cancel(): void
+}
+
+type Claim = { owner: ArenaOwner; resolved: boolean }
+
+let claims = new Map<number, Claim>()
+
+export let arena = {
+  /**
+   * Provisionally claim an unowned pointer. Returns false (claim refused) when
+   * any recognizer already owns it. The claim is stealable until the owner
+   * releases it or a steal resolves the arena.
+   */
+  claim(pointerId: number, owner: ArenaOwner): boolean {
+    if (claims.has(pointerId)) return false
+    claims.set(pointerId, { owner, resolved: false })
+    return true
+  },
+
+  /**
+   * Take the pointer on positive evidence of a gesture, cancelling the current
+   * provisional owner (if any), and resolve the arena: the resulting claim
+   * cannot be stolen. Returns false when the arena is already resolved, in
+   * which case the caller lost and must stand down.
+   */
+  steal(pointerId: number, owner: ArenaOwner): boolean {
+    let current = claims.get(pointerId)
+    if (current) {
+      if (current.resolved) return false
+      current.owner.cancel()
+    }
+    claims.set(pointerId, { owner, resolved: true })
+    return true
+  },
+
+  /** Release the claim on a pointer, if `owner` still holds it. */
+  release(pointerId: number, owner: ArenaOwner): void {
+    if (claims.get(pointerId)?.owner === owner) claims.delete(pointerId)
+  },
+}

package/src/color.ts

@@ -7,10 +7,13 @@ extend([namesPlugin, mixPlugin])
  * Parses a CSS color string (named, hex, `rgb()`, `hsl()`, ...) into a packed
  * `0xRRGGBBAA` u32: red in the high byte, alpha in the low byte. Alpha is scaled
  * from colord's 0..1 to 0..255. This is the wire format the runtime expects for
- * the `color` property.
+ * the `color` property. Throws on a string that is not a valid CSS color, so a
+ * typo fails on the line that wrote it instead of silently painting black.
  */
 export function parseColor(color: string): number {
-  let { r, g, b, a } = colord(color).toRgb()
+  let c = colord(color)
+  if (!c.isValid()) throw new Error(`Invalid color "${color}"`)
+  let { r, g, b, a } = c.toRgb()
   return (((r & 0xFF) << 24) | ((g & 0xFF) << 16) | ((b & 0xFF) << 8) | ((a * 255) & 0xFF)) >>> 0
 }
 

package/src/gpu.ts

@@ -178,24 +178,22 @@ export {
  */
 export let glsl = String.raw
 
-// captureSnapshot renders a node to a texture and readTexture reads any
-// texture's bytes back. A laid-out node captures its layout box; a `d-*` node
-// captures its painted box - its own w/h when set, else the nearest laid-out
-// ancestor's box, its x/y offset mapped to the texture origin. Re-exported raw
-// (no reactive auto-cleanup wrapper):
-// captureSnapshot resolves asynchronously, by which point the reactive owner is
-// no longer current, so the caller owns the returned id and frees it with
-// destroyTexture (as with any texture created after an await).
+// captureSnapshot renders a node to pixels and readTexture reads any
+// texture's bytes back; both resolve the same { width, height, data } shape.
+// A laid-out node captures its layout box; a `d-*` node captures its painted
+// box - its own w/h when set, else the nearest laid-out ancestor's box, its
+// x/y offset mapped to the texture origin. A capture creates no texture and
+// nothing needs freeing; to display or sample the result, upload it with
+// createTexture.
 //
-// Together they are the one-shot bake path: draw something only the engine can
-// produce (shaped text, an SVG, a themed view), capture it, read the pixels and
-// process them on the CPU - baking a glyph atlas is the worked example. Not a
-// rendering path: a capture rasterizes the subtree offscreen, reads it back to
-// the CPU and re-uploads it, costing a full GPU -> CPU -> GPU round trip and a
-// paint pass of latency every call. Batch captures (one paint pass services
-// many), never run them per frame, and do not use them to feed live screen
-// content into a shader - for that the source has to update in place (another
-// pipeline's target, a camera texture).
+// This is the one-shot bake path: draw something only the engine can produce
+// (shaped text, an SVG, a themed view), capture it and process the pixels on
+// the CPU - baking a glyph atlas is the worked example. Not a rendering path:
+// a capture rasterizes the subtree offscreen and reads it back to the CPU,
+// costing a readback stall and a paint pass of latency every call. Batch
+// captures (one paint pass services many), never run them per frame, and do
+// not use them to feed live screen content into a shader - for that the
+// source has to update in place (another pipeline's target, a camera texture).
 export { captureSnapshot, readTexture } from "flux:gpu"
 
 /**

package/src/index.ts

@@ -20,7 +20,14 @@ export { parseSvg, svg } from "./svg"
 export type { SvgDocument, SvgDraw } from "./svg"
 export { createScroll } from "./scroll"
 export type { Scroll, ScrollAxis, ScrollOffset, ScrollOptions } from "./scroll"
+export { arena } from "./arena"
+export type { ArenaOwner } from "./arena"
+export { createPan } from "./pan"
+export type { PanAxis, PanOptions } from "./pan"
+export { createTransform } from "./transform"
+export type { TransformDelta, TransformOptions } from "./transform"
 export type {
+  Element,
   LayoutProps,
   TransformProps,
   PointerProps,

package/src/pan.ts

@@ -0,0 +1,105 @@
+import { onSettled } from "@solidjs/signals"
+import type { PointerEvent } from "./types"
+import { arena } from "./arena"
+
+// Movement in logical pixels before a pan activates. Below this a drag still
+// reads as a press (tap wiggle); crossing it is the positive evidence that the
+// gesture is a pan, at which point the pan steals the pointer in the arena.
+const PAN_SLOP = 8
+
+export type PanAxis = "vertical" | "horizontal" | "both"
+
+export interface PanOptions {
+  /**
+   * Which movement direction activates the pan. Slop is axis-aware: a
+   * "vertical" pan only activates once vertical travel crosses the threshold,
+   * so nested cross-axis scrollers each take only drags along their own axis.
+   * Default "both" (straight-line distance).
+   */
+  axis?: PanAxis
+  onPanStart?: () => void
+  /** Pointer movement since the previous event; positive dx is rightward, positive dy downward. */
+  onPanMove?: (dx: number, dy: number) => void
+  onPanEnd?: () => void
+}
+
+// The pan recognizer: turns a drag into a movement-delta stream. On a down it
+// arms and starts measuring; when travel from the down point crosses the slop
+// along the enabled axis it activates, stealing the pointer in the arena (a
+// press that provisionally owned it is cancelled - its feedback retracts) and
+// resolving it so no other recognizer can take the drag over. If the arena is
+// already resolved (an inner pan won first) the recognizer disarms and stays
+// out. The slop distance itself is swallowed: deltas stream from the
+// activation point on. 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
+// multi-pointer pinch/rotate compose createTransform instead.
+export function createPan(options: PanOptions) {
+  // Down position while armed; last delivered position while active.
+  let origin: { x: number; y: number } | null = null
+  let active: number | null = null
+  let armed: number | null = null
+
+  let past = (e: PointerEvent) => {
+    if (!origin) return false
+    let dx = Math.abs(e.clientX - origin.x)
+    let dy = Math.abs(e.clientY - origin.y)
+    let axis = options.axis ?? "both"
+    if (axis === "vertical") return dy >= PAN_SLOP
+    if (axis === "horizontal") return dx >= PAN_SLOP
+    return dx * dx + dy * dy >= PAN_SLOP * PAN_SLOP
+  }
+
+  let reset = () => {
+    if (active != null) {
+      arena.release(active, owner)
+      active = null
+    }
+    armed = null
+    origin = null
+  }
+  let cancel = reset
+  let owner = { cancel }
+
+  // An unmount mid-drag must not leave a resolved claim behind.
+  onSettled(() => reset)
+
+  let handlers = {
+    onPointerDown: (e: PointerEvent) => {
+      if (e.button != null && e.button !== 0) return
+      if (armed == null && active == null) {
+        armed = e.pointerId
+        origin = { x: e.clientX, y: e.clientY }
+      }
+    },
+    onPointerMove: (e: PointerEvent) => {
+      if (armed === e.pointerId && past(e)) {
+        if (arena.steal(e.pointerId, owner)) {
+          active = e.pointerId
+          armed = null
+          origin = { x: e.clientX, y: e.clientY }
+          options.onPanStart?.()
+        } else {
+          // The arena is resolved against us; the drag belongs elsewhere.
+          reset()
+        }
+        return
+      }
+      if (active === e.pointerId && origin) {
+        options.onPanMove?.(e.clientX - origin.x, e.clientY - origin.y)
+        origin = { x: e.clientX, y: e.clientY }
+      }
+    },
+    onPointerUp: (e: PointerEvent) => {
+      if (active === e.pointerId) {
+        reset()
+        options.onPanEnd?.()
+      } else if (armed === e.pointerId) {
+        reset()
+      }
+    },
+  }
+
+  return { handlers, cancel }
+}

package/src/renderer.ts

@@ -148,8 +148,11 @@ function setTreeProperty(node: ProxyNode, name: string, value: unknown): void {
   try {
     tree.setProperty(node.id, name, value)
   } catch (e) {
+    // Name-level rejections (the exact prefixes apply_jsx in flux emits) are
+    // warn-and-continue so a stale prop does not kill the app; a bad VALUE for
+    // a known property rethrows, per the throw-in-dev validation policy.
     let message = String(e)
-    if (!message.includes("unknown property") && !message.includes("detached-only")) throw e
+    if (!message.includes("Unknown property") && !message.includes("Detached-only")) throw e
     let key = node.elementType + "." + name
     if (warnedRejectedProps.has(key)) return
     warnedRejectedProps.add(key)

package/src/runtime-modules.d.ts

@@ -49,7 +49,11 @@ declare module "*.ogg" {
 }
 
 // UI event bus (lattice), provided by the runtime as a builtin module.
-// on/once return an unsubscribe function.
+// on/once return an unsubscribe function. Notable events: the routed pointer
+// stream ("pointerMove"/"pointerDown"/... consumed by window.ts),
+// "pointerFrame" (the move-batch terminator: fires after all of a frame's
+// pointer moves have dispatched, every pointer the same age - multi-pointer
+// recognizers measure there), and "render" (the per-frame signal).
 declare module "srt:events" {
   export function on(event: string, callback: (data: any) => void): () => void
   export function once(event: string, callback: (data: any) => void): () => void

package/src/transform.ts

@@ -0,0 +1,300 @@
+import { onSettled } from "@solidjs/signals"
+import { on } from "srt:events"
+import type { PointerEvent } from "./types"
+import { arena, type ArenaOwner } from "./arena"
+
+// Focal travel or span change in logical pixels before the transform
+// activates; the same threshold createPan uses, so the two race fairly.
+const SLOP = 8
+// Per-frame EMA weight for the span that feeds `scale` (~50ms time constant
+// at a 65Hz frame rate - see the zoom-noise note below). The pre-batching
+// weight was 0.15 stepped per event at ~130Hz combined; steps now come once
+// per frame, so the weight compounds: 1 - (1 - 0.15)^2.
+const SPAN_SMOOTH = 0.28
+// Pinch-vs-hold discrimination on the span RATE, an EMA (QUIET_SMOOTH
+// weight) of the smoothed span's per-frame change. Engaging needs both a
+// SLOP excursion and rate >= ENGAGE (~40px/s at 65Hz); an engaged pinch
+// re-locks when rate falls under QUIET (~20px/s). Creep sits near 0.14
+// px/frame, deliberate pinches at 1.5+ - the 2x gap between the two
+// thresholds is the hysteresis that keeps the gate from chattering.
+// All three step-based constants assume a ~65Hz frame rate (the captured
+// tablet); a 120Hz panel halves per-step deltas. If that ever bites,
+// convert the thresholds to px/s with performance.now() read at the
+// pointerFrame terminator.
+const QUIET = 0.3
+const ENGAGE = 0.6
+const QUIET_SMOOTH = 0.19
+
+export type TransformDelta = {
+  /** Focal-point movement since the previous frame, logical px. */
+  dx: number
+  dy: number
+  /** Multiplicative span change since the previous frame (1 = unchanged, >1 = fingers spreading). */
+  scale: number
+  /** Rotation of the pointer pair since the previous frame, radians (0 with a single pointer). */
+  rotation: number
+  /** Current focal point in window coordinates (the clientX/clientY frame) - the zoom-about anchor. */
+  x: number
+  y: number
+  /** How many pointers are down right now. Consumers that give one- and
+   * two-finger translation different meanings (rotate vs pan) route on this;
+   * dx/dy alone cannot tell them apart, both are focal movement. */
+  pointers: number
+}
+
+export interface TransformOptions {
+  onTransformStart?: () => void
+  /** Streams one delta per frame; compose them multiplicatively (scale) / additively (dx, dy, rotation). */
+  onTransformMove?: (t: TransformDelta) => void
+  onTransformEnd?: () => void
+}
+
+// The merged transform recognizer: pan + pinch + rotate as ONE gesture over
+// the set of pointers down on the node (Flutter's Scale model). Splitting
+// them into separate recognizers would make them fight in the arena over the
+// same fingers, so the genuinely-simultaneous case (drag while pinching a
+// photo, one-finger orbit vs two-finger zoom) is a single recognizer that
+// streams focal-point translation, span scale, and pair rotation together;
+// consumers use the components they care about (an orbit camera reads dx/dy
+// and scale, ignores rotation).
+//
+// Pointers arm silently on their down (no arena claim); when focal travel or
+// span change from the armed configuration crosses the slop, that is positive
+// evidence and the recognizer steals EVERY tracked pointer, all or nothing:
+// if any is already resolved elsewhere (an inner pan won that finger) the
+// whole gesture stands down. The slop is swallowed - deltas stream from the
+// activation configuration on. With one finger it degrades to a plain pan
+// (scale 1, rotation 0), so a drag on the node gets arena arbitration too.
+//
+// Measurement is per FRAME, not per event. Move events update pointer
+// positions and arena state as they bubble (claims must stay visible
+// synchronously within the dispatch walk), but the cross-pointer measure -
+// centroid, span, angle - waits for the "pointerFrame" terminator the
+// runtime emits after all of a frame's moves have dispatched. At that point
+// every pointer is the same age, so the per-event scissor is gone by
+// construction (measuring on each event paired one fresh position with the
+// other pointers' frame-stale ones, and the span oscillated around its true
+// value under perfectly smooth motion), and one delta emits per frame - the
+// cadence anything painting consumes anyway. Anchors defer to the same
+// terminator for the same reason: a mid-batch anchor would bake one
+// mixed-age jolt into the first delta after it.
+//
+// Residual span noise survives batching, tuned against a captured tablet
+// stream (sensor dither +-1-3px/event - and a resting pair's span WANDERS
+// 28-76px over seconds, human fingers cannot hold separation, so no
+// threshold alone can stay closed):
+//   - a slop gate: scale is 1 until the span leaves its gesture baseline by
+//     SLOP, so a pan or hold that never really pinches never zooms;
+//   - a low-pass: once engaged, scale comes from an EMA of the span
+//     (SPAN_SMOOTH). Zero-mean dither averages out; deliberate pinching - a
+//     sustained signed drift - passes with ~50ms lag. With the scissor gone
+//     this is belt-and-braces; a retirement candidate after an on-device
+//     A/B against the raw batched span.
+//   - a re-lock: pressed fingertips that HOLD still slowly flatten and roll
+//     toward each other, which the sensor reports as a genuine ~9px/s span
+//     shrink - a held pinch would zoom out forever. Deliberate pinches
+//     measured 100-160px/s, an order of magnitude above creep, so when the
+//     smoothed span rate stays under QUIET the gate re-locks and rebases;
+//     crossing SLOP from the new base re-engages instantly. No amount of
+//     batching removes creep: it is real reported motion.
+// dx/dy have no gate or filter: their noise term is a fraction of a pixel.
+//
+// Set changes rebase: a finger joining (stolen outright - the gesture is
+// already established) or lifting mid-gesture re-anchors the reference
+// 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
+// onTransformEnd. Options are read at event time.
+export function createTransform(options: TransformOptions) {
+  // All tracked pointers, in down order (the first two define the rotation pair).
+  let pointers = new Map<number, { x: number; y: number }>()
+  let active = false
+  // Slop baseline while armed; last delivered configuration while active.
+  let ref: { x: number; y: number; span: number; angle: number } | null = null
+  // The zoom gate and filter (see the zoom-noise note above): scale stays 1
+  // until the SMOOTHED span leaves spanBase by SLOP, then streams smoothed
+  // ratios for the rest of the gesture.
+  let pinch = false
+  let spanBase = 0
+  let smoothSpan = 0
+  // Warm-started at each engage so a fresh pinch cannot instantly re-lock.
+  let spanRate = 0
+  // Motion arrived this frame; measured and emitted at the terminator.
+  let dirty = false
+  // The anchor must be retaken at the terminator (activation and set-change
+  // rebases): mid-batch the pointer map is mixed-age, so anchoring
+  // immediately would bake a jolt into the next delta. A rebase frame
+  // emits nothing.
+  let rebase = false
+
+  let measure = () => {
+    let n = pointers.size
+    let x = 0
+    let y = 0
+    for (let p of pointers.values()) {
+      x += p.x
+      y += p.y
+    }
+    x /= n
+    y /= n
+    let span = 0
+    for (let p of pointers.values()) span += Math.hypot(p.x - x, p.y - y)
+    span /= n
+    let angle = 0
+    if (n >= 2) {
+      let pair = pointers.values()
+      let a = pair.next().value!
+      let b = pair.next().value!
+      angle = Math.atan2(b.y - a.y, b.x - a.x)
+    }
+    return { x, y, span, angle }
+  }
+
+  let reset = () => {
+    if (active) for (let id of pointers.keys()) arena.release(id, owner)
+    pointers.clear()
+    active = false
+    ref = null
+    pinch = false
+    dirty = false
+    rebase = false
+  }
+  let cancel = reset
+  let owner: ArenaOwner = { cancel }
+
+  // The per-frame measure point: runs at the pointerFrame terminator, when
+  // every tracked pointer's position is the same age.
+  let flush = () => {
+    if (!active) return
+    if (rebase) {
+      // Anchor from same-age positions; emits nothing - an activation or
+      // set change must not produce a jump delta. Motion that arrived in
+      // the same batch folds into the anchor.
+      ref = measure()
+      spanBase = ref.span
+      smoothSpan = ref.span
+      rebase = false
+      dirty = false
+      return
+    }
+    if (!dirty || !ref) return
+    dirty = false
+    let m = measure()
+    let prevSpan = smoothSpan
+    smoothSpan += (m.span - smoothSpan) * SPAN_SMOOTH
+    spanRate += (Math.abs(smoothSpan - prevSpan) - spanRate) * QUIET_SMOOTH
+    if (!pinch && Math.abs(smoothSpan - spanBase) >= SLOP) {
+      // A slop excursion at speed is a pinch; at creep speed the base
+      // just follows, so drift can wander forever without engaging.
+      if (spanRate >= ENGAGE) pinch = true
+      else spanBase = smoothSpan
+    }
+    let scale = pinch && prevSpan > 0 && smoothSpan > 0 ? smoothSpan / prevSpan : 1
+    if (pinch && spanRate < QUIET) {
+      // Holding, not pinching (see the re-lock note above).
+      pinch = false
+      spanBase = smoothSpan
+    }
+    let rotation = 0
+    if (pointers.size >= 2) {
+      rotation = m.angle - ref.angle
+      if (rotation > Math.PI) rotation -= 2 * Math.PI
+      else if (rotation < -Math.PI) rotation += 2 * Math.PI
+    }
+    let dx = m.x - ref.x
+    let dy = m.y - ref.y
+    ref = m
+    options.onTransformMove?.({ dx, dy, scale, rotation, x: m.x, y: m.y, pointers: pointers.size })
+  }
+
+  // An unmount mid-gesture must not leave resolved claims behind (or a live
+  // terminator subscription).
+  onSettled(() => {
+    let unsub = on("pointerFrame", flush)
+    return () => {
+      unsub()
+      reset()
+    }
+  })
+
+  let handlers = {
+    onPointerDown: (e: PointerEvent) => {
+      if (e.button != null && e.button !== 0) return
+      if (pointers.has(e.pointerId)) return
+      if (active) {
+        // A finger joining an established gesture belongs to it outright; if
+        // the arena refuses (resolved elsewhere) the finger stays out.
+        if (!arena.steal(e.pointerId, owner)) return
+        pointers.set(e.pointerId, { x: e.clientX, y: e.clientY })
+        rebase = true
+        return
+      }
+      pointers.set(e.pointerId, { x: e.clientX, y: e.clientY })
+      ref = measure()
+    },
+    onPointerMove: (e: PointerEvent) => {
+      let p = pointers.get(e.pointerId)
+      if (!p || !ref) return
+      p.x = e.clientX
+      p.y = e.clientY
+      if (!active) {
+        // Arming runs per event: the slop test tolerates a mixed-age
+        // measure (8px against <=1 frame of staleness), and the arena
+        // steal must happen synchronously inside the dispatch walk.
+        let m = measure()
+        let travel = Math.hypot(m.x - ref.x, m.y - ref.y)
+        if (travel < SLOP && Math.abs(m.span - ref.span) < SLOP) return
+        let taken: number[] = []
+        let refused = false
+        for (let id of pointers.keys()) {
+          if (arena.steal(id, owner)) taken.push(id)
+          else {
+            refused = true
+            break
+          }
+        }
+        if (refused) {
+          // The gesture belongs elsewhere; hand back what we took and disarm.
+          for (let id of taken) arena.release(id, owner)
+          pointers.clear()
+          ref = null
+          return
+        }
+        active = true
+        // A span-driven activation IS a deliberate pinch - engaging the
+        // zoom gate now avoids demanding a second slop-crossing from it.
+        pinch = Math.abs(m.span - ref.span) >= SLOP
+        spanRate = pinch ? 1 : 0
+        rebase = true
+        options.onTransformStart?.()
+        return
+      }
+      dirty = true
+    },
+    onPointerUp: (e: PointerEvent) => {
+      if (!pointers.has(e.pointerId)) return
+      if (active) {
+        arena.release(e.pointerId, owner)
+        pointers.delete(e.pointerId)
+        if (pointers.size === 0) {
+          active = false
+          ref = null
+          pinch = false
+          dirty = false
+          rebase = false
+          options.onTransformEnd?.()
+        } else {
+          rebase = true
+          pinch = pinch && pointers.size >= 2
+          spanRate = 1
+        }
+        return
+      }
+      pointers.delete(e.pointerId)
+      ref = pointers.size > 0 ? measure() : null
+    },
+  }
+
+  return { handlers, cancel }
+}

package/src/types.d.ts

@@ -415,8 +415,10 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
    * transform - it never sizes the element, so give the box its size with
    * layout props. Composed innermost: the transform props still operate in
    * box space, and pointer events on children arrive in design coordinates.
-   * The natural wrapper for parseSvg draws, or any d-* subtree authored in
-   * fixed design units.
+   * The overflow clip and scrollX/scrollY stay box properties too: the clip
+   * rect is the layout box and scroll offsets are box pixels, regardless of
+   * fit scale. The natural wrapper for parseSvg draws, or any d-* subtree
+   * authored in fixed design units.
    */
   viewBox?: [number, number]
   /**
@@ -582,11 +584,13 @@ export interface TextureProps extends PaintProps, PointerProps {
   srcY?: number
   srcW?: number
   srcH?: number
-  // Shader uniform values, when src names a shader texture. Applied at the
-  // next repaint (not synchronously), so a fast-changing signal stays paced
-  // to real frames rather than triggering a GL render pass per write. A
-  // number drives a scalar (`float`/`int`); a flat number array drives the
-  // declared GLSL type: 2/3/4 for `vec2`/`vec3`/`vec4`, 16 (column-major)
-  // for `mat4`.
+  // Shader uniform values, when src names a render target: the same channel
+  // setTargetParams drives, written through it directly - prop and
+  // imperative writes validate and error identically (an unknown name
+  // throws, and set src before params: a write with no src to route to
+  // throws). However often a signal writes, the target renders once per
+  // frame at the raster flush. A number drives a scalar (`float`/`int`); a
+  // flat number array drives the declared GLSL type: 2/3/4 for
+  // `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`.
   params?: Record<string, number | number[]>
 }

package/src/window.ts

@@ -38,26 +38,42 @@ let refreshRate = 60
  * the present count, and `rate` is the current refresh rate in Hz. `tick` is paced
  * by the runtime (one refresh period per present, slow-corrected toward the wall
  * clock) so animations driven off it stay smooth even when swap-return times
- * jitter. For raw, continuous wall-clock time (e.g. measuring code), use
- * performance.now() instead.
+ * jitter. performance.now() and timers report/march on this same paced timeline
+ * (so the whole time surface freezes together under the dev tools' clock
+ * control); for real wall-clock time use Date.now().
  * Returns a cleanup function; also auto-cleans within a reactive scope.
  */
 export function onFrame(fn: (tick: number, frame: number, rate: number) => void) {
   let frameId: number = null!
+  // Cancellation is a flag, not map membership: while a frame runs the whole
+  // callback map is swapped out, so a cleanup() called from another onFrame
+  // callback in the same tick could not reach this entry through the map.
+  let cancelled = false
 
   let extendedFn = (tick: number, frame: number, rate: number) => {
-    fn(tick, frame, rate)
+    if (cancelled) return
+    // Re-register BEFORE running fn, so a throwing callback stays subscribed
+    // (event-listener semantics: the error is reported, the subscription
+    // lives) and a cleanup() from inside fn sees the current frameId. A
+    // pending onFrame callback is a standing request for the next frame.
     frameId = nextFrameId++
     animationFrames.set(frameId, extendedFn)
-    // A pending onFrame callback is a standing request for the next frame.
     requestFrame()
+    try {
+      fn(tick, frame, rate)
+    } catch (err) {
+      console.error("Error in onFrame callback:", err)
+    }
   }
 
   frameId = nextFrameId++
   animationFrames.set(frameId, extendedFn)
   requestFrame()
 
-  let cleanup = () => animationFrames.delete(frameId)
+  let cleanup = () => {
+    cancelled = true
+    animationFrames.delete(frameId)
+  }
   onCleanup(cleanup)
   return cleanup
 }
@@ -253,7 +269,13 @@ export function attachWindow(nodeId: number) {
       animationFrames = new Map()
       for (let fn of frames.values()) fn(t, frame, refreshRate)
     }
-    flush()
+    try {
+      // A throwing effect must not skip renderFrame: the frame still paints
+      // whatever state committed before the throw.
+      flush()
+    } catch (err) {
+      console.error("Error in reactive flush:", err)
+    }
     scanForOrphans(t)
     renderFrame()
   }
@@ -298,7 +320,13 @@ export function attachWindow(nodeId: number) {
         e.localY = localY[i]!
         e.parentX = parentX[i]!
         e.parentY = parentY[i]!
-        getEventHandler(targets[i]!, handler)?.(e)
+        try {
+          getEventHandler(targets[i]!, handler)?.(e)
+        } catch (err) {
+          // One throwing handler must not suppress delivery to the rest of
+          // the path (or the focus/blur step that follows the loop).
+          console.error(`Error in ${handler} handler:`, err)
+        }
         if (stopped) break
       }
     }