@clankagent/puck 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Puck contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# Puck
+
+A small TypeScript library for responsive SpaceMouse pan and zoom. Zero runtime dependencies.
+
+Incoming reports update input state. Your animation loop consumes time-based motion. Your application owns the camera and renderer.
+
+```sh
+pnpm add @clankagent/puck
+```
+
+```js
+import { createPanZoom } from '@clankagent/puck';
+import { connectWebHid } from '@clankagent/puck/webhid';
+
+const motion = createPanZoom({ zoomInput: 'press' });
+
+connectButton.onclick = async () => {
+  connectButton.disabled = true;
+  try {
+    connection = await connectWebHid({
+      onInput: motion.setInput,
+      onReset: motion.reset,
+      onDisconnect() { connection = null; connectButton.disabled = false; },
+    });
+  } finally {
+    connectButton.disabled = Boolean(connection);
+  }
+};
+
+function frame(timestamp) {
+  const delta = motion.step(timestamp);
+  if (delta.moving) {
+    // Apply zoom about your chosen anchor, then pan in screen pixels.
+    camera.zoomAround(viewCenter, delta.zoomFactor);
+    camera.panBy(delta.panX, delta.panY);
+    render(camera);
+  }
+  requestAnimationFrame(frame);
+}
+let connection = null;
+requestAnimationFrame(frame);
+
+// A control can change this live. Pan and camera position are unaffected.
+motion.setZoomInput('twist');
+
+// On application teardown:
+// await connection?.close();
+// Cancel the application's animation frame as part of its own cleanup.
+```
+
+`camera`, `render`, `viewCenter` and `connectButton` above belong to your app. There is no camera implementation or framework dependency in the package. See `examples/camera.mjs` for the complete anchor calculation, including zoom limits.
+
+## Responsibilities
+
+| Part | Responsibility |
+|---|---|
+| Decoder | Convert a supported motion report to normalized six-axis cap deflection; ignore status packets. |
+| WebHID adapter | Device selection, report delivery, foreground policy and connection cleanup. |
+| Pan/zoom controller | Hold the latest input, apply deadzones, integrate response over frame time, emit movement deltas. |
+| Your application | Own the render loop, input ownership, camera, zoom anchor, limits, and rendering. |
+
+The core imports in Node without a browser. The browser adapter is a separate entry point and accesses browser APIs only when connecting. It starts no animation loop, timers, server, storage, or telemetry.
+
+## 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).
+
+## Development
+
+```sh
+pnpm install
+pnpm check
+```
+
+The build emits ESM and declarations. Tests run against those emitted modules. Runtime dependencies: none. Licensed under MIT. See [CONTRIBUTING.md](CONTRIBUTING.md) for development and device support.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+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';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { decodeCombinedReport, neutralInput } from './input.js';
+export { createPanZoom } from './motion.js';

package/dist/input.d.ts

@@ -0,0 +1,12 @@
+/** Normalized cap deflection, in device coordinates. Not distance or velocity. */
+export interface InputState {
+    x: number;
+    y: number;
+    z: number;
+    rx: number;
+    ry: number;
+    rz: number;
+}
+export declare const neutralInput: Readonly<InputState>;
+/** Decode the measured combined report. Non-motion reports return null. */
+export declare function decodeCombinedReport(reportId: number, data: DataView): InputState | null;

package/dist/input.js

@@ -0,0 +1,10 @@
+export const neutralInput = Object.freeze({
+    x: 0, y: 0, z: 0, rx: 0, ry: 0, rz: 0,
+});
+/** Decode the measured combined report. Non-motion reports return null. */
+export function decodeCombinedReport(reportId, data) {
+    if (reportId !== 1 || data.byteLength !== 12)
+        return null;
+    const axis = (offset) => Math.max(-1, Math.min(1, data.getInt16(offset, true) / 350));
+    return { x: axis(0), y: axis(2), z: axis(4), rx: axis(6), ry: axis(8), rz: axis(10) };
+}

package/dist/motion.d.ts

@@ -0,0 +1,33 @@
+import type { InputState } from './input.js';
+export type ZoomInput = 'twist' | 'press';
+export interface PanZoomOptions {
+    /** Positive twist or downward pressure zooms in. Default: twist. */
+    zoomInput?: ZoomInput;
+    /** Screen pixels per second at full deflection. Default: 1320. */
+    panSpeed?: number;
+    /** Logarithmic zoom change per second at full deflection. Default: 1.5. */
+    zoomSpeed?: number;
+    panDeadzone?: number;
+    zoomDeadzone?: number;
+    /** Acceleration response time. Neutral and reversal do not coast. Default: 25 ms. */
+    responseMs?: number;
+    /** Maximum integrated interval after a render stall. Default: 50 ms. */
+    maxFrameMs?: number;
+}
+export interface MotionDelta {
+    panX: number;
+    panY: number;
+    zoomFactor: number;
+    moving: boolean;
+}
+export interface PanZoomController {
+    /** Copy the latest deflection. Safe to pass directly as a callback. */
+    setInput(input: Readonly<InputState>): void;
+    /** Call once per render frame with a monotonic timestamp in milliseconds. */
+    step(timestampMs: number): MotionDelta;
+    setZoomInput(input: ZoomInput): void;
+    /** Clear input and response when application input ownership changes. */
+    reset(): void;
+}
+/** Stateful input processing; owns no camera, render loop, DOM, or event listeners. */
+export declare function createPanZoom(options?: PanZoomOptions): PanZoomController;

