@solidrt/core 0.0.59 → 0.0.61

package/src/input-pointer.ts

@@ -57,6 +57,24 @@
 // joins nothing, and only the held button's release closes the gesture.
 // The wheel and mouseDelta have no button; a button word on them throws.
 //
+// Discrete gestures are button sources that pulse (pressed for one task,
+// the shape of the `tap()` interaction): `swipe("Left")` at the lift of
+// a one-finger drag that qualifies (swipe.ts: distance, speed, within 30
+// degrees of an axis; the direction is the spec's trailing word, as a
+// drag's button is, and a swipe never has a button word), `longPress`
+// at the hold timer (long-press.ts) and `doubleTap` on the second tap's
+// down (double-tap.ts). They ride the feed's own events - the feed is
+// ONE arena claimant, its transform, so they never steal - and take the
+// chord of the down that opened them. Bound to an AXIS action they
+// nudge 1 with the gesture's focal point (the tap's or hold's position,
+// a fraction of the element) and contribute no rate (input-map.ts skips
+// a pulse's press when it combines an axis's rates), which is how a
+// control learns WHERE a double tap landed (the orbit camera's `focus`,
+// the 2d camera's octave); a swipe has no focal.
+// The drag's end bracket carries the release velocity the transform
+// measured, in element heights per second, so a camera flings from the
+// gesture's speed.
+//
 // The element's laid-out box normalizes the travel: read at the press
 // through getLayoutBox (the untransformed read, so a designSize fit or
 // an ancestor transform never skews it), or from `layout` when given -
@@ -67,14 +85,26 @@
 // Create a feed in an owned scope (a component body): the recognizer
 // registers its cleanup with the owner.
 
+import { createSignal } from "@solidjs/signals"
 import { createTransform } from "./transform"
 import { getLayoutBox } from "./core"
 import { pointerLocked } from "./window"
 import type { PointerEvent, WheelEvent } from "./types"
-import type { DeltaSink, InputSource } from "./input-map"
+import type { ActionKind, DeltaSink, InputDevice, InputSource } from "./input-map"
 import type { Vec2 } from "./input-axes"
-import { chordName, mostSpecific, parseModifiers } from "./input-chord"
+import { chordName, eventModifiers, mostSpecific, parseModifiers } from "./input-chord"
 import type { Modified, Modifier } from "./input-chord"
+import { createVelocityTracker } from "./velocity"
+import type { Velocity } from "./velocity"
+import { classifySwipe, SWIPE_DIRECTIONS } from "./swipe"
+import type { SwipeDirection } from "./swipe"
+import { createHoldTimer } from "./long-press"
+import { createTapSequence } from "./double-tap"
+
+// Source ids (input-id.ts): `pointer:<gesture>` for the bare source and
+// `pointer:<gesture>:<spec>` for a chord or button variant, the spec in
+// its canonical spelling ("Shift+Ctrl+Right").
+const DEVICE = "pointer"
 
 // Octaves per wheel-delta unit: the zoom exponent both cameras used
 // (0.0015 per unit) taken in log2, so a 100-unit notch zooms about a
@@ -94,9 +124,10 @@ const MOUSE_PX_PER_UNIT = 1500
  * then instead of the bare one: the most specific bound chord wins. The
  * same spec returns the same source, so unbind by identity works.
  */
-export type PointerSource<K extends "axis" | "vec2"> = InputSource<K> & ((chord: string) => InputSource<K>)
+export type PointerSource<K extends ActionKind> = InputSource<K> & ((chord: string) => InputSource<K>)
 
