@hkdigital/lib-core 0.5.88 → 0.5.90

package/dist/state/classes/reactive-data-store/ReactiveDataStore.svelte.d.ts

@@ -0,0 +1,152 @@
+export default class ReactiveDataStore {
+    /**
+     * Constructor
+     *
+     * @param {Object} [options]
+     * @param {Record<string, any>} [options.initialData={}]
+     *   Initial key-value pairs
+     * @param {boolean} [options.strictMode=true]
+     *   Throw error when accessing uninitialized keys
+     * @param {boolean} [options.productionGuard=false]
+     *   Dev-only mode: no-op on SET, throw on GET in production
+     * @param {string} [options.errorPrefix='Data key']
+     *   Prefix for error messages
+     */
+    constructor({ initialData, strictMode, productionGuard, errorPrefix }?: {
+        initialData?: Record<string, any> | undefined;
+        strictMode?: boolean | undefined;
+        productionGuard?: boolean | undefined;
+        errorPrefix?: string | undefined;
+    });
+    /**
+     * Set a data property value
+     *
+     * Automatically reactive - effects watching this key will re-run.
+     * Uses fine-grained reactivity via SvelteMap.
+     *
+     * With productionGuard: silent no-op in production (safe to call)
+     *
+     * @param {string} key - Property key
+     * @param {any} value - Property value
+     *
+     * @example
+     * ```javascript
+     * store.set('score', 100);
+     * store.set('playerName', 'Alice');
+     * ```
+     */
+    set(key: string, value: any): void;
+    /**
+     * Get a data property value
+     *
+     * Automatically reactive - creates a dependency on this specific key.
+     * The effect will only re-run when THIS key changes.
+     *
+     * With strictMode: throws if key is not initialized
+     * With productionGuard: throws in production (programming error)
+     *
+     * @param {string} key - Property key
+     *
+     * @returns {any} Property value
+     *
+     * @throws {Error} If key not initialized (strictMode)
+     * @throws {Error} If accessed in production (productionGuard)
+     *
+     * @example
+     * ```javascript
+     * // Reactive - re-runs only when 'score' changes
+     * $effect(() => {
+     *   const score = store.get('score');
+     *   console.log('Score:', score);
+     * });
+     * ```
+     */
+    get(key: string): any;
+    /**
+     * Get all data properties as plain object
+     *
+     * Note: Returns a snapshot (plain object), not reactive.
+     * Use for serialization or inspection, not for reactive tracking.
+     *
+     * @returns {Record<string, any>} Plain object with all data
+     *
+     * @example
+     * ```javascript
+     * const allData = store.getAll();
+     * await saveToServer(allData);
+     * ```
+     */
+    getAll(): Record<string, any>;
+    /**
+     * Update multiple data properties at once
+     *
+     * Each property update triggers fine-grained reactivity.
+     * Only effects watching the specific changed keys will re-run.
+     *
+     * @param {Record<string, any>} updates
+     *   Object with key-value pairs to update
+     *
+     * @example
+     * ```javascript
+     * store.update({
+     *   score: 100,
+     *   level: 5,
+     *   completed: true
+     * });
+     * ```
+     */
+    update(updates: Record<string, any>): void;
+    /**
+     * Delete a data property
+     *
+     * @param {string} key - Property key to delete
+     *
+     * @returns {boolean} True if the key existed and was deleted
+     *
+     * @example
+     * ```javascript
+     * store.delete('temporaryFlag');
+     * ```
+     */
+    delete(key: string): boolean;
+    /**
+     * Check if data property exists
+     *
+     * With productionGuard: throws in production (same as get)
+     *
+     * @param {string} key - Property key to check
+     *
+     * @returns {boolean} True if the key exists
+     *
+     * @throws {Error} If accessed in production (productionGuard)
+     *
+     * @example
+     * ```javascript
+     * if (store.has('tutorialSeen')) {
+     *   // Skip tutorial
+     * }
+     * ```
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all data properties
+     *
+     * @example
+     * ```javascript
+     * store.clear();  // Reset all data
+     * ```
+     */
+    clear(): void;
+    /**
+     * Get number of data properties
+     *
+     * @returns {number} Number of data entries
+     *
+     * @example
+     * ```javascript
+     * console.log(`Store has ${store.size} entries`);
+     * ```
+     */
+    get size(): number;
+    #private;
+}

package/dist/state/classes/reactive-data-store/ReactiveDataStore.svelte.js

