@dloizides/game-input 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to `@dloizides/game-input` are documented here.
+
+## 1.0.0
+
+Initial release — the haptics primitive of the C4 games shared kit.
+
+- `createHaptics(options)` — player-toggleable, always-safe Web Vibration API wrapper
+  (localStorage-gated, structural/injectable `navigator` + `storage`, never throws into the game loop).
+- `HAPTIC_PATTERNS` — shared semantic vibration vocabulary (tap/select/lock/bump/navigate/success/error/loss/reveal).
+- Zero runtime dependencies; isomorphic; dual CJS/ESM; 100% test coverage.
+
+Extracted from Aurora's `src/input/haptics.ts`. First consumers: Aurora (re-export shim) and Morphe (new adoption).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dloizides
+
+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,67 @@
+# @dloizides/game-input
+
+Framework-agnostic game input primitives. **v1 ships safe, player-toggleable haptics** — a thin wrapper
+over the Web Vibration API that no-ops silently when disabled, unsupported, or blocked, so call sites can
+fire haptics unconditionally alongside their SFX/visual feedback.
+
+Zero runtime dependencies. Isomorphic (no DOM lib required — `navigator` and storage are structural and
+injectable), so it works in browser games, React Native shells, and tests alike.
+
+> **Scope note:** keyboard/gamepad normalization is intentionally *not* in v1. The games that were audited
+> (Aurora, Morphe) implemented input with fundamentally different designs — there is no shared logic to
+> extract yet. It will be added when a genuine 2nd same-stack consumer appears (extract-on-2nd-use).
+
+## Install
+
+```bash
+npm install @dloizides/game-input
+```
+
+## Usage
+
+```ts
+import { createHaptics, HAPTIC_PATTERNS } from '@dloizides/game-input';
+
+// One controller per game; the storage key namespaces the player's preference.
+const haptics = createHaptics({ storageKey: 'aurora.haptics' });
+
+// Fire unconditionally — disabled/unsupported just no-ops.
+haptics.vibrate(HAPTIC_PATTERNS.tap);      // menu navigation / selection
+haptics.vibrate(HAPTIC_PATTERNS.success);  // level cleared
+haptics.vibrate([0, 14, 24, 14]);          // or your own pattern
+
+// Settings toggle — returns the new state, fires a confirming tick when enabling.
+function onHapticsToggle(): boolean {
+  return haptics.toggle();
+}
+haptics.isEnabled();
+```
+
+### Semantic pattern vocabulary
+
+`HAPTIC_PATTERNS` is a shared set of tuned vibration patterns keyed by intent, so every game uses the same
+feel instead of re-picking magic durations:
+
+| Intent | Pattern | Use |
+|---|---|---|
+| `tap` | `10` | menu nav / select / undo / restart |
+| `select` | `12` | pick up a tool/charm/item |
+| `lock` | `18` | something locks into place |
+| `bump` | `24` | action blocked |
+| `navigate` | `16` | portal / page turn |
+| `success` | `[0,40,50,90]` | level/chamber cleared |
+| `error` | `[0,14,24,14]` | fatal/destructive event |
+| `loss` | `[0,40,50,40]` | player loses / falls |
+| `reveal` | `[0,14,20,18,26,24]` | puzzle resolves / exit opens |
+
+## API
+
+- `createHaptics(options?)` → `Haptics` — `{ isEnabled, setEnabled, toggle, vibrate }`.
+  - `options.storageKey` (default `game.haptics`) — localStorage key for the on/off preference.
+  - `options.enableConfirmation` (default a `15`ms tick; pass `null` to disable) — fired when turning ON.
+  - `options.navigator` / `options.storage` — inject for tests/RN; default to `globalThis`.
+- `HAPTIC_PATTERNS`, `DEFAULT_HAPTICS_STORAGE_KEY`, `DEFAULT_ENABLE_CONFIRMATION`.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,73 @@
+/**
+ * A vibration pattern: a single duration in ms, or an on/off pattern
+ * (`[wait, on, off, on, ...]`) exactly as the Web Vibration API expects.
+ */
+type VibrationPattern = number | number[];
+/**
+ * The slice of `navigator` haptics needs. Structural so it works with the real
+ * browser `Navigator`, React Native shims, or a test double — no DOM lib required.
+ */
+interface VibrationCapable {
+    vibrate?: (pattern: VibrationPattern) => boolean;
+}
+/**
+ * The slice of `localStorage` haptics needs to persist the player's toggle.
+ * Structural so any key/value store (or a test double) can back it.
+ */
+interface HapticsStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/** Options for {@link createHaptics}. All optional — sensible browser defaults apply. */
+interface HapticsOptions {
+    /** localStorage key the on/off preference is persisted under. Default `game.haptics`. */
+    storageKey?: string;
+    /**
+     * Pattern fired the moment haptics are turned ON, so the player feels it engage.
+     * Pass `null` to disable the confirmation. Default a single 15ms tick.
+     */
+    enableConfirmation?: VibrationPattern | null;
+    /** Vibration source. Defaults to `globalThis.navigator`. Inject for tests/RN. */
+    navigator?: VibrationCapable;
+    /** Preference store. Defaults to `globalThis.localStorage`. Inject for tests. */
+    storage?: HapticsStorage;
+}
+/**
+ * A player-toggleable, always-safe haptics controller. Every call no-ops silently
+ * when haptics are disabled, unsupported, or blocked by the platform — so call sites
+ * can fire haptics unconditionally alongside their SFX/visual feedback.
+ */
+interface Haptics {
+    /** Whether haptics are currently enabled. */
+    isEnabled(): boolean;
+    /** Set the enabled state, persist it, and (when enabling) fire the confirmation tick. Returns the new state. */
+    setEnabled(enabled: boolean): boolean;
+    /** Flip the enabled state (for a settings toggle). Returns the new state. */
+    toggle(): boolean;
+    /** Vibrate with the given pattern. No-ops when disabled/unsupported; never throws. */
+    vibrate(pattern: VibrationPattern): void;
+}
+
+/**
+ * Create a player-toggleable, always-safe haptics controller.
+ *
+ * The on/off preference is read from (and persisted to) the configured storage key
+ * so it survives reloads. Every vibration routes through one gated call that no-ops
+ * when disabled, when no Vibration API is present, or if the platform blocks it.
+ */
+declare function createHaptics(options?: HapticsOptions): Haptics;
+
+/** Default localStorage key for the haptics on/off preference. */
+declare const DEFAULT_HAPTICS_STORAGE_KEY = "game.haptics";
+/** Default confirmation tick fired when haptics are turned ON (ms). */
+declare const DEFAULT_ENABLE_CONFIRMATION = 15;
+/** The semantic intents games map their events onto. */
+type HapticIntent = 'tap' | 'select' | 'lock' | 'bump' | 'navigate' | 'success' | 'error' | 'loss' | 'reveal';
+/**
+ * A shared vocabulary of vibration patterns keyed by intent, so every game uses
+ * the same tuned feel instead of re-picking magic durations. Pass any of these to
+ * {@link Haptics.vibrate} (or supply your own pattern).
+ */
+declare const HAPTIC_PATTERNS: Record<HapticIntent, VibrationPattern>;
+
+export { DEFAULT_ENABLE_CONFIRMATION, DEFAULT_HAPTICS_STORAGE_KEY, HAPTIC_PATTERNS, type HapticIntent, type Haptics, type HapticsOptions, type HapticsStorage, type VibrationCapable, type VibrationPattern, createHaptics };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A vibration pattern: a single duration in ms, or an on/off pattern
+ * (`[wait, on, off, on, ...]`) exactly as the Web Vibration API expects.
+ */
+type VibrationPattern = number | number[];
+/**
+ * The slice of `navigator` haptics needs. Structural so it works with the real
+ * browser `Navigator`, React Native shims, or a test double — no DOM lib required.
+ */
+interface VibrationCapable {
+    vibrate?: (pattern: VibrationPattern) => boolean;
+}
+/**
+ * The slice of `localStorage` haptics needs to persist the player's toggle.
+ * Structural so any key/value store (or a test double) can back it.
+ */
+interface HapticsStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/** Options for {@link createHaptics}. All optional — sensible browser defaults apply. */
+interface HapticsOptions {
+    /** localStorage key the on/off preference is persisted under. Default `game.haptics`. */
+    storageKey?: string;
+    /**
+     * Pattern fired the moment haptics are turned ON, so the player feels it engage.
+     * Pass `null` to disable the confirmation. Default a single 15ms tick.
+     */
+    enableConfirmation?: VibrationPattern | null;
+    /** Vibration source. Defaults to `globalThis.navigator`. Inject for tests/RN. */
+    navigator?: VibrationCapable;
+    /** Preference store. Defaults to `globalThis.localStorage`. Inject for tests. */
+    storage?: HapticsStorage;
+}
+/**
+ * A player-toggleable, always-safe haptics controller. Every call no-ops silently
+ * when haptics are disabled, unsupported, or blocked by the platform — so call sites
+ * can fire haptics unconditionally alongside their SFX/visual feedback.
+ */
+interface Haptics {
+    /** Whether haptics are currently enabled. */
+    isEnabled(): boolean;
+    /** Set the enabled state, persist it, and (when enabling) fire the confirmation tick. Returns the new state. */
+    setEnabled(enabled: boolean): boolean;
+    /** Flip the enabled state (for a settings toggle). Returns the new state. */
+    toggle(): boolean;
+    /** Vibrate with the given pattern. No-ops when disabled/unsupported; never throws. */
+    vibrate(pattern: VibrationPattern): void;
+}
+
+/**
+ * Create a player-toggleable, always-safe haptics controller.
+ *
+ * The on/off preference is read from (and persisted to) the configured storage key
+ * so it survives reloads. Every vibration routes through one gated call that no-ops
+ * when disabled, when no Vibration API is present, or if the platform blocks it.
+ */
+declare function createHaptics(options?: HapticsOptions): Haptics;
+
+/** Default localStorage key for the haptics on/off preference. */
+declare const DEFAULT_HAPTICS_STORAGE_KEY = "game.haptics";
+/** Default confirmation tick fired when haptics are turned ON (ms). */
+declare const DEFAULT_ENABLE_CONFIRMATION = 15;
+/** The semantic intents games map their events onto. */
+type HapticIntent = 'tap' | 'select' | 'lock' | 'bump' | 'navigate' | 'success' | 'error' | 'loss' | 'reveal';
+/**
+ * A shared vocabulary of vibration patterns keyed by intent, so every game uses
+ * the same tuned feel instead of re-picking magic durations. Pass any of these to
+ * {@link Haptics.vibrate} (or supply your own pattern).
+ */
+declare const HAPTIC_PATTERNS: Record<HapticIntent, VibrationPattern>;
+
+export { DEFAULT_ENABLE_CONFIRMATION, DEFAULT_HAPTICS_STORAGE_KEY, HAPTIC_PATTERNS, type HapticIntent, type Haptics, type HapticsOptions, type HapticsStorage, type VibrationCapable, type VibrationPattern, createHaptics };