-export interface PointerFeed {
+export interface PointerFeed extends InputDevice {
+  readonly name: "pointer"
   /** Spread on the element whose pointer events feed the sources. */
   handlers: {
     onPointerDown(event: PointerEvent): void
@@ -120,6 +151,23 @@ export interface PointerFeed {
   /** Raw mouse motion while the pointer is locked, in view-height
    * equivalents (see MOUSE_PX_PER_UNIT); unbracketed. */
   mouseDelta: PointerSource<"vec2">
+  /** A one-finger swipe in the spec's direction ("Left", "Ctrl+Right"):
+   * a button pulsing once at the lift. */
+  swipe(spec: string): InputSource<"button">
+  /** A pointer held still for the long-press hold: a button pulsing once
+   * at the timer. */
+  longPress: PointerSource<"button">
+  /** Two quick taps: a button pulsing once on the second down. */
+  doubleTap: PointerSource<"button">
+  /** The source of an id's spec ("drag", "drag:Ctrl+Right", "wheel",
+   * "swipe:Left", "longPress:Ctrl"). */
+  resolve(spec: string): InputSource
+  /** For a rebind: `found` gets the next gesture of `kind` the pointer
+   * opens on the element (a drag, pan or locked mouse motion for a vec2;
+   * a pinch, twist or wheel notch for an axis; a swipe, long-press or
+   * double-tap for a button), as the variant of the chord and button or
+   * direction that opened it. Returns the stop. */
+  listen(kind: ActionKind, found: (source: InputSource) => void): () => void
 }
 
 export interface PointerFeedOptions {
@@ -142,9 +190,11 @@ const PRIMARY = 0
 // bound mid-gesture joins it.
 type Bucket = { mods: Modifier[]; button: number; sinks: Set<DeltaSink>; source: InputSource }
 
-function gesture<K extends "axis" | "vec2">(kind: K, label: string, buttons: boolean) {
+function gesture<K extends "axis" | "vec2">(kind: K, id: string, label: string, buttons: boolean) {
   let buckets = new Map<string, Bucket>()
   let open: Set<DeltaSink>[] = []
+  // Rebind listeners: told the variant each bracket or send opens.
+  let probes = new Set<(source: InputSource) => void>()
   let variant = (mods: Modifier[], button: number): InputSource<K> => {
     let name = [chordName(mods), button === PRIMARY ? "" : Object.keys(BUTTONS)[button]!].filter(Boolean).join("+")
     let bucket = buckets.get(name)
@@ -153,6 +203,8 @@ function gesture<K extends "axis" | "vec2">(kind: K, label: string, buttons: boo
       let source: InputSource<K> = {
         kind,
         label: name ? `${label} (${name})` : label,
+        id: name ? `${DEVICE}:${id}:${name}` : `${DEVICE}:${id}`,
+        device: DEVICE,
         deltas(sink) {
           sinks.add(sink)
           return () => {
@@ -176,39 +228,134 @@ function gesture<K extends "axis" | "vec2">(kind: K, label: string, buttons: boo
     }
     return variant(parseModifiers(label, text, parts), button)
   }
-  let source: PointerSource<K> = Object.assign(spec, { kind, label: bare.label, deltas: bare.deltas! })
+  let source: PointerSource<K> = Object.assign(spec, { kind, label: bare.label, id: bare.id, device: bare.device, deltas: bare.deltas! })
   let resolve = (event: Modified, button: number): Set<DeltaSink>[] =>
     mostSpecific(
       [...buckets.values()].filter(b => b.sinks.size > 0 && b.button === button),
       b => b.mods,
       event,
     ).map(b => b.sinks)
+  let probe = (event: Modified, button: number) => {
+    if (probes.size === 0) return
+    let found = variant(eventModifiers(event), button)
+    probes.forEach(p => p(found))
+  }
   return {
     source,
+    spec,
+    listen(found: (source: InputSource) => void) {
+      probes.add(found)
+      return () => {
+        probes.delete(found)
+      }
+    },
     begin(event: Modified, button: number) {
+      probe(event, button)
       open = resolve(event, button)
       for (let sinks of open) sinks.forEach(k => k.begin())
     },
     delta(value: number | Vec2, focal?: Vec2) {
       for (let sinks of open) sinks.forEach(k => k.delta(value, focal))
     },
-    end() {
-      for (let sinks of open) sinks.forEach(k => k.end())
+    end(velocity?: number | Vec2) {
+      for (let sinks of open) sinks.forEach(k => k.end(velocity))
       open = []
     },
     send(event: Modified, value: number | Vec2, focal?: Vec2) {
+      probe(event, PRIMARY)
       for (let sinks of resolve(event, PRIMARY)) sinks.forEach(k => k.delta(value, focal))
     },
   }
 }
 
+// A discrete gesture's sources, bucketed by spec like a delta gesture's:
+// the chord plus, when the gesture takes one, a trailing word from
+// `words` (a swipe's direction; then the bare spec has no meaning and
+// `spec` demands the word). A fire resolves the buckets of the word whose
+// chord the event carries, narrowed to the most specific, and pulses each:
+// pressed now, released on the next task, so a map's onPress sees the
+// edge (input-processors.ts `tap`). A created variant counts as bound.
+type PulseBucket = { mods: Modifier[]; word: string | null; source: InputSource<"button">; set: (pressed: boolean) => void; sinks: Set<DeltaSink> }
+
+function pulses(id: string, label: string, words: readonly string[] | null) {
+  let buckets = new Map<string, PulseBucket>()
+  let probes = new Set<(source: InputSource) => void>()
+  let variant = (mods: Modifier[], word: string | null): InputSource<"button"> => {
+    let name = [chordName(mods), word ?? ""].filter(Boolean).join("+")
+    let bucket = buckets.get(name)
+    if (!bucket) {
+      // ownedWrite: a fire lands inside a pointer handler or a timer.
+      let [pressed, set] = createSignal(false, { ownedWrite: true })
+      let sinks = new Set<DeltaSink>()
+      let source: InputSource<"button"> = {
+        kind: "button",
+        label: name ? `${label} (${name})` : label,
+        id: name ? `${DEVICE}:${id}:${name}` : `${DEVICE}:${id}`,
+        device: DEVICE,
+        rate: pressed,
+        deltas(sink) {
+          sinks.add(sink)
+          return () => {
+            sinks.delete(sink)
+          }
+        },
+      }
+      bucket = { mods, word, source, set, sinks }
+      buckets.set(name, bucket)
+    }
+    return bucket.source
+  }
+  let spec = (text: string): InputSource<"button"> => {
+    if (typeof text !== "string" || text.length === 0) throw new Error(`${label}: expected a spec such as "Ctrl"${words ? `, "${words[0]}" or "Shift+${words[0]}"` : ' or "Shift+Alt"'}, got ${String(text)}`)
+    let parts = text.split("+")
+    let word: string | null = null
+    if (words && words.includes(parts[parts.length - 1]!)) word = parts.pop()!
+    if (words && word === null) throw new Error(`${label}: "${text}" must end in a direction (${words.join(", ")})`)
+    return variant(parseModifiers(label, text, parts), word)
+  }
+  let bare = words ? null : variant([], null)
+  return {
+    /** The bare source (null for a gesture that needs its word). */
+    bare,
+    spec,
+    listen(found: (source: InputSource) => void) {
+      probes.add(found)
+      return () => {
+        probes.delete(found)
+      }
+    },
+    fire(event: Modified, word: string | null, focal?: Vec2) {
+      if (probes.size > 0) {
+        let found = variant(eventModifiers(event), word)
+        probes.forEach(p => p(found))
+      }
+      let hit = mostSpecific(
+        [...buckets.values()].filter(b => b.word === word),
+        b => b.mods,
+        event,
+      )
+      for (let b of hit) {
+        b.set(true)
+        setTimeout(() => b.set(false), 0)
+        b.sinks.forEach(k => k.delta(1, focal))
+      }
+    },
+  }
+}
+
 export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed {
-  let drag = gesture("vec2", "pointer drag", true)
-  let pan = gesture("vec2", "pointer two-finger pan", true)
-  let pinch = gesture("axis", "pointer pinch", true)
-  let twist = gesture("axis", "pointer twist", true)
-  let wheel = gesture("axis", "pointer wheel", false)
-  let mouseDelta = gesture("vec2", "mouse motion (pointer locked)", false)
+  let drag = gesture("vec2", "drag", "pointer drag", true)
+  let pan = gesture("vec2", "pan", "pointer two-finger pan", true)
+  let pinch = gesture("axis", "pinch", "pointer pinch", true)
+  let twist = gesture("axis", "twist", "pointer twist", true)
+  let wheel = gesture("axis", "wheel", "pointer wheel", false)
+  let mouseDelta = gesture("vec2", "mouseDelta", "mouse motion (pointer locked)", false)
+  let gestures = { drag, pan, pinch, twist, wheel, mouseDelta }
+  let swipe = pulses("swipe", "pointer swipe", SWIPE_DIRECTIONS)
+  let longPress = pulses("longPress", "pointer long press", null)
+  let doubleTap = pulses("doubleTap", "pointer double tap", null)
+  let discrete = { swipe, longPress, doubleTap }
+  let callable = (p: typeof longPress): PointerSource<"button"> => Object.assign(p.spec, { kind: "button" as const, label: p.bare!.label, id: p.bare!.id, device: p.bare!.device, rate: p.bare!.rate!, deltas: p.bare!.deltas! })
 
   // The element's box, read at each press (see the header). A detached
   // leaf has no layout box and must bring `layout`: normalizing by
@@ -226,8 +373,14 @@ export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed
   let unit = () => (box.height > 0 ? box.height : 1)
   let focalOf = (x: number, y: number): Vec2 | undefined => (box.width > 0 && box.height > 0 ? [x / box.width, y / box.height] : undefined)
 
+  // The release velocity of the gesture that just ended, for the drag's
+  // end bracket (the transform's up runs before `lifted`).
+  let released: Velocity | null = null
   let transform = createTransform({
     buttons: "any",
+    onTransformEnd: v => {
+      released = v.vx !== 0 || v.vy !== 0 ? v : null
+    },
     onTransformMove: t => {
       let h = unit()
       let travel: Vec2 = [t.dx / h, t.dy / h]
@@ -267,27 +420,66 @@ export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed
       twist.end()
       drag.begin(e, [...downs.values()][0]!)
     }
-    if (downs.size === 0) drag.end()
+    if (downs.size === 0) {
+      let h = unit()
+      drag.end(released ? [released.vx / h, released.vy / h] : undefined)
+      released = null
+    }
   }
 
+  // The discrete gestures over the primary button's first pointer: the
+  // finger's window-px velocity and the opening down for the swipe (a
+  // second finger disqualifies it), the hold timer, the tap sequence.
+  let finger = createVelocityTracker()
+  let opening: { id: number; x: number; y: number; mods: Modified; alone: boolean } | null = null
+  // The primary pointer's last down, as a focal: where a double tap or
+  // a long press landed (both fire from that down's own sequence).
+  let downFocal: Vec2 | undefined
+  let hold = createHoldTimer({ onFire: (_id, _at, mods) => longPress.fire(mods, null, downFocal) })
+  let taps = createTapSequence({ onDouble: (_id, _at, mods) => doubleTap.fire(mods, null, downFocal) })
+  let mods = (e: PointerEvent): Modified => ({ shiftKey: e.shiftKey, ctrlKey: e.ctrlKey, altKey: e.altKey, metaKey: e.metaKey })
+
   return {
     handlers: {
       onPointerDown(e) {
         if (downs.has(e.pointerId)) return
         if (downs.size === 0) box = size(e)
-        landed(e, e.button ?? PRIMARY)
+        let button = e.button ?? PRIMARY
+        landed(e, button)
         transform.handlers.onPointerDown(e)
+        if (button === PRIMARY) {
+          downFocal = focalOf(e.localX, e.localY)
+          hold.down(e)
+          taps.down(e)
+          if (downs.size === 1) {
+            opening = { id: e.pointerId, x: e.clientX, y: e.clientY, mods: mods(e), alone: true }
+            finger.reset()
+            finger.push(e.clientX, e.clientY)
+          } else if (opening) opening.alone = false
+        }
       },
       onPointerMove(e) {
         if (pointerLocked() && e.pointerType === "mouse" && (e.movementX !== 0 || e.movementY !== 0)) {
           mouseDelta.send(e, [e.movementX / MOUSE_PX_PER_UNIT, e.movementY / MOUSE_PX_PER_UNIT])
         }
         transform.handlers.onPointerMove(e)
+        hold.move(e)
+        taps.move(e)
+        if (opening && opening.id === e.pointerId) finger.push(e.clientX, e.clientY)
       },
       onPointerUp(e) {
         if (downs.get(e.pointerId) !== (e.button ?? PRIMARY)) return
         transform.handlers.onPointerUp(e)
         lifted(e)
+        hold.up(e)
+        taps.up(e)
+        if (opening && opening.id === e.pointerId) {
+          if (opening.alone && downs.size === 0) {
+            let direction: SwipeDirection | null = classifySwipe(finger.velocity(), { dx: e.clientX - opening.x, dy: e.clientY - opening.y })
+            if (direction) swipe.fire(opening.mods, direction)
+          }
+          opening = null
+        }
       },
       onPointerLeave() {},
       onWheel(e) {
@@ -296,11 +488,43 @@ export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed
         wheel.send(e, -e.deltaY * WHEEL_OCTAVES, focalOf(e.localX, e.localY))
       },
     },
+    name: DEVICE,
     drag: drag.source,
     pan: pan.source,
     pinch: pinch.source,
     twist: twist.source,
     wheel: wheel.source,
     mouseDelta: mouseDelta.source,
+    swipe: swipe.spec,
+    longPress: callable(longPress),
+    doubleTap: callable(doubleTap),
+    resolve(spec) {
+      let colon = spec.indexOf(":")
+      let name = colon < 0 ? spec : spec.slice(0, colon)
+      let rest = colon < 0 ? null : spec.slice(colon + 1)
+      let g = gestures[name as keyof typeof gestures]
+      if (g) return rest === null ? g.source : g.spec(rest)
+      let p = discrete[name as keyof typeof discrete]
+      if (p) {
+        if (rest === null) {
+          if (!p.bare) throw new Error(`pointer.resolve: "${spec}" needs a direction (swipe:Left)`)
+          return p.bare
+        }
+        return p.spec(rest)
+      }
+      throw new Error(`pointer.resolve: unknown gesture "${spec}" (${[...Object.keys(gestures), ...Object.keys(discrete)].join(", ")}, each with an optional :<chord>; swipe with its direction)`)
+    },
+    listen(kind, found) {
+      if (kind !== "button" && kind !== "axis" && kind !== "vec2") throw new Error(`pointer.listen: expected a kind, got ${String(kind)}`)
+      if (typeof found !== "function") throw new Error("pointer.listen: expects a function")
+      let stops = kind === "button"
+        ? Object.values(discrete).map(p => p.listen(found))
+        : Object.values(gestures)
+            .filter(g => g.source.kind === kind)
+            .map(g => g.listen(found))
+      return () => {
+        for (let stop of stops) stop()
+      }
+    },
   }
 }

package/src/input-processors.ts

@@ -0,0 +1,214 @@
+// Processors and interactions: sources made from sources. A processor
+// changes a value (Unity's Invert and Scale), an interaction recognizes a
+// pattern on a button over time (Unity's Hold, Tap and MultiTap
+// interactions, Unreal's Triggers) and is itself a button source, so an
+// action binds `hold(pad.button("west"))` for a charged attack next to
+// the plain press on another action, and the consumer reads one bool.
+//
+// Timing: an interaction watches its source's rate under a root of its
+// own and keeps time with setTimeout, so it works headless and needs no
+// frame loop; the root is disposed with the creating scope (a component
+// body) and lives for the session without one. `tap` and `doubleTap`
+// are edges, not levels: they read pressed for one task, long enough
+// for a map's onPress to fire, then release on their own.
+//
+// Every processor composes the source's id (`invert(gamepad:leftStick)`,
+// `hold(400,keyboard:key:Space)`), so a saved binding restores through
+// the same processor (input-id.ts), and carries its device through for
+// InputMap.device(). A processor's key/blur hooks forward to the source,
+// so a keyboard source keeps receiving the map's key events under one.
+
+import { createEffect, createRoot, createSignal, getOwner, onCleanup } from "@solidjs/signals"
+import type { ActionKind, InputSource } from "./input-map"
+import type { Vec2 } from "./input-axes"
+
+// Time a button must stay down before hold() reads pressed (Unity's Hold
+// interaction default).
+const HOLD_MS = 400
+// Longest press that still counts as a tap (Unity's Tap default).
+const TAP_MS = 200
+// Longest gap between two taps that makes a double tap.
+const DOUBLE_TAP_GAP_MS = 300
+
+export function checkSource(source: unknown): InputSource {
+  let s = source as InputSource
+  // A pointer gesture is a callable source (`pointer.drag("Ctrl")` is its chord variant).
+  if (!s || (typeof s !== "object" && typeof s !== "function") || (s.kind !== "button" && s.kind !== "axis" && s.kind !== "vec2") || typeof s.label !== "string" || typeof s.id !== "string") {
+    throw new Error(`createInputMap: not an input source: ${String(source)}`)
+  }
+  return s
+}
+
+let checkAxisSource = (what: string, source: InputSource): void => {
+  checkSource(source)
+  if ((source.kind as ActionKind) === "button") throw new Error(`${what}: "${source.label}" is a button`)
+}
+
+let checkButtonSource = (what: string, source: InputSource): void => {
+  checkSource(source)
+  if (source.kind !== "button") throw new Error(`${what}: "${source.label}" is a ${source.kind}, not a button`)
+}
+
+let checkMs = (what: string, ms: number): void => {
+  if (!Number.isFinite(ms) || ms < 0) throw new Error(`${what}: ms must be a non-negative number, got ${String(ms)}`)
+}
+
+/**
+ * A source with its values negated - Unity's Invert processor. The one
+ * convention split every engine has: a drag moves the CONTENT under the
+ * finger, while keys and sticks move the CAMERA, so a preset binds the
+ * arrows or a stick to `pan` or `rotate` through invert() and the axis
+ * keeps one meaning.
+ */
+export function invert<K extends "axis" | "vec2">(source: InputSource<K>): InputSource<K> {
+  checkAxisSource("invert", source)
+  let neg = (v: number | Vec2): number | Vec2 => (typeof v === "number" ? -v : [-v[0], -v[1]])
+  return {
+    kind: source.kind,
+    label: `${source.label} (inverted)`,
+    id: `invert(${source.id})`,
+    device: source.device,
+    rate: source.rate ? () => neg(source.rate!() as number | Vec2) as never : undefined,
+    deltas: source.deltas
+      ? sink => source.deltas!({ begin: sink.begin, end: velocity => sink.end(velocity === undefined ? undefined : neg(velocity)), delta: (value, focal) => sink.delta(neg(value), focal) })
+      : undefined,
+    key: source.key,
+    blur: source.blur,
+  }
+}
+
+/** A source scaled by `factor` (rates and deltas alike) - Unity's Scale
+ * processor: a slower stick, a finer wheel. */
+export function scale<K extends "axis" | "vec2">(source: InputSource<K>, factor: number): InputSource<K> {
+  checkAxisSource("scale", source)
+  if (!Number.isFinite(factor)) throw new Error(`scale: factor must be a finite number, got ${factor}`)
+  let mul = (v: number | Vec2): number | Vec2 => (typeof v === "number" ? v * factor : [v[0] * factor, v[1] * factor])
+  return {
+    kind: source.kind,
+    label: `${source.label} (x${factor})`,
+    id: `scale(${factor},${source.id})`,
+    device: source.device,
+    rate: source.rate ? () => mul(source.rate!() as number | Vec2) as never : undefined,
+    deltas: source.deltas
+      ? sink => source.deltas!({ begin: sink.begin, end: velocity => sink.end(velocity === undefined ? undefined : mul(velocity)), delta: (value, focal) => sink.delta(mul(value), focal) })
+      : undefined,
+    key: source.key,
+    blur: source.blur,
+  }
+}
+
+// A button source derived from one button source's press and release
+// edges: `edge(down, now)` runs on each, with `set` for the derived
+// state and `later` for a timer that the disposal clears.
+type EdgeHooks = { set: (pressed: boolean) => void; later: (ms: number, run: () => void) => void; clearLater: () => void }
+
+function derived(source: InputSource<"button">, label: string, id: string, edge: (down: boolean, now: number, hooks: EdgeHooks) => void): InputSource<"button"> {
+  // ownedWrite: the edges land inside an effect and timers.
+  let [pressed, setPressed] = createSignal(false, { ownedWrite: true })
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let hooks: EdgeHooks = {
+    set: setPressed,
+    later(ms, run) {
+      hooks.clearLater()
+      timer = setTimeout(() => {
+        timer = null
+        run()
+      }, ms)
+    },
+    clearLater() {
+      if (timer !== null) clearTimeout(timer)
+      timer = null
+    },
+  }
+  let dispose = createRoot(dispose => {
+    createEffect(
+      () => source.rate!(),
+      (down, prev) => {
+        if (down !== prev) edge(down, performance.now(), hooks)
+      },
+      { defer: true },
+    )
+    return dispose
+  })
+  if (getOwner()) {
+    onCleanup(() => {
+      hooks.clearLater()
+      dispose()
+    })
+  }
+  return { kind: "button", label, id, device: source.device, rate: pressed, key: source.key, blur: source.blur }
+}
+
+// A one-task pulse: pressed now, released on the next task, so a map's
+// onPress effect (which runs at the flush in between) sees the edge.
+let pulse = (hooks: EdgeHooks): void => {
+  hooks.set(true)
+  hooks.later(0, () => hooks.set(false))
+}
+
+/** Pressed once `source` has been held `ms` (default 400), until released:
+ * a charged attack, a long-press menu. */
+export function hold(source: InputSource<"button">, ms = HOLD_MS): InputSource<"button"> {
+  checkButtonSource("hold", source)
+  checkMs("hold", ms)
+  return derived(source, `${source.label} (hold ${ms} ms)`, `hold(${ms},${source.id})`, (down, _now, hooks) => {
+    if (down) hooks.later(ms, () => hooks.set(true))
+    else {
+      hooks.clearLater()
+      hooks.set(false)
+    }
+  })
+}
+
+/** A press released within `ms` (default 200): pressed for one task on the
+ * release, so onPress fires once per tap and a long press is not one. */
+export function tap(source: InputSource<"button">, ms = TAP_MS): InputSource<"button"> {
+  checkButtonSource("tap", source)
+  checkMs("tap", ms)
+  let downAt = 0
+  return derived(source, `${source.label} (tap)`, `tap(${ms},${source.id})`, (down, now, hooks) => {
+    if (down) downAt = now
+    else if (now - downAt <= ms) pulse(hooks)
+  })
+}
+
+/** Two taps (each within `tapMs`, default 200) at most `gapMs` (default
+ * 300) apart: pressed for one task on the second release. */
+export function doubleTap(source: InputSource<"button">, gapMs = DOUBLE_TAP_GAP_MS, tapMs = TAP_MS): InputSource<"button"> {
+  checkButtonSource("doubleTap", source)
+  checkMs("doubleTap", gapMs)
+  checkMs("doubleTap", tapMs)
+  let downAt = 0
+  let lastTap = -Infinity
+  return derived(source, `${source.label} (double tap)`, `doubleTap(${gapMs},${tapMs},${source.id})`, (down, now, hooks) => {
+    if (down) {
+      downAt = now
+      return
+    }
+    if (now - downAt > tapMs) return
+    if (now - lastTap <= gapMs) {
+      lastTap = -Infinity
+      pulse(hooks)
+    } else lastTap = now
+  })
+}
+
+/** Pressed while every source is: Shift+click on one action, a two-button
+ * combo on a pad. Key events reach each keyboard source among them. */
+export function chord(...sources: InputSource<"button">[]): InputSource<"button"> {
+  if (sources.length < 2) throw new Error("chord: needs at least two button sources")
+  for (let s of sources) checkButtonSource("chord", s)
+  return {
+    kind: "button",
+    label: sources.map(s => s.label).join(" + "),
+    id: `chord(${sources.map(s => s.id).join(",")})`,
+    device: sources[0]!.device,
+    rate: () => sources.every(s => s.rate?.() === true),
+    key: (event, down) => {
+      for (let s of sources) s.key?.(event, down)
+    },
+    blur: () => {
+      for (let s of sources) s.blur?.()
+    },
+  }
+}

package/src/input.ts

@@ -4,8 +4,10 @@
 // event bus). The map, the control-side axes contract and the keyboard
 // device are pure; the gamepad device and the pointer feed need the
 // runtime and live on the main entry.
-export { createInputMap, invert, scale } from "./input-map"
-export type { ActionKind, ActionValue, ActionsDecl, Binding, DeltaSink, GestureListener, InputMap, InputSource } from "./input-map"
+export { createInputMap } from "./input-map"
+export type { ActionKind, ActionValue, ActionsDecl, Binding, DeltaSink, DeviceName, GestureListener, InputDevice, InputDeviceSet, InputMap, InputSource, RebindOptions, RebindPart } from "./input-map"
+export { chord, doubleTap, hold, invert, scale, tap } from "./input-processors"
+export { resolveSource } from "./input-id"
 export { createAxes, combineRates } from "./input-axes"
 export type { Axes, AxesDecl, AxesHooks, AxisKind, AxisValue, Vec2 } from "./input-axes"
 export { keyboard } from "./input-keyboard"