@@ -0,0 +1,300 @@
+/**
+ * Reactive key-value data store with fine-grained reactivity
+ *
+ * Built on SvelteMap for fine-grained reactivity where effects only re-run
+ * when the specific keys they access change.
+ *
+ * Features:
+ * - Fine-grained reactivity using SvelteMap
+ * - Strict mode: throws on access to uninitialized keys
+ * - Production guard: dev-only data throws on read in production
+ * - Initialization from plain object
+ *
+ * @example
+ * ```javascript
+ * // Regular data store
+ * const store = new ReactiveDataStore({
+ *   initialData: { score: 0, level: 1 }
+ * });
+ *
+ * store.set('score', 100);
+ * const score = store.get('score');  // Reactive access
+ *
+ * // Dev-only data store
+ * const devStore = new ReactiveDataStore({
+ *   initialData: { autoNav: false },
+ *   productionGuard: true,
+ *   errorPrefix: 'Dev data key'
+ * });
+ *
+ * devStore.set('autoNav', true);  // No-op in production
+ * devStore.get('autoNav');        // Throws in production
+ * ```
+ */
+
+import { SvelteMap } from 'svelte/reactivity';
+import { dev } from '$app/environment';
+
+export default class ReactiveDataStore {
+  /**
+   * Internal reactive map
+   * @type {SvelteMap<string, any>}
+   */
+  #data;
+
+  /**
+   * Throw on access to uninitialized keys
+   * @type {boolean}
+   */
+  #strictMode;
+
+  /**
+   * Guard against production access (for dev-only data)
+   * @type {boolean}
+   */
+  #productionGuard;
+
+  /**
+   * Prefix for error messages
+   * @type {string}
+   */
+  #errorPrefix;
+
+  /**
+   * Constructor
+   *
+   * @param {Object} [options]
+   * @param {Record<string, any>} [options.initialData={}]
+   *   Initial key-value pairs
+   * @param {boolean} [options.strictMode=true]
+   *   Throw error when accessing uninitialized keys
+   * @param {boolean} [options.productionGuard=false]
+   *   Dev-only mode: no-op on SET, throw on GET in production
+   * @param {string} [options.errorPrefix='Data key']
+   *   Prefix for error messages
+   */
+  constructor({
+    initialData = {},
+    strictMode = true,
+    productionGuard = false,
+    errorPrefix = 'Data key'
+  } = {}) {
+    this.#strictMode = strictMode;
+    this.#productionGuard = productionGuard;
+    this.#errorPrefix = errorPrefix;
+
+    // Initialize map
+    this.#data = new SvelteMap();
+
+    // Only populate initial data in dev mode if guard is enabled
+    if (!productionGuard || dev) {
+      for (const [key, value] of Object.entries(initialData)) {
+        this.#data.set(key, value);
+      }
+    }
+  }
+
+  /**
+   * Set a data property value
+   *
+   * Automatically reactive - effects watching this key will re-run.
+   * Uses fine-grained reactivity via SvelteMap.
+   *
+   * With productionGuard: silent no-op in production (safe to call)
+   *
+   * @param {string} key - Property key
+   * @param {any} value - Property value
+   *
+   * @example
+   * ```javascript
+   * store.set('score', 100);
+   * store.set('playerName', 'Alice');
+   * ```
+   */
+  set(key, value) {
+    // Production guard: no-op silently (safe to call conditionally)
+    if (this.#productionGuard && !dev) {
+      return;
+    }
+
+    this.#data.set(key, value);
+  }
+
+  /**
+   * Get a data property value
+   *
+   * Automatically reactive - creates a dependency on this specific key.
+   * The effect will only re-run when THIS key changes.
+   *
+   * With strictMode: throws if key is not initialized
+   * With productionGuard: throws in production (programming error)
+   *
+   * @param {string} key - Property key
+   *
+   * @returns {any} Property value
+   *
+   * @throws {Error} If key not initialized (strictMode)
+   * @throws {Error} If accessed in production (productionGuard)
+   *
+   * @example
+   * ```javascript
+   * // Reactive - re-runs only when 'score' changes
+   * $effect(() => {
+   *   const score = store.get('score');
+   *   console.log('Score:', score);
+   * });
+   * ```
+   */
+  get(key) {
+    // Production guard: THROW on read in production
+    if (this.#productionGuard && !dev) {
+      throw new Error(
+        `${this.#errorPrefix} "${key}" accessed in production. ` +
+        `This data is only available in development mode.`
+      );
+    }
+
+    // Strict mode: validate key exists
+    if (this.#strictMode && !this.#data.has(key)) {
+      throw new Error(
+        `${this.#errorPrefix} "${key}" is not initialized.`
+      );
+    }
+
+    return this.#data.get(key);
+  }
+
+  /**
+   * Get all data properties as plain object
+   *
+   * Note: Returns a snapshot (plain object), not reactive.
+   * Use for serialization or inspection, not for reactive tracking.
+   *
+   * @returns {Record<string, any>} Plain object with all data
+   *
+   * @example
+   * ```javascript
+   * const allData = store.getAll();
+   * await saveToServer(allData);
+   * ```
+   */
+  getAll() {
+    if (this.#productionGuard && !dev) {
+      return {};
+    }
+
+    return Object.fromEntries(this.#data);
+  }
+
+  /**
+   * Update multiple data properties at once
+   *
+   * Each property update triggers fine-grained reactivity.
+   * Only effects watching the specific changed keys will re-run.
+   *
+   * @param {Record<string, any>} updates
+   *   Object with key-value pairs to update
+   *
+   * @example
+   * ```javascript
+   * store.update({
+   *   score: 100,
+   *   level: 5,
+   *   completed: true
+   * });
+   * ```
+   */
+  update(updates) {
+    if (this.#productionGuard && !dev) {
+      return;
+    }
+
+    for (const [key, value] of Object.entries(updates)) {
+      this.#data.set(key, value);
+    }
+  }
+
+  /**
+   * Delete a data property
+   *
+   * @param {string} key - Property key to delete
+   *
+   * @returns {boolean} True if the key existed and was deleted
+   *
+   * @example
+   * ```javascript
+   * store.delete('temporaryFlag');
+   * ```
+   */
+  delete(key) {
+    if (this.#productionGuard && !dev) {
+      return false;
+    }
+
+    return this.#data.delete(key);
+  }
+
+  /**
+   * Check if data property exists
+   *
+   * With productionGuard: throws in production (same as get)
+   *
+   * @param {string} key - Property key to check
+   *
+   * @returns {boolean} True if the key exists
+   *
+   * @throws {Error} If accessed in production (productionGuard)
+   *
+   * @example
+   * ```javascript
+   * if (store.has('tutorialSeen')) {
+   *   // Skip tutorial
+   * }
+   * ```
+   */
+  has(key) {
+    // Production guard: THROW on read in production
+    if (this.#productionGuard && !dev) {
+      throw new Error(
+        `${this.#errorPrefix} "${key}" existence check in production. ` +
+        `This data is only available in development mode.`
+      );
+    }
+
+    return this.#data.has(key);
+  }
+
+  /**
+   * Clear all data properties
+   *
+   * @example
+   * ```javascript
+   * store.clear();  // Reset all data
+   * ```
+   */
+  clear() {
+    if (this.#productionGuard && !dev) {
+      return;
+    }
+
+    this.#data.clear();
+  }
+
+  /**
+   * Get number of data properties
+   *
+   * @returns {number} Number of data entries
+   *
+   * @example
+   * ```javascript
+   * console.log(`Store has ${store.size} entries`);
+   * ```
+   */
+  get size() {
+    if (this.#productionGuard && !dev) {
+      return 0;
+    }
+
+    return this.#data.size;
+  }
+}

package/dist/state/classes.d.ts

@@ -1 +1,2 @@
 export { default as SubscribersCount } from "./classes/subscribers-count/SubscribersCount.js";
+export { default as ReactiveDataStore } from "./classes/reactive-data-store/ReactiveDataStore.svelte.js";

package/dist/state/classes.js

@@ -1 +1,2 @@
 export { default as SubscribersCount } from './classes/subscribers-count/SubscribersCount.js';
+export { default as ReactiveDataStore } from './classes/reactive-data-store/ReactiveDataStore.svelte.js';

package/dist/state/machines/page-machine/PageMachine.svelte.d.ts

@@ -9,6 +9,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)
      *
