phaser-hooks 0.1.0

package/dist/hooks/with-debounced-state.d.ts

@@ -0,0 +1,22 @@
+import { type HookState } from './type';
+/**
+ * Creates a state hook with debounced updates
+ * @template T The type of the state value
+ * @param scene The Phaser scene instance
+ * @param key Unique identifier for the state
+ * @param initialValue Initial value for the state
+ * @param debounceMs Debounce delay in milliseconds
+ * @returns HookState with debounced set operations
+ *
+ * @example
+ * ```typescript
+ * const debouncedSearch = withDebouncedState<string>(scene, 'search', '', 300);
+ *
+ * // These rapid calls will be debounced
+ * debouncedSearch.set('a');
+ * debouncedSearch.set('ab');
+ * debouncedSearch.set('abc'); // Only this final value will be set after 300ms
+ * ```
+ */
+export declare const withDebouncedState: <T>(scene: Phaser.Scene, key: string, initialValue: T, debounceMs: number) => HookState<T>;
+//# sourceMappingURL=with-debounced-state.d.ts.map

package/dist/hooks/with-debounced-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-debounced-state.d.ts","sourceRoot":"","sources":["../../src/hooks/with-debounced-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAC;AAGxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EAClC,OAAO,MAAM,CAAC,KAAK,EACnB,KAAK,MAAM,EACX,cAAc,CAAC,EACf,YAAY,MAAM,KACjB,SAAS,CAAC,CAAC,CAoBb,CAAC"}

package/dist/hooks/with-debounced-state.js

@@ -0,0 +1,39 @@
+import { withLocalState } from './with-local-state';
+/**
+ * Creates a state hook with debounced updates
+ * @template T The type of the state value
+ * @param scene The Phaser scene instance
+ * @param key Unique identifier for the state
+ * @param initialValue Initial value for the state
+ * @param debounceMs Debounce delay in milliseconds
+ * @returns HookState with debounced set operations
+ *
+ * @example
+ * ```typescript
+ * const debouncedSearch = withDebouncedState<string>(scene, 'search', '', 300);
+ *
+ * // These rapid calls will be debounced
+ * debouncedSearch.set('a');
+ * debouncedSearch.set('ab');
+ * debouncedSearch.set('abc'); // Only this final value will be set after 300ms
+ * ```
+ */
+export const withDebouncedState = (scene, key, initialValue, debounceMs) => {
+    const actualState = withLocalState(scene, key, initialValue);
+    let timeoutId = null;
+    const debouncedSet = (value) => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            actualState.set(value);
+            timeoutId = null;
+        }, debounceMs);
+    };
+    return {
+        get: actualState.get,
+        set: debouncedSet,
+        onChange: actualState.onChange,
+    };
+};
+//# sourceMappingURL=with-debounced-state.js.map

package/dist/hooks/with-debounced-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-debounced-state.js","sourceRoot":"","sources":["../../src/hooks/with-debounced-state.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAmB,EACnB,GAAW,EACX,YAAe,EACf,UAAkB,EACJ,EAAE;IAChB,MAAM,WAAW,GAAG,cAAc,CAAI,KAAK,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;IAChE,IAAI,SAAS,GAAyC,IAAI,CAAC;IAE3D,MAAM,YAAY,GAAG,CAAC,KAAQ,EAAQ,EAAE;QACtC,IAAI,SAAS,EAAE,CAAC;YACd,YAAY,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;QAED,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;YAC1B,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACvB,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO;QACL,GAAG,EAAE,WAAW,CAAC,GAAG;QACpB,GAAG,EAAE,YAAY;QACjB,QAAQ,EAAE,WAAW,CAAC,QAAQ;KAC/B,CAAC;AACJ,CAAC,CAAC"}

package/dist/hooks/with-global-state.d.ts

