@solidrt/core 0.0.60 → 0.0.61

package/src/double-tap.ts

@@ -0,0 +1,150 @@
+// The double-tap recognizer: two taps, the second down within
+// DOUBLE_TAP_MS of the first up, within DOUBLE_TAP_SLOP of it and at
+// least DOUBLE_TAP_MIN_MS after it (a bouncing contact is one tap, not
+// two). Fires on the second DOWN (Flutter, iOS), so it is not delayed by
+// the second lift. A tap is a down that stays within TAP_SLOP and lifts
+// before the long-press hold (a longer hold is a long-press, never half a
+// double-tap).
+//
+// Arena: the first tap claims nothing (it must not disturb a press on the
+// same node) but PENDS a decision on its pointer, so a press that
+// resolved at the first lift defers its firing (arena.defer): the single
+// tap fires once the window passes with no second tap, and never when
+// the double-tap wins. The second down steals its pointer outright (the
+// press's provisional claim is cancelled, so the second tap never shows
+// pressed or fires) and releases it at the lift. Options are read at
+// event time; cancel() retracts without firing; an unmount clears the
+// window timer. Mouse and touch alike (a double-click double-taps).
+//
+// The tap bookkeeping (createTapSequence) is shared with the pointer
+// feed's doubleTap source, which pulses instead of stealing.
+
+import { onSettled } from "@solidjs/signals"
+import type { PointerEvent } from "./types"
+import { arena, type ArenaOwner } from "./arena"
+import { pastSlop, pointAt, type PointerPoint } from "./gesture"
+
+// Second down at most this long after the first up.
+const DOUBLE_TAP_MS = 300
+// Second down at most this far (window px) from the first down: Flutter's
+// kDoubleTapSlop, generous because the second tap of a quick pair lands
+// where the hand is, not where the eye is.
+const DOUBLE_TAP_SLOP = 100
+// Second down at least this long after the first up (Flutter's
+// kDoubleTapMinTime): sooner is a contact bounce.
+const DOUBLE_TAP_MIN_MS = 40
+// A down held longer than this before its lift is not a tap.
+const TAP_MAX_MS = 500
+
+type Mods = { shiftKey: boolean; ctrlKey: boolean; altKey: boolean; metaKey: boolean }
+
+export interface TapSequenceOptions {
+  /** A first tap started: its outcome will be decided. */
+  onPend?: (pointerId: number) => void
+  /** The first tap's outcome: won (a second tap followed) or lost. */
+  onDecide?: (pointerId: number, won: boolean) => void
+  /** The second qualifying down, with its position and modifiers. */
+  onDouble: (pointerId: number, at: PointerPoint, mods: Mods) => void
+}
+
+/** 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(). */
+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
+  let settle = (won: boolean) => {
+    if (!first) return
+    if (timer !== null) clearTimeout(timer)
+    timer = null
+    let id = first.id
+    first = null
+    options.onDecide?.(id, won)
+  }
+  return {
+    down(e: PointerEvent) {
+      let now = performance.now()
+      if (first) {
+        if (first.upAt === null) {
+          // A second finger while the first is down: neither is a tap.
+          if (first.id !== e.pointerId) settle(false)
+          return
+        }
+        let gap = now - first.upAt
+        if (gap >= DOUBLE_TAP_MIN_MS && gap <= DOUBLE_TAP_MS && !pastSlop(e, first.at, DOUBLE_TAP_SLOP)) {
+          settle(true)
+          options.onDouble(e.pointerId, pointAt(e), { shiftKey: e.shiftKey, ctrlKey: e.ctrlKey, altKey: e.altKey, metaKey: e.metaKey })
+          return
+        }
+        // Too far, too late or a bounce: the first tap stands alone and
+        // this down starts over.
+        settle(false)
+      }
+      first = { id: e.pointerId, at: pointAt(e), downAt: now, upAt: null }
+      options.onPend?.(e.pointerId)
+    },
+    move(e: PointerEvent) {
+      if (first && first.id === e.pointerId && first.upAt === null && pastSlop(e, first.at)) settle(false)
+    },
+    up(e: PointerEvent) {
+      if (!first || first.id !== e.pointerId || first.upAt !== null) return
+      let now = performance.now()
+      if (now - first.downAt > TAP_MAX_MS) {
+        settle(false)
+        return
+      }
+      first.upAt = now
+      timer = setTimeout(() => {
+        timer = null
+        settle(false)
+      }, DOUBLE_TAP_MS)
+    },
+    cancel: () => settle(false),
+  }
+}
+
+export interface DoubleTapOptions {
+  /** The second tap's down, with its position. */
+  onDoubleTap?: (at: PointerPoint) => void
+}
+
+export function createDoubleTap(options: DoubleTapOptions) {
+  // The second tap's pointer, held from its down to its lift.
+  let second: number | null = null
+  let release = () => {
+    if (second !== null) {
+      arena.release(second, owner)
+      second = null
+    }
+  }
+  let cancel = () => {
+    taps.cancel()
+    release()
+  }
+  let owner: ArenaOwner = { cancel }
+  let taps = createTapSequence({
+    onPend: id => arena.pend(id, owner),
+    onDecide: (id, won) => arena.decide(id, owner, won),
+    onDouble: (id, at) => {
+      if (!arena.steal(id, owner)) return
+      second = id
+      options.onDoubleTap?.(at)
+    },
+  })
+  onSettled(() => cancel)
+
+  let handlers = {
+    onPointerDown: (e: PointerEvent) => {
+      if (e.button != null && e.button !== 0) return
+      taps.down(e)
+    },
+    onPointerMove: (e: PointerEvent) => {
+      taps.move(e)
+    },
+    onPointerUp: (e: PointerEvent) => {
+      if (second === e.pointerId) release()
+      taps.up(e)
+    },
+  }
+  return { handlers, cancel }
+}

