@forgeax/engine-input 0.1.2

package/src/plugin-service.ts

@@ -0,0 +1,31 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+
+import type { InputBackend } from './input-snapshot';
+
+declare module '@forgeax/engine-plugin' {
+  interface EngineContextServices {
+    input?: InputBackend;
+  }
+}
+
+export function inputBackendPlugin(backend: InputBackend): Plugin {
+  return {
+    name: 'input-backend',
+    provide: 'input',
+    apply(ctx) {
+      ctx.provide('input', backend);
+    },
+  };
+}
+
+/** Provide an App-acquired input backend and release its Host listeners with the Fiber. */
+export function ownedInputBackendPlugin(backend: InputBackend, dispose: () => void): Plugin {
+  return {
+    name: 'input-backend',
+    provide: 'input',
+    apply(ctx) {
+      ctx.provide('input', backend);
+      ctx.effect(() => dispose, 'input/backend');
+    },
+  };
+}

package/src/ui-ownership.ts

@@ -0,0 +1,61 @@
+/** Event-path ownership and lifecycle reset primitives for browser hosts. */
+
+export interface UiOwnershipResult {
+  readonly owned: boolean;
+  readonly source: 'composed-path' | 'target-fallback' | 'unknown';
+}
+
+export interface UiInputResetBoundaryOptions {
+  readonly clear: () => void;
+  readonly signal?: AbortSignal;
+}
+
+export interface UiInputResetBoundary {
+  readonly reset: () => void;
+  readonly dispose: () => void;
+}
+
+function contains(root: Node, value: EventTarget | null): boolean {
+  const NodeCtor = globalThis.Node;
+  return NodeCtor && value instanceof NodeCtor ? value === root || root.contains(value) : false;
+}
+
+export function resolveUiOwnership(event: Event, host: Node): UiOwnershipResult {
+  const path = event.composedPath;
+  if (typeof path === 'function') {
+    const composed = path.call(event);
+    return {
+      owned:
+        composed.some((item) => contains(host, item)) ||
+        (composed.length === 0 && contains(host, event.target)),
+      source: composed.length === 0 ? 'target-fallback' : 'composed-path',
+    };
+  }
+  if ('target' in event) {
+    return { owned: contains(host, event.target), source: 'target-fallback' };
+  }
+  return { owned: false, source: 'unknown' };
+}
+
+export function isUiOwnedEvent(event: Event, host: Node): boolean {
+  return resolveUiOwnership(event, host).owned;
+}
+
+export function createUiInputResetBoundary(
+  options: UiInputResetBoundaryOptions,
+): UiInputResetBoundary {
+  let disposed = false;
+  const reset = (): void => {
+    if (!disposed) options.clear();
+  };
+  const onAbort = (): void => reset();
+  options.signal?.addEventListener('abort', onAbort, { once: true });
+  return {
+    reset,
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      options.signal?.removeEventListener('abort', onAbort);
+    },
+  };
+}

package/src/virtual-joystick.ts

@@ -0,0 +1,103 @@
+// virtual-joystick.ts -- pure-function virtual joystick derivation (M3).
+//
+// No DOM dependency; backend closure holds per-joystick bindState
+// and calls deriveVirtualAxes each sample() frame.
+//
+// @internal -- only the browser backend calls these functions; the
+// barrel does not re-export them.
+
+import type { VirtualAxisSample, VirtualJoystickConfig } from './input-snapshot';
+
+/**
+ * Per-joystick binding state. The backend closure owns a
+ * Map<string, BindState> keyed by joystick config name.
+ */
+export interface BindState {
+  /** bound pointerId, or undefined if unbound */
+  pointerId?: number | undefined;
+  /** origin in canvas pixels (anchor for fixed, first-touch for floating) */
+  originX: number;
+  originY: number;
+}
+
+function computeVec(
+  ptrX: number,
+  ptrY: number,
+  originX: number,
+  originY: number,
+  radius: number,
+  deadzone: number,
+): { x: number; y: number } {
+  const rawX = (ptrX - originX) / radius;
+  const rawY = (ptrY - originY) / radius;
+  const mag = Math.sqrt(rawX * rawX + rawY * rawY);
+  if (mag < deadzone) return { x: 0, y: 0 };
+  if (mag > 1) {
+    // Clamp to unit vector: normalize direction, magnitude = 1.
+    return { x: rawX / mag, y: rawY / mag };
+  }
+  return { x: rawX, y: rawY };
+}
+
+/**
+ * Derive one frame of virtual axis outputs from live pointer state and
+ * per-joystick binding state.
+ *
+ * Pure function: no DOM access. The backend closure is the SSOT for
+ * per-joystick state; binding + origin selection happens in
+ * browser-backend.ts onPointerDown. This function only reads bindState
+ * and computes per-frame vectors.
+ *
+ * Unbound joysticks always produce the zero vector.
+ *
+ * @param configs - configured virtual joysticks
+ * @param pointerMap - live pointer positions keyed by pointerId
+ * @param bindState - per-joystick binding state (read-only)
+ * @returns one VirtualAxisSample per configured joystick
+ */
+export function deriveVirtualAxes(
+  configs: readonly VirtualJoystickConfig[],
+  pointerMap: Map<number, { readonly x: number; readonly y: number }>,
+  bindState: Map<string, BindState>,
+): VirtualAxisSample[] {
+  const results: VirtualAxisSample[] = [];
+
+  for (const cfg of configs) {
+    const bs = bindState.get(cfg.name);
+
+    if (bs?.pointerId !== undefined) {
+      // Bound: compute vector from current pointer position.
+      const ptr = pointerMap.get(bs.pointerId);
+      if (ptr) {
+        const vec = computeVec(ptr.x, ptr.y, bs.originX, bs.originY, cfg.radius, cfg.deadzone);
+        results.push({ name: cfg.name, x: vec.x, y: vec.y });
+      } else {
+        // Pointer disappeared (up/cancel handled by backend unbind,
+        // but this guards against pointer removal without unbind).
+        bs.pointerId = undefined;
+        results.push({ name: cfg.name, x: 0, y: 0 });
+      }
+    } else {
+      // Unbound: zero vector. Binding is the backend's responsibility.
+      results.push({ name: cfg.name, x: 0, y: 0 });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Unbind a joystick when its bound pointer goes up or is cancelled.
+ * Sets pointerId to undefined; the next deriveVirtualAxes call will
+ * produce a zero vector for the unbound joystick.
+ */
+export function handleVirtualJoystickUnbind(
+  bindState: Map<string, BindState>,
+  pointerId: number,
+): void {
+  for (const bs of bindState.values()) {
+    if (bs.pointerId === pointerId) {
+      bs.pointerId = undefined;
+    }
+  }
+}