@@ -0,0 +1,150 @@
+import { type HookState, type StateChangeCallback } from './type';
+/**
+ * Global state manager singleton.
+ * Manages application-wide state without dependency on specific scenes.
+ */
+declare class GlobalState {
+    private static registry;
+    private static listeners;
+    /**
+     * Set a value in the global state
+     */
+    static set<T>(key: string, value: T): void;
+    /**
+     * Get a value from the global state
+     */
+    static get<T>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Check if a key exists in the global state
+     */
+    static has(key: string): boolean;
+    /**
+     * Register a callback for when a specific key changes
+     */
+    static onChange<T>(key: string, callback: StateChangeCallback<T>): void;
+    /**
+     * Remove a callback for a specific key
+     */
+    static offChange<T>(key: string, callback: StateChangeCallback<T>): void;
+    /**
+     * Clear all global state (useful for testing or resetting game)
+     */
+    static clear(): void;
+    /**
+     * Get all keys in the global state
+     */
+    static keys(): string[];
+    /**
+     * Get debug information about the global state
+     */
+    static debug(): {
+        registry: Record<string, unknown>;
+        listeners: Record<string, number>;
+    };
+}
+/**
+ * Configuration for global state management
+ */
+export type GlobalStateOptions = {
+    /**
+     * Validator function to validate state values
+     */
+    validator?: (value: unknown) => boolean | string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+};
+/**
+ * Creates a global state hook that persists across all scenes in the game.
+ * Global state is managed by a singleton registry, removing dependency on specific scenes.
+ * Perfect for user settings, game progress, authentication state, or any data that
+ * should persist throughout the game session.
+ *
+ * @template T The type of the state value
+ * @param scene Phaser scene instance (kept for API compatibility, not used internally)
+ * @param key Unique identifier for the global state
+ * @param initialValue Optional initial value to set if state doesn't exist
+ * @param options Optional configuration for validation and debugging
+ * @returns HookState interface for managing the global state
+ *
+ * @throws {Error} When key is invalid
+ * @throws {Error} When validator rejects the initial value
+ *
+ * @example
+ * ```typescript
+ * // User settings that persist across scenes
+ * interface UserSettings {
+ *   soundVolume: number;
+ *   musicEnabled: boolean;
+ *   difficulty: 'easy' | 'normal' | 'hard';
+ * }
+ *
+ * const settingsState = withGlobalState<UserSettings>(scene, 'settings', {
+ *   soundVolume: 0.8,
+ *   musicEnabled: true,
+ *   difficulty: 'normal'
+ * });
+ *
+ * // Game progress
+ * interface GameProgress {
+ *   currentLevel: number;
+ *   unlockedLevels: number[];
+ *   totalScore: number;
+ * }
+ *
+ * const progressState = withGlobalState<GameProgress>(scene, 'progress', {
+ *   currentLevel: 1,
+ *   unlockedLevels: [1],
+ *   totalScore: 0
+ * });
+ *
+ * // Listen to changes globally
+ * progressState.onChange((newProgress, oldProgress) => {
+ *   console.log('Game progress updated:', newProgress);
+ *   // Could trigger achievements, save to localStorage, etc.
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With validation
+ * const scoreState = withGlobalState<number>(scene, 'score', 0, {
+ *   validator: (value) => {
+ *     if (typeof value !== 'number' || value < 0) {
+ *       return 'Score must be a positive number';
+ *     }
+ *     return true;
+ *   },
+ *   debug: true
+ * });
+ *
+ * // Authentication state example
+ * interface AuthState {
+ *   isLoggedIn: boolean;
+ *   username: string | null;
+ *   token: string | null;
+ * }
+ *
+ * const authState = withGlobalState<AuthState>(scene, 'auth', {
+ *   isLoggedIn: false,
+ *   username: null,
+ *   token: null
+ * });
+ *
+ * // Use from any scene - no dependency on Boot scene!
+ * if (authState.get().isLoggedIn) {
+ *   // Show authenticated content
+ * }
+ * ```
+ *
+ * @see {@link withLocalState} For scene-specific state
+ * @see {@link withStateDef} For low-level state management
+ */
+export declare const withGlobalState: <T = unknown>(key: string, initialValue?: T, options?: GlobalStateOptions) => HookState<T>;
+/**
+ * Export the GlobalState class for advanced use cases
+ * (testing, debugging, manual state management)
+ */
+export { GlobalState };
+//# sourceMappingURL=with-global-state.d.ts.map

