feat(signal): design signal concepts and add single-pointer signal stream

Author: devphilip21

.github/workflows/publish-package.yml

@@ -38,6 +38,9 @@ jobs:
       - name: Build package
         run: npx nx build @gesturejs/${{ inputs.package }}
 
+      - name: Remove npm protocol from dependencies
+        run: sed -i 's/"npm:@[^@]*@/""/g' packages/${{ inputs.package }}/package.json
+
       - name: Publish to npm
         run: pnpm --filter @gesturejs/${{ inputs.package }} publish --access public --no-git-checks
         env:

packages/signal/README.md

@@ -0,0 +1,77 @@
+# @gesturejs/signal
+
+**Signal** is a higher-level abstraction over events that merges and refines disparate inputs into a single, composable stream.
+
+## Why @gesturejs/signal?
+
+- **Unified Interface** - Subscribe to diverse event sources through one consistent API by normalizing them into a unified signal stream.
+- **GC Optimized** - Built-in object pooling prevents garbage collection pauses during high-frequency input (60+ events/sec)
+- **Observable-Based** - Works seamlessly with reactive patterns via `@gesturejs/stream`.
+
+## Installation
+
+```bash
+npm install @gesturejs/signal
+```
+
+## Quick Start
+
+### Single Pointer
+
+```typescript
+import { singlePointer } from "@gesturejs/signal";
+
+const stream = singlePointer(canvasElement);
+const unsub = stream.subscribe((pointer) => {
+  console.log(pointer.x, pointer.y);
+  console.log(pointer.phase); // start, move, end, cancel
+});
+```
+
+## Recipes
+
+### Use Other Events
+
+```typescript
+import { touchEventsToSinglePointer } from "@gesturejs/signal";
+import { fromEvent, merge, pipe, filter } from "@gesturejs/stream";
+
+/**
+ * The `singlePointer()` factory is primarily designed for PointerEvents.
+ * If you're working with TouchEvents, you can convert a TouchEvent stream via
+ * `touchEventsToSinglePointer()` and keep using the same SinglePointer pipeline.
+ */
+const stream = pipe(
+  merge(
+    fromEvent(el, "touchstart"),
+    fromEvent(el, "touchmove"),
+    fromEvent(el, "touchend"),
+    fromEvent(el, "touchcancel")
+  ),
+  touchEventsToSinglePointer(),
+  filter((p) => p.phase === "move")
+);
+const unsub = stream.subscribe((pointer) => {
+  draw(pointer.x, pointer.y);
+});
+```
+
+### Object Pooling
+
+```typescript
+/**
+ * Pooling reduces allocations/GC pressure for high-frequency input
+ * - but emitted objects are reused (mutated/reset). Don't keep references.
+ * - If you need to persist data, copy the fields you need.
+ */
+const spStream = singlePointer(canvasElement, { pooling: true });
+```
+
+## Documentation
+
+- [API Reference](./docs/api.md)
+- [Signal Structure](./docs/signal.md)
+
+## License
+
+MIT

packages/signal/docs/api.md

@@ -0,0 +1,95 @@
+# API Reference
+
+## Factory
+
+```typescript
+import { singlePointer } from "@gesturejs/signal";
+
+const pointer$ = singlePointer(element, options?);
+```
+
+### Options
+
+```typescript
+interface SinglePointerOptions {
+  deviceId?: string;
+  pooling?: boolean;
+  listenerOptions?: AddEventListenerOptions;
+}
+```
+
+### Variants
+
+```typescript
+// PointerEvent-based (default)
+import { singlePointer } from "@gesturejs/signal";
+
+// TouchEvent-based
+import { touchSinglePointer } from "@gesturejs/signal";
+
+// MouseEvent-based
+import { mouseSinglePointer } from "@gesturejs/signal";
+```
+
+---
+
+## Operator
+
+For custom pipelines.
+
+```typescript
+import { pointerEventsToSinglePointer } from "@gesturejs/signal";
+import { touchEventsToSinglePointer } from "@gesturejs/signal";
+import { mouseEventsToSinglePointer } from "@gesturejs/signal";
+```
+
+```typescript
+import { pointerEventsToSinglePointer } from "@gesturejs/signal";
+import { fromEvent, merge, pipe, filter } from "@gesturejs/stream";
+
+const pointer$ = pipe(
+  merge(
+    fromEvent(el, "pointerdown"),
+    fromEvent(el, "pointermove"),
+    fromEvent(el, "pointerup"),
+    fromEvent(el, "pointercancel")
+  ),
+  pointerEventsToSinglePointer({ pooling: true }),
+  filter((p) => p.phase === "move")
+);
+```
+
+---
+
+## Emitter
+
+For manual event handling.
+
+```typescript
+import { createPointerEmitter } from "@gesturejs/signal";
+import { createTouchEmitter } from "@gesturejs/signal";
+import { createMouseEmitter } from "@gesturejs/signal";
+```
+
+```typescript
+import { createPointerEmitter } from "@gesturejs/signal";
+
+const emitter = createPointerEmitter({ pooling: true });
+
+element.addEventListener("pointerdown", (e) => {
+  const pointer = emitter.process(e);
+  if (pointer) {
+    console.log(pointer.x, pointer.y);
+  }
+});
+
+emitter.dispose();
+```
+
+---
+
+## Pooling
+
+When `pooling: true`, objects are reused to reduce GC pressure. The emitter automatically releases the previous pointer when a new event arrives. No manual release is required.
+
+**Warning**: Do not store pointer references outside the callback. They will be reused on the next event.

