@hkdigital/lib-core 0.5.88 → 0.5.91

package/dist/state/machines/page-machine/PageMachine.svelte.js

@@ -69,8 +69,8 @@
  * });
  * ```
  */
-import { SvelteMap, SvelteSet } from 'svelte/reactivity';
-import { dev } from '$app/environment';
+import { SvelteSet } from 'svelte/reactivity';
+import { ReactiveDataStore } from '../../classes.js';
 
 export default class PageMachine {
 	/**
@@ -99,17 +99,14 @@ export default class PageMachine {
 	#routes = [];
 
 	/**
-	 * Reactive map for business/domain data
-	 * Uses SvelteMap for fine-grained reactivity
-	 * @type {SvelteMap<string, any>}
+	 * Reactive data store for business/domain data
+	 * @type {ReactiveDataStore}
 	 */
 	#data;
 
 	/**
-	 * Reactive map for dev-mode helper data
-	 * Uses SvelteMap for fine-grained reactivity
-	 * Only available in dev mode
-	 * @type {SvelteMap<string, any>|null}
+	 * Reactive data store for dev-mode helper data
+	 * @type {ReactiveDataStore}
 	 */
 	#devData;
 
@@ -130,6 +127,8 @@ export default class PageMachine {
 	 *   Optional list of valid routes (for validation/dev tools)
 	 * @param {Record<string, any>} [config.initialData={}]
 	 *   Initial data properties (use KEY_ constants for keys)
+	 * @param {Record<string, any>} [config.initialDevData={}]
+	 *   Initial dev data properties (use KEY_DEV_ constants for keys)
 	 * @param {import('../../../logging/client.js').Logger} [config.logger]
 	 *   Logger instance (optional)
 	 *
@@ -138,6 +137,7 @@ export default class PageMachine {
 	 * const ROUTE_INTRO = '/intro/start';
 	 * const KEY_INTRO_COMPLETED = 'intro-completed';
 	 * const KEY_SCORE = 'score';
+	 * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
 	 *
 	 * const machine = new PageMachine({
 	 *   startPath: ROUTE_INTRO,
@@ -145,11 +145,14 @@ export default class PageMachine {
 	 *   initialData: {
 	 *     [KEY_INTRO_COMPLETED]: false,
 	 *     [KEY_SCORE]: 0
+	 *   },
+	 *   initialDevData: {
+	 *     [KEY_DEV_AUTO_NAVIGATION]: false
 	 *   }
 	 * });
 	 * ```
 	 */
-	constructor({ startPath, routes = [], initialData = {}, logger = null }) {
+	constructor({ startPath, routes = [], initialData = {}, initialDevData = {}, logger = null }) {
 		if (!startPath) {
 			throw new Error('PageMachine requires startPath parameter');
 		}
@@ -160,18 +163,17 @@ export default class PageMachine {
 		this.#current = startPath;
 
 		// Initialize reactive data structures
-		this.#data = new SvelteMap();
-		this.#visitedRoutes = new SvelteSet();
+		this.#data = new ReactiveDataStore({
+			initialData
+		});
 
-		// Initialize dev data (only in dev mode)
-		if (dev) {
-			this.#devData = new SvelteMap();
-		}
+		this.#devData = new ReactiveDataStore({
+			initialData: initialDevData,
+			productionGuard: true,
+			errorPrefix: 'Dev data key'
+		});
 
-		// Populate initial data
-		for (const [key, value] of Object.entries(initialData)) {
-			this.#data.set(key, value);
-		}
+		this.#visitedRoutes = new SvelteSet();
 
 		// Mark start path as visited
 		this.#visitedRoutes.add(startPath);
