@clankagent/puck 0.1.0 → 0.2.0

package/dist/gestures.js

@@ -0,0 +1,125 @@
+import { defaultGestureTune } from './tune.js';
+/** Experimental pulse recognizer. No timers, DOM, transport, or motion side effects. */
+export function createGestures(configuration = defaultGestureTune) {
+    const options = 'toOptions' in configuration ? configuration.toOptions() : configuration;
+    const activation = options.activation ?? .35;
+    const release = options.release ?? .12;
+    const pressActivation = options.pressActivation ?? options.activation;
+    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 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 },
+    };
+    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 dominance = options.dominance ?? 1.4;
+    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
+        || Object.values(thresholds).some(v => !Number.isFinite(v.activation) || !Number.isFinite(v.release) || v.release < 0 || v.activation <= v.release || v.activation > 1)
+        || maxPulseMs < minPulseMs || neutralMs < 0 || doubleMs < 0 || dominance < 1
+        || !['exclusive', 'immediate'].includes(singleMode))
+        throw new RangeError('Invalid gesture options.');
+    let last = -Infinity;
+    let z = 0, rz = 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;
+    function clock(t) {
+        if (!Number.isFinite(t) || t < last)
+            throw new RangeError('Gesture timestamps must be finite and monotonic.');
+        last = t;
+    }
+    function tick(t) {
+        const events = [];
+        if (phase === 'releasing' && releasedAt !== null && active && t >= releasedAt + neutralMs) {
+            const durationMs = releasedAt - active.start;
+            const completedAt = releasedAt + neutralMs;
+            if (durationMs >= minPulseMs && durationMs <= maxPulseMs) {
+                const pulse = { direction: active.direction, kind: 'single', timestamp: completedAt, durationMs };
+                if (pending && pending.direction === pulse.direction && completedAt - pending.timestamp <= doubleMs) {
+                    events.push({ ...pulse, kind: 'double' });
+                    pending = null;
+                }
+                else {
+                    if (pending && singleMode === 'exclusive')
+                        events.push({ ...pending, timestamp: Math.min(completedAt, pending.timestamp + doubleMs) });
+                    pending = pulse;
+                    if (singleMode === 'immediate')
+                        events.push(pulse);
+                }
+            }
+            active = null;
+            releasedAt = null;
+            phase = 'neutral';
+        }
+        if (active && phase === 'active' && t - active.start > 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 });
+            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'; },
+        advance(t) { clock(t); return tick(t); },
+        update(input, t) {
+            if (!Number.isFinite(input.z) || !Number.isFinite(input.rz))
+                throw new RangeError('Gesture axes must be finite.');
+            clock(t);
+            const events = tick(t);
+            z = Math.max(-1, Math.min(1, input.z));
+            rz = Math.max(-1, Math.min(1, input.rz));
+            if (phase === 'blocked') {
+                if (neutral())
+                    phase = 'neutral';
+                return events;
+            }
+            if (active) {
+                const signed = active.direction === 'push' ? z : active.direction === 'pull' ? -z : active.direction === 'clockwise' ? rz : -rz;
+                if (neutral()) {
+                    if (releasedAt === null)
+                        releasedAt = t;
+                    phase = 'releasing';
+                }
+                else if (signed < -thresholds[active.direction].release) {
+                    // Reversal without a neutral dwell is not a completed pulse.
+                    active = null;
+                    releasedAt = null;
+                    phase = 'blocked';
+                }
+                else {
+                    phase = 'active';
+                    releasedAt = null;
+                }
+            }
+            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');
+                if (strong >= thresholds[direction].activation && strong >= weak * dominance) {
+                    active = { direction, start: t };
+                    phase = 'active';
+                }
+            }
+            return events.concat(tick(t));
+        },
+    };
+}

package/dist/graph.d.ts

@@ -0,0 +1,39 @@
+import type { GestureDirection } from './gestures.js';
+import type { GestureTune } from './tune.js';
+import type { GestureRecording } from './recording.js';
+import type { CalibrationAction } from './calibration.js';
+export interface GestureGraphLane {
+    direction: GestureDirection;
+    label: string;
+    center: number;
+    low: number;
+    high: number;
+    activation: number;
+    release: number;
+    points: {
+        t: number;
+        value: number;
+    }[];
+    actions: {
+        start: number;
+        end: number;
+        kind: 'single' | 'double';
+    }[];
+}
+export interface GestureGraph {
+    start: number;
+    end: number;
+    lanes: GestureGraphLane[];
+}
+/** Renderer-neutral graph data. Use your charting library or the optional SVG renderer. */
+export declare function createGestureGraph(recording: GestureRecording, tune?: GestureTune, config?: {
+    start?: number;
+    end?: number;
+    actions?: readonly CalibrationAction[];
+    recordingIndex?: number;
+}): GestureGraph;
+/** Standalone accessible SVG. No DOM, canvas, frameworks or global listeners. */
+export declare function renderGestureGraphSvg(graph: GestureGraph, options?: {
+    width?: number;
+    title?: string;
+}): string;

