@clankagent/puck 0.1.0 → 0.3.0

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

@@ -0,0 +1,58 @@
+import type { GestureOptions } from './gestures.js';
+export interface ForceBand {
+    readonly center: number;
+    readonly low: number;
+    readonly high: number;
+    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;
+    readonly push: ForceBand;
+    readonly pull: ForceBand;
+    readonly timing: {
+        readonly minPulseMs: number;
+        readonly maxPulseMs: number;
+        readonly neutralMs: number;
+        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;
+    harden(amount: number): GestureTune;
+    narrow(amount: number): GestureTune;
+    widen(amount: number): GestureTune;
+    toOptions(): GestureOptions;
+    toJSON(): GestureTuneData;
+}
+/** Restore a plain JSON tune; all nested objects are copied and frozen. */
+export declare function createGestureTune(data?: GestureTuneData): GestureTune;
+export declare const defaultGestureTune: GestureTune;
+export declare const gesturePresets: Readonly<{
+    default: GestureTune;
+    soft: GestureTune;
+    hard: GestureTune;
+}>;

package/dist/tune.js

@@ -0,0 +1,56 @@
+const base = {
+    version: 1,
+    rotation: { center: .465, low: .349, high: .57, activation: .25, release: .15 },
+    push: { center: .314, low: .274, high: .354, activation: .20, release: .08 },
+    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 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;
+    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) {
+        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));
+                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);
+                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, 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() { 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();
+export const gesturePresets = Object.freeze({ default: defaultGestureTune, soft: defaultGestureTune.soften(.2), hard: defaultGestureTune.harden(.2) });

package/docs/agents.md

@@ -0,0 +1,34 @@
+# Agent integration guide
+
+[Documentation](../README.md) · [API reference](api.md) · [Complete integration](quickstart.md)
+
+This guide is for agents building applications with Puck. Repository contribution instructions live separately in [AGENTS.md](../AGENTS.md).
+
+1. Read the README version note. Match docs to the installed package version and its exports/declarations; experimental checkout APIs may not exist in the registry release.
+2. Read the API reference for exact entry points, axis signs, units and defaults. Use public imports only. Core is transport-independent; WebHID and graph rendering are optional.
+3. Adapt the complete session example for gestures/recording, or the motion example for cameras. The application owns timers, rendering, persistence and teardown.
+4. Verify behavior with synthetic inputs and the actual application lifecycle. Do not claim physical compatibility or subjective feel from synthetic tests.
+
+## Integration invariants
+
+- Six axes are normalized deflection, not velocity or angle. Verified signs: +rz clockwise, +z push down. Gestures are cap pulses, not physical button events.
+- Feed every input report to the recognizer and recorder. Call advance during report silence. Use one monotonic millisecond clock; do not mix performance.now() reports with rAF-supplied gesture timestamps.
+- Ignore the adapter's exact neutralInput lifecycle sentinel in the gesture report callback; reset on onReset. Do not infer a physical release on blur/disconnect. Reset requires fresh neutral to rearm.
+- Exclusive singles intentionally wait for the double window. Immediate mode produces an additive single then double. Choose consciously.
+- Tune edits return new immutable values. Persist JSON data; restore through createGestureTune. Rotation shares one band for both directions. Typical low/high are not acceptance limits.
+- Calibration needs at least three instances of EACH of eight actions, in any order. Check tune for null, show missing/ambiguous results, and retain raw input for inspection. Deduplicate recordings before combining. Inferred counts are not labeled intent accuracy.
+- No automatic backend, upload, storage or device reconnection is supplied. Never invent those capabilities or promise unverified hardware support.
+
+## Verification checklist
+
+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

@@ -0,0 +1,93 @@
+# API reference
+
+[Documentation](../README.md) · [Quickstart](quickstart.md) · [Tuning guide](tuning.md)
+
+This reference describes 0.2.0, including its experimental gesture APIs. Emitted `dist/*.d.ts` files are the exact TypeScript signatures for your build. Named exports only; use the three supported entry points below, not deep imports into `dist`.
+
+## Imports and units
+
+| Entry point | Runtime exports |
+|---|---|
+| `@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`, `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.
+
+`decodeCombinedReport(reportId, DataView)` accepts report 1 with exactly 12 bytes, decodes six little-endian signed 16-bit values divided by 350 and clamps to [-1,1]. Other reports return `null`. `neutralInput` is a shared frozen zero input; the WebHID adapter also uses its identity as a lifecycle sentinel.
+
+## Motion
+
+`createPanZoom(options?)` returns `setInput(input)`, `step(time)`, `setZoomInput('twist'|'press')`, `reset()`. Step returns `{panX, panY, zoomFactor, moving}`. Pan is screen pixels; zoom is multiplicative. First step is idle. Input is held until replaced; neutral stops on the next step.
+
+| Option | Default |
+|---|---|
+| `zoomInput` | `'twist'` |
+| `panSpeed`, `zoomSpeed` | 1320 pixels/s, 1.5 log-units/s |
+| `panDeadzone`, `zoomDeadzone` | .05, .1 |
+| `responseMs`, `maxFrameMs` | 25, 50 |
+
+Speeds/times must be finite and nonnegative; deadzones are in [0,1). Invalid options throw `RangeError`.
+
+## Gestures
+
+`createGestures(tuneOrOptions?)` returns `update(input,time)`, `advance(time)`, `reset()`, and read-only `state` (`phase`, `direction`, `pending`). Both update and advance return event arrays. Process EVERY report; advance even when reports are silent. Timestamps must be finite and nondecreasing or throw `RangeError`.
+
+An event is `{direction, kind, timestamp, durationMs}`. Direction is `clockwise|counterclockwise|push|pull`; kind is `single|double`. Timestamp is the logical recognition deadline, which can precede dispatch. Reset cancels pending actions and requires fresh neutral input. A hold is not repeated presses; reversal without neutral cancels the action.
+
+| Default | Rotation (both signs) | Push | Pull |
+|---|---|---|---|
+| Center | .465 | .314 | .289 |
+| Typical low–high | .349–.570 | .274–.354 | .180–.357 |
+| Activation / release | .25 / .15 | .20 / .08 | .12 / .06 |
+
+Timing defaults: `minPulseMs:35`, `maxPulseMs:650`, `neutralMs:25`, `doubleMs:400`; `dominance:1.4`. The double window is completion-to-completion. Both gesture axes must return below their release levels for neutral dwell.
+
+`singleMode:'exclusive'` (default) waits before emitting a single so a double can replace it. `'immediate'` emits a single first and later an additive double; no undo is emitted. Prefer exclusive when actions must not both fire.
+
+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.
+
+`defaultGestureTune` and `gesturePresets.default` are the baseline; `.soft` and `.hard` use 20% force adjustments. Methods `soften(x)`, `harden(x)`, `narrow(x)`, `widen(x)` return new tunes and never change timing. Amounts are fractions: .1 means 10%. Soften/narrow allow [0,1), harden/widen [0,10]. See [exact editing semantics](tuning.md#gesture-tunes).
+
+`toOptions()` produces recognizer configuration. `toJSON()` produces frozen portable data. Restore parsed JSON with `createGestureTune(data)`; JSON alone has no methods. For nested edits, use a new object, e.g. `createGestureTune({...tune.toJSON(), timing:{...tune.timing,doubleMs:450}})`. Typical low/high are descriptive, not rejection cutoffs.
+
+## Recording
+
+`createGestureRecorder({startTimeMs,tune?,options?,source?,note?,maxDurationMs?,maxEntries?})` returns `input(input,time)`, `advance(time)`, `reset(time)`, `events(events)`, `snapshot(time)` and `full`. Explicit `options` takes precedence over tune. Source defaults to `'device'`; use `'simulator'` for generated input.
+
+Input/tick/reset calls share a finite nondecreasing clock. Samples are copied. Default bounds are 120000 ms and 50000 entries (maximum configurable entries 60000); events cap at 10000. `full` signals a rejected timeline entry due to bounds; the app owns stopping and saving. Snapshot is detached, not a stop operation.
+
+`GestureRecording` shape: `{version:1,source,note,durationMs,options,timeline,events}`. Timeline entries are `{type:'input',t,input}` or `{type:'advance'|'reset',t}`. All times, including stored event timestamps, are relative to capture start. `validateGestureRecording(recording)` checks version, duration and timeline shape/bounds/axis values; it is not exhaustive validation of every metadata field. Invalid recording input throws `RangeError`.
+
+## Calibration
+
+`calibrateGestures(recordingOrArray, settings?)` accepts 1–20 recordings. Settings: `minimumPerAction` integer 3–100 (default 3), `detectionFloor` (0,.1] (default .025), `pairGapMs` 50–500 (default 250).
+
+Returns `{status,tune,counts,missing,stats,pulses,actions,issues}`. Status is `ready|incomplete|ambiguous`; **check `result.tune !== null` before using it** (the TypeScript interface is not a discriminated union). Counts use eight keys such as `clockwise.single` and `pull.double`. Stats hold per-direction peak count/mean/percentiles/min/max. Actions hold direction, kind, start, end, pulses and zero-based recording index. Pulses also expose peak, peakTime, valleyBefore and reset segment.
+
+The parser infers actions from raw shape, independent of order and recognized event labels. Never claim counts are labeled accuracy. Separate captures/resets cannot form pairs. Repeated copies of a recording are NOT deduplicated by the SDK; the app must avoid duplicate evidence. See [calibration behavior](tuning.md#recording-and-custom-calibration).
+
+## Graphs
+
+`createGestureGraph(recording,tune?,{start?,end?,actions?,recordingIndex?}?)` returns `{start,end,lanes}`. Each of four lanes has direction/label, band values, `{t,value}` points and action spans. Times are capture-relative; values are positive magnitudes. Default tune is the baseline. A custom time window must be finite with `0 <= start < end`. For combined analysis, pass the matching `recordingIndex` (default 0).
+
+`renderGestureGraphSvg(model,{width?,title?}?)` returns a standalone SVG string. Width defaults to 960, range 280–4000. Blue steps are held input, green dashed is activation, gray dotted is release, pale fill is typical range; shaded spans are inferred actions. Labels, title and description supplement color. Provide a text count/status summary alongside graphs in your UI. The model can also feed your own accessible chart renderer.
+
+## WebHID lifecycle
+
+`connectWebHid({onInput,onReset?,onDisconnect?,profile?,hid?,pauseOnBlur?})` returns a promise of connection or null on chooser cancellation. Connection exposes `device`, `pause()`, `resume()`, async `close()`. Default `pauseOnBlur:true` clears on blur/hidden. Pause/close/disconnect also clear; returning to foreground/resume requires a fresh report.
+
+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.

package/docs/lab.md

@@ -0,0 +1,62 @@
+# Gesture lab
+
+[Documentation](../README.md)
+
+Run from a source checkout; the lab server is not shipped in the npm package.
+
+## Local gesture lab
+
+```sh
+pnpm build
+pnpm lab
+```
+
+The example demonstrates the same public SDK: freeform recording, automatic
+calibration, minimum-example coverage, reusable tune JSON, immutable adjustments,
+and inspectable graphs. Choose **Analyze saved recording**, then select an action
+to zoom into it. **Use this tune** applies the result to live input. The default,
+soft and hard presets are also available. Recordings can be combined to supply
+missing examples; replaying the same saved ID does not duplicate its evidence.
+
+The example server binds to loopback. Recordings stay outside the repository in
+the user's local application data directory under `Puck/recordings`
+(`PUCK_RECORDINGS_DIR` overrides it), and are not in the npm package. Apps should
+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/motion.md

@@ -0,0 +1,20 @@
+# Motion and hardware
+
+[Documentation](../README.md) · [API reference](api.md)
+
+## 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).

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/quickstart.md

@@ -0,0 +1,78 @@
+# Browser quickstart
+
+[Documentation](../README.md) · [API reference](api.md)
+
+These examples target the source checkout described in the README. Use a browser with WebHID in a secure context and call connection from a user click. A cancelled chooser returns `null`; unsupported browsers and device errors reject the promise. Catch and display those errors in your UI.
+
+Copy [gesture-session.mjs](../examples/gesture-session.mjs) into your app. It is a complete connection and recording wrapper using public imports, with one clock, lifecycle resets and frame cleanup. Resolve its package imports through your bundler. It is an example file, not a package export.
+
+```js
+import { connectGestureSession } from './gesture-session.mjs';
+import { calibrateGestures, defaultGestureTune } from '@clankagent/puck';
+import { createGestureGraph, renderGestureGraphSvg } from '@clankagent/puck/graph';
+
+// Your page supplies buttons with these IDs and a pre with id="output".
+const connect = document.querySelector('#connect');
+const start = document.querySelector('#start');
+const stop = document.querySelector('#stop');
+const output = document.querySelector('#output');
+let session = null;
+let connecting = false;
+connect.onclick = async () => {
+  if (session || connecting) return;
+  connecting = true;
+  try {
+    session = await connectGestureSession({
+      onEvents: events => { output.textContent = JSON.stringify(events, null, 2); },
+      onDisconnect: () => { output.textContent = 'Disconnected. Save the capture before reconnecting.'; },
+    });
+  } catch (error) { output.textContent = String(error); }
+  finally { connecting = false; }
+};
+start.onclick = () => {
+  try { session?.startRecording(); }
+  catch (error) { output.textContent = String(error); }
+};
+stop.onclick = () => {
+  const recording = session?.stopRecording();
+  if (!recording) return;
+  const result = calibrateGestures(recording);
+  output.textContent = JSON.stringify({ status: result.status, counts: result.counts, issues: result.issues }, null, 2);
+  const graph = createGestureGraph(recording, result.tune ?? defaultGestureTune, { actions: result.actions });
+  // Add this SVG to a graph container, or save it as an .svg file.
+  const svg = renderGestureGraphSvg(graph);
+  console.log(svg);
+  // Persist JSON.stringify(recording) using your app's download/storage UI.
+  // When result.tune is non-null, persist JSON.stringify(result.tune) separately.
+};
+// On component teardown or before reconnecting:
+async function dispose() {
+  const recording = session?.stopRecording(); // Save this if wanted.
+  await session?.close();
+  session = null;
+  return recording;
+}
+```
+
+Start capture while the cap is neutral. Perform at least three singles AND three doubles in EACH direction: clockwise, counterclockwise, push down, pull up. Any order works. Finish with neutral and allow the double window to expire before stopping. The recorder is bounded; check `session.recordingFull` in your UI and stop/save when full. Reconnect with a new session after disconnect. To apply a learned tune, close the old session and pass `{ tune: result.tune }` when connecting the next one.
+
+## Pan and zoom
+
+```js
+import { createPanZoom } from '@clankagent/puck';
+import { connectWebHid } from '@clankagent/puck/webhid';
+
+const motion = createPanZoom({ zoomInput: 'press' });
+let frameId;
+function frame(time) {
+  const delta = motion.step(time);
+  // Your camera consumes delta.panX, delta.panY and delta.zoomFactor.
+  frameId = requestAnimationFrame(frame);
+}
+// In your connect click handler:
+const connection = await connectWebHid({ onInput: motion.setInput, onReset: motion.reset });
+if (connection) frameId = requestAnimationFrame(frame);
+// On teardown: cancelAnimationFrame(frameId); await connection?.close();
+```
+
+[Camera arithmetic](../examples/camera.mjs) shows zoom anchors and limits. Motion-only code can use rAF timestamps because reports do not advance its clock. For gestures use `performance.now()` in both callbacks, as in the session example. If combining motion and gestures, fan each report out to both processors and reset both on lifecycle changes; keep a single app-owned frame loop.