@solidrt/core 0.0.56 → 0.0.58

package/AGENTS.md

@@ -132,6 +132,14 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   window (message, stack, a Reset button that retries the failed
   computations) and logs `Uncaught error`. `<Errored>` gives a subtree its
   own in-place fallback.
+  An `onFrame` callback is its own boundary, event-listener style: a throw
+  is caught and logged (`Error in onFrame callback`, repeating every
+  frame), the subscription stays, and THE REST OF THAT CALLBACK IS
+  ABANDONED - what it wrote before the throw lands, what came after never
+  does, frame after frame while the app keeps presenting. A partial frame
+  is therefore a live possibility: every sprite drawn after the throwing
+  line simply stops appearing, which reads on screen as a logic bug, not a
+  crash. Check the logs before reasoning about a rendering symptom.
 
 - Two kinds of element:
   - Containers - `<window>`, `<view>`. Do layout + transform + pointer events.
@@ -312,6 +320,97 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   rather than track pointers ad hoc, or they will double-handle against
   scrollers and pressables.
 
+- The input map (input-map.ts) is how anything drives a control:
+  ARCHITECTURE.md's rule is that a control (a camera, a character
+  controller) consumes a device-free abstraction and never handles events
+  or reads a device itself, and the map is the named, typed layer between
+  devices and consumers - Godot's InputMap and Unity's action maps in
+  reactive form. `createInputMap({ look: "vec2", move: "vec2", zoom:
+  "axis", jump: "button" })` declares the app's actions once; devices bind
+  to them by name (`input.bind("look", pointer.drag, gamepad(0).rightStick)`,
+  `input.bind("move", keyboard.wasd, gamepad(0).leftStick)`); consumers
+  read the action, never the device. Every axis/vec2 action carries TWO
+  channels: the RATE (the sum of every bound source's current value,
+  clamped - an axis to -1..1, a vec2 to unit length - reactive, sampled per
+  frame by the consumer and integrated over dt at its own speed) and the
+  DELTAS (immediate amounts a gesture produced, in device-free units: a
+  drag in element heights, a wheel notch or a pinch in octaves, a twist in
+  turns, with begin/end brackets around a finger's gesture and the focal
+  point as a fraction of the element). Values use the screen convention
+  throughout: x right, y down, a stick pushed up reads y = -1, and a
+  consumer that means "forward" by a vec2 reads -y. A button source may
+  bind to an axis action (1 while pressed); a vec2 source on an axis
+  action throws.
+  Devices are the nouns: `keyboard.key("Space")`, `keyboard.axis("KeyQ",
+  "KeyE")`, `keyboard.vec2({ up, down, left, right })`, `keyboard.wasd`,
+  `keyboard.arrows`, a spec with modifiers ahead of the key
+  ("Shift+Tab", "Ctrl+KeyS": the most specific spec in a source wins a
+  down, an up releases on the bare key) (key events reach them through
+  `input.handlers`, spread on `<window>` for app-global keys or on the
+  leaf that should hold focus for them - keys bubble to the window, so a
+  TextInput's consumed keys never arrive); `gamepad(slot)`, `gamepad()`
+  for every pad, or `gamepad.next()` for the next unclaimed pad to press
+  any button (split screen seats players in pick-up order; its `slot`
+  resolves reactively and frees when the creating scope is disposed),
+  with `leftStick`, `rightStick`, `dpad`, `triggers` (right minus left),
+  `shoulders`, `axis(name)`, `button(name)`, reactive over gamepads() so a
+  stick wakes a control's frame loop; `createPointerFeed()` for the one
+  device that is not global - a pointer event belongs to the element
+  under it, so the feed is per element: spread `feed.handlers` on the
+  leaf (`<Scene pointer>`, `<View3d pointer>`, `<SpriteLayer pointer>` and
+  `<View2d pointer>` take a feed and spread it on their built-in leaf) and
+  bind its gestures `drag` (one pointer), `pan` (two), `pinch`, `twist`,
+  `wheel` and `mouseDelta` (raw motion while pointerLocked()). One
+  merged recognizer serves them, so they arbitrate in the arena as one.
+  Each gesture takes a chord in the key-spec grammar: `pointer.drag("Ctrl")`
+  fires only when the event that opens the gesture carries Ctrl, and then
+  instead of the bare `drag` (the most specific bound chord wins, as a
+  key spec does), held for the whole gesture - so plain drag on `rotate`
+  and `drag("Ctrl")` on `pan` is one binding each, the every-viewport
+  default. A bracketed spec may end in its button (`drag("Right")`,
+  `drag("Shift+Middle")`; bare means Left), a discriminator rather than
+  a modifier: a right drag feeds only Right specs. Touch carries no
+  modifiers or buttons: a chord is the desktop path, the bare binding
+  stays for fingers. A
+  detached d-* leaf has no layout box: give the feed `{ layout }` or it
+  throws at the first press. `invert(source)` and `scale(source, k)` are
+  the two processors: keys and sticks move the CAMERA where a drag moves
+  the content, so a preset binds arrows or a stick to `pan`/`rotate`
+  through invert() and the action keeps one meaning.
+  Consumers with the axes contract (`createAxes({ rotate: "vec2", zoom:
+  "axis" }, { onNudge, onBegin, onEnd })`, what every camera control
+  exposes as `.axes`) are connected by name with `input.drive(control.axes,
+  names?)`: each axis takes the action of the same name, or the one
+  `names` gives it (null skips one), both channels; the camera components
+  take the map as their `input` prop and do exactly that. Injection by
+  name is the wire for scripts, debug commands, peers and replays:
+  `input.set("move", [0, -1])` holds a rate, `press`/`release` a button,
+  `nudge`/`begin`/`end` feed the delta channel. `bindings()` lists what is
+  bound (source labels are display strings), `unbind` removes one, and a
+  preset (`orbitBindings`, `firstPersonBindings` in @solidrt/3d,
+  `camera2dBindings` in @solidrt/2d) is a plain bindings list the app
+  applies and edits - nothing binds unless the app says so (the one
+  built-in default is the UI set inside components' createFocusNav, the
+  platform's own layer). The map is an instance: two pads on two views is
+  two maps. Contexts are a switch per action: `input.disable("move",
+  "jump")` / `enable(...)` (a set is a list of names, so
+  `disable(...Object.keys(gameActions))` when a menu opens); a disabled
+  action reads neutral, drops its deltas and closes the gesture it had
+  open, while its sources keep their state so a key still held when it
+  comes back reads at once; `enabled(name)` is reactive. Create maps and
+  feeds in an owned scope (a component body): onPress/onRelease run
+  effects under it and the feed's recognizer registers its cleanup there. The vocabulary the
+  controls share, one kind and unit per word: `pan` vec2 (view heights),
+  `zoom` axis (octaves, positive in), `rotate` vec2 (orbit turns), `roll`
+  axis (turns about the view axis), `look` vec2 (turns), `move` vec2
+  ([right, forward], forward = -y), `rise` axis (up). The runtime-free
+  half (`createInputMap`, `createAxes`, `keyboard`, the processors) is
+  importable as `@solidrt/core/input` for headless checks;
+  checks/input-map-check.ts runs it on the bare flux binary, and
+  checks/input-gamepad-check.ts drives the gamepad device and the join
+  order over a signal of pad snapshots (input-gamepad-device.ts is
+  runtime-free; input-gamepad.ts hands it gamepads()).
+
 - 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
@@ -347,7 +446,11 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   TypeScript with no @solidrt imports, with the JSX reading it and the
   per-frame hook doing one state step plus a handful of property writes.
   That shape runs under bun with no window (tests, audits, replaying a whole
-  session in seconds) and it is what keeps per-frame work cheap.
+  session in seconds) and it is what keeps per-frame work cheap. For a game
+  it is the tuning loop itself: minutes of play run headless in a fraction
+  of a second, so a difficulty curve or a spawn table is tuned against
+  scripted policies in seconds instead of by playing, and the design bugs
+  that only show at scale surface there first.
 - Animation is target-shaped first: declare `transition` on the element and
   write targets, and the runtime animates natively with no per-frame JS.
   Enter and exit are per-property entries on that same spec: `from` is the
@@ -359,7 +462,11 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   descendants declare `from`/`exit`. An enter plays once per mount; to
   replay it, remount the subtree (`<Show when={epoch()} keyed>` around it,
   then bump `epoch`). See examples/stagger.tsx.
-  Reach for per-frame work only for genuinely procedural motion:
+  Per-frame work is for genuinely procedural motion, and a game or a
+  simulation is that in full: its natural shape is ONE `onFrame` doing one
+  sim step and N property (or sprite) writes, which is not a smell but the
+  budget the runtime is built for - agents/performance.md rule 4 has the
+  rules, @solidrt/2d's notes the measured write costs at scale.
   `onFrame((tick, frame, rate) => {})` is the native hook (runtime-paced,
   returns a cleanup, auto-cleaned inside an owned scope; from an effect's
   apply, return it so the loop runs only while the condition holds); `rate` is the

package/examples/README.md

@@ -25,6 +25,9 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 ## Pointer input
 - `pointer-local-coords.tsx` - the three pointer coordinate frames (`clientX` window, `localX` the handling node's own frame, `parentX` its path-parent's frame - where the node's x/y live) and the transform-proof drag idiom: grab offset from `localX` at down, place with `parentX - offset` on moves. Exact inside rotated/scaled ancestors and when the pointer leaves the node mid-drag.
 
+## Gamepads
+- `gamepad.tsx` - the pad test bed: every connected pad's raw `gamepads()` snapshot (slots, buttons, axes) and two players seated by `gamepad.next()` - press any button on a pad to join player 1, another pad joins player 2 - each an input map (`move` on the left stick and dpad, `zoom` on the triggers, `jump` on south) printing its values live and walking a marker with `move`. Nothing moves until a pad does.
+
 ## Performance
 - `snapshot-texture.tsx` - `snapshotTexture(ref)`: a `repaintBoundary="snapshot"` view's rasterized pixels as a live texture id; a shader texture samples the panel and a sibling `<texture>` shows the warped copy. The boundary re-rasterizes only when its content changes.
 - `repaint-boundary.tsx` - `repaintBoundary` on a `<view>` to keep static content from rebuilding while a neighbor animates: `{true}` retains the recorded draw list, `"snapshot"` also retains the rasterized pixels as a GPU texture (for raster-expensive, screen-aligned, static subtrees). `"snapshot-no-aa"` rasterizes without anti-aliasing: cheaper, fine for text and axis-aligned rects, hard-edged on vector content.

package/examples/gamepad.tsx

@@ -0,0 +1,94 @@
+// Gamepad test bed: every connected pad's raw snapshot (gamepads()) at the
+// top, and two players seated by gamepad.next() below - press any button
+// on a pad and it joins player 1, another pad joins player 2. Each player
+// is an input map (`move` vec2 on the left stick and the dpad, `zoom` axis
+// on the triggers, `jump` button on south) whose values print live, plus
+// a marker that walks with `move`, so what a pad does is on screen.
+// Nothing moves until a pad does.
+import { createInputMap, createSignal, gamepad, gamepads, onFrame, render, untrack, windowSize, For } from "@solidrt/core"
+import type { Vec2 } from "@solidrt/core"
+
+const PLAYERS = 2
+// Marker travel at full stick deflection, pixels per second.
+const SPEED = 300
+const MARKER = 28
+const COLORS = ["#ffcc4d", "#66e6ff"]
+
+let fmt = (v: number) => (v < 0 ? "" : " ") + v.toFixed(2)
+let clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))
+
+function App() {
+  let players = Array.from({ length: PLAYERS }, (_, i) => {
+    let pad = gamepad.next()
+    let input = createInputMap({ move: "vec2", zoom: "axis", jump: "button" })
+    input.bind("move", pad.leftStick, pad.dpad)
+    input.bind("zoom", pad.triggers)
+    input.bind("jump", pad.button("south"))
+    // The marker: plain numbers stepped per frame, a signal to redraw.
+    let x = 80 + i * 120
+    let y = 260
+    let [pos, setPos] = createSignal<Vec2>([x, y])
+    let [jumps, setJumps] = createSignal(0)
+    input.onPress("jump", () => setJumps(n => n + 1))
+    let step = (dt: number) => {
+      let [mx, my] = untrack(() => input.value("move"))
+      if (mx === 0 && my === 0) return
+      let size = untrack(windowSize)
+      x = clamp(x + mx * SPEED * dt, 0, Math.max(0, size.width - MARKER))
+      y = clamp(y + my * SPEED * dt, 0, Math.max(0, size.height - MARKER))
+      setPos([x, y])
+    }
+    return { pad, input, pos, jumps, step }
+  })
+  let last: number | null = null
+  onFrame(tick => {
+    let dt = last === null ? 0 : (tick - last) / 1000
+    last = tick
+    for (let p of players) p.step(dt)
+  })
+  let padLine = (slot: number, pad: { name: string; buttons: string[]; axes: Record<string, number> } | null) => {
+    if (!pad) return `slot ${slot}: empty`
+    let a = pad.axes
+    return `slot ${slot}: ${pad.name} - buttons [${pad.buttons.join(" ")}] left${fmt(a.leftX ?? 0)},${fmt(a.leftY ?? 0)} right${fmt(a.rightX ?? 0)},${fmt(a.rightY ?? 0)} triggers${fmt(a.leftTrigger ?? 0)},${fmt(a.rightTrigger ?? 0)}`
+  }
+  return (
+    <window>
+      <d-rect color="#181820" />
+      <view flexDirection="column" gap={10} padding={24}>
+        <text color="#eef4ff" fontSize={22} fontWeight={700}>
+          Gamepads
+        </text>
+        <text color="#a9bcd6" fontSize={14}>
+          press any button on a pad to join as player 1, another pad for player 2 - left stick or dpad walks the marker, triggers read zoom, south counts jumps
+        </text>
+        <view flexDirection="column" gap={2}>
+          <text color="#a9bcd6" fontSize={14}>
+            connected: {String(gamepads().filter(p => p !== null).length)}
+          </text>
+          <For each={gamepads()} keyed={false}>
+            {(pad, i) => (
+              <text color="#eef4ff" fontSize={14}>
+                {padLine(i, pad())}
+              </text>
+            )}
+          </For>
+        </view>
+        <For each={players}>
+          {(p, i) => (
+            <view flexDirection="column" gap={2}>
+              <text color={COLORS[i()]} fontSize={16} fontWeight={700}>
+                player {String(i() + 1)}: {p.pad.slot === undefined ? "press any button on a pad to join" : `pad ${p.pad.slot}`}
+              </text>
+              <text color="#eef4ff" fontSize={14}>
+                move{fmt(p.input.value("move")[0])},{fmt(p.input.value("move")[1])} zoom{fmt(p.input.value("zoom"))} jump {p.input.pressed("jump") ? "down" : "up"} (x{String(p.jumps())})
+              </text>
+            </view>
+          )}
+        </For>
+      </view>
+      <For each={players}>{(p, i) => <d-rect x={p.pos()[0]} y={p.pos()[1]} w={MARKER} h={MARKER} radius={6} color={COLORS[i()]} />}</For>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -13,6 +13,7 @@
     "./data": "./src/data.ts",
     "./gpu": "./src/gpu.ts",
     "./image": "./src/image.ts",
+    "./input": "./src/input.ts",
     "./audio": "./src/audio.ts",
     "./microphone": "./src/microphone.ts",
     "./speech-recognition": "./src/speech-recognition.ts",
@@ -30,7 +31,7 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.56"
+    "@solidrt/flux-types": "0.0.58"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.6",

package/src/index.ts

@@ -28,6 +28,16 @@ export { createPan } from "./pan"
 export type { PanAxis, PanOptions } from "./pan"
 export { createTransform } from "./transform"
 export type { TransformDelta, TransformOptions } from "./transform"
+export { createInputMap, invert, scale } from "./input-map"
+export type { ActionKind, ActionValue, ActionsDecl, Binding, DeltaSink, GestureListener, InputMap, InputSource } from "./input-map"
+export { createAxes } from "./input-axes"
+export type { Axes, AxesDecl, AxesHooks, AxisKind, AxisValue, Vec2 } from "./input-axes"
+export { keyboard } from "./input-keyboard"
+export type { KeyboardDevice, KeyboardVec2Keys } from "./input-keyboard"
+export { gamepad } from "./input-gamepad"
+export type { GamepadDevice } from "./input-gamepad"
+export { createPointerFeed } from "./input-pointer"
+export type { PointerFeed, PointerFeedOptions, PointerSource } from "./input-pointer"
 export type {
   Element,
   LayoutProps,
@@ -91,6 +101,8 @@ export {
   createRoot,
   createStore,
   reconcile,
+  merge,
+  omit,
   mapArray,
   repeat,
   untrack,

package/src/input-axes.ts

@@ -0,0 +1,180 @@
+// The control side of the input abstraction (ARCHITECTURE.md: controls
+// through an abstraction, never direct event handling). A control - a
+// camera controller, a character controller - declares the axes it
+// consumes and receives input only through them, in device-free units:
+//
+// - rates: -1..1 values sampled at update time (a held key, a deflected
+//   stick, a value an app set), which the control integrates over dt at
+//   its own speeds. Sources are added, never set: several may feed one
+//   axis (keys and a stick), and the control sums and clamps them, so
+//   removing one never has to know what the others hold.
+// - nudges: immediate deltas (a drag, a wheel notch, a pinch) in the
+//   vocabulary's units - view heights of travel, octaves of zoom, turns -
+//   applied at once, with the focal point (a fraction of the element)
+//   when the gesture has one. begin/end bracket a gesture, so a control
+//   can tell a finger's tracking (apply exactly) from an impulse (a wheel
+//   notch, unbracketed: ease it), stop a glide when a finger lands, and
+//   fling when it lifts.
+//
+// The values use the screen convention throughout: x right, y down, the
+// way pointer deltas and the web Gamepad API report (a stick pushed up
+// reads y = -1). A control that means "forward" by a vec2 reads -y.
+//
+// `active()` is the frame-loop gate: reactive, true while any rate source
+// reads non-zero, so a control's loop runs only while something drives it.
+// A rate source must therefore read reactive state (a signal, gamepads());
+// a source over plain variables never wakes the loop - the caller runs
+// update(dt) itself then.
+//
+// An input map drives an Axes object by action name (InputMap.drive); an
+// app can also add its own sources and nudges directly.
+
+import { createMemo, createSignal, untrack } from "@solidjs/signals"
+
+export type AxisKind = "axis" | "vec2"
+export type Vec2 = [number, number]
+export type AxisValue<K extends AxisKind> = K extends "axis" ? number : Vec2
+
+export type AxesDecl = Record<string, AxisKind>
+
+export interface AxesHooks<A extends AxesDecl> {
+  /** An immediate delta on `name`: view heights for a vec2, the axis's
+   * unit (octaves, turns) for an axis; `focal` in 0..1 of the element
+   * when the gesture has one (a pinch, a wheel). */
+  onNudge?: <N extends keyof A & string>(name: N, delta: AxisValue<A[N]>, focal: Vec2 | undefined) => void
+  /** A gesture on `name` started (a finger landed) / ended (lifted). */
+  onBegin?: (name: keyof A & string) => void
+  onEnd?: (name: keyof A & string) => void
+}
+
+export interface Axes<A extends AxesDecl> {
+  /** The declared axes, name to kind - what a map's drive() reads. */
+  readonly kinds: A
+  /** Add a rate source (reactive read, -1..1 per component); returns the
+   * remover. Several sources sum, then clamp (an axis to -1..1, a vec2 to
+   * unit length). */
+  add<N extends keyof A & string>(name: N, rate: () => AxisValue<A[N]>): () => void
+  /** The combined rate of `name` now (reactive read). */
+  rate<N extends keyof A & string>(name: N): AxisValue<A[N]>
+  /** Reactive: whether any rate reads non-zero - the frame-loop gate. */
+  active(): boolean
+  /** Apply an immediate delta (see AxesHooks.onNudge). */
+  nudge<N extends keyof A & string>(name: N, delta: AxisValue<A[N]>, focal?: Vec2): void
+  /** Bracket a gesture on `name`; nested begins count. */
+  begin(name: keyof A & string): void
+  end(name: keyof A & string): void
+  /** Whether a gesture on `name` is open (between begin and end). */
+  inGesture(name: keyof A & string): boolean
+}
+
+let clampNum = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))
+
+/** Sum rate values of one kind and clamp: an axis to -1..1, a vec2 to unit length. */
+export function combineRates(kind: AxisKind, values: (number | Vec2)[]): number | Vec2 {
+  if (kind === "axis") {
+    let sum = 0
+    for (let v of values) sum += v as number
+    return clampNum(sum, -1, 1)
+  }
+  let x = 0
+  let y = 0
+  for (let v of values) {
+    x += (v as Vec2)[0]
+    y += (v as Vec2)[1]
+  }
+  let len = Math.hypot(x, y)
+  return len > 1 ? [x / len, y / len] : [x, y]
+}
+
+function checkValue(what: string, kind: AxisKind, v: unknown): void {
+  if (kind === "axis") {
+    if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`${what}: expected a finite number, got ${String(v)}`)
+    return
+  }
+  if (!Array.isArray(v) || v.length !== 2 || !Number.isFinite(v[0]) || !Number.isFinite(v[1])) {
+    throw new Error(`${what}: expected [x, y] finite numbers, got ${JSON.stringify(v)}`)
+  }
+}
+
+/**
+ * Declare a control's axes: `createAxes({ rotate: "vec2", zoom: "axis" },
+ * { onNudge, onBegin, onEnd })`. The hooks are how nudges reach the
+ * control's pose; rates are read back with `rate()` from its update(dt).
+ */
+export function createAxes<A extends AxesDecl>(kinds: A, hooks: AxesHooks<A> = {}): Axes<A> {
+  for (let [name, kind] of Object.entries(kinds)) {
+    if (kind !== "axis" && kind !== "vec2") throw new Error(`createAxes: axis "${name}" has kind "${String(kind)}", expected "axis" or "vec2"`)
+  }
+  let check = (name: string): AxisKind => {
+    let kind = kinds[name]
+    if (!kind) throw new Error(`createAxes: no axis "${name}" (declared: ${Object.keys(kinds).join(", ")})`)
+    return kind
+  }
+  // Sources per axis: a plain list is the truth (a write and a read in
+  // the same synchronous block must agree, which a signal's deferred
+  // write does not give), and a version signal notifies the reactive
+  // readers - active() and whoever tracks rate() - of a change.
+  let sources = new Map<string, (() => number | Vec2)[]>()
+  // ownedWrite: add() runs from component bodies (a map's drive()).
+  let [version, setVersion] = createSignal(0, { ownedWrite: true })
+  let bump = () => setVersion(untrack(version) + 1)
+  for (let name of Object.keys(kinds)) sources.set(name, [])
+  let rate = (name: string): number | Vec2 => {
+    version()
+    let values: (number | Vec2)[] = []
+    for (let read of sources.get(name)!) values.push(read())
+    return combineRates(kinds[name]!, values)
+  }
+  let active = createMemo(() => {
+    for (let [name, kind] of Object.entries(kinds)) {
+      let v = rate(name)
+      if (kind === "axis" ? v !== 0 : (v as Vec2)[0] !== 0 || (v as Vec2)[1] !== 0) return true
+    }
+    return false
+  })
+  let open = new Map<string, number>()
+  return {
+    kinds,
+    add(name, read) {
+      check(name)
+      if (typeof read !== "function") throw new Error(`createAxes: add("${name}") expects a function`)
+      let list = sources.get(name)!
+      list.push(read)
+      bump()
+      return () => {
+        let i = list.indexOf(read)
+        if (i < 0) return
+        list.splice(i, 1)
+        bump()
+      }
+    },
+    rate(name) {
+      check(name)
+      return rate(name) as never
+    },
+    active,
+    nudge(name, delta, focal) {
+      let kind = check(name)
+      checkValue(`nudge("${name}")`, kind, delta)
+      if (focal !== undefined) checkValue(`nudge("${name}") focal`, "vec2", focal)
+      hooks.onNudge?.(name, delta, focal)
+    },
+    begin(name) {
+      check(name)
+      let depth = open.get(name) ?? 0
+      open.set(name, depth + 1)
+      if (depth === 0) hooks.onBegin?.(name)
+    },
+    end(name) {
+      check(name)
+      let depth = open.get(name) ?? 0
+      if (depth === 0) return
+      open.set(name, depth - 1)
+      if (depth === 1) hooks.onEnd?.(name)
+    },
+    inGesture(name) {
+      check(name)
+      return (open.get(name) ?? 0) > 0
+    },
+  }
+}

package/src/input-chord.ts

@@ -0,0 +1,44 @@
+// Modifier chords, the vocabulary two devices share: a spec names
+// modifiers ahead of what it qualifies ("Shift+Tab" on the keyboard,
+// "Ctrl" on a pointer gesture), the event must carry them, a bare spec
+// ignores them (a shifted W still walks, a Ctrl-drag still drags), and
+// among the specs one event satisfies the most specific wins - Unreal's
+// chord blocker, Three's OrbitControls picking PAN over ROTATE at
+// mousedown; Godot and Unity fire both by default and every app writes
+// the exclusion itself. Which event resolves a chord is the device's
+// call: the keyboard settles each key down, the pointer feed the event
+// that opens a gesture bracket.
+
+export type Modifier = "shiftKey" | "ctrlKey" | "altKey" | "metaKey"
+/** The modifier flags every key, pointer and wheel event carries. */
+export type Modified = Record<Modifier, boolean>
+
+const MODIFIERS: Record<string, Modifier> = { Shift: "shiftKey", Ctrl: "ctrlKey", Control: "ctrlKey", Alt: "altKey", Meta: "metaKey" }
+// The canonical order a chord is spelled in, so one modifier set has one name.
+const ORDER: Modifier[] = ["shiftKey", "ctrlKey", "altKey", "metaKey"]
+const NAMES: Record<Modifier, string> = { shiftKey: "Shift", ctrlKey: "Ctrl", altKey: "Alt", metaKey: "Meta" }
+
+/** The modifiers `parts` name (["Ctrl", "Shift"]), deduplicated, in
+ * canonical order; `what` and `text` name the caller and its spec in the
+ * throw on an unknown name. */
+export function parseModifiers(what: string, text: string, parts: string[]): Modifier[] {
+  let mods = new Set<Modifier>()
+  for (let part of parts) {
+    let mod = MODIFIERS[part]
+    if (!mod) throw new Error(`${what}: unknown modifier "${part}" in "${text}" (Shift, Ctrl, Alt or Meta)`)
+    mods.add(mod)
+  }
+  return ORDER.filter(m => mods.has(m))
+}
+
+/** The canonical spelling of a modifier set: "Shift+Ctrl"; "" for none. */
+export let chordName = (mods: Modifier[]): string => mods.map(m => NAMES[m]).join("+")
+
+/** Of `items`, those whose modifiers the event carries, narrowed to the
+ * most specific (the longest modifier lists, all of them on a tie);
+ * empty when none match. */
+export function mostSpecific<T>(items: T[], mods: (item: T) => Modifier[], event: Modified): T[] {
+  let hits = items.filter(item => mods(item).every(m => event[m]))
+  let most = hits.reduce((n, item) => Math.max(n, mods(item).length), 0)
+  return hits.filter(item => mods(item).length === most)
+}