package/dist/graph.js

@@ -0,0 +1,59 @@
+import { defaultGestureTune } from './tune.js';
+import { validateGestureRecording } from './recording.js';
+const labels = { clockwise: 'Clockwise', counterclockwise: 'Counterclockwise', push: 'Push down', pull: 'Pull up' };
+/** Renderer-neutral graph data. Use your charting library or the optional SVG renderer. */
+export function createGestureGraph(recording, tune = defaultGestureTune, config = {}) {
+    validateGestureRecording(recording);
+    const start = config.start ?? 0, end = config.end ?? Math.max(1, recording.durationMs);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end <= start)
+        throw new RangeError('Invalid graph window.');
+    const lanes = Object.keys(labels).map(direction => {
+        const vertical = direction === 'push' || direction === 'pull', sign = direction === 'clockwise' || direction === 'push' ? 1 : -1;
+        const band = vertical ? tune[direction] : tune.rotation;
+        const all = [];
+        for (const row of recording.timeline) {
+            if (row.type === 'input')
+                all.push({ t: row.t, value: Math.max(0, sign * row.input[vertical ? 'z' : 'rz']) });
+            else if (row.type === 'reset')
+                all.push({ t: row.t, value: 0 });
+        }
+        const preceding = [...all].reverse().find(p => p.t < start);
+        const points = [{ t: start, value: preceding?.value ?? 0 }, ...all.filter(p => p.t >= start && p.t <= end)];
+        points.push({ t: end, value: points[points.length - 1].value });
+        return { direction, label: labels[direction], ...band, points, actions: (config.actions ?? []).filter(a => a.recording === (config.recordingIndex ?? 0) && a.direction === direction && a.end >= start && a.start <= end).map(a => ({ start: a.start, end: a.end, kind: a.kind })) };
+    });
+    return { start, end, lanes };
+}
+const escape = (value) => value.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+/** Standalone accessible SVG. No DOM, canvas, frameworks or global listeners. */
+export function renderGestureGraphSvg(graph, options = {}) {
+    const width = options.width ?? 960;
+    if (!Number.isFinite(width) || width < 280 || width > 4000)
+        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">`];
+    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>`);
+        }
+        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}"/>`);
+        svg.push(`<text x="12" y="${y(1) + 4}">1</text><text x="12" y="${y(0) + 4}">0</text>`);
+        // Steps preserve held input and report silence; no invented sloping interpolation.
+        let path = '';
+        lane.points.forEach((p, i) => { path += i ? `H${x(p.t).toFixed(2)}V${y(p.value).toFixed(2)}` : `M${x(p.t).toFixed(2)},${y(p.value).toFixed(2)}`; });
+        svg.push(`<path d="${path}" fill="none" stroke="#1b4fce" stroke-width="1.8"/>`);
+    });
+    for (let i = 0; i <= 4; i++) {
+        const t = graph.start + (graph.end - graph.start) * i / 4;
+        svg.push(`<text x="${x(t)}" y="${height - 24}" text-anchor="${i === 0 ? 'start' : i === 4 ? 'end' : 'middle'}">${(t / 1000).toFixed(2)} s</text>`);
+    }
+    svg.push('</g></svg>');
+    return svg.join('');
+}

package/dist/index.d.ts

@@ -2,3 +2,11 @@ export { decodeCombinedReport, neutralInput } from './input.js';
 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 { createGestureTune, defaultGestureTune, gesturePresets } from './tune.js';
+export type { GestureTune, GestureTuneData, ForceBand } 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';

package/dist/index.js

@@ -1,2 +1,6 @@
 export { decodeCombinedReport, neutralInput } from './input.js';
 export { createPanZoom } from './motion.js';
+export { createGestures } from './gestures.js';
+export { createGestureTune, defaultGestureTune, gesturePresets } from './tune.js';
+export { createGestureRecorder, validateGestureRecording } from './recording.js';
+export { calibrateGestures, gestureDirections } from './calibration.js';

package/dist/recording.d.ts

