@clankagent/puck 0.1.0 → 0.3.0

package/docs/roadmap.md

@@ -0,0 +1,44 @@
+# Toward Puck 1.0
+
+[Documentation](../README.md) · [Changelog](../CHANGELOG.md)
+
+1.0 means the public contracts and interaction behavior are dependable enough
+for applications to adopt without chasing API changes. It does not mean every
+SpaceMouse model or every possible gesture is supported.
+
+## 0.3: tilt families, still experimental
+
+0.3 adds push/pull + rx/ry tilt and standalone tilt singles/doubles, with
+explicit arbitration and ordinary doubles preserved. Defaults use freeform
+physical evidence, supplemented by synthetic boundary tests. This is enough
+for an experimental release, not for 1.0: next evaluate unintended activations
+during ordinary pan/zoom, repeat sessions, and real application adoption.
+The contracts and calibration heuristics remain open to refinement.
+
+## Requirements for 1.0
+
+- **Stable contracts:** settle event shapes, press modes, tune editing and
+  persisted recording/tune formats. Define backward-compatible restoration and
+  errors, and publish a migration guide for any pre-1.0 changes.
+- **Predictable interactions:** cover boundary timing, mixed gestures, diagonal
+  input, incidental cross-axis motion, holds, reversals, report silence,
+  cancellation and double presses. Identical reports must produce identical
+  events regardless of render cadence.
+- **Physical evidence:** evaluate ordinary and combined gestures on real
+  recordings, including unintended activations during pan/zoom. Separate
+  inferred intent from known intended actions; publish the tested scope and
+  remaining uncertainty without shipping private captures.
+- **Honest calibration:** provide useful coverage and ambiguity feedback for
+  every gesture family advertised as automatically tunable. Do not treat the
+  existing eight-action calibration as evidence for directional gestures.
+- **Usable integration:** ship complete browser and transport-independent
+  examples, typed configuration, accessible recording graphs, lifecycle tests,
+  and clear guidance for keeping gesture actions and camera movement exclusive.
+- **Release reliability:** verify CI, the packaged documentation and public
+  exports, then install and exercise the actual registry release. Keep changelog
+  entries linked to adoption documentation.
+
+Additional device profiles, physical buttons, framework adapters and built-in
+rendering are not prerequisites. Add them only for concrete, verified use cases.
+Until these requirements are met, keep gesture APIs experimental and use 0.x
+releases to refine them. There is no date-based promise for 1.0.

package/docs/troubleshooting.md

@@ -0,0 +1,27 @@
+# Troubleshooting
+
+[Documentation](../README.md) · [API reference](api.md)
+
+| Symptom | Check / fix |
+|---|---|
+| Import or graph entry point missing | Gesture and graph APIs require 0.2.0 or later. Check your installed version and package exports; see the upgrade guide. |
+| Bare import fails in browser | Resolve package imports with a bundler or import map. A browser cannot resolve npm package names by itself. |
+| WebHID unavailable / chooser fails | Use a supporting browser and secure context; connect from a user click and display the caught error. Core processing works without WebHID. |
+| Chooser cancelled | A null connection is expected; allow another click. |
+| Device selected but no usable input | Verify the exact profile/report format. Matching vendor alone does not establish support. |
+| First gesture ignored | Startup/reset is blocked until a fresh neutral input. Start recording before moving the cap. |
+| Single feels delayed | Exclusive mode waits for the double window (default 400 ms). Immediate mode fires a single first and then an additive double; it does not undo the single. |
+| Double becomes two singles | Inspect the completion interval and neutral valley. Check doubleMs and release/dwell settings. Do not blindly increase the activation threshold. |
+| Stronger gesture rejected | Typical high is not a rejection cutoff. Check hold duration, competing axis dominance, and neutral return. |
+| Push/pull harder than twist | Use the separate push/pull bands or calibrate; do not force identical thresholds on all axes. |
+| Nothing fires during report silence | Keep calling advance using the same monotonic clock as update. |
+| Clock throws RangeError | Use performance.now() in both report and frame callbacks for gestures. rAF's supplied timestamp can be older than a report already processed. |
+| Actions fire when leaving the page | Treat the WebHID lifecycle sentinel as reset, not a physical release. See the complete session example. |
+| Calibration incomplete | Show missing/counts; add at least three singles and three doubles per direction. Combining distinct captures is supported. |
+| Calibration ambiguous | Close singles may resemble a double; runs of three or more fast pulses are ambiguous. Inspect raw graph and repeat only unclear actions with pauses between independent actions. |
+| Saved tune has no methods | JSON stores data only. Call createGestureTune(JSON.parse(saved)). |
+| Tune edit throws on assignment | Tunes and toJSON data are frozen. Copy nested objects before editing, or use the immutable methods. |
+| Recorder stops adding entries | Inspect full; stop/save and start another capture. Defaults are two minutes / 50000 timeline entries. |
+| Graph overlays wrong session | Pass the zero-based recordingIndex used in the combined calibration. |
+
+When reporting a problem, include package version, runtime/browser, OS, device IDs and connection type, relevant configuration, expected/actual events and a minimal synthetic reproduction when possible. Remove personal information from any raw capture. See [contribution guidance](../CONTRIBUTING.md) for evidence needed for a new profile.