package/dist/hooks/with-global-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-global-state.d.ts","sourceRoot":"","sources":["../../src/hooks/with-global-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAElE;;;GAGG;AACH,cAAM,WAAW;IACf,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA8B;IACrD,OAAO,CAAC,MAAM,CAAC,SAAS,CAGpB;IAEJ;;OAEG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAqB1C;;OAEG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAM3D;;OAEG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI;IAOvE;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI;IAUxE;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAKpB;;OAEG;IACH,MAAM,CAAC,IAAI,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI;QACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACnC;CAcF;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,MAAM,CAAC;IAEjD;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAIH,eAAO,MAAM,eAAe,GAAI,CAAC,GAAG,OAAO,EACzC,KAAK,MAAM,EACX,eAAe,CAAC,EAChB,UAAS,kBAAuB,KAC/B,SAAS,CAAC,CAAC,CA4Eb,CAAC;AAEF;;;GAGG;AACH,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/hooks/with-global-state.js

@@ -0,0 +1,240 @@
+/**
+ * Global state manager singleton.
+ * Manages application-wide state without dependency on specific scenes.
+ */
+class GlobalState {
+    static registry = new Map();
+    static listeners = new Map();
+    /**
+     * Set a value in the global state
+     */
+    static set(key, value) {
+        const oldValue = this.registry.get(key);
+        this.registry.set(key, value);
+        // Trigger callbacks
+        const callbacks = this.listeners.get(key);
+        if (callbacks) {
+            callbacks.forEach(callback => {
+                try {
+                    callback(value, oldValue);
+                }
+                catch (error) {
+                    // eslint-disable-next-line no-console
+                    console.error(`[GlobalState] Error in onChange callback for "${key}":`, error);
+                }
+            });
+        }
+    }
+    /**
+     * Get a value from the global state
+     */
+    static get(key, defaultValue) {
+        return this.registry.has(key)
+            ? this.registry.get(key)
+            : defaultValue;
+    }
+    /**
+     * Check if a key exists in the global state
+     */
+    static has(key) {
+        return this.registry.has(key);
+    }
+    /**
+     * Register a callback for when a specific key changes
+     */
+    static onChange(key, callback) {
+        if (!this.listeners.has(key)) {
+            this.listeners.set(key, new Set());
+        }
+        this.listeners.get(key)?.add(callback);
+    }
+    /**
+     * Remove a callback for a specific key
+     */
+    static offChange(key, callback) {
+        const callbacks = this.listeners.get(key);
+        if (callbacks) {
+            callbacks.delete(callback);
+            if (callbacks.size === 0) {
+                this.listeners.delete(key);
+            }
+        }
+    }
+    /**
+     * Clear all global state (useful for testing or resetting game)
+     */
+    static clear() {
+        this.registry.clear();
+        this.listeners.clear();
+    }
+    /**
+     * Get all keys in the global state
+     */
+    static keys() {
+        return Array.from(this.registry.keys());
+    }
+    /**
+     * Get debug information about the global state
+     */
+    static debug() {
+        const debugRegistry = {};
+        const debugListeners = {};
+        this.registry.forEach((value, key) => {
+            debugRegistry[key] = value;
+        });
+        this.listeners.forEach((callbacks, key) => {
+            debugListeners[key] = callbacks.size;
+        });
+        return { registry: debugRegistry, listeners: debugListeners };
+    }
+}
+/**
+ * Creates a global state hook that persists across all scenes in the game.
+ * Global state is managed by a singleton registry, removing dependency on specific scenes.
+ * Perfect for user settings, game progress, authentication state, or any data that
+ * should persist throughout the game session.
+ *
+ * @template T The type of the state value
+ * @param scene Phaser scene instance (kept for API compatibility, not used internally)
+ * @param key Unique identifier for the global state
+ * @param initialValue Optional initial value to set if state doesn't exist
+ * @param options Optional configuration for validation and debugging
+ * @returns HookState interface for managing the global state
+ *
+ * @throws {Error} When key is invalid
+ * @throws {Error} When validator rejects the initial value
+ *
+ * @example
+ * ```typescript
+ * // User settings that persist across scenes
+ * interface UserSettings {
+ *   soundVolume: number;
+ *   musicEnabled: boolean;
+ *   difficulty: 'easy' | 'normal' | 'hard';
+ * }
+ *
+ * const settingsState = withGlobalState<UserSettings>(scene, 'settings', {
+ *   soundVolume: 0.8,
+ *   musicEnabled: true,
+ *   difficulty: 'normal'
+ * });
+ *
+ * // Game progress
+ * interface GameProgress {
+ *   currentLevel: number;
+ *   unlockedLevels: number[];
+ *   totalScore: number;
+ * }
+ *
+ * const progressState = withGlobalState<GameProgress>(scene, 'progress', {
+ *   currentLevel: 1,
+ *   unlockedLevels: [1],
+ *   totalScore: 0
+ * });
+ *
+ * // Listen to changes globally
+ * progressState.onChange((newProgress, oldProgress) => {
+ *   console.log('Game progress updated:', newProgress);
+ *   // Could trigger achievements, save to localStorage, etc.
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With validation
+ * const scoreState = withGlobalState<number>(scene, 'score', 0, {
+ *   validator: (value) => {
+ *     if (typeof value !== 'number' || value < 0) {
+ *       return 'Score must be a positive number';
+ *     }
+ *     return true;
+ *   },
+ *   debug: true
+ * });
+ *
+ * // Authentication state example
+ * interface AuthState {
+ *   isLoggedIn: boolean;
+ *   username: string | null;
+ *   token: string | null;
+ * }
+ *
+ * const authState = withGlobalState<AuthState>(scene, 'auth', {
+ *   isLoggedIn: false,
+ *   username: null,
+ *   token: null
+ * });
+ *
+ * // Use from any scene - no dependency on Boot scene!
+ * if (authState.get().isLoggedIn) {
+ *   // Show authenticated content
+ * }
+ * ```
+ *
+ * @see {@link withLocalState} For scene-specific state
+ * @see {@link withStateDef} For low-level state management
+ */
+/* eslint-disable max-lines-per-function */
+/* eslint-disable complexity */
+/* eslint-disable sonarjs/cognitive-complexity */
+export const withGlobalState = (key, initialValue, options = {}) => {
+    if (!key || typeof key !== 'string' || key.trim().length === 0) {
+        throw new Error('[withGlobalState] Key must be a non-empty string');
+    }
+    const { validator, debug } = options;
+    // Prefix the key to indicate it's global state
+    const globalKey = `global:${key}`;
+    // Initialize value if it doesn't exist
+    if (!GlobalState.has(globalKey) && initialValue !== undefined) {
+        if (validator) {
+            const validationResult = validator(initialValue);
+            if (validationResult !== true) {
+                throw new Error(`[withGlobalState] ${validationResult || 'Invalid initial value'}`);
+            }
+        }
+        GlobalState.set(globalKey, initialValue);
+        if (debug) {
+            // eslint-disable-next-line no-console
+            console.debug(`[withGlobalState] Initialized "${key}" with value:`, initialValue);
+        }
+    }
+    return {
+        get: () => {
+            const value = GlobalState.get(globalKey);
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.debug(`[withGlobalState] Getting "${key}":`, value);
+            }
+            return value ?? initialValue;
+        },
+        set: (value) => {
+            if (validator) {
+                const validationResult = validator(value);
+                if (validationResult !== true) {
+                    throw new Error(`[withGlobalState] Invalid value for key "${key}": ${validationResult}`);
+                }
+            }
+            if (debug) {
+                const oldValue = GlobalState.get(globalKey);
+                // eslint-disable-next-line no-console
+                console.debug(`[withGlobalState] Setting "${key}":`, {
+                    oldValue,
+                    newValue: value,
+                });
+            }
+            GlobalState.set(globalKey, value);
+        },
+        onChange: (callback) => {
+            if (typeof callback !== 'function') {
+                throw new Error('[withGlobalState] onChange callback must be a function');
+            }
+            GlobalState.onChange(globalKey, callback);
+        },
+    };
+};
+/**
+ * Export the GlobalState class for advanced use cases
+ * (testing, debugging, manual state management)
+ */
+export { GlobalState };
+//# sourceMappingURL=with-global-state.js.map

