@363045841yyt/klinechart-core 0.8.11-alpha.0 → 0.8.12

package/src/input/__tests__/keyboard.test.ts

@@ -0,0 +1,317 @@
+/**
+ * Tests for `createShortcutRegistry` + the parser helpers.
+ *
+ * Coverage:
+ *   1. parseCombo  — happy paths, all modifier aliases, errors on
+ *      malformed inputs (empty, no key, multi-key).
+ *   2. canonicalCombo — canonical order, modifier-order independence,
+ *      single-letter uppercasing, named-key preservation.
+ *   3. register / unregister / findByCombo — basic CRUD.
+ *   4. Conflict detection — same combo, different ids throws.
+ *   5. Re-binding same id to a new combo drops the old binding.
+ *   6. findByKeyboardEvent — happy path + missing modifier + extra
+ *      modifier + non-matching key.
+ *   7. Platform Mod resolution — mac → metaKey, other → ctrlKey.
+ *   8. `when` predicate gates lookup.
+ *   9. dispose() makes everything a no-op.
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import {
+    createShortcutRegistry,
+    parseCombo,
+    canonicalCombo,
+    type KeyboardEventLike,
+} from '..'
+import { isKLineChartError } from '../../errors'
+
+function evt(over: Partial<KeyboardEventLike>): KeyboardEventLike {
+    return {
+        key: '',
+        ctrlKey: false,
+        metaKey: false,
+        altKey: false,
+        shiftKey: false,
+        ...over,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// parseCombo
+// ---------------------------------------------------------------------------
+
+describe('parseCombo', () => {
+    it('parses a simple letter', () => {
+        const p = parseCombo('k')
+        expect(p.key).toBe('k')
+        expect(p.requiresMod).toBe(false)
+        expect(p.ctrlKey).toBe(false)
+    })
+
+    it.each([
+        ['Mod+K', { requiresMod: true, key: 'K' }],
+        ['Ctrl+K', { ctrlKey: true, key: 'K' }],
+        ['Control+K', { ctrlKey: true, key: 'K' }],
+        ['Meta+K', { metaKey: true, key: 'K' }],
+        ['Cmd+K', { metaKey: true, key: 'K' }],
+        ['Command+K', { metaKey: true, key: 'K' }],
+        ['Alt+K', { altKey: true, key: 'K' }],
+        ['Option+K', { altKey: true, key: 'K' }],
+        ['Shift+K', { shiftKey: true, key: 'K' }],
+    ] as const)('%s parses modifier correctly', (src, expected) => {
+        const p = parseCombo(src)
+        for (const [k, v] of Object.entries(expected)) {
+            expect((p as unknown as Record<string, unknown>)[k]).toBe(v)
+        }
+    })
+
+    it('parses named keys', () => {
+        expect(parseCombo('ArrowRight').key).toBe('ArrowRight')
+        expect(parseCombo('Shift+ArrowRight').shiftKey).toBe(true)
+        expect(parseCombo('F5').key).toBe('F5')
+    })
+
+    it('throws on empty input', () => {
+        try {
+            parseCombo('')
+            expect.fail('expected throw')
+        } catch (e) {
+            expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+        }
+    })
+
+    it('throws on only modifiers, no key', () => {
+        try {
+            parseCombo('Shift+Mod')
+            expect.fail('expected throw')
+        } catch (e) {
+            expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+        }
+    })
+
+    it('throws on multiple non-modifier keys', () => {
+        try {
+            parseCombo('K+J')
+            expect.fail('expected throw')
+        } catch (e) {
+            expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+        }
+    })
+
+    it('ignores extra whitespace', () => {
+        expect(parseCombo('  Mod + K ').key).toBe('K')
+        expect(parseCombo('  Mod + K ').requiresMod).toBe(true)
+    })
+})
+
+// ---------------------------------------------------------------------------
+// canonicalCombo
+// ---------------------------------------------------------------------------
+
+describe('canonicalCombo', () => {
+    it('sorts modifiers into canonical order', () => {
+        expect(canonicalCombo('Shift+Mod+K')).toBe('Mod+Shift+K')
+        expect(canonicalCombo('Alt+Shift+Mod+K')).toBe('Mod+Alt+Shift+K')
+    })
+
+    it('uppercases single-letter keys', () => {
+        expect(canonicalCombo('mod+k')).toBe('Mod+K')
+    })
+
+    it('preserves named-key casing', () => {
+        expect(canonicalCombo('shift+arrowright')).toBe('Shift+arrowright')
+        expect(canonicalCombo('Shift+ArrowRight')).toBe('Shift+ArrowRight')
+    })
+
+    it('is idempotent', () => {
+        const c = canonicalCombo('alt+shift+mod+k')
+        expect(canonicalCombo(c)).toBe(c)
+    })
+})
+
+// ---------------------------------------------------------------------------
+// register / unregister / findByCombo
+// ---------------------------------------------------------------------------
+
+describe('register / unregister / findByCombo', () => {
+    it('round-trips a registered shortcut by canonical combo', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'pan.left', label: 'Pan left', combo: 'ArrowLeft', command: 'pan' })
+        expect(r.findByCombo('ArrowLeft')?.id).toBe('pan.left')
+        expect(r.shortcuts.peek()).toHaveLength(1)
+    })
+
+    it('canonicalises during lookup', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'open', label: 'Open', combo: 'Mod+K', command: 'open' })
+        expect(r.findByCombo('Shift+Mod+K')).toBeNull()
+        expect(r.findByCombo('Mod+K')?.id).toBe('open')
+    })
+
+    it('unregister removes the binding', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'open', label: 'Open', combo: 'Mod+K', command: 'open' })
+        r.unregister('open')
+        expect(r.findByCombo('Mod+K')).toBeNull()
+        expect(r.shortcuts.peek()).toHaveLength(0)
+    })
+
+    it('unregistering an unknown id is a no-op', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        expect(() => r.unregister('nope')).not.toThrow()
+    })
+
+    it('throws on empty id', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        try {
+            r.register({ id: '', label: '', combo: 'K', command: 'x' })
+            expect.fail('expected throw')
+        } catch (e) {
+            expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+        }
+    })
+})
+
+// ---------------------------------------------------------------------------
+// Conflict detection
+// ---------------------------------------------------------------------------
+
+describe('conflict detection', () => {
+    it('throws when a second id registers the same canonical combo', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'a', label: 'A', combo: 'Mod+K', command: 'aCmd' })
+        try {
+            r.register({ id: 'b', label: 'B', combo: 'Shift+Mod+K', command: 'bCmd' })
+            // Note: Shift+Mod+K canonicalises differently, so this is the
+            // POSITIVE path — the test below covers the conflict.
+        } catch {
+            expect.fail('Shift+Mod+K is a different combo and must not conflict')
+        }
+        try {
+            r.register({ id: 'c', label: 'C', combo: 'Mod+K', command: 'cCmd' })
+            expect.fail('expected conflict throw')
+        } catch (e) {
+            expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+            expect((e as Error).message).toContain('a')
+        }
+    })
+
+    it('re-registering the same id with the same combo is a no-op', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'a', label: 'A', combo: 'Mod+K', command: 'aCmd' })
+        expect(() =>
+            r.register({ id: 'a', label: 'A-renamed', combo: 'Mod+K', command: 'aCmd' }),
+        ).not.toThrow()
+        expect(r.findByCombo('Mod+K')?.label).toBe('A-renamed')
+    })
+
+    it('re-binding same id to a different combo drops the old binding', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'a', label: 'A', combo: 'Mod+K', command: 'aCmd' })
+        r.register({ id: 'a', label: 'A', combo: 'Mod+J', command: 'aCmd' })
+        expect(r.findByCombo('Mod+K')).toBeNull()
+        expect(r.findByCombo('Mod+J')?.id).toBe('a')
+    })
+})
+
+// ---------------------------------------------------------------------------
+// findByKeyboardEvent
+// ---------------------------------------------------------------------------
+
+describe('findByKeyboardEvent', () => {
+    it('matches a basic letter', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'r', label: 'Reset', combo: 'R', command: 'reset' })
+        expect(r.findByKeyboardEvent(evt({ key: 'r' }))?.id).toBe('r')
+        expect(r.findByKeyboardEvent(evt({ key: 'R' }))?.id).toBe('r')
+    })
+
+    it('rejects when modifier missing', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'open', label: 'Open', combo: 'Mod+K', command: 'open' })
+        expect(r.findByKeyboardEvent(evt({ key: 'k' }))).toBeNull()
+    })
+
+    it('rejects when extra modifier present', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'r', label: 'Reset', combo: 'R', command: 'reset' })
+        expect(r.findByKeyboardEvent(evt({ key: 'r', shiftKey: true }))).toBeNull()
+    })
+
+    it('rejects when key differs', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'open', label: 'Open', combo: 'Mod+K', command: 'open' })
+        expect(r.findByKeyboardEvent(evt({ key: 'j', ctrlKey: true }))).toBeNull()
+    })
+
+    it('matches named keys', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'panL', label: 'Pan left', combo: 'ArrowLeft', command: 'pan' })
+        expect(r.findByKeyboardEvent(evt({ key: 'ArrowLeft' }))?.id).toBe('panL')
+    })
+})
+
+// ---------------------------------------------------------------------------
+// Platform Mod resolution
+// ---------------------------------------------------------------------------
+
+describe('platform Mod resolution', () => {
+    it('on mac: Mod matches metaKey, not ctrlKey', () => {
+        const r = createShortcutRegistry({ platform: 'mac' })
+        r.register({ id: 'open', label: 'Open', combo: 'Mod+K', command: 'open' })
+        expect(r.findByKeyboardEvent(evt({ key: 'k', metaKey: true }))?.id).toBe('open')
+        expect(r.findByKeyboardEvent(evt({ key: 'k', ctrlKey: true }))).toBeNull()
+    })
+
+    it('on win: Mod matches ctrlKey, not metaKey', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'open', label: 'Open', combo: 'Mod+K', command: 'open' })
+        expect(r.findByKeyboardEvent(evt({ key: 'k', ctrlKey: true }))?.id).toBe('open')
+        expect(r.findByKeyboardEvent(evt({ key: 'k', metaKey: true }))).toBeNull()
+    })
+
+    it('explicit Ctrl + Meta still bind on both platforms', () => {
+        const r = createShortcutRegistry({ platform: 'mac' })
+        r.register({ id: 'a', label: 'A', combo: 'Ctrl+K', command: 'a' })
+        expect(r.findByKeyboardEvent(evt({ key: 'k', ctrlKey: true }))?.id).toBe('a')
+    })
+})
+
+// ---------------------------------------------------------------------------
+// `when` predicate
+// ---------------------------------------------------------------------------
+
+describe('when predicate', () => {
+    it('false predicate skips the shortcut', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        let active = false
+        r.register({
+            id: 'esc',
+            label: 'Cancel tool',
+            combo: 'Escape',
+            command: 'cancel',
+            when: () => active,
+        })
+        expect(r.findByKeyboardEvent(evt({ key: 'Escape' }))).toBeNull()
+        active = true
+        expect(r.findByKeyboardEvent(evt({ key: 'Escape' }))?.id).toBe('esc')
+    })
+})
+
+// ---------------------------------------------------------------------------
+// dispose
+// ---------------------------------------------------------------------------
+
+describe('dispose', () => {
+    it('makes register / unregister / findByCombo no-ops', () => {
+        const r = createShortcutRegistry({ platform: 'win' })
+        r.register({ id: 'a', label: 'A', combo: 'K', command: 'a' })
+        r.dispose()
+        expect(r.findByCombo('K')).toBeNull()
+        expect(() =>
+            r.register({ id: 'b', label: 'B', combo: 'J', command: 'b' }),
+        ).not.toThrow()
+        expect(r.findByCombo('J')).toBeNull()
+    })
+})

package/src/input/gesture.ts

@@ -0,0 +1,357 @@
+/**
+ * Pointer gesture recognizer — 1-pointer pan/swipe + 2-pointer pinch.
+ *
+ * Pure-data state machine: no DOM. Consumers feed `PointerEventLike`
+ * records via `onPointerDown` / `onPointerMove` / `onPointerUp`, and
+ * read recognized gestures off the `events` signal.
+ *
+ * The recognizer is **framework-agnostic** for the same reason as the
+ * shortcut registry: every consumer touches a different event surface
+ * (`PointerEvent`, `MouseEvent`, `TouchEvent`, synthetic events from a
+ * Vue composable). Defining the minimal `PointerEventLike` interface
+ * means none of them have to adapt to ours — they adapt to themselves
+ * and hand us the four fields we need.
+ *
+ * State diagram (simplified):
+ *
+ *     idle ──[1 down]──▶ tracking (1 pointer)
+ *      ▲                      │ ├──[move past deadzone]──▶ pan
+ *      │                      │ ├──[up + velocity > min]──▶ swipe → idle
+ *      │                      │ └──[up + small move]──▶ tap → idle
+ *      │                      │
+ *      │                      └─[2nd down]──▶ pinch (2 pointers)
+ *      │                                      │
+ *      └─[all up / cancel]────────────────────┘
+ *
+ * Pan / pinch emit continuous deltas. Tap and swipe are terminal.
+ *
+ * Why no long-press / double-tap in v1: those are heuristic-laden and
+ * usually better delegated to the host platform. The four gestures
+ * above cover 95 % of finance-chart interactions (pan to scroll
+ * history, pinch to zoom, swipe to flick-scroll, tap to inspect).
+ */
+
+import { createSignal, type Signal } from '../reactivity'
+import { KLineChartError } from '../errors'
+
+// ---------------------------------------------------------------------------
+// Event surface
+// ---------------------------------------------------------------------------
+
+export interface PointerEventLike {
+    /** Identifier consistent across down/move/up for the same finger/pen. */
+    readonly pointerId: number
+    /** Client-space x. */
+    readonly x: number
+    /** Client-space y. */
+    readonly y: number
+    /** Event timestamp in ms (event.timeStamp from browsers, perf.now() OK). */
+    readonly timestamp: number
+}
+
+export type GestureEvent =
+    | { type: 'tap'; x: number; y: number; timestamp: number }
+    | { type: 'panStart'; x: number; y: number; timestamp: number }
+    | { type: 'pan'; x: number; y: number; dx: number; dy: number; timestamp: number }
+    | { type: 'panEnd'; x: number; y: number; timestamp: number }
+    | {
+        type: 'swipe'
+        x: number
+        y: number
+        vx: number
+        vy: number
+        timestamp: number
+    }
+    | {
+        type: 'pinchStart'
+        cx: number
+        cy: number
+        distance: number
+        timestamp: number
+    }
+    | {
+        type: 'pinch'
+        cx: number
+        cy: number
+        distance: number
+        /** Multiplicative scale relative to the pinchStart distance. */
+        scale: number
+        timestamp: number
+    }
+    | { type: 'pinchEnd'; cx: number; cy: number; timestamp: number }
+
+export type GestureState = 'idle' | 'tracking' | 'pan' | 'pinch'
+
+export interface GestureRecognizerOptions {
+    /**
+     * Pixel radius the primary pointer must escape before tracking turns
+     * into a pan. Below this, the gesture is interpreted as a tap on
+     * release. Default 6 — matches the click-vs-drag heuristic UI
+     * frameworks settle on.
+     */
+    readonly panDeadzone?: number
+    /**
+     * Minimum velocity (px/ms) on release to classify a movement as
+     * a swipe rather than a pan-end. Default 0.5 — the median swipe
+     * velocity on mid-range mobile devices.
+     */
+    readonly swipeMinVelocity?: number
+    /**
+     * Window in ms over which the swipe velocity is averaged.
+     * Default 100ms. Larger smooths jitter; smaller catches flicks.
+     */
+    readonly swipeVelocityWindowMs?: number
+}
+
+export interface GestureRecognizer {
+    readonly state: Signal<GestureState>
+    readonly events: Signal<GestureEvent | null>
+    onPointerDown(e: PointerEventLike): void
+    onPointerMove(e: PointerEventLike): void
+    onPointerUp(e: PointerEventLike): void
+    /** Resets to idle without emitting. Use on tab blur, etc. */
+    cancel(): void
+    dispose(): void
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+const DEFAULT_OPTS: Required<GestureRecognizerOptions> = {
+    panDeadzone: 6,
+    swipeMinVelocity: 0.5,
+    swipeVelocityWindowMs: 100,
+}
+
+interface ActivePointer {
+    pointerId: number
+    startX: number
+    startY: number
+    startTs: number
+    lastX: number
+    lastY: number
+    lastTs: number
+    // small ring buffer for velocity smoothing
+    history: Array<{ x: number; y: number; ts: number }>
+}
+
+export function createGestureRecognizer(
+    opts: GestureRecognizerOptions = {},
+): GestureRecognizer {
+    if (opts.panDeadzone !== undefined && opts.panDeadzone < 0) {
+        throw new KLineChartError(
+            'INVALID_PARAM',
+            `createGestureRecognizer: panDeadzone must be >= 0, got ${opts.panDeadzone}`,
+        )
+    }
+    if (opts.swipeMinVelocity !== undefined && opts.swipeMinVelocity < 0) {
+        throw new KLineChartError(
+            'INVALID_PARAM',
+            `createGestureRecognizer: swipeMinVelocity must be >= 0, got ${opts.swipeMinVelocity}`,
+        )
+    }
+    const cfg = { ...DEFAULT_OPTS, ...opts }
+
+    const state = createSignal<GestureState>('idle')
+    const events = createSignal<GestureEvent | null>(null)
+    let disposed = false
+
+    const active = new Map<number, ActivePointer>()
+    // pinchStartDistance captured when transitioning into 'pinch'
+    let pinchStartDistance = 0
+
+    function emit(event: GestureEvent): void {
+        if (disposed) return
+        events.set(event)
+    }
+
+    function dist(a: ActivePointer, b: ActivePointer): number {
+        const dx = a.lastX - b.lastX
+        const dy = a.lastY - b.lastY
+        return Math.sqrt(dx * dx + dy * dy)
+    }
+
+    function centroid(a: ActivePointer, b: ActivePointer): { cx: number; cy: number } {
+        return { cx: (a.lastX + b.lastX) / 2, cy: (a.lastY + b.lastY) / 2 }
+    }
+
+    function pushHistory(p: ActivePointer, e: PointerEventLike): void {
+        p.history.push({ x: e.x, y: e.y, ts: e.timestamp })
+        // Trim history older than the velocity window from the latest
+        const cutoff = e.timestamp - cfg.swipeVelocityWindowMs
+        while (p.history.length > 0 && p.history[0]!.ts < cutoff) {
+            p.history.shift()
+        }
+    }
+
+    function recentVelocity(p: ActivePointer): { vx: number; vy: number } {
+        if (p.history.length < 2) return { vx: 0, vy: 0 }
+        const first = p.history[0]!
+        const last = p.history[p.history.length - 1]!
+        const dt = last.ts - first.ts
+        if (dt <= 0) return { vx: 0, vy: 0 }
+        return { vx: (last.x - first.x) / dt, vy: (last.y - first.y) / dt }
+    }
+
+    function onPointerDown(e: PointerEventLike): void {
+        if (disposed) return
+        const p: ActivePointer = {
+            pointerId: e.pointerId,
+            startX: e.x,
+            startY: e.y,
+            startTs: e.timestamp,
+            lastX: e.x,
+            lastY: e.y,
+            lastTs: e.timestamp,
+            history: [{ x: e.x, y: e.y, ts: e.timestamp }],
+        }
+        active.set(e.pointerId, p)
+        if (active.size === 1) {
+            state.set('tracking')
+        } else if (active.size === 2) {
+            const [a, b] = [...active.values()] as [ActivePointer, ActivePointer]
+            const c = centroid(a, b)
+            pinchStartDistance = Math.max(dist(a, b), 1e-9)
+            state.set('pinch')
+            emit({
+                type: 'pinchStart',
+                cx: c.cx,
+                cy: c.cy,
+                distance: pinchStartDistance,
+                timestamp: e.timestamp,
+            })
+        }
+        // Extra pointers (3+) are ignored — we don't recognise 3-finger
+        // gestures in v1.
+    }
+
+    function onPointerMove(e: PointerEventLike): void {
+        if (disposed) return
+        const p = active.get(e.pointerId)
+        if (p === undefined) return
+        const dx = e.x - p.lastX
+        const dy = e.y - p.lastY
+        p.lastX = e.x
+        p.lastY = e.y
+        p.lastTs = e.timestamp
+        pushHistory(p, e)
+
+        if (state.peek() === 'pinch' && active.size >= 2) {
+            const [a, b] = [...active.values()] as [ActivePointer, ActivePointer]
+            const c = centroid(a, b)
+            const d = dist(a, b)
+            emit({
+                type: 'pinch',
+                cx: c.cx,
+                cy: c.cy,
+                distance: d,
+                scale: d / pinchStartDistance,
+                timestamp: e.timestamp,
+            })
+            return
+        }
+
+        // Single-pointer path: maybe promote tracking → pan
+        if (state.peek() === 'tracking') {
+            const ddx = e.x - p.startX
+            const ddy = e.y - p.startY
+            if (Math.sqrt(ddx * ddx + ddy * ddy) > cfg.panDeadzone) {
+                state.set('pan')
+                emit({ type: 'panStart', x: e.x, y: e.y, timestamp: e.timestamp })
+                // Also emit the first pan event right away. dx/dy carry
+                // the full delta from the down position so the consumer
+                // doesn't have to wait for a second move to react.
+                emit({
+                    type: 'pan',
+                    x: e.x,
+                    y: e.y,
+                    dx: ddx,
+                    dy: ddy,
+                    timestamp: e.timestamp,
+                })
+            }
+            return
+        }
+        if (state.peek() === 'pan') {
+            emit({ type: 'pan', x: e.x, y: e.y, dx, dy, timestamp: e.timestamp })
+        }
+    }
+
+    function onPointerUp(e: PointerEventLike): void {
+        if (disposed) return
+        const p = active.get(e.pointerId)
+        if (p === undefined) return
+
+        if (state.peek() === 'pinch') {
+            // Decommit pinch; if exactly one pointer remains, drop back into
+            // 'tracking' on it (the remaining finger can still pan).
+            active.delete(e.pointerId)
+            const remaining = active.values().next().value as ActivePointer | undefined
+            const c = remaining
+                ? { cx: remaining.lastX, cy: remaining.lastY }
+                : { cx: e.x, cy: e.y }
+            emit({ type: 'pinchEnd', cx: c.cx, cy: c.cy, timestamp: e.timestamp })
+            if (active.size === 1 && remaining !== undefined) {
+                // Re-baseline the remaining pointer so panDeadzone applies
+                // afresh and we don't immediately fall into a pan-tracking
+                // weirdness using the original press position.
+                remaining.startX = remaining.lastX
+                remaining.startY = remaining.lastY
+                remaining.startTs = e.timestamp
+                remaining.history = [
+                    { x: remaining.lastX, y: remaining.lastY, ts: e.timestamp },
+                ]
+                state.set('tracking')
+            } else {
+                state.set('idle')
+            }
+            return
+        }
+
+        // Single-pointer end paths: tap, swipe, panEnd, or just clean up.
+        active.delete(e.pointerId)
+        const ddx = p.lastX - p.startX
+        const ddy = p.lastY - p.startY
+        const distMoved = Math.sqrt(ddx * ddx + ddy * ddy)
+
+        if (state.peek() === 'pan') {
+            const { vx, vy } = recentVelocity(p)
+            const speed = Math.sqrt(vx * vx + vy * vy)
+            if (speed >= cfg.swipeMinVelocity) {
+                emit({
+                    type: 'swipe',
+                    x: e.x,
+                    y: e.y,
+                    vx,
+                    vy,
+                    timestamp: e.timestamp,
+                })
+            } else {
+                emit({ type: 'panEnd', x: e.x, y: e.y, timestamp: e.timestamp })
+            }
+        } else if (state.peek() === 'tracking') {
+            if (distMoved <= cfg.panDeadzone) {
+                emit({ type: 'tap', x: e.x, y: e.y, timestamp: e.timestamp })
+            }
+            // else: aborted gesture, no emit (movement was below deadzone
+            // forever; nothing meaningful happened)
+        }
+
+        state.set(active.size === 0 ? 'idle' : 'tracking')
+    }
+
+    function cancel(): void {
+        if (disposed) return
+        active.clear()
+        state.set('idle')
+    }
+
+    function dispose(): void {
+        if (disposed) return
+        disposed = true
+        active.clear()
+    }
+
+    return { state, events, onPointerDown, onPointerMove, onPointerUp, cancel, dispose }
+}

package/src/input/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @klinechart-quant/core/input — framework-agnostic input layer.
+ *
+ * Shipping module: {@link createShortcutRegistry}. See `./keyboard.ts`
+ * for the design notes.
+ */
+
+export {
+    createShortcutRegistry,
+    parseCombo,
+    canonicalCombo,
+    type ShortcutRegistry,
+    type ShortcutRegistryOptions,
+    type ShortcutDef,
+    type ParsedCombo,
+    type ModifierState,
+    type KeyboardEventLike,
+} from './keyboard'
+export {
+    createGestureRecognizer,
+    type GestureRecognizer,
+    type GestureRecognizerOptions,
+    type GestureEvent,
+    type GestureState,
+    type PointerEventLike,
+} from './gesture'