package/src/gesture.ts

@@ -0,0 +1,32 @@
+// What the discrete recognizers (long-press, double-tap, swipe) share: the
+// copied point of a pointer event, and the slop that separates a tap from
+// a move. The event object itself is rewritten per node while it bubbles
+// (window.ts dispatchPath), so a recognizer keeps a copy, never the event.
+
+import type { PointerEvent } from "./types"
+
+/** A pointer position in every frame the event carried: window pixels
+ * (client), the handler node's own pixels (local), and the frame its
+ * x/y live in (parent). */
+export type PointerPoint = {
+  clientX: number
+  clientY: number
+  localX: number
+  localY: number
+  parentX: number
+  parentY: number
+}
+
+export let pointAt = (e: PointerEvent): PointerPoint => ({ clientX: e.clientX, clientY: e.clientY, localX: e.localX, localY: e.localY, parentX: e.parentX, parentY: e.parentY })
+
+// Finger travel in window pixels that turns a held or tapped pointer into
+// a move: a long-press past it never fires, a tap past it is not one
+// (iOS's 10 pt allowable movement).
+export const TAP_SLOP = 10
+
+/** Whether the pointer has left the slop circle around the down. */
+export let pastSlop = (e: PointerEvent, down: { clientX: number; clientY: number }, slop = TAP_SLOP): boolean => {
+  let dx = e.clientX - down.clientX
+  let dy = e.clientY - down.clientY
+  return dx * dx + dy * dy > slop * slop
+}

package/src/index.ts

@@ -15,6 +15,8 @@ export type { Capabilities, WindowSizeClass } from "./capabilities"
 export { createCubeTexture, createTexture } from "./gpu"
 export type { TextureId } from "./gpu"
 export { createImage, decodeImage, encodeImage } from "./image"
+export { createCursor } from "./cursor"
+export type { CursorFrame, CursorId, CursorName, CursorOptions } from "./cursor"
 export type { DecodedImage, ImageSource } from "./image"
 export { parseSvg, svg } from "./svg"
 export { Logo } from "./logo"
@@ -28,8 +30,19 @@ 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 { createSwipe, classifySwipe } from "./swipe"
+export type { SwipeDirection, SwipeOptions } from "./swipe"
+export { createLongPress } from "./long-press"
+export type { LongPressOptions } from "./long-press"
+export { createDoubleTap } from "./double-tap"
+export type { DoubleTapOptions } from "./double-tap"
+export type { PointerPoint } from "./gesture"
+export { createVelocityTracker, flingVelocity, FLING_MIN_VELOCITY } from "./velocity"
+export type { Velocity, VelocityTracker } from "./velocity"
+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 } from "./input-axes"
 export type { Axes, AxesDecl, AxesHooks, AxisKind, AxisValue, Vec2 } from "./input-axes"
 export { keyboard } from "./input-keyboard"
