@clankagent/puck 0.2.0 → 0.3.0

package/dist/press-tilt-calibration.js

@@ -0,0 +1,88 @@
+import { validateGestureRecording } from './recording.js';
+import { createGestureTune, defaultGestureTune } from './tune.js';
+export const tiltDirections = ['rx+', 'rx-', 'ry+', 'ry-'];
+const quantile = (v, p) => { const a = [...v].sort((x, y) => x - y), at = (a.length - 1) * p, i = Math.floor(at); return a[i] + (a[Math.ceil(at)] - a[i]) * (at - i); };
+/** 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 function calibratePressTilts(input, settings = {}) {
+    const recordings = Array.isArray(input) ? input : [input];
+    const minimum = settings.minimumPerAction ?? 3, base = settings.baseTune ?? defaultGestureTune;
+    if (!Number.isInteger(minimum) || minimum < 3 || minimum > 100 || recordings.length < 1 || recordings.length > 20)
+        throw new RangeError('Use 1–20 recordings and at least three examples per action.');
+    const counts = {};
+    for (const d of ['push', 'pull'])
+        for (const tilt of tiltDirections)
+            counts[`${d}.${tilt}`] = 0;
+    const actions = [], issues = [];
+    let ambiguous = false;
+    function finish(rows, recording) {
+        if (!rows.length)
+            return;
+        const peak = (k) => rows.reduce((a, b) => Math.abs(b.input[k]) > Math.abs(a.input[k]) ? b : a);
+        const px = peak('rx'), py = peak('ry'), pz = peak('z');
+        const axis = Math.abs(px.input.rx) >= Math.abs(py.input.ry) ? 'rx' : 'ry', top = axis === 'rx' ? px : py;
+        const strength = Math.abs(top.input[axis]), other = Math.max(...rows.map(r => Math.abs(r.input[axis === 'rx' ? 'ry' : 'rx'])));
+        if (strength < .25)
+            return; // Plain presses are evidence for the separate simple/double calibration.
+        const direction = pz.input.z > 0 ? 'push' : 'pull', sign = direction === 'push' ? 1 : -1;
+        const pressure = rows.find(r => r.input.z * sign >= base[direction].activation);
+        const onset = rows.find(r => Math.abs(r.input[axis]) >= .25);
+        if (!pressure || !onset || onset.t < pressure.t || rows[rows.length - 1].t - rows[0].t > 1500 || rows.some(r => r.input.z * sign < -base[direction === 'push' ? 'pull' : 'push'].activation) || strength < other * 1.25) {
+            ambiguous = true;
+            issues.push('Excluded a tilt with ambiguous direction, pressure order, reversal or duration.');
+            return;
+        }
+        const tilt = (axis + (top.input[axis] > 0 ? '+' : '-'));
+        actions.push({ direction, tilt, kind: 'single', recording, start: pressure.t, end: rows[rows.length - 1].t, pressurePeak: Math.abs(pz.input.z), tiltPeak: strength, pressureAtTiltPeak: Math.abs(top.input.z), onsetDelayMs: onset.t - pressure.t });
+        counts[`${direction}.${tilt}`]++;
+    }
+    recordings.forEach((recording, index) => {
+        validateGestureRecording(recording);
+        let run = [], quietAt = null, armed = false;
+        for (const row of recording.timeline) {
+            if (row.type === 'reset') {
+                if (run.length)
+                    issues.push('Discarded an interrupted excursion.');
+                run = [];
+                quietAt = null;
+                armed = false;
+                continue;
+            }
+            if (row.type !== 'input')
+                continue;
+            const magnitude = Math.max(Math.abs(row.input.z), Math.abs(row.input.rx), Math.abs(row.input.ry));
+            if (magnitude <= .06) {
+                armed = true;
+                quietAt ?? (quietAt = row.t);
+                continue;
+            }
+            if (run.length && quietAt !== null && row.t - quietAt > 180) {
+                finish(run, index);
+                run = [];
+            }
+            if (armed)
+                run.push(row);
+            quietAt = null;
+        }
+        const inputs = recording.timeline.filter(r => r.type === 'input'), last = inputs[inputs.length - 1];
+        if (run.length) {
+            if (last?.type === 'input' && Math.max(Math.abs(last.input.z), Math.abs(last.input.rx), Math.abs(last.input.ry)) <= .06)
+                finish(run, index);
+            else
+                issues.push('Discarded an unfinished excursion at recording end.');
+        }
+    });
+    const missing = Object.keys(counts).filter(k => counts[k] < minimum);
+    let tune = null;
+    if (!missing.length && !ambiguous) {
+        const peaks = actions.map(a => a.tiltPeak), activation = Math.min(.25, Math.min(...peaks) * .8);
+        const center = peaks[0] + peaks.reduce((sum, v) => sum + v - peaks[0], 0) / peaks.length;
+        tune = createGestureTune({ ...base.toJSON(), pressTilt: {
+                force: { center, low: Math.min(center, quantile(peaks, .1)), high: Math.max(center, quantile(peaks, .9)), activation, release: activation * .48 },
+                minMs: 25, armMs: Math.max(450, Math.ceil((Math.max(...actions.map(a => a.onsetDelayMs)) + 80) / 50) * 50), relaxMs: 180,
+                maxMs: Math.max(1000, Math.ceil(Math.max(...actions.map(a => a.end - a.start)) * 1.5 / 50) * 50), dominance: 1.25,
+            } });
+    }
+    return { status: ambiguous ? 'ambiguous' : missing.length ? 'incomplete' : 'ready', tune, counts, missing, actions, issues: [...new Set(issues)] };
+}

package/dist/tilt-calibration.d.ts

@@ -0,0 +1,26 @@
+import type { CalibrationStats } from './calibration.js';
+import type { TiltDirection } from './gestures.js';
+import type { GestureRecording } from './recording.js';
+import type { GestureTune } from './tune.js';
+export type TiltActionName = `${TiltDirection}.${'single' | 'double'}`;
+export interface TiltCalibrationAction {
+    direction: TiltDirection;
+    kind: 'single' | 'double';
+    start: number;
+    end: number;
+    recording: number;
+}
+export interface TiltCalibration {
+    status: 'ready' | 'incomplete' | 'ambiguous';
+    tune: GestureTune | null;
+    counts: Record<TiltActionName, number>;
+    missing: TiltActionName[];
+    actions: TiltCalibrationAction[];
+    stats: Partial<Record<TiltDirection, CalibrationStats>>;
+    issues: string[];
+}
+/** Reuse the raw pulse parser on rx/ry; never pair across capture/reset boundaries. */
+export declare function calibrateTilts(input: GestureRecording | readonly GestureRecording[], settings?: {
+    baseTune?: GestureTune;
+    minimumPerAction?: number;
+}): TiltCalibration;