package/dist/hooks/with-global-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-global-state.js","sourceRoot":"","sources":["../../src/hooks/with-global-state.ts"],"names":[],"mappings":"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"}

package/dist/hooks/with-local-state.d.ts

@@ -0,0 +1,69 @@
+import * as Phaser from 'phaser';
+import { type HookState } from './type';
+import { type StateDefOptions } from './with-state-def';
+/**
+ * Creates a local state hook scoped to a specific Phaser scene.
+ * Local state is isolated to the scene instance and doesn't persist across scene changes.
+ * This is ideal for UI state, temporary game state, or scene-specific data.
+ *
+ * @template T The type of the state value
+ * @param scene The Phaser scene instance that owns this state
+ * @param key Unique identifier for the state within this scene
+ * @param initialValue Optional initial value to set if state doesn't exist
+ * @param options Optional configuration for state behavior
+ * @returns HookState interface for managing the local state
+ *
+ * @throws {Error} When scene is not available or key is invalid
+ *
+ * @example
+ * ```typescript
+ * // Simple counter state
+ * const counterState = withLocalState<number>(scene, 'counter', 0);
+ *
+ * // Complex object state
+ * interface GameUI {
+ *   isMenuOpen: boolean;
+ *   selectedTab: string;
+ * }
+ *
+ * const uiState = withLocalState<GameUI>(scene, 'ui', {
+ *   isMenuOpen: false,
+ *   selectedTab: 'main'
+ * });
+ *
+ * // Listen to changes
+ * uiState.onChange((newUI, oldUI) => {
+ *   if (newUI.isMenuOpen !== oldUI.isMenuOpen) {
+ *     console.log('Menu visibility changed');
+ *   }
+ * });
+ *
+ * // Update state
+ * uiState.set({ ...uiState.get(), isMenuOpen: true });
+ *
+ * // Array state example
+ * const inventoryState = withLocalState<string[]>(scene, 'inventory', []);
+ * inventoryState.set([...inventoryState.get(), 'new-item']);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With validation
+ * const playerHealthState = withLocalState<number>(
+ *   scene,
+ *   'health',
+ *   100,
+ *   {
+ *     validator: (value) => {
+ *       const health = value as number;
+ *       return health >= 0 && health <= 100 ? true : 'Health must be 0-100';
+ *     }
+ *   }
+ * );
+ * ```
+ *
+ * @see {@link withGlobalState} For state that persists across scenes
+ * @see {@link withStateDef} For low-level state management
+ */
+export declare const withLocalState: <T>(scene: Phaser.Scene, key: string, initialValue?: T, options?: StateDefOptions) => HookState<T>;
+//# sourceMappingURL=with-local-state.d.ts.map