package/dist/motion.js

@@ -0,0 +1,55 @@
+import { neutralInput } from './input.js';
+const idle = Object.freeze({ panX: 0, panY: 0, zoomFactor: 1, moving: false });
+function deadzone(value, threshold) {
+    const unit = Math.max(-1, Math.min(1, value));
+    return Math.abs(unit) <= threshold ? 0 : Math.sign(unit) * (Math.abs(unit) - threshold) / (1 - threshold);
+}
+/** Stateful input processing; owns no camera, render loop, DOM, or event listeners. */
+export function createPanZoom(options = {}) {
+    let zoomInput = options.zoomInput ?? 'twist';
+    const panSpeed = options.panSpeed ?? 1320;
+    const zoomSpeed = options.zoomSpeed ?? 1.5;
+    const panDeadzone = options.panDeadzone ?? .05;
+    const zoomDeadzone = options.zoomDeadzone ?? .1;
+    const responseMs = options.responseMs ?? 25;
+    const maxFrameMs = options.maxFrameMs ?? 50;
+    if (![panSpeed, zoomSpeed, responseMs, maxFrameMs].every(v => Number.isFinite(v) && v >= 0)
+        || ![panDeadzone, zoomDeadzone].every(v => Number.isFinite(v) && v >= 0 && v < 1)) {
+        throw new RangeError('Speeds and times must be finite and non-negative; deadzones must be in [0, 1).');
+    }
+    let current = { ...neutralInput };
+    let previous;
+    const velocity = [0, 0, 0];
+    function integrate(target, i, dt) {
+        if (target === 0) {
+            velocity[i] = 0;
+            return 0;
+        }
+        if (responseMs === 0) {
+            velocity[i] = target;
+            return target * dt / 1000;
+        }
+        const initial = velocity[i] * target < 0 ? 0 : velocity[i];
+        const blend = -Math.expm1(-dt / responseMs);
+        velocity[i] = initial + (target - initial) * blend;
+        return (target * dt + (initial - target) * responseMs * blend) / 1000;
+    }
+    return {
+        setInput(input) { current = { ...input }; },
+        setZoomInput(input) { zoomInput = input; velocity[2] = 0; },
+        reset() { current = { ...neutralInput }; velocity.fill(0); previous = undefined; },
+        step(timestamp) {
+            // Duplicate/out-of-order timestamps must not introduce extra elapsed time.
+            if (previous !== undefined && timestamp <= previous)
+                return idle;
+            const dt = previous === undefined ? 0 : Math.min(maxFrameMs, timestamp - previous);
+            previous = timestamp;
+            const panX = integrate(deadzone(-current.x, panDeadzone), 0, dt) * panSpeed;
+            const panY = integrate(deadzone(-current.y, panDeadzone), 1, dt) * panSpeed;
+            const logZoom = integrate(deadzone(zoomInput === 'press' ? current.z : current.rz, zoomDeadzone), 2, dt) * zoomSpeed;
+            if (panX === 0 && panY === 0 && logZoom === 0)
+                return idle;
+            return { panX, panY, zoomFactor: Math.exp(logZoom), moving: true };
+        },
+    };
+}

package/dist/webhid.d.ts

