@clankagent/puck 0.1.0 → 0.3.0

package/dist/gestures.js

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

package/dist/graph.d.ts

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

package/dist/graph.js

@@ -0,0 +1,111 @@
+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 };
+}
+/** Pressure and tilt in six separate lanes, with each inferred combination labeled on both. */
+export function createPressTiltGraph(recording, tune = defaultGestureTune, config = {}) {
+    const graph = createGestureGraph(recording, tune, { start: config.start, end: config.end });
+    const actions = (config.actions ?? []).filter(a => a.recording === (config.recordingIndex ?? 0) && a.end >= graph.start && a.start <= graph.end);
+    graph.lanes = graph.lanes.filter(l => l.direction === 'push' || l.direction === 'pull');
+    for (const direction of ['rx+', 'rx-', 'ry+', 'ry-']) {
+        const axis = direction.startsWith('rx') ? 'rx' : 'ry', sign = direction.endsWith('+') ? 1 : -1;
+        const points = [];
+        let held = 0;
+        for (const row of recording.timeline) {
+            if (row.t > graph.end)
+                break;
+            if (row.type === 'input')
+                held = Math.max(0, row.input[axis] * sign);
+            else if (row.type === 'reset')
+                held = 0;
+            else
+                continue;
+            if (row.t < graph.start)
+                continue;
+            if (!points.length)
+                points.push({ t: graph.start, value: 0 });
+            points.push({ t: row.t, value: held });
+        }
+        // Seed the left edge with the held sample preceding the requested window.
+        let before = 0;
+        for (const row of recording.timeline) {
+            if (row.t >= graph.start)
+                break;
+            if (row.type === 'input')
+                before = Math.max(0, row.input[axis] * sign);
+            else if (row.type === 'reset')
+                before = 0;
+        }
+        if (!points.length)
+            points.push({ t: graph.start, value: before });
+        else
+            points[0].value = before;
+        points.push({ t: graph.end, value: held });
+        graph.lanes.push({ direction, label: `Tilt ${direction} (device axis)`, ...(tune.pressTilt ?? defaultGestureTune.pressTilt).force, points, actions: [] });
+    }
+    for (const lane of graph.lanes)
+        lane.actions = actions.filter(a => a.direction === lane.direction || a.tilt === lane.direction).map(a => ({ start: a.start, end: a.end, kind: 'single', label: `${a.direction} + ${a.tilt}` }));
+    return graph;
+}
+const escape = (value) => value.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+/** Four standalone tilt lanes with independent rx/ry bands and single/double action spans. */
+export function createTiltGraph(recording, tune = defaultGestureTune, config = {}) {
+    const graph = createPressTiltGraph(recording, tune, { start: config.start, end: config.end });
+    const bands = tune.standaloneTilt ?? defaultGestureTune.standaloneTilt;
+    graph.lanes = graph.lanes.filter(l => l.direction.startsWith('r')).map(l => ({ ...l, ...(l.direction.startsWith('rx') ? bands.rx : bands.ry), actions: (config.actions ?? []).filter(a => a.recording === (config.recordingIndex ?? 0) && a.direction === l.direction && a.end >= graph.start && a.start <= graph.end).map(a => ({ start: a.start, end: a.end, kind: a.kind })) }));
+    return graph;
+}
+/** Standalone accessible SVG. No DOM, canvas, frameworks or global listeners. */
+export function renderGestureGraphSvg(graph, options = {}) {
+    const width = options.width ?? 960;
+    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: independent input directions')}"><desc>Blue is input strength, green dashed is activation, gray dotted is release, pale blue is the typical peak range. Shaded time spans mark inferred actions. Stronger inputs remain accepted above the typical range.</desc><rect width="100%" height="100%" fill="white"/><g font-family="Segoe UI,Arial,sans-serif" font-size="12" fill="#283c55">`];
+    graph.lanes.forEach((lane, index) => {
+        const top = 30 + index * 150, y = (v) => top + 100 - Math.max(0, Math.min(1, v)) * 76;
+        svg.push(`<text x="${left}" y="${top}" font-size="15" font-weight="600">${escape(lane.label)}</text><text x="${width - right}" y="${top}" text-anchor="end" font-size="11">peak ${lane.center.toFixed(2)}</text><text x="${left}" y="${top + 19}">Activate ${lane.activation.toFixed(2)} · release ${lane.release.toFixed(2)}</text>`);
+        svg.push(`<rect x="${left}" y="${y(lane.high)}" width="${plotWidth}" height="${y(lane.low) - y(lane.high)}" fill="#edf3fc"/>`);
+        for (const a of lane.actions) {
+            svg.push(`<rect x="${x(a.start)}" y="${top + 24}" width="${Math.max(2, x(a.end) - x(a.start))}" height="76" fill="#cfdfef" opacity=".45"><title>${escape(a.label ?? a.kind)}</title></rect>`);
+            if (x(a.end) - x(a.start) > (a.label ? 90 : 42))
+                svg.push(`<text x="${x(a.start) + 3}" y="${top + 116}" font-size="11">${escape(a.label ?? a.kind)}</text>`);
+        }
+        for (const [v, color, dash] of [[0, '#afbac8', ''], [lane.activation, '#237442', '6 4'], [lane.release, '#68778b', '2 4']])
+            svg.push(`<line x1="${left}" x2="${width - right}" y1="${y(v)}" y2="${y(v)}" stroke="${color}" stroke-dasharray="${dash}"/>`);
+        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,15 @@ 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, PulseDirection, TiltDirection, PressMode, GestureOptions, GestureEvent, GestureRecognizer } from './gestures.js';
+export { createGestureTune, defaultGestureTune, gesturePresets } from './tune.js';
+export type { GestureTune, GestureTuneData, ForceBand, PressTiltTune, StandaloneTiltTune } from './tune.js';
+export { createGestureRecorder, validateGestureRecording } from './recording.js';
+export type { GestureRecorder, GestureRecording, RecordingEntry } from './recording.js';
+export { calibrateGestures, gestureDirections } from './calibration.js';
+export type { GestureCalibration, CalibrationAction, CalibrationPulse, CalibrationStats, GestureActionName } from './calibration.js';
+export { calibratePressTilts, tiltDirections } from './press-tilt-calibration.js';
+export type { PressTiltCalibration, PressTiltAction, PressTiltActionName } from './press-tilt-calibration.js';
+export { calibrateTilts } from './tilt-calibration.js';
+export type { TiltCalibration, TiltCalibrationAction, TiltActionName } from './tilt-calibration.js';

package/dist/index.js

@@ -1,2 +1,8 @@
 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';
+export { calibratePressTilts, tiltDirections } from './press-tilt-calibration.js';
+export { calibrateTilts } from './tilt-calibration.js';

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

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

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/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.');
+    }
+}