@@ -256,324 +258,75 @@ export default class PageMachine {
 	/* ===== Data Properties (Business/Domain State) ===== */
 
 	/**
-	 * Set a data property value
-	 *
-	 * Automatically reactive - effects watching this key will re-run.
-	 * Uses fine-grained reactivity, so only effects watching this specific
-	 * key will be triggered.
-	 *
-	 * @param {string} key - Property key (use KEY_ constant)
-	 * @param {any} value - Property value
-	 *
-	 * @example
-	 * ```javascript
-	 * const KEY_HAS_STRONG_PROFILE = 'has-strong-profile';
-	 * const KEY_PROFILE_SCORE = 'profile-score';
-	 *
-	 * machine.setData(KEY_HAS_STRONG_PROFILE, true);
-	 * machine.setData(KEY_PROFILE_SCORE, 85);
-	 * ```
-	 */
-	setData(key, value) {
-		this.#data.set(key, value);
-	}
-
-	/**
-	 * Get a data property value
+	 * Get the reactive data store
 	 *
-	 * Automatically reactive - creates a dependency on this specific key.
-	 * The effect will only re-run when THIS key changes, not when other
-	 * keys change.
+	 * Provides read-only access to the data store instance.
+	 * Access all data methods through this property.
 	 *
-	 * @param {string} key - Property key (use KEY_ constant)
-	 *
-	 * @returns {any} Property value or undefined
+	 * @returns {ReactiveDataStore} The data store
 	 *
 	 * @example
 	 * ```javascript
 	 * const KEY_SCORE = 'score';
 	 *
-	 * // Reactive - re-runs only when KEY_SCORE changes
+	 * // Set data
+	 * machine.data.set(KEY_SCORE, 100);
+	 *
+	 * // Get data (reactive)
 	 * $effect(() => {
-	 *   const score = machine.getData(KEY_SCORE);
+	 *   const score = machine.data.get(KEY_SCORE);
 	 *   console.log('Score:', score);
 	 * });
-	 * ```
-	 */
-	getData(key) {
-		return this.#data.get(key);
-	}
-
-	/**
-	 * Get all data properties as plain object
-	 *
-	 * Note: This returns a snapshot (plain object), not a reactive map.
-	 * Use this for serialization or server sync, not for reactive tracking.
-	 *
-	 * @returns {Record<string, any>} Plain object with all data
-	 *
-	 * @example
-	 * ```javascript
-	 * const allData = machine.getAllData();
-	 * await playerService.saveData(allData);
-	 * ```
-	 */
-	getAllData() {
-		return Object.fromEntries(this.#data);
-	}
-
-	/**
-	 * Update multiple data properties at once
-	 *
-	 * Each property update triggers fine-grained reactivity.
-	 *
-	 * @param {Record<string, any>} dataUpdates
-	 *   Object with key-value pairs (use KEY_ constants for keys)
-	 *
-	 * @example
-	 * ```javascript
-	 * const KEY_HAS_STRONG_PROFILE = 'has-strong-profile';
-	 * const KEY_PROFILE_SCORE = 'profile-score';
-	 * const KEY_MATCHED_SECTOR = 'matched-sector';
-	 *
-	 * machine.updateData({
-	 *   [KEY_HAS_STRONG_PROFILE]: true,
-	 *   [KEY_PROFILE_SCORE]: 85,
-	 *   [KEY_MATCHED_SECTOR]: 'technology'
-	 * });
-	 * ```
-	 */
-	updateData(dataUpdates) {
-		for (const [key, value] of Object.entries(dataUpdates)) {
-			this.#data.set(key, value);
-		}
-	}
-
-	/**
-	 * Delete a data property
-	 *
-	 * @param {string} key - Property key to delete (use KEY_ constant)
-	 *
-	 * @returns {boolean} True if the key existed and was deleted
 	 *
-	 * @example
-	 * ```javascript
-	 * const KEY_TEMPORARY_FLAG = 'temporary-flag';
-	 *
-	 * machine.deleteData(KEY_TEMPORARY_FLAG);
+	 * // Other operations
+	 * machine.data.update({ [KEY_SCORE]: 200 });
+	 * machine.data.has(KEY_SCORE);
+	 * machine.data.delete(KEY_SCORE);
+	 * machine.data.clear();
+	 * console.log(machine.data.size);
 	 * ```
 	 */
-	deleteData(key) {
-		return this.#data.delete(key);
-	}
-
-	/**
-	 * Check if data property exists
-	 *
-	 * @param {string} key - Property key to check (use KEY_ constant)
-	 *
-	 * @returns {boolean} True if the key exists
-	 *
-	 * @example
-	 * ```javascript
-	 * const KEY_TUTORIAL_SEEN = 'tutorial-seen';
-	 *
-	 * if (machine.hasData(KEY_TUTORIAL_SEEN)) {
-	 *   // Skip tutorial
-	 * }
-	 * ```
-	 */
-	hasData(key) {
-		return this.#data.has(key);
-	}
-
-	/**
-	 * Clear all data properties
-	 *
-	 * @example
-	 * ```javascript
-	 * machine.clearData();  // Reset all game data
-	 * ```
-	 */
-	clearData() {
-		this.#data.clear();
-	}
-
-	/**
-	 * Get number of data properties
-	 *
-	 * @returns {number} Number of data entries
-	 */
-	get dataSize() {
-		return this.#data.size;
+	get data() {
+		return this.#data;
 	}
 
 	/* ===== Dev Data Properties (Dev-Mode Helpers) ===== */
 
 	/**
-	 * Set a dev data property value
+	 * Get the reactive dev data store
 	 *
-	 * Automatically reactive - effects watching this key will re-run.
-	 * Only available in dev mode - no-op in production.
+	 * Provides read-only access to the dev data store instance.
+	 * Access all dev data methods through this property.
 	 *
-	 * @param {string} key - Property key (use KEY_DEV_ constant)
-	 * @param {any} value - Property value
+	 * Dev data is only available in development mode. In production:
+	 * - SET operations are silent no-ops
+	 * - GET/HAS operations throw errors (programming errors)
 	 *
-	 * @example
-	 * ```javascript
-	 * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
-	 * const KEY_DEV_SKIP_ANIMATIONS = 'dev-skip-animations';
-	 *
-	 * machine.setDevData(KEY_DEV_AUTO_NAVIGATION, true);
-	 * machine.setDevData(KEY_DEV_SKIP_ANIMATIONS, false);
-	 * ```
-	 */
-	setDevData(key, value) {
-		if (!dev) return;
-		this.#devData.set(key, value);
-	}
-
-	/**
-	 * Get a dev data property value
-	 *
-	 * Automatically reactive - creates a dependency on this specific key.
-	 * Only available in dev mode - returns undefined in production.
-	 *
-	 * @param {string} key - Property key (use KEY_DEV_ constant)
-	 *
-	 * @returns {any} Property value or undefined
+	 * @returns {ReactiveDataStore} The dev data store
 	 *
 	 * @example
 	 * ```javascript
-	 * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+	 * const KEY_DEV_AUTO_NAV = 'dev-auto-navigation';
+	 *
+	 * // Set dev data (no-op in production)
+	 * machine.devData.set(KEY_DEV_AUTO_NAV, true);
 	 *
-	 * // Reactive - re-runs only when KEY_DEV_AUTO_NAVIGATION changes
+	 * // Get dev data (throws in production)
 	 * $effect(() => {
-	 *   const autoNav = machine.getDevData(KEY_DEV_AUTO_NAVIGATION);
-	 *   console.log('Auto-navigation:', autoNav);
+	 *   const autoNav = machine.devData.get(KEY_DEV_AUTO_NAV);
+	 *   console.log('Auto-nav:', autoNav);
 	 * });
-	 * ```
-	 */
-	getDevData(key) {
-		if (!dev) return undefined;
-		return this.#devData.get(key);
-	}
-
-	/**
-	 * Get all dev data properties as plain object
-	 *
-	 * Note: Returns a snapshot (plain object), not reactive.
-	 * Only available in dev mode - returns empty object in production.
-	 *
-	 * @returns {Record<string, any>} Plain object with all dev data
 	 *
-	 * @example
-	 * ```javascript
-	 * const allDevData = machine.getAllDevData();
-	 * console.log('Dev settings:', allDevData);
+	 * // Other operations
+	 * machine.devData.update({ [KEY_DEV_AUTO_NAV]: false });
+	 * machine.devData.has(KEY_DEV_AUTO_NAV);
+	 * machine.devData.delete(KEY_DEV_AUTO_NAV);
+	 * machine.devData.clear();
+	 * console.log(machine.devData.size);
 	 * ```
 	 */
-	getAllDevData() {
-		if (!dev) return {};
-		return Object.fromEntries(this.#devData);
-	}
-
-	/**
-	 * Update multiple dev data properties at once
-	 *
-	 * Each property update triggers fine-grained reactivity.
-	 * Only available in dev mode - no-op in production.
-	 *
-	 * @param {Record<string, any>} dataUpdates
-	 *   Object with key-value pairs (use KEY_DEV_ constants for keys)
-	 *
-	 * @example
-	 * ```javascript
-	 * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
-	 * const KEY_DEV_SKIP_ANIMATIONS = 'dev-skip-animations';
-	 *
-	 * machine.updateDevData({
-	 *   [KEY_DEV_AUTO_NAVIGATION]: true,
-	 *   [KEY_DEV_SKIP_ANIMATIONS]: false
-	 * });
-	 * ```
-	 */
-	updateDevData(dataUpdates) {
-		if (!dev) return;
-		for (const [key, value] of Object.entries(dataUpdates)) {
-			this.#devData.set(key, value);
-		}
-	}
-
-	/**
-	 * Delete a dev data property
-	 *
-	 * Only available in dev mode - no-op in production.
-	 *
-	 * @param {string} key - Property key to delete (use KEY_DEV_ constant)
-	 *
-	 * @returns {boolean} True if the key existed and was deleted
-	 *
-	 * @example
-	 * ```javascript
-	 * const KEY_DEV_TEMP_FLAG = 'dev-temp-flag';
-	 *
-	 * machine.deleteDevData(KEY_DEV_TEMP_FLAG);
-	 * ```
-	 */
-	deleteDevData(key) {
-		if (!dev) return false;
-		return this.#devData.delete(key);
-	}
-
-	/**
-	 * Check if dev data property exists
-	 *
-	 * Only available in dev mode - returns false in production.
-	 *
-	 * @param {string} key - Property key to check (use KEY_DEV_ constant)
-	 *
-	 * @returns {boolean} True if the key exists
-	 *
-	 * @example
-	 * ```javascript
-	 * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
-	 *
-	 * if (machine.hasDevData(KEY_DEV_AUTO_NAVIGATION)) {
-	 *   // Dev setting exists
-	 * }
-	 * ```
-	 */
-	hasDevData(key) {
-		if (!dev) return false;
-		return this.#devData.has(key);
-	}
-
-	/**
-	 * Clear all dev data properties
-	 *
-	 * Only available in dev mode - no-op in production.
-	 *
-	 * @example
-	 * ```javascript
-	 * machine.clearDevData();  // Reset all dev settings
-	 * ```
-	 */
-	clearDevData() {
-		if (!dev) return;
-		this.#devData.clear();
-	}
-
-	/**
-	 * Get number of dev data properties
-	 *
-	 * Only available in dev mode - returns 0 in production.
-	 *
-	 * @returns {number} Number of dev data entries
-	 */
-	get devDataSize() {
-		if (!dev) return 0;
-		return this.#devData.size;
+	get devData() {
+		return this.#devData;
 	}
 
 	/* ===== Visited Routes Tracking ===== */

package/dist/state/machines/page-machine/README.md

@@ -78,6 +78,10 @@ const KEY_TUTORIAL_SEEN = 'tutorial-seen';
 const KEY_HIGHEST_LEVEL = 'highest-level';
 const KEY_DIFFICULTY = 'difficulty';
 
+// Dev data keys (use KEY_DEV_ prefix)
+const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+const KEY_DEV_SKIP_ANIMATIONS = 'dev-skip-animations';
+
 export class PuzzleState extends PageMachine {
   #logic;
 
@@ -96,6 +100,10 @@ export class PuzzleState extends PageMachine {
         [KEY_TUTORIAL_SEEN]: false,
         [KEY_HIGHEST_LEVEL]: 1,
         [KEY_DIFFICULTY]: 'normal'
+      },
+      initialDevData: {
+        [KEY_DEV_AUTO_NAVIGATION]: false,
+        [KEY_DEV_SKIP_ANIMATIONS]: false
       }
     });
 
@@ -127,32 +135,32 @@ export class PuzzleState extends PageMachine {
     return this.current === ROUTE_COMPLETE;
   }
 
-  // Persistent settings/progress (use getData/setData)
+  // Persistent settings/progress (use machine.data)
   get hasSeenTutorial() {
-    return this.getData(KEY_TUTORIAL_SEEN) || false;
+    return this.data.get(KEY_TUTORIAL_SEEN) || false;
   }
 
   markTutorialComplete() {
-    this.setData(KEY_TUTORIAL_SEEN, true);
+    this.data.set(KEY_TUTORIAL_SEEN, true);
   }
 
   get highestLevel() {
-    return this.getData(KEY_HIGHEST_LEVEL) || 1;
+    return this.data.get(KEY_HIGHEST_LEVEL) || 1;
   }
 
   updateHighestLevel(level) {
     const current = this.highestLevel;
     if (level > current) {
-      this.setData(KEY_HIGHEST_LEVEL, level);
+      this.data.set(KEY_HIGHEST_LEVEL, level);
     }
   }
 
   get difficulty() {
-    return this.getData(KEY_DIFFICULTY) || 'normal';
+    return this.data.get(KEY_DIFFICULTY) || 'normal';
   }
 
   setDifficulty(level) {
-    this.setData(KEY_DIFFICULTY, level);
+    this.data.set(KEY_DIFFICULTY, level);
   }
 
   // Optional: Lifecycle methods
@@ -265,11 +273,25 @@ puzzleState.isStartPath(path)         // Check if path is start path
 puzzleState.isOnStartPath             // Check if on start path
 puzzleState.redirectToStartPath()     // Navigate to start path
 
-// Persistent data properties
-puzzleState.setData(KEY_NAME, value)
-puzzleState.getData(KEY_NAME)
-puzzleState.getAllData()
-puzzleState.updateData({ KEY1: val1, KEY2: val2 })
+// Persistent data properties (via ReactiveDataStore)
+puzzleState.data.set(KEY_NAME, value)
+puzzleState.data.get(KEY_NAME)
+puzzleState.data.getAll()
+puzzleState.data.update({ KEY1: val1, KEY2: val2 })
+puzzleState.data.has(KEY_NAME)
+puzzleState.data.delete(KEY_NAME)
+puzzleState.data.clear()
+puzzleState.data.size
+
+// Dev data properties (dev-only, via ReactiveDataStore)
+puzzleState.devData.set(KEY_DEV_NAME, value)
+puzzleState.devData.get(KEY_DEV_NAME)
+puzzleState.devData.getAll()
+puzzleState.devData.update({ KEY1: val1 })
+puzzleState.devData.has(KEY_DEV_NAME)
+puzzleState.devData.delete(KEY_DEV_NAME)
+puzzleState.devData.clear()
+puzzleState.devData.size
 
 // Visited routes tracking
 puzzleState.hasVisited(route)         // e.g., hasVisited('/puzzle/intro')
@@ -288,9 +310,9 @@ puzzleState.hasSeenTutorial
 
 ## Data Storage Guidelines
 
-### When to use `getData/setData` (PageMachine)
+### When to use `machine.data` (ReactiveDataStore)
 
-Use PageMachine's data properties for **persistent settings and progress**:
+Use PageMachine's data store for **persistent settings and progress**:
 
 - ✅ Tutorial completion flags
 - ✅ User preferences (difficulty, language, sound)
@@ -311,13 +333,39 @@ const KEY_DIFFICULTY = 'difficulty';
 const KEY_HIGHEST_LEVEL = 'highest-level';
 
 // Use constants (not strings!)
-pageMachine.setData(KEY_TUTORIAL_SEEN, true);       // ✅ Good
-pageMachine.setData(KEY_DIFFICULTY, 'hard');        // ✅ Good
-pageMachine.setData(KEY_HIGHEST_LEVEL, 5);          // ✅ Good
+pageMachine.data.set(KEY_TUTORIAL_SEEN, true);       // ✅ Good
+pageMachine.data.set(KEY_DIFFICULTY, 'hard');        // ✅ Good
+pageMachine.data.set(KEY_HIGHEST_LEVEL, 5);          // ✅ Good
 
 // DON'T use magic strings
-pageMachine.setData('tutorial-seen', true);         // ❌ Avoid
-pageMachine.setData('TUTORIAL_SEEN', true);         // ❌ Avoid
+pageMachine.data.set('tutorial-seen', true);         // ❌ Avoid
+pageMachine.data.set('TUTORIAL_SEEN', true);         // ❌ Avoid
+```
+
+### When to use `machine.devData` (Dev-only ReactiveDataStore)
+
+Use PageMachine's devData store for **development helpers**:
+
+- ✅ Auto-navigation flags
+- ✅ Skip animations/delays
+- ✅ Mock API endpoints
+- ✅ Debug mode flags
+- ✅ Development-only settings
+
+**IMPORTANT**: Use KEY_DEV_ prefix for dev data constants:
+
+```javascript
+// Define constants (at top of file)
+const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+const KEY_DEV_SKIP_ANIMATIONS = 'dev-skip-animations';
+const KEY_DEV_MOCK_API = 'dev-mock-api';
+
+// Use in development (no-op in production)
+pageMachine.devData.set(KEY_DEV_AUTO_NAVIGATION, true);    // ✅ Good
+pageMachine.devData.set(KEY_DEV_SKIP_ANIMATIONS, false);   // ✅ Good
+
+// Reading in production throws error (programming bug)
+const autoNav = pageMachine.devData.get(KEY_DEV_AUTO_NAVIGATION);
 ```
 
 ### When to use GameLogic with `$state`
@@ -350,6 +398,17 @@ export class PuzzleGameLogic {
 - Routes are the source of truth (no state abstraction layer)
 - Use route constants for clarity and maintainability
 - Always sync in `$effect` watching `$page.url.pathname`
-- Use constants for data keys (e.g., `KEY_TUTORIAL_SEEN`)
+- Use constants for data keys (e.g., `KEY_TUTORIAL_SEEN`, `KEY_DEV_AUTO_NAV`)
 - Separate persistent data (PageMachine) from reactive state (GameLogic)
 - Handle animations in pages using `$effect` or `onMount`
+- Data and devData use [ReactiveDataStore](../../classes/reactive-data-store/README.md)
+  for fine-grained reactivity
+- Access data via read-only getters: `machine.data.get()`, `machine.devData.set()`
+
+## See Also
+
+- [ReactiveDataStore](../../classes/reactive-data-store/README.md) - The
+  underlying reactive data storage implementation
+- [FiniteStateMachine](../finite-state-machine/README.md) - For enforced state
+  transitions
+- [State Context](../../context/README.md) - For providing state to components