@@ -0,0 +1,51 @@
+import type { InputState } from './input.js';
+/** Structural browser interfaces keep WebHID globals out of the core package. */
+export interface HidReportEvent extends Event {
+    reportId: number;
+    data: DataView;
+}
+export interface HidDevice extends EventTarget {
+    readonly vendorId: number;
+    readonly productId: number;
+    readonly opened: boolean;
+    open(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface HidAccess extends EventTarget {
+    requestDevice(options: {
+        filters: Array<{
+            vendorId: number;
+            productId: number;
+            usagePage?: number;
+            usage?: number;
+        }>;
+    }): Promise<HidDevice[]>;
+}
+export interface DeviceProfile {
+    vendorId: number;
+    productId: number;
+    usagePage?: number;
+    usage?: number;
+    decode(reportId: number, data: DataView): InputState | null;
+}
+/** Hardware-verified combined six-axis report profile. */
+export declare const combinedProfile: Readonly<DeviceProfile>;
+export interface ConnectionOptions {
+    onInput(input: Readonly<InputState>): void;
+    /** Reset processor timing/response on pause, blur, hidden, close or disconnect. */
+    onReset?(): void;
+    onDisconnect?(): void;
+    profile?: DeviceProfile;
+    /** Inject for tests or an alternative WebHID implementation. */
+    hid?: HidAccess;
+    /** Default true: blur/hidden clears input and waits for a fresh report on return. */
+    pauseOnBlur?: boolean;
+}
+export interface InputConnection {
+    readonly device: HidDevice;
+    pause(): void;
+    resume(): void;
+    close(): Promise<void>;
+}
+/** Call from a user gesture. Cancellation returns null. No frame loop is started. */
+export declare function connectWebHid(options: ConnectionOptions): Promise<InputConnection | null>;

package/dist/webhid.js

@@ -0,0 +1,75 @@
+import { decodeCombinedReport, neutralInput } from './input.js';
+/** Hardware-verified combined six-axis report profile. */
+export const combinedProfile = Object.freeze({
+    vendorId: 0x256f, productId: 0xc63a, usagePage: 1, usage: 8, decode: decodeCombinedReport,
+});
+/** Call from a user gesture. Cancellation returns null. No frame loop is started. */
+export async function connectWebHid(options) {
+    const hid = options.hid ?? globalThis.navigator?.hid;
+    if (!hid)
+        throw new Error('This browser does not provide WebHID.');
+    const profile = options.profile ?? combinedProfile;
+    const candidates = await hid.requestDevice({ filters: [{ vendorId: profile.vendorId, productId: profile.productId, usagePage: profile.usagePage, usage: profile.usage }] });
+    const device = candidates.find(candidate => candidate.vendorId === profile.vendorId && candidate.productId === profile.productId);
+    if (!device)
+        return null;
+    await device.open();
+    const page = typeof window === 'undefined' ? undefined : window;
+    const document = page?.document;
+    const focusPolicy = options.pauseOnBlur ?? true;
+    let paused = false;
+    let closed = false;
+    const isForeground = () => !focusPolicy || !document || document.hasFocus() && !document.hidden;
+    const clear = () => { options.onInput(neutralInput); options.onReset?.(); };
+    const report = (event) => {
+        if (paused || closed || !isForeground())
+            return;
+        const input = event;
+        const decoded = profile.decode(input.reportId, input.data);
+        if (decoded)
+            options.onInput(decoded);
+    };
+    const blur = () => { if (focusPolicy)
+        clear(); };
+    const visibility = () => { if (document?.hidden)
+        blur(); };
+    const detach = () => {
+        device.removeEventListener('inputreport', report);
+        hid.removeEventListener('disconnect', disconnect);
+        page?.removeEventListener('blur', blur);
+        document?.removeEventListener('visibilitychange', visibility);
+    };
+    const disconnect = (event) => {
+        if (event.device !== device)
+            return;
+        closed = true;
+        detach();
+        clear();
+        options.onDisconnect?.();
+    };
+    device.addEventListener('inputreport', report);
+    hid.addEventListener('disconnect', disconnect);
+    page?.addEventListener('blur', blur);
+    document?.addEventListener('visibilitychange', visibility);
+    return {
+        device,
+        pause() { if (!closed) {
+            paused = true;
+            clear();
+        } },
+        resume() { if (!closed)
+            paused = false; },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            detach();
+            try {
+                clear();
+            }
+            finally {
+                await device.close();
+            }
+        },
+    };
+}

package/examples/camera.mjs

@@ -0,0 +1,10 @@
+/** A renderer-owned camera. Coordinates are screen-pixel offsets from world origin. */
+export function applyMotion(camera, delta, anchor, minZoom = .1, maxZoom = 5) {
+  const zoom = Math.max(minZoom, Math.min(maxZoom, camera.zoom * delta.zoomFactor));
+  const ratio = zoom / camera.zoom;
+  return {
+    x: anchor.x + (camera.x - anchor.x) * ratio + delta.panX,
+    y: anchor.y + (camera.y - anchor.y) * ratio + delta.panY,
+    zoom,
+  };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@clankagent/puck",
+  "version": "0.1.0",
+  "description": "Frame-independent six-axis input and pan/zoom motion for the web",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "examples/camera.mjs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./webhid": {
+      "types": "./dist/webhid.d.ts",
+      "import": "./dist/webhid.js"
+    }
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clankagent/puck.git"
+  },
+  "homepage": "https://github.com/clankagent/puck#readme",
+  "bugs": {
+    "url": "https://github.com/clankagent/puck/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "spacemouse",
+    "webhid",
+    "pan",
+    "zoom",
+    "input"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test tests/*.test.mjs",
+    "check": "pnpm run build && pnpm test"
+  }
+}