packages/signal/docs/signal.md

@@ -0,0 +1,42 @@
+# Signal Structure
+
+## SinglePointer
+
+```typescript
+interface SinglePointer {
+  type: "pointer";
+  timestamp: number;
+  deviceId: string;
+  phase: PointerPhase;
+  x: number;
+  y: number;
+  pointerType: PointerType;
+  button: PointerButton;
+  pressure: number; // 0.0 ~ 1.0
+}
+```
+
+## Types
+
+```typescript
+type PointerPhase = "start" | "move" | "end" | "cancel";
+
+type PointerType = "mouse" | "touch" | "pen" | "unknown";
+
+type PointerButton =
+  | "none"
+  | "primary"
+  | "secondary"
+  | "auxiliary"
+  | "back"
+  | "forward";
+```
+
+## Phase
+
+| Phase    | Description                                |
+| -------- | ------------------------------------------ |
+| `start`  | Pointer down (touch start, mouse down)     |
+| `move`   | Pointer moved                              |
+| `end`    | Pointer up (touch end, mouse up)           |
+| `cancel` | Pointer cancelled (e.g. touch interrupted) |

packages/signal/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@gesturejs/signal",
+  "description": "Unified pointer signal abstraction with object pooling for high-frequency gesture input",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "require": "./dist/core/index.cjs"
+    },
+    "./pointer-signal": {
+      "types": "./dist/pointer-signal/index.d.ts",
+      "import": "./dist/pointer-signal/index.js",
+      "require": "./dist/pointer-signal/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "builder build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@gesturejs/stream": "^0.1.0"
+  },
+  "devDependencies": {
+    "@gesturejs/builder": "workspace:*"
+  }
+}

packages/signal/src/core/index.ts

@@ -0,0 +1,10 @@
+export type {
+  Signal,
+  SignalWithMetadata,
+  CancellableSignal,
+  SignalPhase,
+} from "./signal.js";
+export { createSignal } from "./signal.js";
+
+export type { ObjectPool } from "./pool.js";
+export { createObjectPool } from "./pool.js";

packages/signal/src/core/pool.ts

@@ -0,0 +1,53 @@
+export interface ObjectPool<T> {
+  acquire(): T;
+  release(obj: T): void;
+  clear(): void;
+  readonly size: number;
+  readonly active: number;
+}
+
+/** Pre-allocates and reuses objects to reduce GC pressure. */
+export function createObjectPool<T>(
+  factory: () => T,
+  reset: (obj: T) => void,
+  initialSize = 20,
+  maxSize = 100
+): ObjectPool<T> {
+  const pool: T[] = [];
+  let activeCount = 0;
+
+  for (let i = 0; i < initialSize; i++) {
+    pool.push(factory());
+  }
+
+  return {
+    acquire(): T {
+      activeCount++;
+      if (pool.length > 0) {
+        return pool.pop()!;
+      }
+      return factory();
+    },
+
+    release(obj: T): void {
+      activeCount--;
+      reset(obj);
+      if (pool.length < maxSize) {
+        pool.push(obj);
+      }
+    },
+
+    clear(): void {
+      pool.length = 0;
+      activeCount = 0;
+    },
+
+    get size(): number {
+      return pool.length;
+    },
+
+    get active(): number {
+      return activeCount;
+    },
+  };
+}

packages/signal/src/core/signal.ts

@@ -0,0 +1,29 @@
+export interface Signal<TType extends string = string> {
+  type: TType;
+  timestamp: number;
+  deviceId: string;
+}
+
+export interface SignalWithMetadata<TType extends string = string>
+  extends Signal<TType> {
+  id?: string;
+  sequence?: number;
+}
+
+export interface CancellableSignal<TType extends string = string>
+  extends Signal<TType> {
+  cancelled: boolean;
+}
+
+export type SignalPhase = "start" | "update" | "end" | "cancel";
+
+export function createSignal<TType extends string>(
+  type: TType,
+  deviceId: string
+): Signal<TType> {
+  return {
+    type,
+    timestamp: performance.now(),
+    deviceId,
+  };
+}

packages/signal/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./core/index.js";
+
+export * from "./single-pointer/index.js";
+
+export const VERSION = "0.1.0";