package/dist/hooks/with-local-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-local-state.d.ts","sourceRoot":"","sources":["../../src/hooks/with-local-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,OAAO,MAAM,CAAC,KAAK,EACnB,KAAK,MAAM,EACX,eAAe,CAAC,EAChB,UAAU,eAAe,KACxB,SAAS,CAAC,CAAC,CAab,CAAC"}

package/dist/hooks/with-local-state.js

@@ -0,0 +1,78 @@
+import { withStateDef } from './with-state-def';
+/**
+ * Creates a local state hook scoped to a specific Phaser scene.
+ * Local state is isolated to the scene instance and doesn't persist across scene changes.
+ * This is ideal for UI state, temporary game state, or scene-specific data.
+ *
+ * @template T The type of the state value
+ * @param scene The Phaser scene instance that owns this state
+ * @param key Unique identifier for the state within this scene
+ * @param initialValue Optional initial value to set if state doesn't exist
+ * @param options Optional configuration for state behavior
+ * @returns HookState interface for managing the local state
+ *
+ * @throws {Error} When scene is not available or key is invalid
+ *
+ * @example
+ * ```typescript
+ * // Simple counter state
+ * const counterState = withLocalState<number>(scene, 'counter', 0);
+ *
+ * // Complex object state
+ * interface GameUI {
+ *   isMenuOpen: boolean;
+ *   selectedTab: string;
+ * }
+ *
+ * const uiState = withLocalState<GameUI>(scene, 'ui', {
+ *   isMenuOpen: false,
+ *   selectedTab: 'main'
+ * });
+ *
+ * // Listen to changes
+ * uiState.onChange((newUI, oldUI) => {
+ *   if (newUI.isMenuOpen !== oldUI.isMenuOpen) {
+ *     console.log('Menu visibility changed');
+ *   }
+ * });
+ *
+ * // Update state
+ * uiState.set({ ...uiState.get(), isMenuOpen: true });
+ *
+ * // Array state example
+ * const inventoryState = withLocalState<string[]>(scene, 'inventory', []);
+ * inventoryState.set([...inventoryState.get(), 'new-item']);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With validation
+ * const playerHealthState = withLocalState<number>(
+ *   scene,
+ *   'health',
+ *   100,
+ *   {
+ *     validator: (value) => {
+ *       const health = value as number;
+ *       return health >= 0 && health <= 100 ? true : 'Health must be 0-100';
+ *     }
+ *   }
+ * );
+ * ```
+ *
+ * @see {@link withGlobalState} For state that persists across scenes
+ * @see {@link withStateDef} For low-level state management
+ */
+export const withLocalState = (scene, key, initialValue, options) => {
+    if (!scene) {
+        throw new Error('[withLocalState] Scene parameter is required');
+    }
+    // Prefix the key with scene key to ensure locality
+    const sceneKey = scene.scene?.key || 'unknown-scene';
+    const localKey = `local:${sceneKey}:${key}`;
+    return withStateDef(scene, localKey, initialValue, {
+        ...options,
+        persistent: false, // Local state shouldn't persist across scene changes
+    });
+};
+//# sourceMappingURL=with-local-state.js.map