package/dist/tilt-calibration.js

@@ -0,0 +1,46 @@
+import { calibrateGestures } from './calibration.js';
+import { validateGestureRecording } from './recording.js';
+import { createGestureTune, defaultGestureTune } from './tune.js';
+const names = { clockwise: 'rx+', counterclockwise: 'rx-', push: 'ry+', pull: 'ry-' };
+/** Reuse the raw pulse parser on rx/ry; never pair across capture/reset boundaries. */
+export function calibrateTilts(input, settings = {}) {
+    const captures = Array.isArray(input) ? input : [input];
+    const base = settings.baseTune ?? defaultGestureTune;
+    const mapped = captures.map(c => {
+        validateGestureRecording(c);
+        let pressureOwned = false;
+        const timeline = c.timeline.map(row => {
+            if (row.type === 'reset') {
+                pressureOwned = false;
+                return row;
+            }
+            if (row.type !== 'input')
+                return row;
+            const v = row.input;
+            if (Math.max(Math.abs(v.z), Math.abs(v.rz), Math.abs(v.rx), Math.abs(v.ry)) <= .06)
+                pressureOwned = false;
+            if (Math.max(Math.abs(v.rx), Math.abs(v.ry)) < .15 && (v.z >= base.push.activation || -v.z >= base.pull.activation || Math.abs(v.rz) >= base.rotation.activation))
+                pressureOwned = true;
+            if (pressureOwned)
+                return { type: 'reset', t: row.t };
+            return { ...row, input: { x: 0, y: 0, z: v.ry, rz: v.rx, rx: 0, ry: 0 } };
+        });
+        return { ...c, timeline };
+    });
+    const result = calibrateGestures(mapped, { minimumPerAction: settings.minimumPerAction, detectionFloor: .06 });
+    const rename = (key) => { const [direction, kind] = key.split('.'); return `${names[direction]}.${kind}`; };
+    const counts = Object.fromEntries(Object.entries(result.counts).map(([k, v]) => [rename(k), v]));
+    let tune = null;
+    if (result.tune) {
+        const t = result.tune;
+        const rxActivation = Math.min(t.rotation.activation, Math.min(result.stats.clockwise.min, result.stats.counterclockwise.min) * .85);
+        const rx = { ...t.rotation, activation: rxActivation, release: Math.min(t.rotation.release, rxActivation * .8) };
+        const ry = Object.fromEntries(['center', 'low', 'high', 'activation', 'release'].map(k => [k, (t.push[k] + t.pull[k]) / 2]));
+        tune = createGestureTune({ ...base.toJSON(), standaloneTilt: { rx, ry, timing: { ...t.timing, minPulseMs: Math.min(25, t.timing.minPulseMs), neutralMs: 10 } } });
+    }
+    return { status: result.status, tune, counts, missing: result.missing.map(rename),
+        actions: result.actions.map(a => ({ direction: names[a.direction], kind: a.kind, start: a.start, end: a.end, recording: a.recording })),
+        stats: Object.fromEntries(Object.entries(result.stats).map(([k, v]) => [names[k], v])),
+        issues: result.issues.map(issue => issue.replace(/counterclockwise|clockwise|push|pull/g, k => names[k])),
+    };
+}