package/docs/tuning.md

@@ -0,0 +1,146 @@
+# Tunes, recording and calibration
+
+[Documentation](../README.md) · [Complete integration](quickstart.md) · [API reference](api.md)
+
+The snippets below explain individual operations. Use the complete integration example for connection, capture start/stop and cleanup.
+
+## Gesture tunes
+
+The experimental gesture API uses an immutable tune object. The default profile
+has a shared rotation center of .465, push .314, and pull .289. It uses rotation
+activation/release .25/.15, push .20/.08, pull .12/.06, neutral dwell 25 ms, and a
+400 ms double window. These are useful starting defaults, not universal hardware
+calibration. Pan/zoom behavior is unchanged.
+
+```js
+import {
+  createGestures, createGestureTune, defaultGestureTune, gesturePresets,
+} from '@clankagent/puck';
+
+const tune = defaultGestureTune.soften(0.1).widen(0.15);
+const gestures = createGestures(tune);
+// createGestures() uses defaultGestureTune.
+// Also available: gesturePresets.default, .soft (20% softer), .hard (20% harder).
+
+const saved = JSON.stringify(tune);
+const restored = createGestureTune(JSON.parse(saved));
+const another = restored.harden(0.05).narrow(0.1);
+```
+
+Every edit returns a new deeply frozen object, including its nested bands.
+Amounts are fractions: `.soften(.1)` lowers force levels by 10%; `.harden(.1)`
+raises them by 10%. Levels saturate at normalized full scale. `.narrow(.1)`
+reduces distances from the center by 10%, moving the activation gate toward the
+center; `.widen(.1)` expands them and lowers the activation gate. Release remains
+proportional to activation. These methods edit force only; timing remains unchanged.
+Softening and narrowing require amounts in [0,1); hardening and widening accept
+[0,10]. Edits are composable, not algebraic inverses: softening by 10% and then
+hardening by 10% gives 99% of the original force.
+
+Each `rotation`, `push`, and `pull` band contains `center`, `low`, `high`,
+`activation`, and `release`. Low/high describe typical peak variation; they are
+not rejection boundaries. Stronger-than-typical input still counts. Rotation
+always shares a band between clockwise and counterclockwise. `toJSON()` returns
+portable versioned data; `toOptions()` returns the low-level recognizer options.
+For precise timing edits, copy both `toJSON()` and its nested `timing` object, then call
+`createGestureTune(data)` to validate it.
+
+The low-level `createGestures(options)` overload remains available. Missing
+settings use the default tune; `createGestures({})` matches `createGestures()`.
+Explicit signed-direction gates override axis gates, which override shared
+activation/release values. Prefer a tune object for complete configuration.
+## Recording and custom calibration
+
+A complete calibration needs at least **three of each of eight actions**:
+clockwise single/double, counterclockwise single/double, push single/double,
+and pull single/double. Grouping examples is convenient but not required.
+Use short pulses and leave a pause between separate actions. The parser uses
+raw deflection and timing, not the order of action groups or recorded event labels.
+
+```js
+import {
+  createGestureRecorder, createGestures, defaultGestureTune,
+  calibrateGestures, neutralInput,
+} from '@clankagent/puck';
+
+const gestures = createGestures(defaultGestureTune);
+const recorder = createGestureRecorder({
+  startTimeMs: performance.now(), tune: defaultGestureTune, source: 'device',
+});
+
+// Call for every report; don't discard reports between render frames.
+function onInput(input) {
+  const now = performance.now();
+  if (input === neutralInput) { // WebHID lifecycle sentinel, not physical release
+    gestures.reset(); recorder.reset(now); return;
+  }
+  recorder.input(input, now);
+  const events = gestures.update(input, now);
+  recorder.events(events);
+  consume(events); // Your application handles recognized actions.
+}
+function frame() {
+  const now = performance.now(); // Same clock used by onInput.
+  recorder.advance(now);
+  const events = gestures.advance(now);
+  recorder.events(events);
+  consume(events);
+  requestAnimationFrame(frame);
+}
+// Wire WebHID onReset to reset both processors as well.
+// Start your frame loop and pass onInput to your transport.
+
+const recording = recorder.snapshot(performance.now()); // At the end of capture.
+// Your app can download JSON.stringify(recording) or save it to its own backend.
+const result = calibrateGestures(recording);
+// Or combine sessions: calibrateGestures([recordingA, recordingB]).
+if (result.tune !== null) {
+  const tunedGestures = createGestures(result.tune);
+  // Save JSON.stringify(result.tune) for the next session.
+}
+```
+
+The SDK owns no timers, listeners, storage or network access. The recorder copies
+samples, has a default two-minute / 50,000-entry bound, reports `full`, and
+returns detached snapshots. Apps own start/stop and storage. Raw records include
+six axes, relative timestamps, frame ticks, resets, and optional recognized
+events. The latest input remains held during report silence. Reset cancels
+recognition and requires a fresh neutral sample. Use `performance.now()` in both
+callbacks; rAF's supplied timestamp can precede a report already processed.
+
+Calibration returns `status`, `tune`, `counts`, `missing`, `stats`, `pulses`,
+`actions`, and `issues`. Incomplete or ambiguous input returns `tune: null`;
+counts never claim labeled ground-truth accuracy. Quick same-direction singles
+can be indistinguishable from an intended double. Runs of three or more closely
+spaced pulses are flagged as ambiguous. Separate sessions and resets are never
+paired. Long holds, unfinished excursions, and very short spikes are excluded.
+
+The initial parser uses a normalized .025 detection floor, local peak/valley
+shape and a 250 ms maximum inter-pulse gap for pairs. These can be configured
+with `detectionFloor` and `pairGapMs`. `minimumPerAction` can raise the requirement
+but cannot go below three. Candidate centers are per-direction mean peak force;
+rotation uses the unweighted average of the two direction means. Typical bands
+use interpolated 10th/90th percentiles. Gates and timing are derived conservatively
+from observed weaker peaks, return valleys, pulse lengths and double intervals.
+Calibration infers intended actions; it is not evidence of subjective feel or
+new hardware compatibility.
+
+## Graphs for consuming applications
+
+```js
+import { createGestureGraph, renderGestureGraphSvg } from '@clankagent/puck/graph';
+
+const model = createGestureGraph(recording, result.tune ?? defaultGestureTune, {
+  actions: result.actions,
+  // Optional start/end in milliseconds to inspect an individual action.
+});
+container.innerHTML = renderGestureGraphSvg(model, { width: 900 });
+```
+
+`createGestureGraph` returns renderer-neutral data for four separate positive
+magnitude lanes. The optional SVG renderer has no DOM dependencies: it labels
+directions, typical peaks, activation and release, preserves held samples as
+steps, and highlights inferred action intervals. Its text is escaped. For
+combined calibrations, pass the corresponding recording and `recordingIndex`.
+Apps can use the model with their own chart library instead. Only graph a tune
+when available; incomplete calibration can be inspected with the default tune.