package/dist/hooks/with-local-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-local-state.js","sourceRoot":"","sources":["../../src/hooks/with-local-state.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAwB,MAAM,kBAAkB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,KAAmB,EACnB,GAAW,EACX,YAAgB,EAChB,OAAyB,EACX,EAAE;IAChB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,mDAAmD;IACnD,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,IAAI,eAAe,CAAC;IACrD,MAAM,QAAQ,GAAG,SAAS,QAAQ,IAAI,GAAG,EAAE,CAAC;IAE5C,OAAO,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE;QACjD,GAAG,OAAO;QACV,UAAU,EAAE,KAAK,EAAE,qDAAqD;KACzE,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/hooks/with-persistent-state.d.ts

@@ -0,0 +1,19 @@
+import { type HookState } from './type';
+/**
+ * Creates a state hook with automatic localStorage persistence
+ * @template T The type of the state value
+ * @param key Unique identifier for the state
+ * @param initialValue Initial value to use if no stored value exists
+ * @param storageKey Optional custom localStorage key (defaults to the state key)
+ * @returns HookState with automatic persistence
+ *
+ * @example
+ * ```typescript
+ * const persistentSettings = withPersistentState<UserSettings>(
+ *   'settings',
+ *   { volume: 0.8, difficulty: 'normal' }
+ * );
+ * ```
+ */
+export declare const withPersistentState: <T>(key: string, initialValue: T, storageKey?: string) => HookState<T>;
+//# sourceMappingURL=with-persistent-state.d.ts.map

package/dist/hooks/with-persistent-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-persistent-state.d.ts","sourceRoot":"","sources":["../../src/hooks/with-persistent-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAC;AAGxC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,EACnC,KAAK,MAAM,EACX,cAAc,CAAC,EACf,aAAa,MAAM,KAClB,SAAS,CAAC,CAAC,CAkCb,CAAC"}