@clankagent/puck 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,9 @@
+# Package development
+
+Puck is a public library hosted at https://github.com/clankagent/puck, published as @clankagent/puck. Maintain the focused library scope: source, tests, documentation and small code examples. Do not add a website, test page, local server or router setup unless explicitly requested.
+
+Keep the package self-contained. Do not introduce references to private applications, internal servers, local recordings, machine paths, or user metadata. No dependencies on surrounding workspaces. Preserve the established feel when extracting or optimizing; validate timing and neutral behavior with tests.
+
+Input transport, motion processing, and application rendering are separate responsibilities. The core owns no DOM, global listeners or render loop. Browser lifecycle belongs to the optional adapter; camera limits and zoom anchors belong to the consuming application. Avoid framework adapters and additional device abstractions without a concrete use case.
+
+Use pnpm. This library uses the TypeScript compiler and Node's test runner; no Vite application is being created. Run `pnpm check` before delivery. Additional device profiles require evidence; do not claim untested compatibility. Synthetic fixtures are generated from documented report layouts and physical observations, without original capture metadata.

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+User-facing changes, compatibility impact, and links for adopting them. **Unreleased** describes source on main, not an available npm version. Package versions and tune/recording JSON format versions are independent.
+
+## 0.2.0 — 2026-09-19
+
+### Added
+
+| Feature | What it enables | Integration docs |
+|---|---|---|
+| Four-direction single/double cap gestures | Clockwise, counterclockwise, push down and pull up actions | [Browser quickstart](docs/quickstart.md), [event and timing API](docs/api.md#gestures) |
+| Immutable gesture tunes | Shared rotation thresholds, independent push/pull thresholds, default/soft/hard presets and chainable edits | [Tune guide](docs/tuning.md#gesture-tunes), [tune API](docs/api.md#tunes) |
+| Bounded recording SDK | Capture reports, clock ticks, resets and events using the app's storage | [Session example](examples/gesture-session.mjs), [recording API](docs/api.md#recording) |
+| Automatic custom calibration | Infer a tune from freeform captures with three examples of each of eight actions, in any order | [Calibration guide](docs/tuning.md#recording-and-custom-calibration), [result handling](docs/api.md#calibration) |
+| Optional graph entry point | Four direction lanes, inferred action spans and an accessible SVG renderer | [Graph guide](docs/tuning.md#graphs-for-consuming-applications), [graph API](docs/api.md#graphs) |
+| Source-only gesture lab | Record, combine captures, inspect actions, edit tunes and export JSON | [Run the lab](docs/lab.md) |
+| User and agent documentation | API reference, troubleshooting, complete integration and a plain-text index | [Documentation index](README.md#start-here), [agent guide](docs/agents.md), [llms.txt](llms.txt) |
+
+### Compatibility and adoption
+
+- Existing `createPanZoom`, decoding and WebHID APIs/defaults are unchanged from the original 0.1.0 source baseline. Existing motion integrations need no migration for these additions.
+- Gesture APIs are experimental and opt-in. The app still owns its clock, render loop, actions and storage. Adding gestures does not automatically bind actions or suppress pan/zoom.
+- Exclusive singles wait for the double window; immediate mode emits a single followed by an additive double. Choose deliberately.
+- Tune and recording JSON formats start at `version: 1`. Restore tunes through `createGestureTune`; handle a null calibration tune before applying results.
+- Hardware scope is unchanged. Cap gestures do not add physical button decoding or support for unverified devices.
+
+**Adopt the update:** [Upgrade and integration guide](docs/upgrading.md). [Source comparison with the original baseline](https://github.com/clankagent/puck/compare/f065d4a...v0.2.0).
+
+## Original 0.1.0 source baseline
+
+This is a source-history reference, not a claim that an npm release was published on a particular date.
+
+- Normalized six-axis decoding for the verified combined report profile.
+- Frame-independent pan/zoom with held input, neutral stopping and application-owned camera/rendering.
+- Optional WebHID connection, foreground lifecycle resets and cleanup.
+- ESM and TypeScript declarations, no runtime dependencies.
+
+[Baseline source](https://github.com/clankagent/puck/tree/f065d4a) · [Motion behavior and hardware](docs/motion.md)

package/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing
+
+Use Node 24 and the pnpm version in package.json. Run pnpm install and pnpm check.
+Small fixes can go straight to a pull request. For a new API or device profile,
+open an issue describing the use case first so we can agree on the scope.
+
+Keep transport, processing and rendering separate. Preserve neutral stopping,
+held input between reports and frame-rate independence. Include a regression
+test for behavioral changes. Avoid adding dependencies or per-frame work without
+a measured need.
+
+For device support, include vendor/product IDs, connection type, browser/OS,
+report descriptor and a short sequence of report IDs and hexadecimal payloads
+for neutral, each single-axis gesture, hold and release. Relative timestamps
+are sufficient. Remove serial numbers, device names, account information and
+other personal metadata. Do not infer support from a shared vendor ID.
+
+Only describe physical behavior as tested when someone has actually tested it.
+Synthetic report tests establish decoding and lifecycle behavior, not hardware
+compatibility or subjective feel.

package/DESIGN.md

@@ -0,0 +1,42 @@
+# Architecture and release preparation
+
+The product goal is to make responsive six-axis interaction easy to implement correctly. Correct defaults and clear ownership matter more than exposing many switches.
+
+## Boundaries
+
+The core consumes normalized deflection and frame timestamps. It produces screen-space pan deltas and a multiplicative zoom factor. It does not own a view transform, renderer, event loop, browser or device. Incoming reports update a held sample; they never directly advance a camera.
+
+The optional WebHID adapter decodes one verified device profile, handles explicit device permission and connection lifetime, and forwards samples. It clears input on interruption. A consuming application can pause input when a modal/tool takes ownership, or use the core with another transport entirely.
+
+The example camera demonstrates the application boundary: apply the zoom multiplier within app limits, preserve the chosen screen-space anchor using the actual clamped zoom ratio, then apply pan deltas in pixels. This avoids accidentally scaling pan speed with zoom or moving the zoom anchor when a limit is reached.
+
+## Defaults backed by the working prototype
+
+Six-axis combined report: six signed little-endian words, logical range ±350. Device profile 256f:c63a. Clockwise twist and downward pressure zoom in. Independent pan/zoom deadzones .05/.1; acceleration response 25 ms; full pan speed 1320 px/s; full log-zoom speed 1.5/s. Integrate the response analytically over elapsed frame time. Neutral stops without coasting; reversal discards old-direction response. Cap unusually long frame integration at 50 ms; do not expire held input based on report silence.
+
+These are verified defaults for the tested hardware and interaction. They are not a claim that every device uses the same report layout or that everyone prefers the same axis directions.
+
+## Package shape
+
+One ESM TypeScript package, core and `/webhid` exports, no runtime dependencies. Emitted declarations use explicit `.js` relative specifiers and a Node-compatible module resolution mode. Tests import built output, keeping package behavior visible outside the compiler. A renderer can use the core without importing browser glue. [TypeScript library compilation guidance](https://www.typescriptlang.org/docs/handbook/modules/guides/choosing-compiler-options.html#im-writing-a-library), [WebHID lifecycle and reports](https://developer.chrome.com/docs/capabilities/hid).
+
+## Release scope
+
+Puck ships a core and an optional WebHID adapter. No website, renderer or server
+is part of the library. The first release documents the measured hardware scope
+and distinguishes prototype physical testing from extracted-adapter tests.
+
+## Tune and calibration API
+
+Tune data is immutable, versioned JSON with shared rotation and independent
+push/pull force bands. Method edits copy rather than mutate and do not affect
+timing. Gesture recording is a bounded transport-independent utility; apps
+retain responsibility for storage and permissions. Calibration consumes raw
+samples independently of the old recognizer event log or the order of action
+groups, and requires three examples per action. Uncertain trains and missing
+coverage cannot produce a ready tune.
+
+The optional /graph export provides renderer-neutral data and a standalone SVG
+renderer. It draws four unsigned direction lanes instead of overlaying two
+signed axes and four gates. It owns no DOM, camera, subscriptions or frame loop.
+The lab adds selection/zoom and tune editing as application responsibilities.

package/README.md

@@ -1,88 +1,51 @@
 # Puck
 
-A small TypeScript library for responsive SpaceMouse pan and zoom. Zero runtime dependencies.
+Six-axis input, responsive pan/zoom, and tunable single/double gestures for SpaceMouse applications. TypeScript, ESM, zero runtime dependencies. Your app owns its camera, rendering and storage.
 
-Incoming reports update input state. Your animation loop consumes time-based motion. Your application owns the camera and renderer.
+**Version note:** these docs target 0.2.0. Gesture recognition, tunes, recording, calibration and graphs are included, with experimental APIs. See the [changelog](CHANGELOG.md) and [upgrade guide](docs/upgrading.md) when moving from 0.1.0.
 
-```sh
-pnpm add @clankagent/puck
-```
+## Start here
 
-```js
-import { createPanZoom } from '@clankagent/puck';
-import { connectWebHid } from '@clankagent/puck/webhid';
+| You want to… | Read |
+|---|---|
+| See what changed and adopt an update | [Changelog](CHANGELOG.md), [upgrade guide](docs/upgrading.md) |
+| Connect a device and recognize gestures | [Complete browser integration](docs/quickstart.md) |
+| Add smooth pan and zoom | [Motion and hardware](docs/motion.md), [camera arithmetic](examples/camera.mjs) |
+| Set sensitivity or learn a personal tune | [Tunes, recording and calibration](docs/tuning.md) |
+| Look up imports, methods, defaults or units | [API reference](docs/api.md) |
+| Fix input or calibration problems | [Troubleshooting](docs/troubleshooting.md) |
+| Integrate using an agent | [Agent integration guide](docs/agents.md), [plain-text index](llms.txt) |
+| Try and record real input | [Gesture lab](docs/lab.md) |
 
-const motion = createPanZoom({ zoomInput: 'press' });
+For a registry release, install with `pnpm add @clankagent/puck`. For this checkout:
 
-connectButton.onclick = async () => {
-  connectButton.disabled = true;
-  try {
-    connection = await connectWebHid({
-      onInput: motion.setInput,
-      onReset: motion.reset,
-      onDisconnect() { connection = null; connectButton.disabled = false; },
-    });
-  } finally {
-    connectButton.disabled = Boolean(connection);
-  }
-};
+```sh
+pnpm install
+pnpm check
+```
 
-function frame(timestamp) {
-  const delta = motion.step(timestamp);
-  if (delta.moving) {
-    // Apply zoom about your chosen anchor, then pan in screen pixels.
-    camera.zoomAround(viewCenter, delta.zoomFactor);
-    camera.panBy(delta.panX, delta.panY);
-    render(camera);
-  }
-  requestAnimationFrame(frame);
-}
-let connection = null;
-requestAnimationFrame(frame);
+The build emits `dist/*.js` and matching TypeScript declarations. Examples use package imports; a bundler or browser import map must resolve them. No CommonJS build is provided.
 
-// A control can change this live. Pan and camera position are unaffected.
-motion.setZoomInput('twist');
+```js
+import { createGestures, gesturePresets } from '@clankagent/puck';
 
-// On application teardown:
-// await connection?.close();
-// Cancel the application's animation frame as part of its own cleanup.
+const tune = gesturePresets.default.soften(0.1).widen(0.15);
+const gestures = createGestures(tune);
+// Feed every report to update(input, time), and tick advance(time).
+// See the complete integration for clocks, lifecycle and cleanup.
 ```
 
-`camera`, `render`, `viewCenter` and `connectButton` above belong to your app. There is no camera implementation or framework dependency in the package. See `examples/camera.mjs` for the complete anchor calculation, including zoom limits.
-
-## Responsibilities
+## What Puck owns
 
-| Part | Responsibility |
+| Layer | Responsibility |
 |---|---|
-| Decoder | Convert a supported motion report to normalized six-axis cap deflection; ignore status packets. |
-| WebHID adapter | Device selection, report delivery, foreground policy and connection cleanup. |
-| Pan/zoom controller | Hold the latest input, apply deadzones, integrate response over frame time, emit movement deltas. |
-| Your application | Own the render loop, input ownership, camera, zoom anchor, limits, and rendering. |
+| Core `@clankagent/puck` | Decode reports; process motion and gestures; record samples; derive tunes. No browser globals, timers or storage. |
+| Optional `/webhid` | Device chooser, reports and connection lifecycle. |
+| Optional `/graph` | Four-lane graph data and a standalone SVG renderer. |
+| Your app | Render loop, action handling, camera, capture controls, persistence and UI. |
 
-The core imports in Node without a browser. The browser adapter is a separate entry point and accesses browser APIs only when connecting. It starts no animation loop, timers, server, storage, or telemetry.
-
-## Motion behavior
-
-- `step(timestampMs)` uses the timestamp supplied by your render loop, once per frame. The first step produces no movement. It never assumes a display refresh rate.
-- A held cap requests velocity. Input report count does not determine movement distance. The latest deflection remains active between reports, including bursty delivery.
-- Pan has a 0.05 normalized deadzone and full-deflection speed of 1320 screen pixels/second. Zoom has a 0.1 deadzone and log-speed of 1.5/second. Both use a 25 ms acceleration response.
-- Neutral input stops on the next step, without software coasting. Reversal discards response in the old direction.
-- `twist`: clockwise zooms in. `press`: downward pressure zooms in, lifting zooms out. These directions refer to the verified profile.
-- The default 50 ms frame cap limits jumps after rendering stalls. It is not a timeout for input reports.
-- The adapter clears input on blur, hidden state and disconnect. Connect `onReset` to `motion.reset` as above so old response and frame timing are also cleared. Returning to the foreground waits for a fresh report. Use connection `pause()` / `resume()` when another tool owns the input; use controller `reset()` if you provide your own transport.
-- Use one controller per independent input stream. Do not drive both the report callback and frame loop with movement updates.
-
-## Hardware scope
-
-The report layout and motion defaults were measured with vendor `0x256f`, product `0xc63a`, over Bluetooth on Windows: report 1, twelve bytes, six signed little-endian 16-bit axes, logical range ±350. Buttons and other layouts are not implemented yet. Other devices require a matching `DeviceProfile`; profile support should be backed by descriptors and captures, not guessed from the vendor alone.
-
-WebHID requires browser support and device permission. The adapter inherits that availability; the motion core does not. [Official WebHID guide](https://developer.chrome.com/docs/capabilities/hid).
+The verified device profile is vendor `0x256f`, product `0xc63a`, Bluetooth on Windows. Other layouts and physical buttons are not implemented. Gestures are **cap pulses**, not button clicks. See [hardware scope](docs/motion.md#hardware-scope) before adding a profile.
 
 ## Development
 
-```sh
-pnpm install
-pnpm check
-```
-
-The build emits ESM and declarations. Tests run against those emitted modules. Runtime dependencies: none. Licensed under MIT. See [CONTRIBUTING.md](CONTRIBUTING.md) for development and device support.
+Use Node 24 and the pnpm version pinned in `package.json`. `pnpm check` builds and runs tests. Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing an API or device profile; [AGENTS.md](AGENTS.md) describes repository development constraints. [DESIGN.md](DESIGN.md) explains architecture and [VERIFICATION.md](VERIFICATION.md) records validation. MIT licensed.

package/VERIFICATION.md

@@ -0,0 +1,78 @@
+# Local preparation checks
+
+- TypeScript build and 13 tests pass. Tests cover report bounds/signs, zero and non-motion handling, frame-rate independence, held input through report gaps, reversal, zoom-axis switching, snapshots, render-owned zoom anchors/limits, adapter pause/resume/disconnect, foreground interruption and cleanup.
+- A separate local comparison against the working prototype evaluated 3,558 frames at 60, 144 and 240 Hz, both zoom mappings, neutral/reversal and mixed-axis input. Pan and camera zoom matched exactly (maximum difference zero). The comparison harness remains outside this package.
+- Packed artifact installs into a separate ESM TypeScript consumer. Both public entry points resolve, declarations type-check, and importing the adapter in Node does not access browser globals. The packed artifact contains emitted code/declarations, package metadata and README; original captures and workspace documentation are excluded.
+- The extracted adapter has not yet been exercised with physical hardware. Physical testing established the report layout and motion defaults in a prototype; adapter lifecycle coverage is currently synthetic.
+- Package name: @clankagent/puck. License: MIT. Publication status is available from GitHub releases and the npm registry.
+
+## Gesture experiment (2026-09-18)
+
+- `pnpm check`: 26 tests pass. Added four-direction single/double coverage,
+  additive behavior, completion-window boundaries, pulse limits, hysteresis,
+  neutral dwell, reversal rejection, dominance, cancellation, timestamp validation,
+  report bursts, frame-rate independence, and WebHID lifecycle cancellation.
+- Browser QA over HTTPS: pointer double rotation, keyboard single pull, preset
+  changes, save/restore comparison, and clear history verified. Zero minimum
+  pulse/dwell were used for instantaneous automation; balanced defaults restored.
+- Desktop and 390px phone layouts visually inspected. Input trace and threshold
+  lines render; event table fits the phone layout.
+- Fixed mixed report/rAF clock timestamps by using performance.now() in both
+  callbacks. Lifecycle neutral sentinels cancel rather than complete gestures.
+- At this stage the gesture work was a local experiment. Later SDK and delivery
+  verification is recorded below; inferred replay does not establish subjective feel.
+
+## Freeform recording (2026-09-18)
+
+- Recording is the first section. No guided capture or prescribed gesture order.
+- Stores input reports, frame timing, resets and detected events; settings locked
+  during capture, two-minute cap, retry/download fallback, and saved session list.
+- 29 tests pass, including schema validation, session-token enforcement,
+  save/list/readback, and deterministic replay.
+- Browser simulator recording was saved and then read directly by the analysis
+  CLI. Replayed double matched the recorded event; a pending final single was
+  reported correctly. Simulator evidence is not physical gesture calibration.
+- User feedback: vertical push/pull activation should be lower than rotation.
+  Capture raw data first, then infer suitable separate thresholds from natural use.
+
+## Direction threshold refinement
+
+- Added validated axis/direction overrides without changing existing defaults.
+- Lab has one symmetric rotation gate and independent push/pull gates.
+- Recording tuned preset uses rotation activation/release .25/.15, push .20/.08,
+  pull .12/.06, neutral dwell 25 ms, and double window 400 ms.
+- 33 tests pass. Synthetic regressions cover gentle vertical input, independent
+  signs, cross-axis pressure during twist, partial release and invalid thresholds.
+- Physical freeform replay yields 18 doubles and 17 singles under the candidate
+  profile. These are inferred gesture groups, not ground-truth accuracy labels.
+
+## Reusable tune / calibration SDK
+
+- Added immutable versioned tune objects, default/soft/hard presets, fractional
+  soften/harden/narrow/widen transformations and JSON restoration. Missing
+  recognizer configuration now uses the complete default tune consistently.
+- Added bounded recording independent of transport, browser, timers and storage.
+- Added raw-shape calibration, independent of recorded event labels and action
+  ordering. At least three of each of eight actions are required; incomplete or
+  ambiguous evidence produces no tune. Multiple recordings can be combined;
+  reset/session boundaries prevent accidental pairing.
+- 42 tests pass, including shuffled action groups, ambiguity, missing evidence,
+  immutable transforms, JSON round trips, recording bounds, default parity and
+  graph output. Existing pan/zoom, decoding and lifecycle tests continue to pass.
+- The physical freeform capture passes all eight quotas; the automatically
+  generated tune reproduces 18 double and 17 single actions on replay. This is
+  consistency with inferred intent, not a claim of labeled accuracy.
+- Browser QA: analyze saved capture, zoom a double, soften/reset/apply tune,
+  deduplicate combined captures, desktop/phone graph inspection. Mobile graph
+  labels and width were adjusted after visual inspection.
+
+## Documentation and repository delivery (2026-09-18)
+
+- 43 tests pass, including the public integration example's recording lifecycle,
+  pending-action cancellation and frame cleanup.
+- README navigation, API reference, browser integration, calibration guide,
+  troubleshooting and agent guidance are included in the packed artifact.
+- Checked 48 relative documentation links. Package inspection confirms docs and
+  reusable examples ship, while the lab server and raw recordings stay excluded.
+- Gesture APIs remain experimental and are not yet an npm release. Source delivery
+  includes the gesture lab; captured device recordings remain outside the repository.

package/dist/calibration.d.ts

@@ -0,0 +1,49 @@
+import type { GestureDirection } from './gestures.js';
+import type { GestureTune } from './tune.js';
+import type { GestureRecording } from './recording.js';
+export declare const gestureDirections: readonly ['clockwise', 'counterclockwise', 'push', 'pull'];
+export type GestureActionName = `${GestureDirection}.${'single' | 'double'}`;
+export interface CalibrationPulse {
+    direction: GestureDirection;
+    start: number;
+    end: number;
+    peak: number;
+    peakTime: number;
+    valleyBefore: number;
+    recording: number;
+    segment: number;
+}
+export interface CalibrationAction {
+    direction: GestureDirection;
+    kind: 'single' | 'double';
+    start: number;
+    end: number;
+    pulses: CalibrationPulse[];
+    recording: number;
+}
+export interface CalibrationStats {
+    count: number;
+    center: number;
+    low: number;
+    high: number;
+    min: number;
+    max: number;
+}
+export interface GestureCalibration {
+    status: 'ready' | 'incomplete' | 'ambiguous';
+    tune: GestureTune | null;
+    counts: Record<GestureActionName, number>;
+    missing: GestureActionName[];
+    pulses: CalibrationPulse[];
+    actions: CalibrationAction[];
+    stats: Partial<Record<GestureDirection, CalibrationStats>>;
+    issues: string[];
+}
+/** Infer actions from raw shape and timing, independent of event labels and action order.
+ * Closely spaced singles can be indistinguishable from doubles: inferred counts are not ground truth.
+ */
+export declare function calibrateGestures(input: GestureRecording | readonly GestureRecording[], settings?: {
+    minimumPerAction?: number;
+    detectionFloor?: number;
+    pairGapMs?: number;
+}): GestureCalibration;

package/dist/calibration.js

@@ -0,0 +1,135 @@
+import { createGestureTune } from './tune.js';
+import { validateGestureRecording } from './recording.js';
+export const gestureDirections = ['clockwise', 'counterclockwise', 'push', 'pull'];
+const quantile = (values, p) => { const a = [...values].sort((x, y) => x - y); const at = (a.length - 1) * p, lo = Math.floor(at), hi = Math.ceil(at); return a[lo] + (a[hi] - a[lo]) * (at - lo); };
+const mean = (values) => values.reduce((a, b) => a + b, 0) / values.length;
+const clamp = (v, min, max) => Math.max(min, Math.min(max, v));
+/** Infer actions from raw shape and timing, independent of event labels and action order.
+ * Closely spaced singles can be indistinguishable from doubles: inferred counts are not ground truth.
+ */
+export function calibrateGestures(input, settings = {}) {
+    const recordings = Array.isArray(input) ? input : [input];
+    const minimum = settings.minimumPerAction ?? 3, floor = settings.detectionFloor ?? .025, pairGap = settings.pairGapMs ?? 250;
+    if (!Number.isInteger(minimum) || minimum < 3 || minimum > 100 || !Number.isFinite(floor) || floor <= 0 || floor > .1 || !Number.isFinite(pairGap) || pairGap < 50 || pairGap > 500)
+        throw new RangeError('Invalid calibration limits; at least three examples per action are required.');
+    if (recordings.length < 1 || recordings.length > 20)
+        throw new RangeError('Use one to twenty recordings.');
+    const pulses = [], issues = [];
+    function episode(points, direction, recording, segment) {
+        if (points.length < 3 || points[0].v > floor || points[points.length - 1].v > floor)
+            return;
+        const peaks = [];
+        for (let i = 1; i < points.length - 1; i++)
+            if (points[i].v >= Math.max(.06, floor * 2.5) && points[i].v >= points[i - 1].v && points[i].v > points[i + 1].v)
+                peaks.push(i);
+        const selected = [];
+        for (const peak of peaks) {
+            if (!selected.length) {
+                selected.push(peak);
+                continue;
+            }
+            const prev = selected[selected.length - 1];
+            let valley = Infinity;
+            for (let j = prev; j <= peak; j++)
+                valley = Math.min(valley, points[j].v);
+            // Ignore tiny ripples on one excursion. A clear relaxation separates pulses.
+            if (valley > Math.min(points[prev].v, points[peak].v) * .45 || points[peak].t - points[prev].t < 70) {
+                if (points[peak].v > points[prev].v)
+                    selected[selected.length - 1] = peak;
+            }
+            else
+                selected.push(peak);
+        }
+        const bounds = [0];
+        for (let i = 1; i < selected.length; i++) {
+            let index = selected[i - 1];
+            for (let j = index; j <= selected[i]; j++)
+                if (points[j].v < points[index].v)
+                    index = j;
+            bounds.push(index);
+        }
+        bounds.push(points.length - 1);
+        selected.forEach((peak, i) => {
+            const from = points[bounds[i]], to = points[bounds[i + 1]], top = points[peak], duration = to.t - from.t;
+            if (top.v < top.other * 1.4)
+                return; // Incidental pressure while twisting, or vice versa.
+            if (duration < 45 || duration > 1000) {
+                issues.push(`Excluded ${direction} excursion outside 45–1000 ms.`);
+                return;
+            }
+            pulses.push({ direction, start: from.t, end: to.t, peak: top.v, peakTime: top.t, valleyBefore: from.v, recording, segment });
+        });
+    }
+    recordings.forEach((recording, index) => {
+        validateGestureRecording(recording);
+        for (const direction of gestureDirections) {
+            const vertical = direction === 'push' || direction === 'pull', sign = direction === 'push' || direction === 'clockwise' ? 1 : -1;
+            let run = [], previous, segment = 0;
+            for (const row of recording.timeline) {
+                if (row.type === 'reset') {
+                    run = [];
+                    previous = undefined;
+                    segment++;
+                    continue;
+                }
+                if (row.type !== 'input')
+                    continue;
+                const point = { t: row.t, v: Math.max(0, sign * (vertical ? row.input.z : row.input.rz)), other: Math.abs(vertical ? row.input.rz : row.input.z) };
+                if (point.v > floor) {
+                    if (!run.length)
+                        run = previous ? [{ ...previous, t: point.t }] : [];
+                    run.push(point);
+                }
+                else if (run.length) {
+                    run.push(point);
+                    episode(run, direction, index, segment);
+                    run = [];
+                }
+                previous = point;
+            }
+            if (run.length)
+                issues.push(`Unfinished ${direction} excursion at recording end.`);
+        }
+    });
+    pulses.sort((a, b) => a.recording - b.recording || a.start - b.start);
+    const actions = [], counts = {};
+    for (const d of gestureDirections)
+        for (const kind of ['single', 'double'])
+            counts[`${d}.${kind}`] = 0;
+    const paired = (a, b) => a.recording === b.recording && a.segment === b.segment && a.direction === b.direction && b.start - a.end <= pairGap && b.end - a.end <= 650;
+    let ambiguous = false;
+    for (let i = 0; i < pulses.length;) {
+        let end = i + 1;
+        while (end < pulses.length && paired(pulses[end - 1], pulses[end]))
+            end++;
+        if (end - i > 2) {
+            ambiguous = true;
+            issues.push(`Ambiguous run of ${end - i} ${pulses[i].direction} pulses near ${(pulses[i].start / 1000).toFixed(1)} s; leave a longer pause between actions.`);
+            i = end;
+            continue;
+        }
+        const group = pulses.slice(i, end), kind = group.length === 2 ? 'double' : 'single';
+        const action = { direction: group[0].direction, kind, start: group[0].start, end: group[group.length - 1].end, pulses: group, recording: group[0].recording };
+        actions.push(action);
+        counts[`${action.direction}.${kind}`]++;
+        i = end;
+    }
+    const stats = {};
+    for (const d of gestureDirections) {
+        const values = pulses.filter(p => p.direction === d).map(p => p.peak);
+        if (values.length)
+            stats[d] = { count: values.length, center: mean(values), low: quantile(values, .1), high: quantile(values, .9), min: Math.min(...values), max: Math.max(...values) };
+    }
+    const missing = Object.keys(counts).filter(key => counts[key] < minimum);
+    let tune = null;
+    if (!missing.length && !ambiguous) {
+        function band(d) { const s = stats[d]; const activation = clamp(s.low * .7, .04, s.min * .85); const returns = pulses.filter(p => p.direction === d).map(p => p.valleyBefore); const release = clamp(Math.max(activation * .5, ...returns.map(v => v * 1.2)), .01, activation * .8); return { center: s.center, low: s.low, high: s.high, activation, release }; }
+        const cw = band('clockwise'), ccw = band('counterclockwise');
+        const rotation = { center: (cw.center + ccw.center) / 2, low: (cw.low + ccw.low) / 2, high: (cw.high + ccw.high) / 2, activation: (cw.activation + ccw.activation) / 2, release: Math.max(cw.release, ccw.release) };
+        // Equal rotation gates, while still accommodating the shallower inter-pulse return.
+        rotation.release = Math.min(rotation.release, rotation.activation * .85);
+        const lengths = pulses.map(p => p.end - p.start), doubles = actions.filter(a => a.kind === 'double').map(a => a.pulses[1].end - a.pulses[0].end);
+        tune = createGestureTune({ version: 1, rotation, push: band('push'), pull: band('pull'), dominance: 1.4, timing: { minPulseMs: Math.round(clamp(quantile(lengths, .1) * .2, 15, 60)), maxPulseMs: Math.round(clamp(quantile(lengths, .9) * 2, 350, 1000)), neutralMs: 20, doubleMs: Math.round(clamp(Math.max(...doubles) + 40, 200, 650)) } });
+    }
+    return { status: ambiguous ? 'ambiguous' : missing.length ? 'incomplete' : 'ready', tune, counts, missing, pulses, actions, stats, issues: [...new Set(issues)] };
+}

package/dist/gestures.d.ts

@@ -0,0 +1,49 @@
+import type { InputState } from './input.js';
+import type { GestureTune } from './tune.js';
+export type GestureDirection = 'clockwise' | 'counterclockwise' | 'push' | 'pull';
+export interface GestureOptions {
+    activation?: number;
+    release?: number;
+    /** Optional axis-specific thresholds; fall back to activation/release. */
+    pressActivation?: number;
+    pressRelease?: number;
+    twistActivation?: number;
+    twistRelease?: number;
+    clockwiseActivation?: number;
+    clockwiseRelease?: number;
+    counterclockwiseActivation?: number;
+    counterclockwiseRelease?: number;
+    pushActivation?: number;
+    pushRelease?: number;
+    pullActivation?: number;
+    pullRelease?: number;
+    minPulseMs?: number;
+    maxPulseMs?: number;
+    neutralMs?: number;
+    doubleMs?: number;
+    /** Exclusive waits for a double; immediate emits single, then double (additive). */
+    singleMode?: 'exclusive' | 'immediate';
+    /** Strongest axis must exceed the other by this ratio. */
+    dominance?: number;
+}
+export interface GestureEvent {
+    direction: GestureDirection;
+    kind: 'single' | 'double';
+    timestamp: number;
+    durationMs: number;
+}
+export interface GestureRecognizer {
+    /** Process every report with a monotonic timestamp; do not discard reports between frames. */
+    update(input: Readonly<InputState>, timestampMs: number): GestureEvent[];
+    /** Advance pending single/release deadlines, even when no reports arrive. */
+    advance(timestampMs: number): GestureEvent[];
+    /** Cancel everything. Fresh neutral input is required before rearming. */
+    reset(): void;
+    readonly state: {
+        phase: 'neutral' | 'active' | 'releasing' | 'blocked';
+        direction: GestureDirection | null;
+        pending: GestureDirection | null;
+    };
+}
+/** Experimental pulse recognizer. No timers, DOM, transport, or motion side effects. */
+export declare function createGestures(configuration?: GestureOptions | GestureTune): GestureRecognizer;