package/docs/upgrading.md

@@ -0,0 +1,59 @@
+# Upgrading and adopting updates
+
+[Changelog](../CHANGELOG.md) · [Documentation](../README.md) · [API reference](api.md)
+
+## Identify the version first
+
+Read the changelog for the version you are adopting, then use docs from that same tag or installed package. Main can contain unreleased features. `pnpm list @clankagent/puck` shows your app's installed version; its exports and declarations determine which APIs are available.
+
+Gesture, tune, recording, calibration and graph APIs are included in 0.2.0. In your consuming app:
+
+```sh
+pnpm add @clankagent/puck@0.3.0
+pnpm list @clankagent/puck
+```
+
+Commit your app's updated manifest and lockfile. Use the documentation shipped with that package or the v0.3.0 source tag. The new gesture APIs remain experimental; existing motion integrations retain their behavior.
+
+To test future unreleased source, build a chosen revision with `pnpm install --frozen-lockfile`, `pnpm check` and `pnpm pack --pack-destination artifacts`, then install the generated tarball into your app with `pnpm add /path/to/package.tgz`. Record the source commit alongside it; a working-tree package version alone does not identify unreleased changes.
+
+## From 0.2 to 0.3
+
+No new gesture family is enabled automatically. Add `standaloneTilt:true` for
+rx/ry singles and doubles; add `pressMode:'auto'` or `'tilt'` for push/pull +
+tilt combinations. Keep `singleMode:'exclusive'` when combined modes are enabled.
+See the [tilt integration guide](press-tilt.md) for event examples, default gates,
+freeform calibration and graphs. Feed every physical report and advance the clock
+as before; camera arbitration remains application-owned.
+
+`GestureDirection` now also includes four rx/ry directions. TypeScript consumers
+with exhaustive direction maps must extend them, even if the feature stays off.
+Use exported `PulseDirection` for APIs intentionally limited to the original four.
+Combined events add an optional `tilt`; route those before handling plain pressure.
+Tune version stays 1 with optional new fields; old tune JSON is supported.
+
+## Existing pan/zoom applications
+
+No migration is required for the new opt-in features: decoding, `createPanZoom` and `/webhid` behavior and defaults are unchanged from the original baseline. Keep your existing camera, input ownership and render loop.
+
+## Add only what your app needs
+
+| Goal | Add | Application responsibility |
+|---|---|---|
+| React to single/double gestures | `createGestures(tune)` | Feed every report, advance the same clock, reset on lifecycle changes, consume events. [Complete integration](quickstart.md) |
+| Offer softer/harder controls | Presets and immutable tune methods | Retain the returned tune and create a new recognizer to apply it. [Tune editing](tuning.md#gesture-tunes) |
+| Save a personal tune | `createGestureTune` | Save JSON; restore through the constructor. [Tune API](api.md#tunes) |
+| Learn a tune from normal input | Recorder plus `calibrateGestures` | Own capture/storage; show missing/ambiguous evidence and apply only a non-null tune. [Calibration](tuning.md#recording-and-custom-calibration) |
+| Explain the learned result | Optional `/graph` imports | Show a text status/count summary and select the matching capture for overlays. [Graphs](api.md#graphs) |
+
+To add gestures alongside motion, reuse the existing connection and frame loop. Fan physical reports out to both processors. Ignore the exact `neutralInput` lifecycle sentinel for gestures and reset both processors in `onReset`. Use `performance.now()` in both gesture report and frame callbacks. The [session example](../examples/gesture-session.mjs) demonstrates lifecycle handling; adapt it to your existing connection/loop rather than starting duplicate ones.
+
+## Behavior to choose explicitly
+
+- **Single versus double:** exclusive singles wait for the double window. Immediate mode is additive: a double also produces the earlier single. It does not undo an action.
+- **Gesture versus camera:** both processors may react to the same movement. Your app decides whether a gesture tool pauses camera motion or permits both.
+- **Applying a tune:** changing a variable does not retune an existing recognizer. Replace the recognizer or reconnect the example session with the new tune; pending actions are discarded and fresh neutral is required.
+- **Calibration quality:** require three singles and three doubles in each direction. Group order does not matter. Closely spaced singles can look like a double; inferred counts are not labeled accuracy. Avoid duplicate captures as new evidence.
+- **Data versions:** package versions are separate from tune/recording `version: 1`. Validate restored data through public APIs; do not manually change a format version to bypass validation.
+
+Before shipping, check a single, double, held input, neutral rearming, blur/disconnect and teardown. Check JSON restoration and incomplete calibration if used. [Troubleshooting](troubleshooting.md) maps common symptoms to fixes.

package/examples/gesture-session.mjs

@@ -0,0 +1,56 @@
+import { createGestures, createGestureRecorder, defaultGestureTune, neutralInput } from '@clankagent/puck';
+import { connectWebHid } from '@clankagent/puck/webhid';
+
+/** Call from a click handler. Returns null when the chooser is cancelled. */
+export async function connectGestureSession({ tune = defaultGestureTune, options = {}, onEvents = console.log, onDisconnect = () => {} } = {}) {
+  const configuration = {...tune.toOptions(),...options};
+  const gestures = createGestures(configuration);
+  let recorder = null;
+  let frameId;
+  let stopped = false;
+  function emit(events) { recorder?.events(events); if (events.length) onEvents(events); }
+  function reset() { gestures.reset(); recorder?.reset(performance.now()); }
+  const connection = await connectWebHid({
+    onInput(input) {
+      // Lifecycle sentinel is followed by onReset, not a physical release.
+      if (input === neutralInput) return;
+      const now = performance.now();
+      recorder?.input(input, now);
+      emit(gestures.update(input, now));
+    },
+    onReset: reset,
+    onDisconnect() { stopped = true; cancelAnimationFrame(frameId); onDisconnect(); },
+  });
+  if (!connection) return null;
+  function frame() {
+    if (stopped) return;
+    // Same current clock as reports, not rAF's earlier frame timestamp.
+    const now = performance.now();
+    recorder?.advance(now);
+    emit(gestures.advance(now));
+    frameId = requestAnimationFrame(frame);
+  }
+  frameId = requestAnimationFrame(frame);
+  return {
+    startRecording() {
+      if (stopped) throw new Error('Session has ended.');
+      if (recorder) throw new Error('Stop the current recording first.');
+      gestures.reset();
+      recorder = createGestureRecorder({ startTimeMs: performance.now(), options:configuration, source: 'device' });
+    },
+    stopRecording() {
+      if (!recorder) return null;
+      const recording = recorder.snapshot(performance.now());
+      recorder = null;
+      return recording;
+    },
+    get recordingFull() { return recorder?.full ?? false; },
+    pause: connection.pause,
+    resume: connection.resume,
+    async close() {
+      stopped = true;
+      cancelAnimationFrame(frameId);
+      await connection.close();
+    },
+  };
+}

package/llms.txt

@@ -0,0 +1,29 @@
+# Puck
+
+> TypeScript/ESM six-axis input, pan/zoom, tunable cap gestures and freeform calibration. Zero runtime dependencies.
+
+Documentation targets 0.3.0, including experimental gesture/tune/recording/calibration/graph APIs. Match documentation to your installed version.
+
+## Documentation
+
+- [Overview and version status](README.md)
+- [Changelog and compatibility](CHANGELOG.md)
+- [Upgrade and integration paths](docs/upgrading.md)
+- [Complete integration](docs/quickstart.md)
+- [API reference: imports, units, defaults, lifecycle](docs/api.md)
+- [Tunes, recording and calibration](docs/tuning.md)
+- [Motion and hardware scope](docs/motion.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Agent integration invariants](docs/agents.md)
+- [Runnable session wrapper](examples/gesture-session.mjs)
+- [Camera arithmetic](examples/camera.mjs)
+
+## Source development
+
+- [Contribution workflow](CONTRIBUTING.md)
+- [Repository agent instructions](AGENTS.md)
+- [Local gesture lab](docs/lab.md)
+- [Next release and 1.0 criteria](docs/roadmap.md)
+- [Standalone and combined tilt API](docs/press-tilt.md)
+
+Exact build signatures are in dist/index.d.ts, dist/webhid.d.ts and dist/graph.d.ts. Import from @clankagent/puck, @clankagent/puck/webhid and @clankagent/puck/graph only.

package/package.json

@@ -1,15 +1,27 @@
 {
   "name": "@clankagent/puck",
-  "version": "0.1.0",
-  "description": "Frame-independent six-axis input and pan/zoom motion for the web",
+  "version": "0.3.0",
+  "description": "Frame-independent six-axis input, pan/zoom and tunable gestures",
   "type": "module",
   "sideEffects": false,
   "files": [
     "dist",
     "README.md",
-    "examples/camera.mjs"
+    "CHANGELOG.md",
+    "docs",
+    "llms.txt",
+    "examples/camera.mjs",
+    "examples/gesture-session.mjs",
+    "AGENTS.md",
+    "CONTRIBUTING.md",
+    "DESIGN.md",
+    "VERIFICATION.md"
   ],
   "exports": {
+    "./graph": {
+      "types": "./dist/graph.d.ts",
+      "import": "./dist/graph.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -42,6 +54,8 @@
     "input"
   ],
   "scripts": {
+    "lab": "node examples/gestures/serve.mjs",
+    "lab:analyze": "node examples/gestures/analyze-recording.mjs",
     "build": "tsc -p tsconfig.json",
     "test": "node --test tests/*.test.mjs",
     "check": "pnpm run build && pnpm test"