@@ -17,6 +19,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,
@@ -24,14 +27,18 @@ export default class PageMachine {
      *   initialData: {
      *     [KEY_INTRO_COMPLETED]: false,
      *     [KEY_SCORE]: 0
+     *   },
+     *   initialDevData: {
+     *     [KEY_DEV_AUTO_NAVIGATION]: false
      *   }
      * });
      * ```
      */
-    constructor({ startPath, routes, initialData, logger }: {
+    constructor({ startPath, routes, initialData, initialDevData, logger }: {
         startPath: string;
         routes?: string[] | undefined;
         initialData?: Record<string, any> | undefined;
+        initialDevData?: Record<string, any> | undefined;
         logger?: import("../../../logging/client.js").Logger | undefined;
     });
     /**
@@ -63,264 +70,69 @@ export default class PageMachine {
      */
     get routes(): string[];
     /**
-     * Set a data property value
+     * Get the reactive data store
      *
-     * Automatically reactive - effects watching this key will re-run.
-     * Uses fine-grained reactivity, so only effects watching this specific
-     * key will be triggered.
+     * Provides read-only access to the data store instance.
+     * Access all data methods through this property.
      *
-     * @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: string, value: any): void;
-    /**
-     * Get a data property value
-     *
-     * Automatically reactive - creates a dependency on this specific key.
-     * The effect will only re-run when THIS key changes, not when other
-     * keys change.
-     *
-     * @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: string): any;
-    /**
-     * 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);
+     * // 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);
      * ```
      */