package/dist/tune.d.ts

@@ -6,6 +6,24 @@ export interface ForceBand {
     readonly activation: number;
     readonly release: number;
 }
+export interface PressTiltTune {
+    readonly force: ForceBand;
+    readonly minMs: number;
+    readonly armMs: number;
+    readonly relaxMs: number;
+    readonly maxMs: number;
+    readonly dominance: number;
+}
+export interface StandaloneTiltTune {
+    readonly rx: ForceBand;
+    readonly ry: ForceBand;
+    readonly timing: {
+        readonly minPulseMs: number;
+        readonly maxPulseMs: number;
+        readonly neutralMs: number;
+        readonly doubleMs: number;
+    };
+}
 export interface GestureTuneData {
     readonly version: 1;
     readonly rotation: ForceBand;
@@ -18,6 +36,9 @@ export interface GestureTuneData {
         readonly doubleMs: number;
     };
     readonly dominance: number;
+    /** Optional for backward-compatible restoration of 0.2 tunes. Does not enable tilt mode by itself. */
+    readonly pressTilt?: PressTiltTune;
+    readonly standaloneTilt?: StandaloneTiltTune;
 }
 export interface GestureTune extends GestureTuneData {
     soften(amount: number): GestureTune;

package/dist/tune.js

@@ -5,47 +5,51 @@ const base = {
     pull: { center: .289, low: .18, high: .357, activation: .12, release: .06 },
     timing: { minPulseMs: 35, maxPulseMs: 650, neutralMs: 25, doubleMs: 400 },
     dominance: 1.4,
+    pressTilt: { force: { center: .596, low: .401, high: .803, activation: .24, release: .115 }, minMs: 25, armMs: 450, relaxMs: 180, maxMs: 1000, dominance: 1.25 },
+    standaloneTilt: { rx: { center: .458, low: .319, high: .601, activation: .13, release: .104 }, ry: { center: .671, low: .536, high: .806, activation: .28, release: .16 }, timing: { minPulseMs: 25, maxPulseMs: 650, neutralMs: 10, doubleMs: 400 } },
 };
 const finite = (x) => typeof x === 'number' && Number.isFinite(x);
 /** Restore a plain JSON tune; all nested objects are copied and frozen. */
 export function createGestureTune(data = base) {
     if (!data || data.version !== 1 || !finite(data.dominance) || data.dominance < 1)
         throw new RangeError('Invalid tune version or dominance.');
-    for (const key of ['rotation', 'push', 'pull']) {
-        const b = data[key];
+    for (const b of [data.rotation, data.push, data.pull, ...(data.pressTilt ? [data.pressTilt.force] : []), ...(data.standaloneTilt ? [data.standaloneTilt.rx, data.standaloneTilt.ry] : [])]) {
         if (!b || ![b.center, b.low, b.high, b.activation, b.release].every(finite)
             || b.low < 0 || b.low > b.center || b.center > b.high || b.high > 1
             || b.release < 0 || b.activation <= b.release || b.activation > 1 || b.center <= 0)
             throw new RangeError('Invalid force band.');
     }
     const t = data.timing;
-    if (!t || ![t.minPulseMs, t.maxPulseMs, t.neutralMs, t.doubleMs].every(v => finite(v) && v >= 0)
-        || t.minPulseMs > t.maxPulseMs || t.maxPulseMs > 10000 || t.doubleMs > 10000 || t.neutralMs > 1000)
-        throw new RangeError('Invalid tune timing.');
-    const value = Object.freeze({ version: 1, rotation: Object.freeze({ ...data.rotation }), push: Object.freeze({ ...data.push }), pull: Object.freeze({ ...data.pull }), timing: Object.freeze({ ...t }), dominance: data.dominance });
+    const p = data.pressTilt;
+    if (p && (![p.minMs, p.armMs, p.relaxMs, p.maxMs, p.dominance].every(finite) || p.minMs < 0 || p.armMs < p.minMs || p.relaxMs < 0 || p.relaxMs > p.armMs || p.armMs > p.maxMs || p.maxMs > 10000 || p.dominance <= 1))
+        throw new RangeError('Invalid press-tilt tune.');
+    for (const timing of [t, ...(data.standaloneTilt ? [data.standaloneTilt.timing] : [])])
+        if (!timing || ![timing.minPulseMs, timing.maxPulseMs, timing.neutralMs, timing.doubleMs].every(v => finite(v) && v >= 0)
+            || timing.minPulseMs > timing.maxPulseMs || timing.maxPulseMs > 10000 || timing.doubleMs > 10000 || timing.neutralMs > 1000)
+            throw new RangeError('Invalid tune timing.');
+    const s = data.standaloneTilt;
+    const value = Object.freeze({ version: 1, rotation: Object.freeze({ ...data.rotation }), push: Object.freeze({ ...data.push }), pull: Object.freeze({ ...data.pull }), timing: Object.freeze({ ...t }), dominance: data.dominance, ...(p ? { pressTilt: Object.freeze({ ...p, force: Object.freeze({ ...p.force }) }) } : {}), ...(s ? { standaloneTilt: Object.freeze({ rx: Object.freeze({ ...s.rx }), ry: Object.freeze({ ...s.ry }), timing: Object.freeze({ ...s.timing }) }) } : {}) });
     const amount = (x, subtract) => { if (!finite(x) || x < 0 || (subtract && x >= 1) || x > 10)
         throw new RangeError('Amount must be a non-negative fraction; soften/narrow require less than 1.'); return subtract ? 1 - x : 1 + x; };
     function edit(factor, mode) {
-        const bands = {};
-        for (const key of ['rotation', 'push', 'pull']) {
-            const b = value[key];
+        function band(b) {
             if (mode === 'force') {
                 // Scale each band uniformly; saturation preserves ordering and hysteresis.
                 const f = Math.min(factor, 1 / Math.max(b.high, b.activation));
-                bands[key] = { center: b.center * f, low: b.low * f, high: b.high * f, activation: b.activation * f, release: b.release * f };
+                return { center: b.center * f, low: b.low * f, high: b.high * f, activation: b.activation * f, release: b.release * f };
             }
             else {
                 const activation = Math.max(.001, b.center - (b.center - b.activation) * factor);
-                bands[key] = { center: b.center, low: Math.max(0, b.center - (b.center - b.low) * factor), high: Math.min(1, b.center + (b.high - b.center) * factor), activation, release: activation * b.release / b.activation };
+                return { center: b.center, low: Math.max(0, b.center - (b.center - b.low) * factor), high: Math.min(1, b.center + (b.high - b.center) * factor), activation, release: activation * b.release / b.activation };
             }
         }
-        return createGestureTune({ ...value, ...bands });
+        return createGestureTune({ ...value, rotation: band(value.rotation), push: band(value.push), pull: band(value.pull), ...(value.pressTilt ? { pressTilt: { ...value.pressTilt, force: band(value.pressTilt.force) } } : {}), ...(value.standaloneTilt ? { standaloneTilt: { ...value.standaloneTilt, rx: band(value.standaloneTilt.rx), ry: band(value.standaloneTilt.ry) } } : {}) });
     }
     return Object.freeze({ ...value,
         soften(x) { return edit(amount(x, true), 'force'); }, harden(x) { return edit(amount(x, false), 'force'); },
         narrow(x) { return edit(amount(x, true), 'spread'); }, widen(x) { return edit(amount(x, false), 'spread'); },
         toJSON() { return value; },
-        toOptions() { return { twistActivation: value.rotation.activation, twistRelease: value.rotation.release, pushActivation: value.push.activation, pushRelease: value.push.release, pullActivation: value.pull.activation, pullRelease: value.pull.release, ...value.timing, dominance: value.dominance, singleMode: 'exclusive' }; },
+        toOptions() { const p = value.pressTilt, s = value.standaloneTilt; return { twistActivation: value.rotation.activation, twistRelease: value.rotation.release, pushActivation: value.push.activation, pushRelease: value.push.release, pullActivation: value.pull.activation, pullRelease: value.pull.release, ...value.timing, dominance: value.dominance, singleMode: 'exclusive', ...(p ? { tiltActivation: p.force.activation, tiltRelease: p.force.release, tiltMinMs: p.minMs, tiltArmMs: p.armMs, tiltRelaxMs: p.relaxMs, tiltMaxMs: p.maxMs, tiltDominance: p.dominance } : {}), ...(s ? { tiltXActivation: s.rx.activation, tiltXRelease: s.rx.release, tiltYActivation: s.ry.activation, tiltYRelease: s.ry.release, standaloneMinPulseMs: s.timing.minPulseMs, standaloneMaxPulseMs: s.timing.maxPulseMs, standaloneNeutralMs: s.timing.neutralMs, standaloneDoubleMs: s.timing.doubleMs } : {}) }; },
     });
 }
 export const defaultGestureTune = createGestureTune();

package/docs/agents.md

@@ -24,3 +24,11 @@ This guide is for agents building applications with Puck. Repository contributio
 Exercise a single, a double, neutral rearming, a long hold, a reversal, report silence, blur/disconnect and teardown. Confirm one action handler invocation per expected event and no completed gesture caused by disconnect. Check incomplete calibration and JSON tune restoration. Use performance.now() consistently in a browser and an explicit monotonic clock in deterministic tests.
 
 For library contributions, run `pnpm check` from the source checkout. The tests use built ESM modules. Read CONTRIBUTING before proposing API/profile changes. Do not edit generated dist files as the source of truth.
+
+## Tilt integrations (0.3)
+
+Read [standalone and combined tilt](press-tilt.md) before enabling these families.
+Use `calibrateTilts` for standalone singles/doubles and `calibratePressTilts` for
+pressure-first combinations; do not interpret one family's coverage as another.
+Handle expanded direction unions and optional event.tilt. Keep modes separate
+from persisted tune data, and never claim inferred labels are ground truth.

package/docs/api.md

@@ -8,9 +8,9 @@ This reference describes 0.2.0, including its experimental gesture APIs. Emitted
 
 | Entry point | Runtime exports |
 |---|---|
-| `@clankagent/puck` | `decodeCombinedReport`, `neutralInput`, `createPanZoom`, `createGestures`, `createGestureTune`, `defaultGestureTune`, `gesturePresets`, `createGestureRecorder`, `validateGestureRecording`, `calibrateGestures`, `gestureDirections` |
+| `@clankagent/puck` | `decodeCombinedReport`, `neutralInput`, `createPanZoom`, `createGestures`, `createGestureTune`, `defaultGestureTune`, `gesturePresets`, `createGestureRecorder`, `validateGestureRecording`, `calibrateGestures`, `gestureDirections`, `calibratePressTilts`, `calibrateTilts`, `tiltDirections` |
 | `@clankagent/puck/webhid` | `connectWebHid`, `combinedProfile` |
-| `@clankagent/puck/graph` | `createGestureGraph`, `renderGestureGraphSvg` |
+| `@clankagent/puck/graph` | `createGestureGraph`, `createPressTiltGraph`, `createTiltGraph`, `renderGestureGraphSvg` |
 
 `InputState` has six finite normalized axes: `x,y,z,rx,ry,rz`, each in [-1,1]. They represent deflection, not angles. For the verified profile, positive `rz` is clockwise and positive `z` is push down; negative values are counterclockwise and pull up. Force bands use positive magnitudes [0,1]. Times are milliseconds. Recorder and calibration times are relative to capture start; live recognizer event times use the supplied clock.
 
@@ -47,6 +47,13 @@ Timing defaults: `minPulseMs:35`, `maxPulseMs:650`, `neutralMs:25`, `doubleMs:40
 
 Low-level gates are `activation/release`, `pressActivation/pressRelease`, `twistActivation/twistRelease`, and `clockwiseActivation/clockwiseRelease` (likewise `counterclockwise`, `push`, `pull`). Precedence: direction → axis → shared → default tune. `createGestures({})` matches the no-argument form. Gates require `0 <= release < activation <= 1`; invalid options throw `RangeError`.
 
+For opt-in standalone rx/ry and combined pressure/tilt options, event shapes,
+timing, calibration results and graph constructors, see the [tilt API](press-tilt.md).
+`PulseDirection` names the original four; `TiltDirection` names rx+/rx-/ry+/ry-;
+`GestureDirection` is their union. `GestureEvent.tilt` is optional and only present
+for a combined single. `PressMode` is simple/auto/tilt. Exported tune types include
+`PressTiltTune` and `StandaloneTiltTune`.
+
 ## Tunes
 
 `createGestureTune(data?)` validates and copies a version-1 `GestureTuneData`: `{version, rotation, push, pull, timing, dominance}`. Each band contains `{center,low,high,activation,release}`; timing contains the four millisecond fields above. Returned objects are deeply frozen.
@@ -83,4 +90,4 @@ The parser infers actions from raw shape, independent of order and recognized ev
 
 A clear calls `onInput(neutralInput)` then `onReset()`. For gestures, ignore that exact sentinel in onInput and reset the recognizer in onReset, so a lifecycle change cannot finish a press. Real zero reports are separate objects. Custom decoders should return fresh input objects for physical reports. Motion can consume the sentinel directly. Close removes listeners; your app must cancel its own frame loop.
 
-`DeviceProfile` contains vendorId, productId, optional usagePage/usage, and `decode(reportId,data)`. An injected `hid` implements `HidAccess` for tests/custom transport integration. The default `combinedProfile` uses the verified IDs from the README. Do not infer additional device support from vendor ID alone.
+`DeviceProfile` contains vendorId, productId, optional usagePage/usage, and `decode(reportId,data)`. An injected `hid` implements `HidAccess` for tests/custom transport integration. The default `combinedProfile` uses the verified IDs from the README. Do not infer additional device support from vendor ID alone.

package/docs/lab.md

@@ -25,3 +25,38 @@ provide their own storage. This example uses a same-origin session token for
 writes, no CORS and no user authentication: keep it on loopback or behind a
 trusted private proxy. Failed saves retain a retry/download backup. `pnpm
 lab:analyze` reads the newest device recording, or accepts a JSON file path.
+
+## Combined-gesture research
+
+Open the lab with `?capture=press-move` for freeform push-move/pull-move capture.
+Use natural pressure, including relaxation while rotating or tilting the cap.
+Aim for three examples per push/pull × movement direction, plus ordinary single and
+double presses for comparison; no required order or guided sequence. Multiple
+captures are fine if two minutes is too short.
+
+The recorder saves all six raw axes regardless of existing recognition gates.
+The combined-tilt parser shows eight-direction coverage and six lanes for
+pressure and tilt. Its tune preserves the base simple/double-press settings.
+See the [combined gesture guide](press-tilt.md) and [1.0 criteria](roadmap.md).
+
+For standalone tilt research, use `?capture=tilt`. Record at least three
+singles and three doubles for each of the four rx/ry directions, without
+deliberate push/pull or twist. Any order is fine. These captures are marked
+separately and analyzed with the standalone tuner. Choose the Analyze selector
+to override automatic family detection. Enable Combine with loaded recordings
+before loading another partial capture. Use this tune enables the matching
+family. The standalone toggle and push/pull mode can also be set independently.
+
+## Verify capture before starting
+
+Connect the device and move the cap once. Start recording remains disabled
+until an actual device movement report arrives. During capture the report and
+movement counts must rise when you move; all six axes are retained independently
+of the gesture gates. Captures without movement are not saved as usable
+recordings. Disconnect ends and saves a partial capture if movement was received.
+The download backup remains available even for an empty diagnostic capture.
+
+Simulator recording is only enabled explicitly with `?source=simulator` (or
+`&source=simulator` after an existing query). It is labeled as simulator input
+and is not physical calibration evidence. Reload after lab updates; a reload
+requires reconnecting the device.

package/docs/press-tilt.md

@@ -0,0 +1,131 @@
+# Standalone and combined tilts (0.3.0)
+
+[Documentation](../README.md) · [Roadmap](roadmap.md)
+
+These experimental APIs are opt-in. Existing simple gestures remain the default.
+
+```js
+import {createGestures, defaultGestureTune} from '@clankagent/puck';
+const gestures = createGestures({...defaultGestureTune.toOptions(), pressMode:'auto'});
+// A combined event: {direction:'push', tilt:'rx+', kind:'single', timestamp, durationMs}
+```
+
+`pressMode` is `simple` (existing default), `auto` (choose plain or combined), or
+`tilt` (combined actions plus plain doubles; suppress plain singles). `pushMode`
+and `pullMode` override it independently. Combined modes require
+`singleMode:'exclusive'`. The `rx+`, `rx-`, `ry+`, `ry-` labels are device-axis
+directions; applications map these to their own screen orientation.
+
+Pressure arms tilt detection. The cap may relax while tilting; it need not stay
+above the pressure activation gate. A brief full release can still be joined
+to a subsequent tilt. Sustained tilt on the strongest direction chooses the
+action; a substantially stronger later direction can replace a preparatory
+tilt. A pressure reversal cancels the excursion. Pre-existing tilt cannot arm a
+combination. Neutral, interruption and maximum duration prevent repeated holds.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `tiltActivation`, `tiltRelease` | .24, .115 | Normalized force gates |
+| `tiltMinMs` | 25 | Short noise dwell, not a target execution speed |
+| `tiltArmMs` | 450 | Maximum time from pressure to tilt onset |
+| `tiltRelaxMs` | 180 | Maximum gap from pressure release to resumed tilt |
+| `tiltMaxMs` | 1000 | Maximum combined excursion duration |
+| `tiltDominance` | 1.25 | Required directional separation |
+
+The reference input is treated as the slower end of normal. Faster movements
+are accepted; the upper allowances are not mandatory waits. Combined events
+emit on full release plus neutral dwell, without waiting for a plain double.
+Repeated combinations are separate single actions; the recognizer does not pair
+them into combined doubles. Ordinary doubles retain completion-to-completion
+timing. With an unusually short `doubleMs`, plain singles wait at least
+`tiltRelaxMs + tiltMinMs` to leave time for a possible combination.
+
+## Tunes, recordings and graphs
+
+Tune JSON version 1 accepts optional `pressTilt` containing `force` (a standard
+force band), `minMs`, `armMs`, `relaxMs`, `maxMs`, and `dominance`. Old tunes
+remain restorable. The default tune includes these settings, but does not
+enable combined recognition. Immutable force edits also edit the tilt band;
+timings stay unchanged. Save the mode separately from the tune.
+
+`calibratePressTilts(recordingOrArray, {baseTune?, minimumPerAction?})` derives
+tilt settings from raw z/rx/ry, independent of event labels and group order. It
+requires at least three inferred examples of all eight push/pull × tilt
+combinations. The result has `status`, `tune`, `counts`, `missing`, `actions`
+and `issues`; only use a non-null tune. The base defaults to
+`defaultGestureTune`; ordinary press/twist force and double timing are preserved.
+No inferred count is a claim of labeled accuracy. Simulator input is useful
+for tests, not physical evidence. The parser uses fixed exploratory boundaries
+(.06 neutral, .25 tilt detection, 180 ms quiet gap); very different motion may
+need manual review. It does not learn every timing value from one capture.
+
+From `@clankagent/puck/graph`, `createPressTiltGraph(recording,tune,{actions,
+recordingIndex?,start?,end?})` produces six lanes (push, pull, four tilts) for
+`renderGestureGraphSvg`. Each combination marks both its pressure and tilt lane.
+Select a short window to see pressure relaxation instead of comparing an
+entire minute at once.
+
+The session example accepts `options:{pressMode:'auto'}` and records the exact
+configuration. Lifecycle reset still cancels all pending actions. Apps retain
+ownership of camera arbitration, recording storage, clocks and rendering.
+
+## Standalone directional singles and doubles
+
+Enable `standaloneTilt:true` to recognize rx+/rx−/ry+/ry− without a deliberate
+push, pull or twist. Events use `direction:'rx+'` (or another tilt direction)
+and `kind:'single'|'double'`, with no `tilt` field. Signs are device axes, not
+screen directions. Map them in the consuming app.
+
+```js
+const gestures = createGestures({
+  ...defaultGestureTune.toOptions(),
+  standaloneTilt: true,
+  pressMode: 'auto', // optional: also recognize pressure-first combinations
+});
+```
+
+The first qualifying motion owns the excursion: pressure-first can become a
+combination; tilt-first remains standalone even if incidental pressure follows.
+Neutral rx/ry completes a standalone pulse. Reversals without neutral cancel.
+A double pairs completions within its own double window. Exclusive singles
+wait; immediate singles are additive, as with ordinary presses. Combined modes
+still require exclusive singles. Long holds and lifecycle resets do not emit taps.
+
+| Standalone option | Default |
+|---|---|
+| `tiltXActivation`, `tiltXRelease` | .13, .104 |
+| `tiltYActivation`, `tiltYRelease` | .28, .16 |
+| `standaloneMinPulseMs`, `standaloneMaxPulseMs` | 25, 650 |
+| `standaloneNeutralMs`, `standaloneDoubleMs` | 10, 400 |
+
+Tune version 1 also accepts optional `standaloneTilt:{rx,ry,timing}`. Each axis
+has a force band shared by its positive/negative directions; timing contains
+`minPulseMs,maxPulseMs,neutralMs,doubleMs`. Old JSON remains valid. Presets and
+immutable edits include these bands; `toOptions()` supplies thresholds without
+enabling recognition. Store your mode choices alongside the tune.
+
+```js
+import {calibrateTilts, createGestureTune} from '@clankagent/puck';
+import {createTiltGraph, renderGestureGraphSvg} from '@clankagent/puck/graph';
+const result = calibrateTilts(recordings, {baseTune: defaultGestureTune});
+if (result.tune) {
+  const saved = JSON.stringify(result.tune);
+  const restored = createGestureTune(JSON.parse(saved));
+  const gestures = createGestures({...restored.toOptions(), standaloneTilt:true});
+}
+// Display result.status, counts, missing and issues even when tune is null.
+const model = createTiltGraph(recordings[0], result.tune ?? defaultGestureTune,
+  {actions:result.actions, recordingIndex:0});
+const svg = renderGestureGraphSvg(model);
+```
+
+`calibrateTilts(recordingOrArray,{baseTune?,minimumPerAction?})` requires three
+singles and three doubles per direction (eight action types), in any order.
+It accepts 1–20 captures, preserves capture/reset boundaries, and ignores
+pressure-first excursions. The result includes status, tune, counts, missing,
+actions, stats and issues. Other gesture families retain their base settings.
+Use one copy of each capture; duplicates are not new evidence. The parser uses
+.06 exploratory neutral/detection and .15 early-pressure separation; review
+unusual motion manually. Closely spaced singles may be inferred as doubles.
+The graph shows four signed tilt lanes, force bands and inferred action spans.
+These inferred labels are useful tuning evidence, not measured recognition accuracy.

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

@@ -24,4 +24,4 @@
 | 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.
+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/upgrading.md

@@ -9,14 +9,29 @@ Read the changelog for the version you are adopting, then use docs from that sam
 Gesture, tune, recording, calibration and graph APIs are included in 0.2.0. In your consuming app:
 
 ```sh
-pnpm add @clankagent/puck@0.2.0
+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.2.0 source tag. The new gesture APIs remain experimental; existing motion integrations retain their behavior.
+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.
@@ -41,4 +56,4 @@ To add gestures alongside motion, reuse the existing connection and frame loop.
 - **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.
+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

@@ -2,8 +2,9 @@ import { createGestures, createGestureRecorder, defaultGestureTune, neutralInput
 import { connectWebHid } from '@clankagent/puck/webhid';
 
 /** Call from a click handler. Returns null when the chooser is cancelled. */
-export async function connectGestureSession({ tune = defaultGestureTune, onEvents = console.log, onDisconnect = () => {} } = {}) {
-  const gestures = createGestures(tune);
+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;
@@ -35,7 +36,7 @@ export async function connectGestureSession({ tune = defaultGestureTune, onEvent
       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(), tune, source: 'device' });
+      recorder = createGestureRecorder({ startTimeMs: performance.now(), options:configuration, source: 'device' });
     },
     stopRecording() {
       if (!recorder) return null;

package/llms.txt

@@ -2,7 +2,7 @@
 
 > TypeScript/ESM six-axis input, pan/zoom, tunable cap gestures and freeform calibration. Zero runtime dependencies.
 
-Documentation targets 0.2.0, including experimental gesture/tune/recording/calibration/graph APIs. Match documentation to your installed version.
+Documentation targets 0.3.0, including experimental gesture/tune/recording/calibration/graph APIs. Match documentation to your installed version.
 
 ## Documentation
 
@@ -23,5 +23,7 @@ Documentation targets 0.2.0, including experimental gesture/tune/recording/calib
 - [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.
+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,6 +1,6 @@
 {
   "name": "@clankagent/puck",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Frame-independent six-axis input, pan/zoom and tunable gestures",
   "type": "module",
   "sideEffects": false,