@clankagent/puck 0.2.0 → 0.3.0

package/AGENTS.md

@@ -1,5 +1,10 @@
 # Package development
 
+For requested Puck updates, complete implementation, tests, linked changelog/docs,
+commit and push, CI verification, versioned npm publication, and a clean install
+check before reporting completion. Stop only for an actual blocker or an explicit
+source-only request.
+
 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.

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 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.3.0 — 2026-09-19
+
+- Added opt-in [standalone rx/ry singles and doubles and push/pull + tilt](docs/press-tilt.md).
+  Combined modes support pressure relaxation and preserve ordinary doubles.
+  Faster execution is accepted; timing allowances are upper bounds.
+- Added `calibrateTilts`, `calibratePressTilts`, matching graph constructors,
+  and immutable, serializable tuning fields. Each family needs three examples
+  of its eight action types; freeform order and multiple captures are supported.
+- Updated the lab with automatic family detection, an explicit analysis selector,
+  standalone controls, per-action inspection and reusable tune export.
+- Fixed empty/disconnected captures being accepted as usable recordings. Partial
+  captures survive disconnect; simulator capture requires explicit test mode.
+- Defined [1.0 readiness criteria](docs/roadmap.md). APIs remain experimental.
+
+Existing gesture behavior is unchanged unless enabled. The TypeScript direction
+union expands and combined events have an optional tilt field; see the
+[upgrade guide](docs/upgrading.md#from-02-to-03). Tune/recording format stays 1,
+and old tune JSON is supported. [Compare versions](https://github.com/clankagent/puck/compare/v0.2.0...v0.3.0).
+
 ## 0.2.0 — 2026-09-19
 
 ### Added
@@ -35,4 +54,4 @@ This is a source-history reference, not a claim that an npm release was publishe
 - 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)
+[Baseline source](https://github.com/clankagent/puck/tree/f065d4a) · [Motion behavior and hardware](docs/motion.md)

package/README.md

@@ -2,7 +2,7 @@
 
 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.
 
-**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.
+**Version note:** these docs target 0.3.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 adopting updates.
 
 ## Start here
 
@@ -16,6 +16,8 @@ Six-axis input, responsive pan/zoom, and tunable single/double gestures for Spac
 | 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) |
+| Understand the next release and 1.0 criteria | [Roadmap](docs/roadmap.md) |
+| Add standalone or pressure-first tilts | [Push/pull + tilt](docs/press-tilt.md) |
 
 For a registry release, install with `pnpm add @clankagent/puck`. For this checkout:
 
@@ -41,11 +43,11 @@ const gestures = createGestures(tune);
 |---|---|
 | 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. |
+| Optional `/graph` | Gesture-family graph data and a standalone SVG renderer. |
 | Your app | Render loop, action handling, camera, capture controls, persistence and UI. |
 
 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
 
-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.
+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

@@ -20,7 +20,7 @@
 - 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.
+  verification is recorded below; inferred replay does not establish subjective feel.
 
 ## Freeform recording (2026-09-18)
 
@@ -33,7 +33,7 @@
   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.
+  Capture raw data first, then infer suitable separate thresholds from natural use.
 
 ## Direction threshold refinement
 
@@ -44,7 +44,7 @@
 - 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.
+  profile. These are inferred gesture groups, not ground-truth accuracy labels.
 
 ## Reusable tune / calibration SDK
 
@@ -76,3 +76,17 @@
   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.
+
+## 0.3 gesture scope
+
+Synthetic tests cover four standalone directions, singles/doubles, brief neutral
+valleys, pressure-first vs tilt-first ownership, reversals, holds, lifecycle
+resets, multi-capture calibration and graph overlays. Combined recognition was
+replayed against physical freeform input at original, 2× and 3× timestamps;
+39 inferred combinations and four plain actions were preserved. The original
+35-action simple reference remained unchanged with both families enabled.
+Two standalone captures supply at least three inferred singles and doubles per
+direction; interrupted/outlying excursions are excluded. Inferred labels are
+not ground truth or an accuracy score. No new hardware compatibility is claimed.
+Ordinary pan/zoom false-positive rates and multi-session robustness remain
+1.0 validation work. Raw captures and user metadata are not distributed.

package/dist/calibration.d.ts

@@ -1,4 +1,4 @@
-import type { GestureDirection } from './gestures.js';
+import type { PulseDirection as 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'];

package/dist/calibration.js

@@ -2,7 +2,7 @@ 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 mean = (values) => values[0] + values.reduce((a, b) => a + (b - values[0]), 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.
@@ -18,6 +18,10 @@ export function calibrateGestures(input, settings = {}) {
     function episode(points, direction, recording, segment) {
         if (points.length < 3 || points[0].v > floor || points[points.length - 1].v > floor)
             return;
+        if ((direction === 'push' || direction === 'pull') && points.some(p => p.tilt >= .25)) {
+            issues.push('Excluded a press with tilt; use calibratePressTilts for combined gestures.');
+            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)
@@ -74,7 +78,7 @@ export function calibrateGestures(input, settings = {}) {
                 }
                 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) };
+                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), tilt: Math.max(Math.abs(row.input.rx), Math.abs(row.input.ry)) };
                 if (point.v > floor) {
                     if (!run.length)
                         run = previous ? [{ ...previous, t: point.t }] : [];

package/dist/gestures.d.ts

@@ -1,7 +1,30 @@
 import type { InputState } from './input.js';
 import type { GestureTune } from './tune.js';
-export type GestureDirection = 'clockwise' | 'counterclockwise' | 'push' | 'pull';
+export type PulseDirection = 'clockwise' | 'counterclockwise' | 'push' | 'pull';
+export type TiltDirection = 'rx+' | 'rx-' | 'ry+' | 'ry-';
+export type GestureDirection = PulseDirection | TiltDirection;
+export type PressMode = 'simple' | 'tilt' | 'auto';
 export interface GestureOptions {
+    standaloneTilt?: boolean;
+    tiltXActivation?: number;
+    tiltXRelease?: number;
+    tiltYActivation?: number;
+    tiltYRelease?: number;
+    standaloneMinPulseMs?: number;
+    standaloneMaxPulseMs?: number;
+    standaloneNeutralMs?: number;
+    standaloneDoubleMs?: number;
+    /** Simple preserves 0.2 behavior; tilt suppresses plain singles; auto chooses. Plain doubles work in all modes. */
+    pressMode?: PressMode;
+    pushMode?: PressMode;
+    pullMode?: PressMode;
+    tiltActivation?: number;
+    tiltRelease?: number;
+    tiltMinMs?: number;
+    tiltArmMs?: number;
+    tiltRelaxMs?: number;
+    tiltMaxMs?: number;
+    tiltDominance?: number;
     activation?: number;
     release?: number;
     /** Optional axis-specific thresholds; fall back to activation/release. */
@@ -28,6 +51,8 @@ export interface GestureOptions {
 }
 export interface GestureEvent {
     direction: GestureDirection;
+    /** Present for a combined push/pull + tilt. Such events have kind single. */
+    tilt?: TiltDirection;
     kind: 'single' | 'double';
     timestamp: number;
     durationMs: number;

package/dist/gestures.js

@@ -8,18 +8,44 @@ export function createGestures(configuration = defaultGestureTune) {
     const pressRelease = options.pressRelease ?? options.release;
     const twistActivation = options.twistActivation ?? options.activation ?? defaultGestureTune.rotation.activation;
     const twistRelease = options.twistRelease ?? options.release ?? defaultGestureTune.rotation.release;
+    const standalone = options.standaloneTilt ?? false;
+    const st = defaultGestureTune.standaloneTilt;
+    const tx = { activation: options.tiltXActivation ?? st.rx.activation, release: options.tiltXRelease ?? st.rx.release };
+    const ty = { activation: options.tiltYActivation ?? st.ry.activation, release: options.tiltYRelease ?? st.ry.release };
     const thresholds = {
         clockwise: { activation: options.clockwiseActivation ?? twistActivation, release: options.clockwiseRelease ?? twistRelease },
         counterclockwise: { activation: options.counterclockwiseActivation ?? twistActivation, release: options.counterclockwiseRelease ?? twistRelease },
         push: { activation: options.pushActivation ?? pressActivation ?? defaultGestureTune.push.activation, release: options.pushRelease ?? pressRelease ?? defaultGestureTune.push.release },
         pull: { activation: options.pullActivation ?? pressActivation ?? defaultGestureTune.pull.activation, release: options.pullRelease ?? pressRelease ?? defaultGestureTune.pull.release },
+        'rx+': tx, 'rx-': tx, 'ry+': ty, 'ry-': ty,
     };
     const minPulseMs = options.minPulseMs ?? 35;
     const maxPulseMs = options.maxPulseMs ?? 650;
     const neutralMs = options.neutralMs ?? defaultGestureTune.timing.neutralMs;
     const doubleMs = options.doubleMs ?? defaultGestureTune.timing.doubleMs;
     const singleMode = options.singleMode ?? 'exclusive';
+    const standaloneMin = options.standaloneMinPulseMs ?? st.timing.minPulseMs, standaloneMax = options.standaloneMaxPulseMs ?? st.timing.maxPulseMs;
+    const standaloneNeutral = options.standaloneNeutralMs ?? st.timing.neutralMs, standaloneDouble = options.standaloneDoubleMs ?? st.timing.doubleMs;
+    if (typeof standalone !== 'boolean' || ![standaloneMin, standaloneMax, standaloneNeutral, standaloneDouble].every(Number.isFinite) || standaloneMin < 0 || standaloneMax < standaloneMin || standaloneNeutral < 0 || standaloneDouble < 0)
+        throw new RangeError('Invalid standalone tilt options.');
+    const isTilt = (d) => d.startsWith('rx') || d.startsWith('ry');
+    const dwell = (d) => isTilt(d) ? standaloneNeutral : neutralMs;
+    const doubleWindow = (d) => isTilt(d) ? standaloneDouble : doubleMs;
     const dominance = options.dominance ?? 1.4;
+    const modes = { push: options.pushMode ?? options.pressMode ?? 'simple', pull: options.pullMode ?? options.pressMode ?? 'simple' };
+    const tiltActivation = options.tiltActivation ?? defaultGestureTune.pressTilt.force.activation, tiltRelease = options.tiltRelease ?? defaultGestureTune.pressTilt.force.release;
+    const tiltMinMs = options.tiltMinMs ?? 25, tiltArmMs = options.tiltArmMs ?? 450;
+    const tiltRelaxMs = options.tiltRelaxMs ?? 180, tiltMaxMs = options.tiltMaxMs ?? 1000;
+    const tiltDominance = options.tiltDominance ?? 1.25;
+    const combinedEnabled = modes.push !== 'simple' || modes.pull !== 'simple';
+    const tiltEnabled = combinedEnabled || standalone;
+    const tiltMode = (d) => (d === 'push' || d === 'pull') && modes[d] !== 'simple';
+    if ([options.pressMode, options.pushMode, options.pullMode].some(v => v !== undefined && !['simple', 'tilt', 'auto'].includes(v))
+        || ![tiltActivation, tiltRelease, tiltMinMs, tiltArmMs, tiltRelaxMs, tiltMaxMs, tiltDominance].every(Number.isFinite)
+        || tiltRelease < 0 || tiltActivation <= tiltRelease || tiltActivation > 1 || tiltDominance <= 1
+        || tiltMinMs < 0 || tiltArmMs < tiltMinMs || tiltArmMs > tiltMaxMs || tiltMaxMs > 10000
+        || tiltRelaxMs < 0 || tiltRelaxMs > tiltArmMs || (combinedEnabled && singleMode !== 'exclusive'))
+        throw new RangeError('Invalid press-tilt options; combined gestures require exclusive single mode.');
     if (![activation, release, twistActivation, twistRelease, minPulseMs, maxPulseMs, neutralMs, doubleMs, dominance].every(Number.isFinite)
         || release < 0 || activation <= release || activation > 1 || minPulseMs < 0
         || twistRelease < 0 || twistActivation <= twistRelease || twistActivation > 1
@@ -28,13 +54,28 @@ export function createGestures(configuration = defaultGestureTune) {
         || !['exclusive', 'immediate'].includes(singleMode))
         throw new RangeError('Invalid gesture options.');
     let last = -Infinity;
-    let z = 0, rz = 0;
+    let z = 0, rz = 0, rx = 0, ry = 0;
     let phase = 'blocked';
     let active = null;
     let releasedAt = null;
     let pending = null;
-    const neutral = () => Math.abs(z) <= thresholds[z >= 0 ? 'push' : 'pull'].release
-        && Math.abs(rz) <= thresholds[rz >= 0 ? 'clockwise' : 'counterclockwise'].release;
+    const tiltNeutral = () => Math.max(Math.abs(rx), Math.abs(ry)) <= tiltRelease;
+    const standaloneRest = () => Math.abs(rx) <= tx.release && Math.abs(ry) <= ty.release;
+    const neutral = () => active && isTilt(active.direction) ? standaloneRest() : Math.abs(z) <= thresholds[z >= 0 ? 'push' : 'pull'].release
+        && Math.abs(rz) <= thresholds[rz >= 0 ? 'clockwise' : 'counterclockwise'].release
+        && (!(active ? tiltMode(active.direction) : combinedEnabled) || tiltNeutral())
+        && (Boolean(active) || !standalone || standaloneRest());
+    const allowSingle = (e) => e.direction !== 'push' && e.direction !== 'pull' || modes[e.direction] !== 'tilt';
+    const pendingStart = () => pending.timestamp - neutralMs - pending.durationMs;
+    const canResume = (t) => pending && tiltMode(pending.direction) && t <= pending.timestamp - neutralMs + tiltRelaxMs && t <= pendingStart() + tiltArmMs;
+    const deadline = (e) => e.timestamp + (tiltMode(e.direction) ? Math.max(doubleMs, tiltRelaxMs + tiltMinMs) : doubleWindow(e.direction));
+    function tiltDirection() {
+        if (Math.abs(rx) >= tiltActivation && Math.abs(rx) >= Math.abs(ry) * tiltDominance)
+            return rx > 0 ? 'rx+' : 'rx-';
+        if (Math.abs(ry) >= tiltActivation && Math.abs(ry) >= Math.abs(rx) * tiltDominance)
+            return ry > 0 ? 'ry+' : 'ry-';
+        return undefined;
+    }
     function clock(t) {
         if (!Number.isFinite(t) || t < last)
             throw new RangeError('Gesture timestamps must be finite and monotonic.');
@@ -42,20 +83,36 @@ export function createGestures(configuration = defaultGestureTune) {
     }
     function tick(t) {
         const events = [];
-        if (phase === 'releasing' && releasedAt !== null && active && t >= releasedAt + neutralMs) {
+        if (active?.candidate && active.candidateAt !== undefined && t >= active.candidateAt + tiltMinMs
+            && (!active.tilt || active.candidate === active.tilt || active.candidatePeak > active.tiltPeak * tiltDominance)) {
+            if (canResume(active.candidateAt) && pending.direction === active.direction) {
+                active.start = pendingStart();
+                pending = null;
+            }
+            active.tilt = active.candidate;
+            active.tiltPeak = Math.max(active.tiltPeak ?? 0, active.candidatePeak ?? 0);
+        }
+        if (phase === 'releasing' && releasedAt !== null && active && t >= releasedAt + dwell(active.direction)) {
             const durationMs = releasedAt - active.start;
-            const completedAt = releasedAt + neutralMs;
-            if (durationMs >= minPulseMs && durationMs <= maxPulseMs) {
+            const completedAt = releasedAt + dwell(active.direction);
+            if (active.tilt && durationMs <= tiltMaxMs) {
+                // Combined gestures consume one excursion; repeats are separate actions, not tilt doubles.
+                if (pending && allowSingle(pending))
+                    events.push({ ...pending, timestamp: Math.min(completedAt, deadline(pending)) });
+                pending = null;
+                events.push({ direction: active.direction, tilt: active.tilt, kind: 'single', timestamp: completedAt, durationMs });
+            }
+            else if (!active.borrowed && !active.attemptedTilt && durationMs >= (isTilt(active.direction) ? standaloneMin : minPulseMs) && durationMs <= (isTilt(active.direction) ? standaloneMax : maxPulseMs)) {
                 const pulse = { direction: active.direction, kind: 'single', timestamp: completedAt, durationMs };
-                if (pending && pending.direction === pulse.direction && completedAt - pending.timestamp <= doubleMs) {
+                if (pending && pending.direction === pulse.direction && completedAt - pending.timestamp <= doubleWindow(pulse.direction)) {
                     events.push({ ...pulse, kind: 'double' });
                     pending = null;
                 }
                 else {
-                    if (pending && singleMode === 'exclusive')
-                        events.push({ ...pending, timestamp: Math.min(completedAt, pending.timestamp + doubleMs) });
+                    if (pending && singleMode === 'exclusive' && allowSingle(pending))
+                        events.push({ ...pending, timestamp: Math.min(completedAt, deadline(pending)) });
                     pending = pulse;
-                    if (singleMode === 'immediate')
+                    if (singleMode === 'immediate' && allowSingle(pulse))
                         events.push(pulse);
                 }
             }
@@ -63,36 +120,65 @@ export function createGestures(configuration = defaultGestureTune) {
             releasedAt = null;
             phase = 'neutral';
         }
-        if (active && phase === 'active' && t - active.start > maxPulseMs) {
+        if (active && phase === 'active' && t - active.start > (isTilt(active.direction) ? standaloneMax : active.tilt || active.candidate ? tiltMaxMs : maxPulseMs)) {
             phase = 'blocked';
             active = null;
         }
         // A double is defined by completion-to-completion time, including neutral dwell.
-        if (pending && t > pending.timestamp + doubleMs) {
-            if (singleMode === 'exclusive')
-                events.push({ ...pending, timestamp: pending.timestamp + doubleMs });
+        if (pending && t > deadline(pending)) {
+            if (singleMode === 'exclusive' && allowSingle(pending))
+                events.push({ ...pending, timestamp: deadline(pending) });
             pending = null;
         }
         return events;
     }
     return {
         get state() { return { phase, direction: active?.direction ?? null, pending: pending?.direction ?? null }; },
-        reset() { last = -Infinity; z = rz = 0; active = pending = null; releasedAt = null; phase = 'blocked'; },
+        reset() { last = -Infinity; z = rz = rx = ry = 0; active = pending = null; releasedAt = null; phase = 'blocked'; },
         advance(t) { clock(t); return tick(t); },
         update(input, t) {
-            if (!Number.isFinite(input.z) || !Number.isFinite(input.rz))
+            if (![input.z, input.rz, ...(tiltEnabled ? [input.rx, input.ry] : [])].every(Number.isFinite))
                 throw new RangeError('Gesture axes must be finite.');
             clock(t);
             const events = tick(t);
+            const tiltWasBelowActivation = Math.max(Math.abs(rx), Math.abs(ry)) < tiltActivation;
             z = Math.max(-1, Math.min(1, input.z));
             rz = Math.max(-1, Math.min(1, input.rz));
+            if (tiltEnabled) {
+                rx = Math.max(-1, Math.min(1, input.rx));
+                ry = Math.max(-1, Math.min(1, input.ry));
+            }
             if (phase === 'blocked') {
                 if (neutral())
                     phase = 'neutral';
                 return events;
             }
+            const side = tiltEnabled ? tiltDirection() : undefined;
+            if (!active && side && canResume(t)) {
+                active = { direction: pending.direction, start: pendingStart(), borrowed: true, tiltEligible: true };
+                phase = 'active';
+            }
             if (active) {
-                const signed = active.direction === 'push' ? z : active.direction === 'pull' ? -z : active.direction === 'clockwise' ? rz : -rz;
+                if (tiltMode(active.direction) && active.tiltEligible) {
+                    if (Math.max(Math.abs(rx), Math.abs(ry)) >= tiltActivation)
+                        active.attemptedTilt = true;
+                    if (side && (active.tilt || active.candidate === side || t - active.start <= tiltArmMs)) {
+                        const strength = Math.abs(side.startsWith('rx') ? rx : ry);
+                        if (active.candidate !== side) {
+                            active.candidate = side;
+                            active.candidateAt = t;
+                            active.candidatePeak = strength;
+                        }
+                        else
+                            active.candidatePeak = Math.max(active.candidatePeak ?? 0, strength);
+                    }
+                    else {
+                        active.candidate = undefined;
+                        active.candidateAt = undefined;
+                        active.candidatePeak = undefined;
+                    }
+                }
+                const signed = active.direction === 'push' ? z : active.direction === 'pull' ? -z : active.direction === 'clockwise' ? rz : active.direction === 'counterclockwise' ? -rz : (active.direction.startsWith('rx') ? rx : ry) * (active.direction.endsWith('+') ? 1 : -1);
                 if (neutral()) {
                     if (releasedAt === null)
                         releasedAt = t;
@@ -111,11 +197,30 @@ export function createGestures(configuration = defaultGestureTune) {
             }
             else {
                 const vertical = Math.abs(z) >= Math.abs(rz);
-                const strong = vertical ? Math.abs(z) : Math.abs(rz);
-                const weak = vertical ? Math.abs(rz) : Math.abs(z);
-                const direction = vertical ? (z > 0 ? 'push' : 'pull') : (rz > 0 ? 'clockwise' : 'counterclockwise');
+                let strong = vertical ? Math.abs(z) : Math.abs(rz);
+                let weak = vertical ? Math.abs(rz) : Math.abs(z);
+                let direction = vertical ? (z > 0 ? 'push' : 'pull') : (rz > 0 ? 'clockwise' : 'counterclockwise');
+                if (standalone) {
+                    const axis = Math.abs(rx) >= Math.abs(ry) ? 'rx' : 'ry';
+                    const sideStrength = Math.abs(axis === 'rx' ? rx : ry);
+                    if (sideStrength >= (axis === 'rx' ? tx.activation : ty.activation)) {
+                        if (sideStrength > strong) {
+                            weak = Math.max(strong, Math.abs(axis === 'rx' ? ry : rx));
+                            strong = sideStrength;
+                            direction = (axis + ((axis === 'rx' ? rx : ry) > 0 ? '+' : '-'));
+                        }
+                        else
+                            weak = Math.max(weak, sideStrength);
+                    }
+                }
                 if (strong >= thresholds[direction].activation && strong >= weak * dominance) {
-                    active = { direction, start: t };
+                    active = { direction, start: t, tiltEligible: tiltWasBelowActivation };
+                    if (tiltMode(direction) && active.tiltEligible && side) {
+                        active.candidate = side;
+                        active.candidateAt = t;
+                        active.candidatePeak = Math.abs(side.startsWith('rx') ? rx : ry);
+                        active.attemptedTilt = true;
+                    }
                     phase = 'active';
                 }
             }

package/dist/graph.d.ts

@@ -1,9 +1,11 @@
-import type { GestureDirection } from './gestures.js';
+import type { PulseDirection as GestureDirection, TiltDirection } from './gestures.js';
+import type { PressTiltAction } from './press-tilt-calibration.js';
+import type { TiltCalibrationAction } from './tilt-calibration.js';
 import type { GestureTune } from './tune.js';
 import type { GestureRecording } from './recording.js';
 import type { CalibrationAction } from './calibration.js';
 export interface GestureGraphLane {
-    direction: GestureDirection;
+    direction: GestureDirection | TiltDirection;
     label: string;
     center: number;
     low: number;
@@ -18,6 +20,7 @@ export interface GestureGraphLane {
         start: number;
         end: number;
         kind: 'single' | 'double';
+        label?: string;
     }[];
 }
 export interface GestureGraph {
@@ -32,6 +35,20 @@ export declare function createGestureGraph(recording: GestureRecording, tune?: G
     actions?: readonly CalibrationAction[];
     recordingIndex?: number;
 }): GestureGraph;
+/** Pressure and tilt in six separate lanes, with each inferred combination labeled on both. */
+export declare function createPressTiltGraph(recording: GestureRecording, tune?: GestureTune, config?: {
+    start?: number;
+    end?: number;
+    actions?: readonly PressTiltAction[];
+    recordingIndex?: number;
+}): GestureGraph;
+/** Four standalone tilt lanes with independent rx/ry bands and single/double action spans. */
+export declare function createTiltGraph(recording: GestureRecording, tune?: GestureTune, config?: {
+    start?: number;
+    end?: number;
+    actions?: readonly TiltCalibrationAction[];
+    recordingIndex?: number;
+}): GestureGraph;
 /** Standalone accessible SVG. No DOM, canvas, frameworks or global listeners. */
 export declare function renderGestureGraphSvg(graph: GestureGraph, options?: {
     width?: number;

package/dist/graph.js

@@ -24,7 +24,59 @@ export function createGestureGraph(recording, tune = defaultGestureTune, config
     });
     return { start, end, lanes };
 }
+/** Pressure and tilt in six separate lanes, with each inferred combination labeled on both. */
+export function createPressTiltGraph(recording, tune = defaultGestureTune, config = {}) {
+    const graph = createGestureGraph(recording, tune, { start: config.start, end: config.end });
+    const actions = (config.actions ?? []).filter(a => a.recording === (config.recordingIndex ?? 0) && a.end >= graph.start && a.start <= graph.end);
+    graph.lanes = graph.lanes.filter(l => l.direction === 'push' || l.direction === 'pull');
+    for (const direction of ['rx+', 'rx-', 'ry+', 'ry-']) {
+        const axis = direction.startsWith('rx') ? 'rx' : 'ry', sign = direction.endsWith('+') ? 1 : -1;
+        const points = [];
+        let held = 0;
+        for (const row of recording.timeline) {
+            if (row.t > graph.end)
+                break;
+            if (row.type === 'input')
+                held = Math.max(0, row.input[axis] * sign);
+            else if (row.type === 'reset')
+                held = 0;
+            else
+                continue;
+            if (row.t < graph.start)
+                continue;
+            if (!points.length)
+                points.push({ t: graph.start, value: 0 });
+            points.push({ t: row.t, value: held });
+        }
+        // Seed the left edge with the held sample preceding the requested window.
+        let before = 0;
+        for (const row of recording.timeline) {
+            if (row.t >= graph.start)
+                break;
+            if (row.type === 'input')
+                before = Math.max(0, row.input[axis] * sign);
+            else if (row.type === 'reset')
+                before = 0;
+        }
+        if (!points.length)
+            points.push({ t: graph.start, value: before });
+        else
+            points[0].value = before;
+        points.push({ t: graph.end, value: held });
+        graph.lanes.push({ direction, label: `Tilt ${direction} (device axis)`, ...(tune.pressTilt ?? defaultGestureTune.pressTilt).force, points, actions: [] });
+    }
+    for (const lane of graph.lanes)
+        lane.actions = actions.filter(a => a.direction === lane.direction || a.tilt === lane.direction).map(a => ({ start: a.start, end: a.end, kind: 'single', label: `${a.direction} + ${a.tilt}` }));
+    return graph;
+}
 const escape = (value) => value.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+/** Four standalone tilt lanes with independent rx/ry bands and single/double action spans. */
+export function createTiltGraph(recording, tune = defaultGestureTune, config = {}) {
+    const graph = createPressTiltGraph(recording, tune, { start: config.start, end: config.end });
+    const bands = tune.standaloneTilt ?? defaultGestureTune.standaloneTilt;
+    graph.lanes = graph.lanes.filter(l => l.direction.startsWith('r')).map(l => ({ ...l, ...(l.direction.startsWith('rx') ? bands.rx : bands.ry), actions: (config.actions ?? []).filter(a => a.recording === (config.recordingIndex ?? 0) && a.direction === l.direction && a.end >= graph.start && a.start <= graph.end).map(a => ({ start: a.start, end: a.end, kind: a.kind })) }));
+    return graph;
+}
 /** Standalone accessible SVG. No DOM, canvas, frameworks or global listeners. */
 export function renderGestureGraphSvg(graph, options = {}) {
     const width = options.width ?? 960;
@@ -32,15 +84,15 @@ export function renderGestureGraphSvg(graph, options = {}) {
         throw new RangeError('SVG width must be between 280 and 4000.');
     const height = graph.lanes.length * 150 + 64, left = 45, right = 20, plotWidth = width - left - right;
     const x = (t) => left + (Math.max(graph.start, Math.min(graph.end, t)) - graph.start) / (graph.end - graph.start) * plotWidth;
-    const svg = [`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escape(options.title ?? 'Gesture recording: four independent directions')}"><desc>Blue is input strength, green dashed is activation, gray dotted is release, pale blue is the typical peak range. Shaded time spans mark inferred actions. Stronger inputs remain accepted above the typical range.</desc><rect width="100%" height="100%" fill="white"/><g font-family="Segoe UI,Arial,sans-serif" font-size="12" fill="#283c55">`];
+    const svg = [`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escape(options.title ?? 'Gesture recording: independent input directions')}"><desc>Blue is input strength, green dashed is activation, gray dotted is release, pale blue is the typical peak range. Shaded time spans mark inferred actions. Stronger inputs remain accepted above the typical range.</desc><rect width="100%" height="100%" fill="white"/><g font-family="Segoe UI,Arial,sans-serif" font-size="12" fill="#283c55">`];
     graph.lanes.forEach((lane, index) => {
         const top = 30 + index * 150, y = (v) => top + 100 - Math.max(0, Math.min(1, v)) * 76;
         svg.push(`<text x="${left}" y="${top}" font-size="15" font-weight="600">${escape(lane.label)}</text><text x="${width - right}" y="${top}" text-anchor="end" font-size="11">peak ${lane.center.toFixed(2)}</text><text x="${left}" y="${top + 19}">Activate ${lane.activation.toFixed(2)} · release ${lane.release.toFixed(2)}</text>`);
         svg.push(`<rect x="${left}" y="${y(lane.high)}" width="${plotWidth}" height="${y(lane.low) - y(lane.high)}" fill="#edf3fc"/>`);
         for (const a of lane.actions) {
-            svg.push(`<rect x="${x(a.start)}" y="${top + 24}" width="${Math.max(2, x(a.end) - x(a.start))}" height="76" fill="#cfdfef" opacity=".45"/>`);
-            if (x(a.end) - x(a.start) > 42)
-                svg.push(`<text x="${x(a.start) + 3}" y="${top + 116}" font-size="11">${a.kind}</text>`);
+            svg.push(`<rect x="${x(a.start)}" y="${top + 24}" width="${Math.max(2, x(a.end) - x(a.start))}" height="76" fill="#cfdfef" opacity=".45"><title>${escape(a.label ?? a.kind)}</title></rect>`);
+            if (x(a.end) - x(a.start) > (a.label ? 90 : 42))
+                svg.push(`<text x="${x(a.start) + 3}" y="${top + 116}" font-size="11">${escape(a.label ?? a.kind)}</text>`);
         }
         for (const [v, color, dash] of [[0, '#afbac8', ''], [lane.activation, '#237442', '6 4'], [lane.release, '#68778b', '2 4']])
             svg.push(`<line x1="${left}" x2="${width - right}" y1="${y(v)}" y2="${y(v)}" stroke="${color}" stroke-dasharray="${dash}"/>`);

package/dist/index.d.ts

@@ -3,10 +3,14 @@ export type { InputState } from './input.js';
 export { createPanZoom } from './motion.js';
 export type { PanZoomController, PanZoomOptions, MotionDelta, ZoomInput } from './motion.js';
 export { createGestures } from './gestures.js';
-export type { GestureDirection, GestureOptions, GestureEvent, GestureRecognizer } from './gestures.js';
+export type { GestureDirection, PulseDirection, TiltDirection, PressMode, GestureOptions, GestureEvent, GestureRecognizer } from './gestures.js';
 export { createGestureTune, defaultGestureTune, gesturePresets } from './tune.js';
-export type { GestureTune, GestureTuneData, ForceBand } from './tune.js';
+export type { GestureTune, GestureTuneData, ForceBand, PressTiltTune, StandaloneTiltTune } from './tune.js';
 export { createGestureRecorder, validateGestureRecording } from './recording.js';
 export type { GestureRecorder, GestureRecording, RecordingEntry } from './recording.js';
 export { calibrateGestures, gestureDirections } from './calibration.js';
 export type { GestureCalibration, CalibrationAction, CalibrationPulse, CalibrationStats, GestureActionName } from './calibration.js';
+export { calibratePressTilts, tiltDirections } from './press-tilt-calibration.js';
+export type { PressTiltCalibration, PressTiltAction, PressTiltActionName } from './press-tilt-calibration.js';
+export { calibrateTilts } from './tilt-calibration.js';
+export type { TiltCalibration, TiltCalibrationAction, TiltActionName } from './tilt-calibration.js';

package/dist/index.js

@@ -4,3 +4,5 @@ export { createGestures } from './gestures.js';
 export { createGestureTune, defaultGestureTune, gesturePresets } from './tune.js';
 export { createGestureRecorder, validateGestureRecording } from './recording.js';
 export { calibrateGestures, gestureDirections } from './calibration.js';
+export { calibratePressTilts, tiltDirections } from './press-tilt-calibration.js';
+export { calibrateTilts } from './tilt-calibration.js';

package/dist/press-tilt-calibration.d.ts

@@ -0,0 +1,32 @@
+import type { TiltDirection } from './gestures.js';
+import type { GestureRecording } from './recording.js';
+import type { GestureTune } from './tune.js';
+export declare const tiltDirections: readonly ['rx+', 'rx-', 'ry+', 'ry-'];
+export type PressTiltActionName = `${'push' | 'pull'}.${TiltDirection}`;
+export interface PressTiltAction {
+    direction: 'push' | 'pull';
+    tilt: TiltDirection;
+    kind: 'single';
+    recording: number;
+    start: number;
+    end: number;
+    pressurePeak: number;
+    tiltPeak: number;
+    pressureAtTiltPeak: number;
+    onsetDelayMs: number;
+}
+export interface PressTiltCalibration {
+    status: 'ready' | 'incomplete' | 'ambiguous';
+    tune: GestureTune | null;
+    counts: Record<PressTiltActionName, number>;
+    missing: PressTiltActionName[];
+    actions: PressTiltAction[];
+    issues: string[];
+}
+/** Infer combined single excursions from raw z/rx/ry. Preserves the base simple/double tune.
+ * Coverage is inferred evidence, not ground-truth labels or measured classification accuracy.
+ */
+export declare function calibratePressTilts(input: GestureRecording | readonly GestureRecording[], settings?: {
+    baseTune?: GestureTune;
+    minimumPerAction?: number;
+}): PressTiltCalibration;