@@ -45,6 +58,7 @@ export type {
   PointerProps,
   TransitionProps,
   Transition,
+  TransitionCurve,
   TransitionPropName,
   TransitionEndEvent,
   PointerEvent,

package/src/input-axes.ts

@@ -42,9 +42,12 @@ export interface AxesHooks<A extends AxesDecl> {
    * 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). */
+  /** A gesture on `name` started (a finger landed) / ended (lifted). The
+   * end carries the release velocity in the axis's units per second when
+   * the gesture measured one (a drag's lift: view heights per second, the
+   * fling a control glides on), else undefined. */
   onBegin?: (name: keyof A & string) => void
-  onEnd?: (name: keyof A & string) => void
+  onEnd?: <N extends keyof A & string>(name: N, velocity: AxisValue<A[N]> | undefined) => void
 }
 
 export interface Axes<A extends AxesDecl> {
@@ -60,9 +63,10 @@ export interface Axes<A extends AxesDecl> {
   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. */
+  /** Bracket a gesture on `name`; nested begins count. An end may carry
+   * the release velocity (see AxesHooks.onEnd). */
   begin(name: keyof A & string): void
-  end(name: keyof A & string): void
+  end<N extends keyof A & string>(name: N, velocity?: AxisValue<A[N]>): void
   /** Whether a gesture on `name` is open (between begin and end). */
   inGesture(name: keyof A & string): boolean
 }
@@ -165,12 +169,13 @@ export function createAxes<A extends AxesDecl>(kinds: A, hooks: AxesHooks<A> = {
       open.set(name, depth + 1)
       if (depth === 0) hooks.onBegin?.(name)
     },
-    end(name) {
-      check(name)
+    end(name, velocity) {
+      let kind = check(name)
+      if (velocity !== undefined) checkValue(`end("${name}") velocity`, kind, velocity)
       let depth = open.get(name) ?? 0
       if (depth === 0) return
       open.set(name, depth - 1)
-      if (depth === 1) hooks.onEnd?.(name)
+      if (depth === 1) hooks.onEnd?.(name, velocity as never)
     },
     inGesture(name) {
       check(name)

package/src/input-chord.ts

@@ -34,6 +34,9 @@ export function parseModifiers(what: string, text: string, parts: string[]): Mod
 /** The canonical spelling of a modifier set: "Shift+Ctrl"; "" for none. */
 export let chordName = (mods: Modifier[]): string => mods.map(m => NAMES[m]).join("+")
 
+/** The modifiers an event carries, in canonical order. */
+export let eventModifiers = (event: Modified): Modifier[] => ORDER.filter(m => event[m])
+
 /** 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. */

package/src/input-gamepad-device.ts

@@ -15,18 +15,28 @@
 // they pick up a pad. A claim lasts until the owning scope is disposed
 // (an unmounted pane frees its pad); with no owner, for the session.
 
-import { createEffect, createRoot, createSignal, getOwner, onCleanup } from "@solidjs/signals"
+import { createEffect, createRoot, createSignal, getOwner, onCleanup, untrack } from "@solidjs/signals"
 import type { GamepadState } from "./gamepad"
-import type { InputSource } from "./input-map"
+import type { ActionKind, InputDevice, InputSource } from "./input-map"
 import type { Vec2 } from "./input-axes"
 
 // Stick deflection below which a resting stick reads as zero (radial:
 // the whole vector, so a stick nudged diagonally also rests).
 const STICK_DEADZONE = 0.15
+// Deflection (a stick's vector, a trigger or raw axis) that names the
+// control a rebind listens for: past a rest twitch, short of full travel.
+const LISTEN_THRESHOLD = 0.5
+
+// Source ids (input-id.ts): `gamepad:leftStick`, `gamepad:rightStick`,
+// `gamepad:dpad`, `gamepad:triggers`, `gamepad:shoulders`,
+// `gamepad:axis:<name>`, `gamepad:button:<name>`. No slot in the id: a
+// saved binding restores onto the device the app hands in.
+const DEVICE = "gamepad"
 
 export type PadsAccessor = () => (GamepadState | null)[]
 
-export interface GamepadDevice {
+export interface GamepadDevice extends InputDevice {
+  readonly name: "gamepad"
   /** The slot this device reads: a number for one pad, undefined for every
    * connected pad (`gamepad()`) or for a joining device no pad has claimed
    * yet (reactive: it resolves when one joins). */
@@ -43,10 +53,25 @@ export interface GamepadDevice {
   axis(name: string): InputSource<"axis">
   /** A button by SDL positional name ("south", "start", "leftShoulder", ...). */
   button(name: string): InputSource<"button">
+  /** The source of an id's spec ("button:south", "leftStick", "axis:leftX"). */
+  resolve(spec: string): InputSource
+  /** For a rebind: `found` gets the next control of `kind` the pad
+   * actuates past rest (a button pressed, a trigger or raw axis pulled,
+   * a stick pushed or the dpad, as `axis`/`button`/the stick sources);
+   * what is held when the listen starts must be released first. Returns
+   * the stop. */
+  listen(kind: ActionKind, found: (source: InputSource) => void): () => void
 }
 
 let deadzone = (x: number, y: number): Vec2 => (Math.hypot(x, y) < STICK_DEADZONE ? [0, 0] : [x, y])
 
+// The sticks as (name, x axis, y axis) for the listener.
+const STICKS = [
+  ["leftStick", "leftX", "leftY"],
+  ["rightStick", "rightX", "rightY"],
+] as const
+const DPAD_BUTTONS = ["dpadUp", "dpadDown", "dpadLeft", "dpadRight"]
+
 /**
  * The sources over `pads()` (the pads this device reads now, reactive),
  * with `slot()` as the device's slot and `who` as the label prefix.
@@ -72,9 +97,15 @@ export function createGamepadDevice(pads: () => GamepadState[], slot: () => numb
   let stick = (side: "left" | "right"): InputSource<"vec2"> => ({
     kind: "vec2",
     label: `${who} ${side} stick`,
+    id: `${DEVICE}:${side}Stick`,
+    device: DEVICE,
     rate: sumVec2(pad => deadzone(pad.axes[`${side}X`] ?? 0, pad.axes[`${side}Y`] ?? 0)),
   })
-  return {
+  // Same name, same source: unbind by identity works for a resolved id too.
+  let axes = new Map<string, InputSource<"axis">>()
+  let buttons = new Map<string, InputSource<"button">>()
+  let device: GamepadDevice = {
+    name: DEVICE,
     get slot() {
       return slot()
     },
@@ -83,27 +114,105 @@ export function createGamepadDevice(pads: () => GamepadState[], slot: () => numb
     dpad: {
       kind: "vec2",
       label: `${who} dpad`,
+      id: `${DEVICE}:dpad`,
+      device: DEVICE,
       rate: sumVec2(pad => [pressed(pad, "dpadRight") - pressed(pad, "dpadLeft"), pressed(pad, "dpadDown") - pressed(pad, "dpadUp")]),
     },
     triggers: {
       kind: "axis",
       label: `${who} triggers`,
+      id: `${DEVICE}:triggers`,
+      device: DEVICE,
       rate: sumAxis(pad => (pad.axes.rightTrigger ?? 0) - (pad.axes.leftTrigger ?? 0)),
     },
     shoulders: {
       kind: "axis",
       label: `${who} shoulders`,
+      id: `${DEVICE}:shoulders`,
+      device: DEVICE,
       rate: sumAxis(pad => pressed(pad, "rightShoulder") - pressed(pad, "leftShoulder")),
     },
     axis(name) {
       if (typeof name !== "string" || name.length === 0) throw new Error(`gamepad.axis: expected an axis name, got ${String(name)}`)
-      return { kind: "axis", label: `${who} ${name}`, rate: sumAxis(pad => pad.axes[name] ?? 0) }
+      let source = axes.get(name)
+      if (!source) {
+        source = { kind: "axis", label: `${who} ${name}`, id: `${DEVICE}:axis:${name}`, device: DEVICE, rate: sumAxis(pad => pad.axes[name] ?? 0) }
+        axes.set(name, source)
+      }
+      return source
     },
     button(name) {
       if (typeof name !== "string" || name.length === 0) throw new Error(`gamepad.button: expected a button name, got ${String(name)}`)
-      return { kind: "button", label: `${who} ${name}`, rate: anyButton(name) }
+      let source = buttons.get(name)
+      if (!source) {
+        source = { kind: "button", label: `${who} ${name}`, id: `${DEVICE}:button:${name}`, device: DEVICE, rate: anyButton(name) }
+        buttons.set(name, source)
+      }
+      return source
+    },
+    resolve(spec) {
+      let colon = spec.indexOf(":")
+      let head = colon < 0 ? spec : spec.slice(0, colon)
+      let rest = colon < 0 ? "" : spec.slice(colon + 1)
+      switch (head) {
+        case "leftStick":
+        case "rightStick":
+        case "dpad":
+        case "triggers":
+        case "shoulders":
+          if (rest) break
+          return device[head]
+        case "axis":
+          return device.axis(rest)
+        case "button":
+          return device.button(rest)
+      }
+      throw new Error(`gamepad.resolve: unknown source "${spec}" (leftStick, rightStick, dpad, triggers, shoulders, axis:<name>, button:<name>)`)
+    },
+    listen(kind, found) {
+      if (kind !== "button" && kind !== "axis" && kind !== "vec2") throw new Error(`gamepad.listen: expected a kind, got ${String(kind)}`)
+      if (typeof found !== "function") throw new Error("gamepad.listen: expects a function")
+      // What is actuated as the listen starts, released before it counts.
+      let held = new Set<string>()
+      let arm = (pads: GamepadState[]) => {
+        let now = new Set<string>()
+        for (let pad of pads) {
+          for (let b of pad.buttons) now.add(b)
+          for (let [name, v] of Object.entries(pad.axes)) if (Math.abs(v) >= LISTEN_THRESHOLD) now.add(name)
+          for (let [name, x, y] of STICKS) if (Math.hypot(pad.axes[x] ?? 0, pad.axes[y] ?? 0) >= LISTEN_THRESHOLD) now.add(name)
+        }
+        for (let name of held) if (!now.has(name)) held.delete(name)
+        return now
+      }
+      for (let name of arm(untrack(pads))) held.add(name)
+      let fresh = (now: Set<string>, name: string) => now.has(name) && !held.has(name)
+      return createRoot(dispose => {
+        createEffect(
+          () => pads(),
+          ps => {
+            let now = arm(ps)
+            let pick = (): InputSource | undefined => {
+              if (kind === "button") {
+                for (let pad of ps) for (let b of pad.buttons) if (fresh(now, b)) return device.button(b)
+                return
+              }
+              if (kind === "axis") {
+                for (let pad of ps) for (let name of Object.keys(pad.axes)) if (fresh(now, name)) return device.axis(name)
+                return
+              }
+              for (let [name] of STICKS) if (fresh(now, name)) return device[name]
+              for (let pad of ps) for (let b of pad.buttons) if (DPAD_BUTTONS.includes(b) && fresh(now, b)) return device.dpad
+            }
+            let source = pick()
+            if (source) found(source)
+          },
+          { defer: true },
+        )
+        return dispose
+      })
     },
   }
+  return device
 }
 
 /** One slot, or every connected pad when `slot` is undefined. */

package/src/input-id.ts

@@ -0,0 +1,92 @@
+// Source ids: the serializable half of a binding. A label is what a
+// settings screen prints ("gamepad 0 south"); an id is what it saves and
+// what a saved file restores from, so it names the source without the
+// device instance: `gamepad:button:south` restores onto whichever pad
+// device the app hands in, and player 2's file lands on player 2's pad.
+//
+// The grammar is one line: `<device>:<spec>` for a device's source, the
+// spec being the device's own vocabulary (input-keyboard.ts,
+// input-gamepad-device.ts, input-pointer.ts each document theirs), and
+// `<processor>(<args>)` around it for a processed one, args separated
+// by commas with ids nested as they are:
+//
+//   keyboard:key:Shift+Tab      keyboard:axis:Minus/Equal
+//   keyboard:vec2:KeyW/KeyS/KeyA/KeyD
+//   gamepad:leftStick           gamepad:button:south       gamepad:axis:leftTrigger
+//   pointer:drag                pointer:drag:Ctrl+Right    pointer:wheel
+//   invert(gamepad:leftStick)   scale(0.5,pointer:wheel)   hold(400,keyboard:key:Space)
+//   chord(keyboard:key:Shift,keyboard:key:KeyA)
+//
+// A custom source names itself under a prefix of its own; load() resolves
+// only the devices it is given and throws on anything else, so a file
+// from another version of the app fails loudly, not silently half-bound.
+
+import type { InputDeviceSet, InputSource } from "./input-map"
+import { chord, doubleTap, hold, invert, scale, tap } from "./input-processors"
+
+// Split processor arguments at top-level commas (nested ids keep theirs).
+let splitArgs = (text: string): string[] => {
+  let out: string[] = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < text.length; i++) {
+    let c = text[i]
+    if (c === "(") depth++
+    else if (c === ")") depth--
+    else if (c === "," && depth === 0) {
+      out.push(text.slice(start, i))
+      start = i + 1
+    }
+  }
+  out.push(text.slice(start))
+  return out
+}
+
+let number = (id: string, text: string): number => {
+  let n = Number(text)
+  if (text.trim() === "" || !Number.isFinite(n)) throw new Error(`resolveSource: "${id}" has a non-numeric argument "${text}"`)
+  return n
+}
+
+/** The source an id names, built from `devices`; throws when the id names
+ * a device not given, an unknown processor, or a spec the device rejects. */
+export function resolveSource(id: string, devices: InputDeviceSet): InputSource {
+  if (typeof id !== "string" || id.length === 0) throw new Error(`resolveSource: expected an id, got ${String(id)}`)
+  let processed = /^([A-Za-z]+)\((.*)\)$/.exec(id)
+  if (processed) {
+    let [, name, inner] = processed
+    let args = splitArgs(inner!)
+    let axis = (i: number) => resolveSource(args[i]!, devices) as InputSource<"axis" | "vec2">
+    let button = (i: number) => resolveSource(args[i]!, devices) as InputSource<"button">
+    let arity = (n: number) => {
+      if (args.length !== n) throw new Error(`resolveSource: ${name}() takes ${n} argument(s), "${id}" gives ${args.length}`)
+    }
+    switch (name) {
+      case "invert":
+        arity(1)
+        return invert(axis(0))
+      case "scale":
+        arity(2)
+        return scale(axis(1), number(id, args[0]!))
+      case "hold":
+        arity(2)
+        return hold(button(1), number(id, args[0]!))
+      case "tap":
+        arity(2)
+        return tap(button(1), number(id, args[0]!))
+      case "doubleTap":
+        arity(3)
+        return doubleTap(button(2), number(id, args[0]!), number(id, args[1]!))
+      case "chord":
+        return chord(...args.map((_, i) => button(i)))
+      default:
+        throw new Error(`resolveSource: unknown processor "${name}" in "${id}"`)
+    }
+  }
+  let colon = id.indexOf(":")
+  if (colon <= 0) throw new Error(`resolveSource: "${id}" names no device (expected "<device>:<spec>")`)
+  let name = id.slice(0, colon) as keyof InputDeviceSet
+  let device = devices[name]
+  if (!device) throw new Error(`resolveSource: no "${name}" device given for "${id}" (given: ${Object.keys(devices).join(", ") || "none"})`)
+  return device.resolve(id.slice(colon + 1))
+}

package/src/input-keyboard.ts

@@ -28,9 +28,14 @@ import { createSignal } from "@solidjs/signals"
 import type { KeyEvent } from "./types"
 import type { InputSource } from "./input-map"
 import type { Vec2 } from "./input-axes"
-import { mostSpecific, parseModifiers } from "./input-chord"
+import { chordName, eventModifiers, mostSpecific, parseModifiers } from "./input-chord"
 import type { Modifier } from "./input-chord"
 
+// Source ids (input-id.ts): `keyboard:key:<spec>`, `keyboard:axis:<neg>/<pos>`,
+// `keyboard:vec2:<up>/<down>/<left>/<right>`; specs as given, so a saved
+// id restores the very spec the app or the player wrote.
+const DEVICE = "keyboard"
+
 // A parsed spec: the text as given (the held-state key and the label),
 // the key it names, and the modifiers the down must carry.
 type Spec = { text: string; key: string; mods: Modifier[] }
@@ -87,6 +92,8 @@ function key(spec: string): InputSource<"button"> {
   return {
     kind: "button",
     label: `keyboard ${spec}`,
+    id: `${DEVICE}:key:${spec}`,
+    device: DEVICE,
     rate: () => state.count() > 0,
     key: state.key,
     blur: state.blur,
@@ -99,6 +106,8 @@ function axis(neg: string, pos: string): InputSource<"axis"> {
   return {
     kind: "axis",
     label: `keyboard ${neg}/${pos}`,
+    id: `${DEVICE}:axis:${neg}/${pos}`,
+    device: DEVICE,
     rate: () => {
       state.count()
       return (state.has(pos) ? 1 : 0) - (state.has(neg) ? 1 : 0)
@@ -117,6 +126,8 @@ function vec2(keys: KeyboardVec2Keys): InputSource<"vec2"> {
   return {
     kind: "vec2",
     label: `keyboard ${keys.up}/${keys.left}/${keys.down}/${keys.right}`,
+    id: `${DEVICE}:vec2:${keys.up}/${keys.down}/${keys.left}/${keys.right}`,
+    device: DEVICE,
     rate: (): Vec2 => {
       state.count()
       return [(state.has(keys.right) ? 1 : 0) - (state.has(keys.left) ? 1 : 0), (state.has(keys.down) ? 1 : 0) - (state.has(keys.up) ? 1 : 0)]
@@ -126,18 +137,54 @@ function vec2(keys: KeyboardVec2Keys): InputSource<"vec2"> {
   }
 }
 
+/** A key event as a spec a rebind binds: the modifiers it carries ahead
+ * of its code (or its key, for a synthetic event without one); null for a
+ * bare modifier key, which names nothing on its own. */
+export function keySpec(event: KeyEvent): string | null {
+  if (MODIFIER_NAMES.has(event.key)) return null
+  let key = event.code || event.key
+  if (!key) return null
+  let mods = chordName(eventModifiers(event))
+  return mods ? `${mods}+${key}` : key
+}
+
+// The logical key names of the modifiers, as key events report them.
+const MODIFIER_NAMES = new Set(["Shift", "Control", "Alt", "Meta"])
+
+// A device spec (the id past "keyboard:") back to a source.
+function resolve(spec: string): InputSource {
+  let colon = spec.indexOf(":")
+  let kind = colon < 0 ? spec : spec.slice(0, colon)
+  let rest = colon < 0 ? "" : spec.slice(colon + 1)
+  let parts = rest.split("/")
+  switch (kind) {
+    case "key":
+      return key(rest)
+    case "axis":
+      if (parts.length !== 2) throw new Error(`keyboard.resolve: "${spec}" needs two keys, neg/pos`)
+      return axis(parts[0]!, parts[1]!)
+    case "vec2":
+      if (parts.length !== 4) throw new Error(`keyboard.resolve: "${spec}" needs four keys, up/down/left/right`)
+      return vec2({ up: parts[0]!, down: parts[1]!, left: parts[2]!, right: parts[3]! })
+    default:
+      throw new Error(`keyboard.resolve: unknown source "${spec}" (key:<spec>, axis:<neg>/<pos>, vec2:<up>/<down>/<left>/<right>)`)
+  }
+}
+
 /**
  * The keyboard device: `keyboard.key("Space")`, `keyboard.axis("KeyQ",
  * "KeyE")`, `keyboard.vec2({ up, down, left, right })`, and the two
  * composites every game binds, `keyboard.wasd` and `keyboard.arrows`.
  * A spec may carry modifiers ("Shift+Tab", "Ctrl+KeyS"). Each call makes
  * an independent source with its own held state; the composites are
- * shared singletons.
+ * shared singletons. `resolve` rebuilds a source from its id's spec.
  */
 export let keyboard = {
+  name: DEVICE as "keyboard",
   key,
   axis,
   vec2,
+  resolve,
   wasd: vec2({ up: "KeyW", down: "KeyS", left: "KeyA", right: "KeyD" }),
   arrows: vec2({ up: "ArrowUp", down: "ArrowDown", left: "ArrowLeft", right: "ArrowRight" }),
 }