package/dist/index.js

@@ -0,0 +1,91 @@
+'use strict';
+
+// src/constants.ts
+var DEFAULT_HAPTICS_STORAGE_KEY = "game.haptics";
+var DEFAULT_ENABLE_CONFIRMATION = 15;
+var DISABLED_VALUE = "0";
+var ENABLED_VALUE = "1";
+var HAPTIC_PATTERNS = {
+  /** Light tick for menu navigation / selection / undo / restart. */
+  tap: 10,
+  /** Light pulse when a tool/charm/item is picked up or selected. */
+  select: 12,
+  /** Short pulse when something locks into place. */
+  lock: 18,
+  /** Dull buzz when an action is blocked. */
+  bump: 24,
+  /** Quick pulse when stepping through a portal / page turn. */
+  navigate: 16,
+  /** Celebratory pattern when a level/chamber is cleared. */
+  success: [0, 40, 50, 90],
+  /** Sharp double crack for a fatal/destructive event. */
+  error: [0, 14, 24, 14],
+  /** Heavier buzz when the player loses / falls. */
+  loss: [0, 40, 50, 40],
+  /** Rising triple pulse the instant a puzzle resolves / an exit opens. */
+  reveal: [0, 14, 20, 18, 26, 24]
+};
+
+// src/haptics.ts
+function resolveNavigator(explicit) {
+  if (explicit) {
+    return explicit;
+  }
+  return globalThis.navigator;
+}
+function resolveStorage(explicit) {
+  if (explicit) {
+    return explicit;
+  }
+  return globalThis.localStorage;
+}
+function createHaptics(options = {}) {
+  const storageKey = options.storageKey ?? DEFAULT_HAPTICS_STORAGE_KEY;
+  const confirmation = options.enableConfirmation === void 0 ? DEFAULT_ENABLE_CONFIRMATION : options.enableConfirmation;
+  const navigator = resolveNavigator(options.navigator);
+  const storage = resolveStorage(options.storage);
+  const readPref = () => {
+    try {
+      return storage?.getItem(storageKey) !== DISABLED_VALUE;
+    } catch {
+      return true;
+    }
+  };
+  let enabled = readPref();
+  const vibrate = (pattern) => {
+    if (!enabled) {
+      return;
+    }
+    try {
+      navigator?.vibrate?.(pattern);
+    } catch {
+    }
+  };
+  const persist = () => {
+    try {
+      storage?.setItem(storageKey, enabled ? ENABLED_VALUE : DISABLED_VALUE);
+    } catch {
+    }
+  };
+  const setEnabled = (next) => {
+    enabled = next;
+    persist();
+    if (enabled && confirmation !== null) {
+      vibrate(confirmation);
+    }
+    return enabled;
+  };
+  return {
+    isEnabled: () => enabled,
+    setEnabled,
+    toggle: () => setEnabled(!enabled),
+    vibrate
+  };
+}
+
+exports.DEFAULT_ENABLE_CONFIRMATION = DEFAULT_ENABLE_CONFIRMATION;
+exports.DEFAULT_HAPTICS_STORAGE_KEY = DEFAULT_HAPTICS_STORAGE_KEY;
+exports.HAPTIC_PATTERNS = HAPTIC_PATTERNS;
+exports.createHaptics = createHaptics;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts","../src/haptics.ts"],"names":[],"mappings":";;;AAGO,IAAM,2BAAA,GAA8B;AAGpC,IAAM,2BAAA,GAA8B;AAGpC,IAAM,cAAA,GAAiB,GAAA;AAGvB,IAAM,aAAA,GAAgB,GAAA;AAmBtB,IAAM,eAAA,GAA0D;AAAA;AAAA,EAErE,GAAA,EAAK,EAAA;AAAA;AAAA,EAEL,MAAA,EAAQ,EAAA;AAAA;AAAA,EAER,IAAA,EAAM,EAAA;AAAA;AAAA,EAEN,IAAA,EAAM,EAAA;AAAA;AAAA,EAEN,QAAA,EAAU,EAAA;AAAA;AAAA,EAEV,OAAA,EAAS,CAAC,CAAA,EAAG,EAAA,EAAI,IAAI,EAAE,CAAA;AAAA;AAAA,EAEvB,KAAA,EAAO,CAAC,CAAA,EAAG,EAAA,EAAI,IAAI,EAAE,CAAA;AAAA;AAAA,EAErB,IAAA,EAAM,CAAC,CAAA,EAAG,EAAA,EAAI,IAAI,EAAE,CAAA;AAAA;AAAA,EAEpB,QAAQ,CAAC,CAAA,EAAG,IAAI,EAAA,EAAI,EAAA,EAAI,IAAI,EAAE;AAChC;;;AC1CA,SAAS,iBAAiB,QAAA,EAA2D;AACnF,EAAA,IAAI,QAAA,EAAU;AACZ,IAAA,OAAO,QAAA;AAAA,EACT;AACA,EAAA,OAAQ,UAAA,CAAgD,SAAA;AAC1D;AAEA,SAAS,eAAe,QAAA,EAAuD;AAC7E,EAAA,IAAI,QAAA,EAAU;AACZ,IAAA,OAAO,QAAA;AAAA,EACT;AACA,EAAA,OAAQ,UAAA,CAAiD,YAAA;AAC3D;AASO,SAAS,aAAA,CAAc,OAAA,GAA0B,EAAC,EAAY;AACnE,EAAA,MAAM,UAAA,GAAa,QAAQ,UAAA,IAAc,2BAAA;AACzC,EAAA,MAAM,YAAA,GACJ,OAAA,CAAQ,kBAAA,KAAuB,MAAA,GAAY,8BAA8B,OAAA,CAAQ,kBAAA;AACnF,EAAA,MAAM,SAAA,GAAY,gBAAA,CAAiB,OAAA,CAAQ,SAAS,CAAA;AACpD,EAAA,MAAM,OAAA,GAAU,cAAA,CAAe,OAAA,CAAQ,OAAO,CAAA;AAE9C,EAAA,MAAM,WAAW,MAAe;AAC9B,IAAA,IAAI;AACF,MAAA,OAAO,OAAA,EAAS,OAAA,CAAQ,UAAU,CAAA,KAAM,cAAA;AAAA,IAC1C,CAAA,CAAA,MAAQ;AAEN,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF,CAAA;AAEA,EAAA,IAAI,UAAU,QAAA,EAAS;AAEvB,EAAA,MAAM,OAAA,GAAU,CAAC,OAAA,KAAoC;AACnD,IAAA,IAAI,CAAC,OAAA,EAAS;AACZ,MAAA;AAAA,IACF;AACA,IAAA,IAAI;AACF,MAAA,SAAA,EAAW,UAAU,OAAO,CAAA;AAAA,IAC9B,CAAA,CAAA,MAAQ;AAAA,IAER;AAAA,EACF,CAAA;AAEA,EAAA,MAAM,UAAU,MAAY;AAC1B,IAAA,IAAI;AACF,MAAA,OAAA,EAAS,OAAA,CAAQ,UAAA,EAAY,OAAA,GAAU,aAAA,GAAgB,cAAc,CAAA;AAAA,IACvE,CAAA,CAAA,MAAQ;AAAA,IAER;AAAA,EACF,CAAA;AAEA,EAAA,MAAM,UAAA,GAAa,CAAC,IAAA,KAA2B;AAC7C,IAAA,OAAA,GAAU,IAAA;AACV,IAAA,OAAA,EAAQ;AAER,IAAA,IAAI,OAAA,IAAW,iBAAiB,IAAA,EAAM;AACpC,MAAA,OAAA,CAAQ,YAAY,CAAA;AAAA,IACtB;AACA,IAAA,OAAO,OAAA;AAAA,EACT,CAAA;AAEA,EAAA,OAAO;AAAA,IACL,WAAW,MAAe,OAAA;AAAA,IAC1B,UAAA;AAAA,IACA,MAAA,EAAQ,MAAe,UAAA,CAAW,CAAC,OAAO,CAAA;AAAA,IAC1C;AAAA,GACF;AACF","file":"index.js","sourcesContent":["import type { VibrationPattern } from './types';\n\n/** Default localStorage key for the haptics on/off preference. */\nexport const DEFAULT_HAPTICS_STORAGE_KEY = 'game.haptics';\n\n/** Default confirmation tick fired when haptics are turned ON (ms). */\nexport const DEFAULT_ENABLE_CONFIRMATION = 15;\n\n/** Stored value meaning \"disabled\". Any other value (or absent) means enabled. */\nexport const DISABLED_VALUE = '0';\n\n/** Stored value meaning \"enabled\". */\nexport const ENABLED_VALUE = '1';\n\n/** The semantic intents games map their events onto. */\nexport type HapticIntent =\n  | 'tap'\n  | 'select'\n  | 'lock'\n  | 'bump'\n  | 'navigate'\n  | 'success'\n  | 'error'\n  | 'loss'\n  | 'reveal';\n\n/**\n * A shared vocabulary of vibration patterns keyed by intent, so every game uses\n * the same tuned feel instead of re-picking magic durations. Pass any of these to\n * {@link Haptics.vibrate} (or supply your own pattern).\n */\nexport const HAPTIC_PATTERNS: Record<HapticIntent, VibrationPattern> = {\n  /** Light tick for menu navigation / selection / undo / restart. */\n  tap: 10,\n  /** Light pulse when a tool/charm/item is picked up or selected. */\n  select: 12,\n  /** Short pulse when something locks into place. */\n  lock: 18,\n  /** Dull buzz when an action is blocked. */\n  bump: 24,\n  /** Quick pulse when stepping through a portal / page turn. */\n  navigate: 16,\n  /** Celebratory pattern when a level/chamber is cleared. */\n  success: [0, 40, 50, 90],\n  /** Sharp double crack for a fatal/destructive event. */\n  error: [0, 14, 24, 14],\n  /** Heavier buzz when the player loses / falls. */\n  loss: [0, 40, 50, 40],\n  /** Rising triple pulse the instant a puzzle resolves / an exit opens. */\n  reveal: [0, 14, 20, 18, 26, 24],\n};\n","import {\n  DEFAULT_ENABLE_CONFIRMATION,\n  DEFAULT_HAPTICS_STORAGE_KEY,\n  DISABLED_VALUE,\n  ENABLED_VALUE,\n} from './constants';\nimport type { Haptics, HapticsOptions, HapticsStorage, VibrationCapable, VibrationPattern } from './types';\n\nfunction resolveNavigator(explicit?: VibrationCapable): VibrationCapable | undefined {\n  if (explicit) {\n    return explicit;\n  }\n  return (globalThis as { navigator?: VibrationCapable }).navigator;\n}\n\nfunction resolveStorage(explicit?: HapticsStorage): HapticsStorage | undefined {\n  if (explicit) {\n    return explicit;\n  }\n  return (globalThis as { localStorage?: HapticsStorage }).localStorage;\n}\n\n/**\n * Create a player-toggleable, always-safe haptics controller.\n *\n * The on/off preference is read from (and persisted to) the configured storage key\n * so it survives reloads. Every vibration routes through one gated call that no-ops\n * when disabled, when no Vibration API is present, or if the platform blocks it.\n */\nexport function createHaptics(options: HapticsOptions = {}): Haptics {\n  const storageKey = options.storageKey ?? DEFAULT_HAPTICS_STORAGE_KEY;\n  const confirmation =\n    options.enableConfirmation === undefined ? DEFAULT_ENABLE_CONFIRMATION : options.enableConfirmation;\n  const navigator = resolveNavigator(options.navigator);\n  const storage = resolveStorage(options.storage);\n\n  const readPref = (): boolean => {\n    try {\n      return storage?.getItem(storageKey) !== DISABLED_VALUE;\n    } catch {\n      // Reading storage can throw (blocked cookies / sandboxed iframe) — default ON.\n      return true;\n    }\n  };\n\n  let enabled = readPref();\n\n  const vibrate = (pattern: VibrationPattern): void => {\n    if (!enabled) {\n      return;\n    }\n    try {\n      navigator?.vibrate?.(pattern);\n    } catch {\n      // Vibration can throw if blocked by the platform — never let it break a move.\n    }\n  };\n\n  const persist = (): void => {\n    try {\n      storage?.setItem(storageKey, enabled ? ENABLED_VALUE : DISABLED_VALUE);\n    } catch {\n      // Writing storage can throw (private mode / quota) — ignore.\n    }\n  };\n\n  const setEnabled = (next: boolean): boolean => {\n    enabled = next;\n    persist();\n    // A confirming tick when turning ON so the player feels it engage.\n    if (enabled && confirmation !== null) {\n      vibrate(confirmation);\n    }\n    return enabled;\n  };\n\n  return {\n    isEnabled: (): boolean => enabled,\n    setEnabled,\n    toggle: (): boolean => setEnabled(!enabled),\n    vibrate,\n  };\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,86 @@
+// src/constants.ts
+var DEFAULT_HAPTICS_STORAGE_KEY = "game.haptics";
+var DEFAULT_ENABLE_CONFIRMATION = 15;
+var DISABLED_VALUE = "0";
+var ENABLED_VALUE = "1";
+var HAPTIC_PATTERNS = {
+  /** Light tick for menu navigation / selection / undo / restart. */
+  tap: 10,
+  /** Light pulse when a tool/charm/item is picked up or selected. */
+  select: 12,
+  /** Short pulse when something locks into place. */
+  lock: 18,
+  /** Dull buzz when an action is blocked. */
+  bump: 24,
+  /** Quick pulse when stepping through a portal / page turn. */
+  navigate: 16,
+  /** Celebratory pattern when a level/chamber is cleared. */
+  success: [0, 40, 50, 90],
+  /** Sharp double crack for a fatal/destructive event. */
+  error: [0, 14, 24, 14],
+  /** Heavier buzz when the player loses / falls. */
+  loss: [0, 40, 50, 40],
+  /** Rising triple pulse the instant a puzzle resolves / an exit opens. */
+  reveal: [0, 14, 20, 18, 26, 24]
+};
+
+// src/haptics.ts
+function resolveNavigator(explicit) {
+  if (explicit) {
+    return explicit;
+  }
+  return globalThis.navigator;
+}
+function resolveStorage(explicit) {
+  if (explicit) {
+    return explicit;
+  }
+  return globalThis.localStorage;
+}
+function createHaptics(options = {}) {
+  const storageKey = options.storageKey ?? DEFAULT_HAPTICS_STORAGE_KEY;
+  const confirmation = options.enableConfirmation === void 0 ? DEFAULT_ENABLE_CONFIRMATION : options.enableConfirmation;
+  const navigator = resolveNavigator(options.navigator);
+  const storage = resolveStorage(options.storage);
+  const readPref = () => {
+    try {
+      return storage?.getItem(storageKey) !== DISABLED_VALUE;
+    } catch {
+      return true;
+    }
+  };
+  let enabled = readPref();
+  const vibrate = (pattern) => {
+    if (!enabled) {
+      return;
+    }
+    try {
+      navigator?.vibrate?.(pattern);
+    } catch {
+    }
+  };
+  const persist = () => {
+    try {
+      storage?.setItem(storageKey, enabled ? ENABLED_VALUE : DISABLED_VALUE);
+    } catch {
+    }
+  };
+  const setEnabled = (next) => {
+    enabled = next;
+    persist();
+    if (enabled && confirmation !== null) {
+      vibrate(confirmation);
+    }
+    return enabled;
+  };
+  return {
+    isEnabled: () => enabled,
+    setEnabled,
+    toggle: () => setEnabled(!enabled),
+    vibrate
+  };
+}
+
+export { DEFAULT_ENABLE_CONFIRMATION, DEFAULT_HAPTICS_STORAGE_KEY, HAPTIC_PATTERNS, createHaptics };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts","../src/haptics.ts"],"names":[],"mappings":";AAGO,IAAM,2BAAA,GAA8B;AAGpC,IAAM,2BAAA,GAA8B;AAGpC,IAAM,cAAA,GAAiB,GAAA;AAGvB,IAAM,aAAA,GAAgB,GAAA;AAmBtB,IAAM,eAAA,GAA0D;AAAA;AAAA,EAErE,GAAA,EAAK,EAAA;AAAA;AAAA,EAEL,MAAA,EAAQ,EAAA;AAAA;AAAA,EAER,IAAA,EAAM,EAAA;AAAA;AAAA,EAEN,IAAA,EAAM,EAAA;AAAA;AAAA,EAEN,QAAA,EAAU,EAAA;AAAA;AAAA,EAEV,OAAA,EAAS,CAAC,CAAA,EAAG,EAAA,EAAI,IAAI,EAAE,CAAA;AAAA;AAAA,EAEvB,KAAA,EAAO,CAAC,CAAA,EAAG,EAAA,EAAI,IAAI,EAAE,CAAA;AAAA;AAAA,EAErB,IAAA,EAAM,CAAC,CAAA,EAAG,EAAA,EAAI,IAAI,EAAE,CAAA;AAAA;AAAA,EAEpB,QAAQ,CAAC,CAAA,EAAG,IAAI,EAAA,EAAI,EAAA,EAAI,IAAI,EAAE;AAChC;;;AC1CA,SAAS,iBAAiB,QAAA,EAA2D;AACnF,EAAA,IAAI,QAAA,EAAU;AACZ,IAAA,OAAO,QAAA;AAAA,EACT;AACA,EAAA,OAAQ,UAAA,CAAgD,SAAA;AAC1D;AAEA,SAAS,eAAe,QAAA,EAAuD;AAC7E,EAAA,IAAI,QAAA,EAAU;AACZ,IAAA,OAAO,QAAA;AAAA,EACT;AACA,EAAA,OAAQ,UAAA,CAAiD,YAAA;AAC3D;AASO,SAAS,aAAA,CAAc,OAAA,GAA0B,EAAC,EAAY;AACnE,EAAA,MAAM,UAAA,GAAa,QAAQ,UAAA,IAAc,2BAAA;AACzC,EAAA,MAAM,YAAA,GACJ,OAAA,CAAQ,kBAAA,KAAuB,MAAA,GAAY,8BAA8B,OAAA,CAAQ,kBAAA;AACnF,EAAA,MAAM,SAAA,GAAY,gBAAA,CAAiB,OAAA,CAAQ,SAAS,CAAA;AACpD,EAAA,MAAM,OAAA,GAAU,cAAA,CAAe,OAAA,CAAQ,OAAO,CAAA;AAE9C,EAAA,MAAM,WAAW,MAAe;AAC9B,IAAA,IAAI;AACF,MAAA,OAAO,OAAA,EAAS,OAAA,CAAQ,UAAU,CAAA,KAAM,cAAA;AAAA,IAC1C,CAAA,CAAA,MAAQ;AAEN,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF,CAAA;AAEA,EAAA,IAAI,UAAU,QAAA,EAAS;AAEvB,EAAA,MAAM,OAAA,GAAU,CAAC,OAAA,KAAoC;AACnD,IAAA,IAAI,CAAC,OAAA,EAAS;AACZ,MAAA;AAAA,IACF;AACA,IAAA,IAAI;AACF,MAAA,SAAA,EAAW,UAAU,OAAO,CAAA;AAAA,IAC9B,CAAA,CAAA,MAAQ;AAAA,IAER;AAAA,EACF,CAAA;AAEA,EAAA,MAAM,UAAU,MAAY;AAC1B,IAAA,IAAI;AACF,MAAA,OAAA,EAAS,OAAA,CAAQ,UAAA,EAAY,OAAA,GAAU,aAAA,GAAgB,cAAc,CAAA;AAAA,IACvE,CAAA,CAAA,MAAQ;AAAA,IAER;AAAA,EACF,CAAA;AAEA,EAAA,MAAM,UAAA,GAAa,CAAC,IAAA,KAA2B;AAC7C,IAAA,OAAA,GAAU,IAAA;AACV,IAAA,OAAA,EAAQ;AAER,IAAA,IAAI,OAAA,IAAW,iBAAiB,IAAA,EAAM;AACpC,MAAA,OAAA,CAAQ,YAAY,CAAA;AAAA,IACtB;AACA,IAAA,OAAO,OAAA;AAAA,EACT,CAAA;AAEA,EAAA,OAAO;AAAA,IACL,WAAW,MAAe,OAAA;AAAA,IAC1B,UAAA;AAAA,IACA,MAAA,EAAQ,MAAe,UAAA,CAAW,CAAC,OAAO,CAAA;AAAA,IAC1C;AAAA,GACF;AACF","file":"index.mjs","sourcesContent":["import type { VibrationPattern } from './types';\n\n/** Default localStorage key for the haptics on/off preference. */\nexport const DEFAULT_HAPTICS_STORAGE_KEY = 'game.haptics';\n\n/** Default confirmation tick fired when haptics are turned ON (ms). */\nexport const DEFAULT_ENABLE_CONFIRMATION = 15;\n\n/** Stored value meaning \"disabled\". Any other value (or absent) means enabled. */\nexport const DISABLED_VALUE = '0';\n\n/** Stored value meaning \"enabled\". */\nexport const ENABLED_VALUE = '1';\n\n/** The semantic intents games map their events onto. */\nexport type HapticIntent =\n  | 'tap'\n  | 'select'\n  | 'lock'\n  | 'bump'\n  | 'navigate'\n  | 'success'\n  | 'error'\n  | 'loss'\n  | 'reveal';\n\n/**\n * A shared vocabulary of vibration patterns keyed by intent, so every game uses\n * the same tuned feel instead of re-picking magic durations. Pass any of these to\n * {@link Haptics.vibrate} (or supply your own pattern).\n */\nexport const HAPTIC_PATTERNS: Record<HapticIntent, VibrationPattern> = {\n  /** Light tick for menu navigation / selection / undo / restart. */\n  tap: 10,\n  /** Light pulse when a tool/charm/item is picked up or selected. */\n  select: 12,\n  /** Short pulse when something locks into place. */\n  lock: 18,\n  /** Dull buzz when an action is blocked. */\n  bump: 24,\n  /** Quick pulse when stepping through a portal / page turn. */\n  navigate: 16,\n  /** Celebratory pattern when a level/chamber is cleared. */\n  success: [0, 40, 50, 90],\n  /** Sharp double crack for a fatal/destructive event. */\n  error: [0, 14, 24, 14],\n  /** Heavier buzz when the player loses / falls. */\n  loss: [0, 40, 50, 40],\n  /** Rising triple pulse the instant a puzzle resolves / an exit opens. */\n  reveal: [0, 14, 20, 18, 26, 24],\n};\n","import {\n  DEFAULT_ENABLE_CONFIRMATION,\n  DEFAULT_HAPTICS_STORAGE_KEY,\n  DISABLED_VALUE,\n  ENABLED_VALUE,\n} from './constants';\nimport type { Haptics, HapticsOptions, HapticsStorage, VibrationCapable, VibrationPattern } from './types';\n\nfunction resolveNavigator(explicit?: VibrationCapable): VibrationCapable | undefined {\n  if (explicit) {\n    return explicit;\n  }\n  return (globalThis as { navigator?: VibrationCapable }).navigator;\n}\n\nfunction resolveStorage(explicit?: HapticsStorage): HapticsStorage | undefined {\n  if (explicit) {\n    return explicit;\n  }\n  return (globalThis as { localStorage?: HapticsStorage }).localStorage;\n}\n\n/**\n * Create a player-toggleable, always-safe haptics controller.\n *\n * The on/off preference is read from (and persisted to) the configured storage key\n * so it survives reloads. Every vibration routes through one gated call that no-ops\n * when disabled, when no Vibration API is present, or if the platform blocks it.\n */\nexport function createHaptics(options: HapticsOptions = {}): Haptics {\n  const storageKey = options.storageKey ?? DEFAULT_HAPTICS_STORAGE_KEY;\n  const confirmation =\n    options.enableConfirmation === undefined ? DEFAULT_ENABLE_CONFIRMATION : options.enableConfirmation;\n  const navigator = resolveNavigator(options.navigator);\n  const storage = resolveStorage(options.storage);\n\n  const readPref = (): boolean => {\n    try {\n      return storage?.getItem(storageKey) !== DISABLED_VALUE;\n    } catch {\n      // Reading storage can throw (blocked cookies / sandboxed iframe) — default ON.\n      return true;\n    }\n  };\n\n  let enabled = readPref();\n\n  const vibrate = (pattern: VibrationPattern): void => {\n    if (!enabled) {\n      return;\n    }\n    try {\n      navigator?.vibrate?.(pattern);\n    } catch {\n      // Vibration can throw if blocked by the platform — never let it break a move.\n    }\n  };\n\n  const persist = (): void => {\n    try {\n      storage?.setItem(storageKey, enabled ? ENABLED_VALUE : DISABLED_VALUE);\n    } catch {\n      // Writing storage can throw (private mode / quota) — ignore.\n    }\n  };\n\n  const setEnabled = (next: boolean): boolean => {\n    enabled = next;\n    persist();\n    // A confirming tick when turning ON so the player feels it engage.\n    if (enabled && confirmation !== null) {\n      vibrate(confirmation);\n    }\n    return enabled;\n  };\n\n  return {\n    isEnabled: (): boolean => enabled,\n    setEnabled,\n    toggle: (): boolean => setEnabled(!enabled),\n    vibrate,\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@dloizides/game-input",
+  "version": "1.0.0",
+  "description": "Framework-agnostic game input primitives. v1 ships safe, player-toggleable haptics (Vibration API wrapper, localStorage-gated, zero deps). Extracted from Aurora; consumed across EisaiPollis games.",
+  "keywords": [
+    "haptics",
+    "vibration",
+    "game-input",
+    "phaser",
+    "web-game",
+    "eisaipollis"
+  ],
+  "author": "dloizides",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openmindednewby/game-input.git"
+  },
+  "homepage": "https://github.com/openmindednewby/game-input#readme",
+  "bugs": {
+    "url": "https://github.com/openmindednewby/game-input/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsup",
+    "build:watch": "tsup --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "security:audit": "npm audit --audit-level=high",
+    "prepublishOnly": "npm run clean && npm run build && npm run test"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.19.32",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.0",
+    "ts-jest": "^29.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}