@@ -0,0 +1,40 @@
+import type { InputState } from './input.js';
+import type { GestureEvent, GestureOptions } from './gestures.js';
+import type { GestureTune } from './tune.js';
+export type RecordingEntry = {
+    type: 'input';
+    t: number;
+    input: InputState;
+} | {
+    type: 'advance' | 'reset';
+    t: number;
+};
+export interface GestureRecording {
+    version: 1;
+    source: 'device' | 'simulator';
+    note: string;
+    durationMs: number;
+    options: GestureOptions;
+    timeline: RecordingEntry[];
+    events: GestureEvent[];
+}
+export interface GestureRecorder {
+    readonly full: boolean;
+    input(input: Readonly<InputState>, timestampMs: number): void;
+    advance(timestampMs: number): void;
+    reset(timestampMs: number): void;
+    events(events: readonly GestureEvent[]): void;
+    snapshot(timestampMs: number): GestureRecording;
+}
+/** Transport-independent bounded recording. The app owns clock, saving and storage. */
+export declare function createGestureRecorder(config: {
+    startTimeMs: number;
+    tune?: GestureTune;
+    options?: GestureOptions;
+    source?: 'device' | 'simulator';
+    note?: string;
+    maxDurationMs?: number;
+    maxEntries?: number;
+}): GestureRecorder;
+/** Validate data before calibration or graphing; recordings contain untrusted input. */
+export declare function validateGestureRecording(recording: GestureRecording): void;

package/dist/recording.js

@@ -0,0 +1,48 @@
+import { defaultGestureTune } from './tune.js';
+/** Transport-independent bounded recording. The app owns clock, saving and storage. */
+export function createGestureRecorder(config) {
+    const start = config.startTimeMs, max = config.maxDurationMs ?? 120000, limit = config.maxEntries ?? 50000;
+    if (!Number.isFinite(start) || !Number.isFinite(max) || max <= 0 || max > 120000 || !Number.isInteger(limit) || limit < 1 || limit > 60000)
+        throw new RangeError('Invalid recording bounds.');
+    const options = { ...(config.options ?? (config.tune ?? defaultGestureTune).toOptions()) };
+    const timeline = [], events = [];
+    let last = start, full = false;
+    function time(t) { if (!Number.isFinite(t) || t < last)
+        throw new RangeError('Recording clock must be finite and monotonic.'); last = t; return t - start; }
+    function add(row) { if (full)
+        return; if (row.t > max || timeline.length >= limit) {
+        full = true;
+        return;
+    } timeline.push(row); }
+    const copyInput = (input) => { const copy = {}; for (const key of ['x', 'y', 'z', 'rx', 'ry', 'rz']) {
+        if (!Number.isFinite(input[key]) || Math.abs(input[key]) > 1)
+            throw new RangeError('Recording axes must be in [-1,1].');
+        copy[key] = input[key];
+    } return copy; };
+    return {
+        get full() { return full; },
+        input(input, t) { const copied = copyInput(input); add({ type: 'input', t: time(t), input: copied }); },
+        advance(t) { add({ type: 'advance', t: time(t) }); }, reset(t) { add({ type: 'reset', t: time(t) }); },
+        events(values) { for (const e of values) {
+            const timestamp = e.timestamp - start;
+            if (!full && timestamp >= 0 && timestamp <= max && events.length < 10000)
+                events.push({ ...e, timestamp });
+        } },
+        snapshot(t) { const durationMs = Math.min(max, time(t)); return { version: 1, source: config.source ?? 'device', note: (config.note ?? '').slice(0, 500), durationMs, options: { ...options }, timeline: timeline.map(row => row.type === 'input' ? { ...row, input: { ...row.input } } : { ...row }), events: events.filter(e => e.timestamp <= durationMs).map(e => ({ ...e })) }; },
+    };
+}
+/** Validate data before calibration or graphing; recordings contain untrusted input. */
+export function validateGestureRecording(recording) {
+    if (!recording || recording.version !== 1 || !Number.isFinite(recording.durationMs) || recording.durationMs < 0 || recording.durationMs > 122000 || !Array.isArray(recording.timeline) || recording.timeline.length > 60000)
+        throw new RangeError('Invalid recording.');
+    let last = 0;
+    for (const row of recording.timeline) {
+        if (!row || !Number.isFinite(row.t) || row.t < last || row.t > recording.durationMs || !['input', 'advance', 'reset'].includes(row.type))
+            throw new RangeError('Invalid recording timeline.');
+        last = row.t;
+        if (row.type === 'input')
+            for (const k of ['x', 'y', 'z', 'rx', 'ry', 'rz'])
+                if (!row.input || !Number.isFinite(row.input[k]) || Math.abs(row.input[k]) > 1)
+                    throw new RangeError('Invalid recording input.');
+    }
+}

package/dist/tune.d.ts

@@ -0,0 +1,37 @@
+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 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;
+}
+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,52 @@
+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,
+};
+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];
+        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 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];
+            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 };
+            }
+            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 createGestureTune({ ...value, ...bands });
+    }
+    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' }; },
+    });
+}
+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,26 @@
+# 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.

package/docs/api.md

@@ -0,0 +1,86 @@
+# 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` |
+| `@clankagent/puck/webhid` | `connectWebHid`, `combinedProfile` |
+| `@clankagent/puck/graph` | `createGestureGraph`, `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`.
+
+## 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,27 @@
+# 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.

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).