-    getAllData(): Record<string, any>;
+    get data(): ReactiveDataStore;
     /**
-     * Update multiple data properties at once
+     * Get the reactive dev data store
      *
-     * Each property update triggers fine-grained reactivity.
+     * Provides read-only access to the dev data store instance.
+     * Access all dev data methods through this property.
      *
-     * @param {Record<string, any>} dataUpdates
-     *   Object with key-value pairs (use KEY_ constants for keys)
+     * 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_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: Record<string, any>): void;
-    /**
-     * Delete a data property
-     *
-     * @param {string} key - Property key to delete (use KEY_ constant)
-     *
-     * @returns {boolean} True if the key existed and was deleted
+     * @returns {ReactiveDataStore} The dev data store
      *
      * @example
      * ```javascript
-     * const KEY_TEMPORARY_FLAG = 'temporary-flag';
+     * const KEY_DEV_AUTO_NAV = 'dev-auto-navigation';
      *
-     * machine.deleteData(KEY_TEMPORARY_FLAG);
-     * ```
-     */
-    deleteData(key: string): boolean;
-    /**
-     * 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: string): boolean;
-    /**
-     * Clear all data properties
-     *
-     * @example
-     * ```javascript
-     * machine.clearData();  // Reset all game data
-     * ```
-     */
-    clearData(): void;
-    /**
-     * Get number of data properties
-     *
-     * @returns {number} Number of data entries
-     */
-    get dataSize(): number;
-    /**
-     * Set a dev data property value
-     *
-     * Automatically reactive - effects watching this key will re-run.
-     * Only available in dev mode - no-op in production.
-     *
-     * @param {string} key - Property key (use KEY_DEV_ constant)
-     * @param {any} value - Property value
-     *
-     * @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: string, value: any): void;
-    /**
-     * Get a dev data property value
+     * // Set dev data (no-op in production)
+     * machine.devData.set(KEY_DEV_AUTO_NAV, true);
      *
-     * 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
-     *
-     * @example
-     * ```javascript
-     * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
-     *
-     * // 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: string): any;
-    /**
-     * 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);
-     * ```
-     */
-    getAllDevData(): Record<string, any>;
-    /**
-     * 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: Record<string, any>): void;
-    /**
-     * 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);
+     * // 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);
      * ```
      */
-    deleteDevData(key: string): boolean;
-    /**
-     * 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: string): boolean;
-    /**
-     * Clear all dev data properties
-     *
-     * Only available in dev mode - no-op in production.
-     *
-     * @example
-     * ```javascript
-     * machine.clearDevData();  // Reset all dev settings
-     * ```
-     */
-    clearDevData(): void;
-    /**
-     * Get number of dev data properties
-     *
-     * Only available in dev mode - returns 0 in production.
-     *
-     * @returns {number} Number of dev data entries
-     */
-    get devDataSize(): number;
+    get devData(): ReactiveDataStore;
     /**
      * Check if a route has been visited
      *
@@ -425,3 +237,4 @@ export default class PageMachine {
     redirectToStartPath(): void;
     #private;
 }
+import { ReactiveDataStore } from '../../classes.js';

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
       }
     });
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.5.88",
+	"version": "0.5.90",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"

package/dist/state/classes/subscribers-count/index.d.ts

@@ -1 +0,0 @@
-export { default as SubScribersCount } from "./SubscribersCount.js";

package/dist/state/classes/subscribers-count/index.js

@@ -1 +0,0 @@
-export { default as SubScribersCount } from './SubscribersCount.js';