@hkdigital/lib-core 0.5.44 → 0.5.45

package/dist/state/context/README.md

@@ -0,0 +1,226 @@
+# RouteStateContext
+
+Base class for route-level state containers.
+
+## How it connects
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ PuzzleState (extends RouteStateContext)                 │
+│ - Container for route-level concerns                    │
+│ - Contains PageMachine instance                         │
+│ - Optional: services, preload, reset, etc.              │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 │ Provided via Svelte context
+                 │
+┌────────────────▼────────────────────────────────────────┐
+│ +layout.svelte                                          │
+│ - Creates state with createOrGetPuzzleState()           │
+│ - IMPORTANT: Syncs URL with pageMachine.syncFromPath()  │
+│ - Optional: Calls validateAndRedirect() for protection  │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 │ Context available to children
+                 │
+        ┌────────┴─────────┬────────────────┐
+        ▼                  ▼                ▼
+  ┌──────────┐      ┌──────────┐    ┌──────────┐
+  │ +page    │      │ +page    │    │ Component│
+  │ .svelte  │      │ .svelte  │    │          │
+  └──────────┘      └──────────┘    └──────────┘
+  Gets state via getPuzzleState()
+```
+
+## Main Purposes
+
+1. **State container** - Hold route-level concerns in one place
+2. **Apply enforceStartPath** - Control navigation flow (users must visit
+   start path before accessing subroutes)
+3. **Provide validateAndRedirect** - Route protection via layout
+
+## Key Features
+
+- Share state between layout and pages without prop drilling
+- Persist state across navigation within the same route group
+- Lifecycle methods for setup/teardown (preload, reset)
+
+## Basic Usage
+
+### 1. Create state container class
+
+```javascript
+// routes/puzzle/puzzle.state.svelte.js
+import { defineStateContext } from '@hkdigital/lib-core/state/context.js';
+import { RouteStateContext } from '$lib/state/context.js';
+import PuzzlePageMachine from './puzzle.machine.svelte.js';
+
+export class PuzzleState extends RouteStateContext {
+  #pageMachine;
+
+  constructor() {
+    super({
+      startPath: '/puzzle',
+      enforceStartPath: true  // Optional: enforce route protection
+    });
+    this.#pageMachine = new PuzzlePageMachine();
+  }
+
+  get pageMachine() {
+    return this.#pageMachine;
+  }
+
+  // Optional: Service accessors
+  getPuzzleService() {
+    return getPuzzleService();
+  }
+
+  // Optional: Lifecycle methods
+  preload(onProgress) {
+    return loadPuzzleAssets(onProgress);
+  }
+
+  reset() {
+    // Reset state when needed
+  }
+}
+
+// Export helper functions
+export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
+  defineStateContext(PuzzleState);
+```
+
+### 2. Provide context in layout
+
+```svelte
+<!-- routes/puzzle/+layout.svelte -->
+<script>
+  import { page } from '$app/stores';
+  import { createOrGetPuzzleState } from './puzzle.state.svelte.js';
+
+  // Create or get existing state container
+  const puzzleState = createOrGetPuzzleState();
+
+  // IMPORTANT: Sync URL with PageMachine state
+  $effect(() => {
+    puzzleState.pageMachine.syncFromPath($page.url.pathname);
+  });
+
+  // Optional: Enforce start path (redirect if user skips intro)
+  $effect(() => {
+    puzzleState.validateAndRedirect($page.url.pathname);
+  });
+
+  // Optional: Preload assets
+  puzzleState.preload((progress) => {
+    console.log('Loading:', progress);
+  });
+</script>
+
+<slot />
+```
+
+### 3. Consume context in pages
+
+```svelte
+<!-- routes/puzzle/level1/+page.svelte -->
+<script>
+  import { getPuzzleState } from '../puzzle.state.svelte.js';
+
+  const puzzleState = getPuzzleState();
+  const pageMachine = puzzleState.pageMachine;
+</script>
+
+<div>Current state: {pageMachine.current}</div>
+```
+
+## Context Helpers
+
+The `defineStateContext` helper creates three functions:
+
+```javascript
+// Get existing or create new (use in layout)
+const state = createOrGetPuzzleState();
+
+// Force create new instance
+const state = createPuzzleState();
+
+// Get existing (throws if not found, use in pages/components)
+const state = getPuzzleState();
+```
+
+## Constructor Options
+
+```javascript
+constructor({ startPath, enforceStartPath })
+```
+
+- `startPath` **(required)** - The start path for this route
+  (e.g., `/puzzle`)
+- `enforceStartPath` **(optional, default: false)** - If true, users must
+  visit the start path before accessing subroutes
+
+## validateAndRedirect Method
+
+Automatically redirects users if they try to access subroutes before visiting
+the start path.
+
+**How it works:**
+- If `enforceStartPath: true` is set in constructor
+- User tries to access a subroute (e.g., `/puzzle/level2`)
+- But hasn't visited the start path yet (`/puzzle`)
+- → Automatically redirects to start path
+
+**Example use case:** Puzzle game where users must see the intro before
+accessing puzzle levels.
+
+```javascript
+// In state constructor
+export class PuzzleState extends RouteStateContext {
+  constructor() {
+    super({
+      startPath: '/puzzle',
+      enforceStartPath: true
+    });
+  }
+}
+```
+
+```svelte
+<!-- In +layout.svelte -->
+<script>
+  import { page } from '$app/stores';
+
+  const puzzleState = createOrGetPuzzleState();
+
+  // Enforce route protection
+  $effect(() => {
+    puzzleState.validateAndRedirect($page.url.pathname);
+  });
+</script>
+```
+
+**Result:** If user navigates directly to `/puzzle/level2`, they'll be
+redirected to `/puzzle` first. After visiting `/puzzle`, they can freely
+navigate to any subroute.
+
+**Custom redirect URL:**
+```javascript
+// Redirect to a different URL instead of startPath
+puzzleState.validateAndRedirect($page.url.pathname, '/puzzle/welcome');
+```
+
+## Separation of Concerns
+
+**State Container** = Route-level concerns (MULTIPLE responsibilities)
+- PageMachine instance
+- Game engines
+- Service accessors
+- Media preloading
+- Any other route-level concern
+
+**PageMachine** = Page/view state ONLY (SINGLE responsibility)
+- Current page state
+- Route mapping
+- Visited states
+- Computed properties for state checks

package/dist/state/context/RouteStateContext.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Base class for route state containers
+ *
+ * Main purposes:
+ * - Container for route-level concerns (PageMachine, services, engines)
+ * - Apply enforceStartPath to control navigation flow
+ * - Provide validateAndRedirect for route protection
+ *
+ * @example
+ * ```javascript
+ * export class PuzzleState extends RouteStateContext {
+ *   constructor() {
+ *     super({
+ *       startPath: '/puzzle',
+ *       enforceStartPath: true
+ *     });
+ *   }
+ *
+ *   preload(onProgress) {
+ *     return loadAudioAndVideoScenes(onProgress);
+ *   }
+ * }
+ * ```
+ */
+export default class RouteStateContext {
+    /**
+     * @param {Object} options - Configuration options
+     * @param {string} options.startPath - Start path for this route (required)
+     * @param {boolean} [options.enforceStartPath=false] - If true, redirect to start path before allowing subroutes
+     */
+    constructor({ startPath, enforceStartPath }: {
+        startPath: string;
+        enforceStartPath?: boolean | undefined;
+    });
+    /**
+     * Validate current path and redirect if needed
+     * Call this in a $effect in the layout
+     *
+     * @param {string} currentPath - Current URL pathname
+     * @param {string} [redirectUrl] - Optional redirect URL (defaults to startPath)
+     */
+    validateAndRedirect(currentPath: string, redirectUrl?: string): void;
+    #private;
+}

package/dist/state/context/RouteStateContext.svelte.js

@@ -0,0 +1,119 @@
+import { goto } from '$app/navigation';
+
+/**
+ * Base class for route state containers
+ *
+ * Main purposes:
+ * - Container for route-level concerns (PageMachine, services, engines)
+ * - Apply enforceStartPath to control navigation flow
+ * - Provide validateAndRedirect for route protection
+ *
+ * @example
+ * ```javascript
+ * export class PuzzleState extends RouteStateContext {
+ *   constructor() {
+ *     super({
+ *       startPath: '/puzzle',
+ *       enforceStartPath: true
+ *     });
+ *   }
+ *
+ *   preload(onProgress) {
+ *     return loadAudioAndVideoScenes(onProgress);
+ *   }
+ * }
+ * ```
+ */
+export default class RouteStateContext {
+	/**
+	 * Start path for this route
+	 * @type {string}
+	 */
+	#startPath;
+
+	/**
+	 * Whether to enforce that users visit start path before subroutes
+	 * @type {boolean}
+	 */
+	#enforceStartPath = false;
+
+	/**
+	 * Track which paths have been visited during this session
+	 * Used for enforceStartPath validation
+	 * @type {Set<string>}
+	 */
+	// eslint-disable-next-line svelte/prefer-svelte-reactivity
+	#visitedPaths = new Set();
+
+	/**
+	 * @param {Object} options - Configuration options
+	 * @param {string} options.startPath - Start path for this route (required)
+	 * @param {boolean} [options.enforceStartPath=false] - If true, redirect to start path before allowing subroutes
+	 */
+	constructor({ startPath, enforceStartPath = false }) {
+		if (!startPath) {
+			throw new Error(
+				'RouteStateContext requires startPath parameter'
+			);
+		}
+
+		this.#startPath = startPath;
+		this.#enforceStartPath = enforceStartPath;
+	}
+
+	/**
+	 * Determine if current path needs redirection
+	 * Private method - enforces sequential access to subroutes
+	 *
+	 * @param {string} currentPath - Current URL pathname
+	 *
+	 * @returns {string|null}
+	 *   Path to redirect to, or null if no redirect needed
+	 */
+	#determineRedirect(currentPath) {
+		// No enforcement configured
+		if (!this.#enforceStartPath) {
+			return null;
+		}
+
+		// Currently on the start path - mark as visited and allow
+		if (currentPath === this.#startPath) {
+			this.#visitedPaths.add(currentPath);
+			return null;
+		}
+
+		// On a subroute - check if start path was visited
+		if (currentPath.startsWith(this.#startPath + '/')) {
+			// Allow if user has visited the start path
+			if (this.#visitedPaths.has(this.#startPath)) {
+				return null;
+			}
+			// Redirect to start path if not visited yet
+			return this.#startPath;
+		}
+
+		// Path is valid (not a subroute)
+		return null;
+	}
+
+	/**
+	 * Validate current path and redirect if needed
+	 * Call this in a $effect in the layout
+	 *
+	 * @param {string} currentPath - Current URL pathname
+	 * @param {string} [redirectUrl] - Optional redirect URL (defaults to startPath)
+	 */
+	validateAndRedirect(currentPath, redirectUrl = null) {
+		const redirectPath = this.#determineRedirect(currentPath);
+
+		if (redirectPath && redirectPath !== currentPath) {
+			const targetPath = redirectUrl || redirectPath;
+
+			console.debug(
+				`[${this.constructor.name}] Redirecting: ${currentPath} → ${targetPath}`
+			);
+
+			goto(targetPath, { replaceState: true });
+		}
+	}
+}

package/dist/state/context.d.ts

@@ -1 +1,2 @@
-export { defineStateContext, DEFAULT_CONTEXT_KEY } from "./context/state-context.js";
+export { default as RouteStateContext } from "./context/RouteStateContext.svelte.js";
+export { defineStateContext, DEFAULT_CONTEXT_KEY } from "./context/util.js";

package/dist/state/context.js

@@ -1 +1,2 @@
-export { defineStateContext, DEFAULT_CONTEXT_KEY } from './context/state-context.js';
+export { default as RouteStateContext } from './context/RouteStateContext.svelte.js';
+export { defineStateContext, DEFAULT_CONTEXT_KEY } from './context/util.js';

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

@@ -0,0 +1,195 @@
+/**
+ * Base class for page state machines with URL route mapping
+ *
+ * Simple state tracker that maps states to URL routes.
+ * Does NOT enforce FSM transitions - allows free navigation
+ * (because users can navigate to any URL via browser).
+ *
+ * Features:
+ * - State-to-route mapping and sync
+ * - Data properties for business/domain state
+ * - Visited states tracking
+ *
+ * Basic usage:
+ * ```javascript
+ * const machine = cityState.getOrCreatePageMachine('intro', IntroPageMachine);
+ *
+ * // Sync machine state with URL changes
+ * $effect(() => {
+ *   machine.syncFromPath($page.url.pathname);
+ * });
+ * ```
+ *
+ * With data properties (for business logic):
+ * ```javascript
+ * // Initialize with server data
+ * const initialData = {
+ *   HAS_STRONG_PROFILE: false,
+ *   PROFILE_COMPLETED: false,
+ *   MATCHED_SECTOR: null
+ * };
+ * const machine = new CircuitPageMachine(initialState, routeMap, initialData);
+ *
+ * // Read data
+ * if (machine.getData('HAS_STRONG_PROFILE')) {
+ *   // Show advanced content
+ * }
+ *
+ * // Update data (triggers reactivity)
+ * machine.setData('HAS_STRONG_PROFILE', true);
+ *
+ * // Check visited states
+ * if (machine.hasVisited(STATE_PROFILE)) {
+ *   // User has seen profile page before
+ * }
+ * ```
+ */
+export default class PageMachine {
+    /**
+     * Constructor
+     *
+     * @param {string} initialState - Initial state name
+     * @param {Record<string, string>} routeMap - Map of states to route paths
+     * @param {Record<string, any>} [initialData={}] - Initial data properties (from server)
+     *
+     * @example
+     * ```javascript
+     * const routeMap = {
+     *   [STATE_MATCH]: '/city/intro/match',
+     *   [STATE_CIRCUIT]: '/city/intro/racecircuit'
+     * };
+     *
+     * const initialData = {
+     *   INTRO_COMPLETED: false,
+     *   PROFILE_SCORE: 0
+     * };
+     *
+     * const machine = new CityIntroPageMachine(STATE_START, routeMap, initialData);
+     * ```
+     */
+    constructor(initialState: string, routeMap?: Record<string, string>, initialData?: Record<string, any>);
+    /**
+     * Synchronize machine state with URL path
+     *
+     * Call this in a $effect that watches $page.url.pathname
+     * Automatically tracks visited states
+     *
+     * @param {string} currentPath - Current URL pathname
+     *
+     * @returns {boolean} True if state was changed
+     */
+    syncFromPath(currentPath: string): boolean;
+    /**
+     * Set the current state directly
+     *
+     * @param {string} newState - Target state
+     */
+    setState(newState: string): void;
+    /**
+     * Get route path for a given state
+     *
+     * @param {string} state - State name
+     *
+     * @returns {string|null} Route path or null if no mapping
+     */
+    getPathForState(state: string): string | null;
+    /**
+     * Get route path for current state
+     *
+     * @returns {string|null} Route path or null if no mapping
+     */
+    getCurrentPath(): string | null;
+    /**
+     * Get current state
+     *
+     * @returns {string} Current state name
+     */
+    get current(): string;
+    /**
+     * Get the route map
+     *
+     * @returns {Record<string, string>} Copy of route map
+     */
+    get routeMap(): Record<string, string>;
+    /**
+     * Set a data property value
+     *
+     * @param {string} key - Property key
+     * @param {any} value - Property value
+     *
+     * @example
+     * ```javascript
+     * machine.setData('HAS_STRONG_PROFILE', true);
+     * machine.setData('PROFILE_SCORE', 85);
+     * ```
+     */
+    setData(key: string, value: any): void;
+    /**
+     * Get a data property value
+     *
+     * @param {string} key - Property key
+     *
+     * @returns {any} Property value or undefined
+     *
+     * @example
+     * ```javascript
+     * const hasProfile = machine.getData('HAS_STRONG_PROFILE');
+     * const score = machine.getData('PROFILE_SCORE');
+     * ```
+     */
+    getData(key: string): any;
+    /**
+     * Get all data properties
+     *
+     * @returns {Record<string, any>} Copy of all data
+     *
+     * @example
+     * ```javascript
+     * const allData = machine.getAllData();
+     * await playerService.saveData(allData);
+     * ```
+     */
+    getAllData(): Record<string, any>;
+    /**
+     * Update multiple data properties at once
+     *
+     * @param {Record<string, any>} dataUpdates - Object with key-value pairs
+     *
+     * @example
+     * ```javascript
+     * machine.updateData({
+     *   HAS_STRONG_PROFILE: true,
+     *   PROFILE_SCORE: 85,
+     *   MATCHED_SECTOR: 'technology'
+     * });
+     * ```
+     */
+    updateData(dataUpdates: Record<string, any>): void;
+    /**
+     * Check if a state has been visited
+     *
+     * @param {string} state - State name to check
+     *
+     * @returns {boolean} True if the state has been visited
+     *
+     * @example
+     * ```javascript
+     * if (machine.hasVisited(STATE_PROFILE)) {
+     *   // User has seen profile page, skip intro
+     * }
+     * ```
+     */
+    hasVisited(state: string): boolean;
+    /**
+     * Get all visited states
+     *
+     * @returns {string[]} Array of visited state names
+     */
+    getVisitedStates(): string[];
+    /**
+     * Reset visited states tracking
+     * Useful for testing or resetting experience
+     */
+    resetVisitedStates(): void;
+    #private;
+}

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

@@ -0,0 +1,337 @@
+/**
+ * Base class for page state machines with URL route mapping
+ *
+ * Simple state tracker that maps states to URL routes.
+ * Does NOT enforce FSM transitions - allows free navigation
+ * (because users can navigate to any URL via browser).
+ *
+ * Features:
+ * - State-to-route mapping and sync
+ * - Data properties for business/domain state
+ * - Visited states tracking
+ *
+ * Basic usage:
+ * ```javascript
+ * const machine = cityState.getOrCreatePageMachine('intro', IntroPageMachine);
+ *
+ * // Sync machine state with URL changes
+ * $effect(() => {
+ *   machine.syncFromPath($page.url.pathname);
+ * });
+ * ```
+ *
+ * With data properties (for business logic):
+ * ```javascript
+ * // Initialize with server data
+ * const initialData = {
+ *   HAS_STRONG_PROFILE: false,
+ *   PROFILE_COMPLETED: false,
+ *   MATCHED_SECTOR: null
+ * };
+ * const machine = new CircuitPageMachine(initialState, routeMap, initialData);
+ *
+ * // Read data
+ * if (machine.getData('HAS_STRONG_PROFILE')) {
+ *   // Show advanced content
+ * }
+ *
+ * // Update data (triggers reactivity)
+ * machine.setData('HAS_STRONG_PROFILE', true);
+ *
+ * // Check visited states
+ * if (machine.hasVisited(STATE_PROFILE)) {
+ *   // User has seen profile page before
+ * }
+ * ```
+ */
+export default class PageMachine {
+	/**
+	 * Current state
+	 * @type {string}
+	 */
+	// @ts-ignore
+	#current = $state();
+
+	/**
+	 * Map of states to route paths
+	 * @type {Record<string, string>}
+	 */
+	#routeMap = {};
+
+	/**
+	 * Reverse map of route paths to states
+	 * @type {Record<string, string>}
+	 */
+	#pathToStateMap = {};
+
+	/**
+	 * Data properties for business/domain state
+	 * Can be initialized from server and synced back
+	 * @type {Record<string, any>}
+	 */
+	#data = $state({});
+
+	/**
+	 * Track which states have been visited during this session
+	 * Useful for showing first-time hints/tips
+	 * @type {Set<string>}
+	 */
+	// eslint-disable-next-line svelte/prefer-svelte-reactivity
+	#visitedStates = new Set();
+
+	/**
+	 * Revision counter for triggering reactivity
+	 * @type {number}
+	 */
+	#revision = $state(0);
+
+	/**
+	 * Constructor
+	 *
+	 * @param {string} initialState - Initial state name
+	 * @param {Record<string, string>} routeMap - Map of states to route paths
+	 * @param {Record<string, any>} [initialData={}] - Initial data properties (from server)
+	 *
+	 * @example
+	 * ```javascript
+	 * const routeMap = {
+	 *   [STATE_MATCH]: '/city/intro/match',
+	 *   [STATE_CIRCUIT]: '/city/intro/racecircuit'
+	 * };
+	 *
+	 * const initialData = {
+	 *   INTRO_COMPLETED: false,
+	 *   PROFILE_SCORE: 0
+	 * };
+	 *
+	 * const machine = new CityIntroPageMachine(STATE_START, routeMap, initialData);
+	 * ```
+	 */
+	constructor(initialState, routeMap = {}, initialData = {}) {
+		this.#current = initialState;
+		this.#routeMap = routeMap;
+		this.#data = initialData;
+
+		// Build reverse map (path -> state)
+		for (const [state, path] of Object.entries(routeMap)) {
+			this.#pathToStateMap[path] = state;
+		}
+
+		// Mark initial state as visited
+		this.#visitedStates.add(initialState);
+	}
+
+	/**
+	 * Synchronize machine state with URL path
+	 *
+	 * Call this in a $effect that watches $page.url.pathname
+	 * Automatically tracks visited states
+	 *
+	 * @param {string} currentPath - Current URL pathname
+	 *
+	 * @returns {boolean} True if state was changed
+	 */
+	syncFromPath(currentPath) {
+		const targetState = this.#getStateFromPath(currentPath);
+
+		if (targetState && targetState !== this.#current) {
+			this.#current = targetState;
+			this.#visitedStates.add(targetState);
+			this.#revision++;
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Set the current state directly
+	 *
+	 * @param {string} newState - Target state
+	 */
+	setState(newState) {
+		if (newState !== this.#current) {
+			this.#current = newState;
+		}
+	}
+
+	/**
+	 * Get state name from URL path
+	 *
+	 * @param {string} path - URL pathname
+	 *
+	 * @returns {string|null} State name or null
+	 */
+	#getStateFromPath(path) {
+		// Try exact match first
+		if (this.#pathToStateMap[path]) {
+			return this.#pathToStateMap[path];
+		}
+
+		// Try partial match (path includes route)
+		for (const [routePath, state] of Object.entries(this.#pathToStateMap)) {
+			if (path.includes(routePath)) {
+				return state;
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Get route path for a given state
+	 *
+	 * @param {string} state - State name
+	 *
+	 * @returns {string|null} Route path or null if no mapping
+	 */
+	getPathForState(state) {
+		return this.#routeMap[state] || null;
+	}
+
+	/**
+	 * Get route path for current state
+	 *
+	 * @returns {string|null} Route path or null if no mapping
+	 */
+	getCurrentPath() {
+		return this.getPathForState(this.#current);
+	}
+
+	/**
+	 * Get current state
+	 *
+	 * @returns {string} Current state name
+	 */
+	get current() {
+		return this.#current;
+	}
+
+	/**
+	 * Get the route map
+	 *
+	 * @returns {Record<string, string>} Copy of route map
+	 */
+	get routeMap() {
+		return { ...this.#routeMap };
+	}
+
+	/* ===== Data Properties (Business/Domain State) ===== */
+
+	/**
+	 * Set a data property value
+	 *
+	 * @param {string} key - Property key
+	 * @param {any} value - Property value
+	 *
+	 * @example
+	 * ```javascript
+	 * machine.setData('HAS_STRONG_PROFILE', true);
+	 * machine.setData('PROFILE_SCORE', 85);
+	 * ```
+	 */
+	setData(key, value) {
+		this.#data[key] = value;
+		this.#revision++;
+	}
+
+	/**
+	 * Get a data property value
+	 *
+	 * @param {string} key - Property key
+	 *
+	 * @returns {any} Property value or undefined
+	 *
+	 * @example
+	 * ```javascript
+	 * const hasProfile = machine.getData('HAS_STRONG_PROFILE');
+	 * const score = machine.getData('PROFILE_SCORE');
+	 * ```
+	 */
+	getData(key) {
+		// Access revision to ensure reactivity
+		this.#revision;
+		return this.#data[key];
+	}
+
+	/**
+	 * Get all data properties
+	 *
+	 * @returns {Record<string, any>} Copy of all data
+	 *
+	 * @example
+	 * ```javascript
+	 * const allData = machine.getAllData();
+	 * await playerService.saveData(allData);
+	 * ```
+	 */
+	getAllData() {
+		// Access revision to ensure reactivity
+		this.#revision;
+		return { ...this.#data };
+	}
+
+	/**
+	 * Update multiple data properties at once
+	 *
+	 * @param {Record<string, any>} dataUpdates - Object with key-value pairs
+	 *
+	 * @example
+	 * ```javascript
+	 * machine.updateData({
+	 *   HAS_STRONG_PROFILE: true,
+	 *   PROFILE_SCORE: 85,
+	 *   MATCHED_SECTOR: 'technology'
+	 * });
+	 * ```
+	 */
+	updateData(dataUpdates) {
+		for (const [key, value] of Object.entries(dataUpdates)) {
+			this.#data[key] = value;
+		}
+		this.#revision++;
+	}
+
+	/* ===== Visited States Tracking ===== */
+
+	/**
+	 * Check if a state has been visited
+	 *
+	 * @param {string} state - State name to check
+	 *
+	 * @returns {boolean} True if the state has been visited
+	 *
+	 * @example
+	 * ```javascript
+	 * if (machine.hasVisited(STATE_PROFILE)) {
+	 *   // User has seen profile page, skip intro
+	 * }
+	 * ```
+	 */
+	hasVisited(state) {
+		// Access revision to ensure reactivity
+		this.#revision;
+		return this.#visitedStates.has(state);
+	}
+
+	/**
+	 * Get all visited states
+	 *
+	 * @returns {string[]} Array of visited state names
+	 */
+	getVisitedStates() {
+		// Access revision to ensure reactivity
+		this.#revision;
+		return Array.from(this.#visitedStates);
+	}
+
+	/**
+	 * Reset visited states tracking
+	 * Useful for testing or resetting experience
+	 */
+	resetVisitedStates() {
+		this.#visitedStates.clear();
+		this.#visitedStates.add(this.#current);
+		this.#revision++;
+	}
+}

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

@@ -0,0 +1,157 @@
+# PageMachine
+
+State machine for managing page view states with URL route mapping.
+
+## How it connects
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ MyFlowPageMachine (extends PageMachine)                 │
+│ - Maps states to URL routes                             │
+│ - Tracks current state and visited states               │
+│ - Provides computed properties (inIntro, inStep1, etc.) │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 │ Contained in state
+                 │
+┌────────────────▼────────────────────────────────────────┐
+│ MyFlowState (extends RouteStateContext)                 │
+│ get pageMachine() { return this.#pageMachine; }         │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 │ Context provided to layout
+                 │
+┌────────────────▼────────────────────────────────────────┐
+│ +layout.svelte                                          │
+│ IMPORTANT: Must sync URL with state:                    │
+│   $effect(() => {                                       │
+│     pageMachine.syncFromPath($page.url.pathname);       │
+│   });                                                   │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 │ Pages use machine state
+                 │
+        ┌────────┴─────────┬────────────────┐
+        ▼                  ▼                ▼
+  ┌──────────┐      ┌──────────┐    ┌──────────┐
+  │ +page    │      │ +page    │    │ Component│
+  │          │      │          │    │          │
+  └──────────┘      └──────────┘    └──────────┘
+  Access via: pageMachine.current, pageMachine.inIntro, etc.
+```
+
+## Main Purposes
+
+1. **Track current view/step** - Which page is active
+2. **Map states to URL paths** - Connect state names to routes
+3. **Sync with browser navigation** - Keep state in sync with URL
+4. **Track visited states** - Know which pages user has seen
+
+## Basic Usage
+
+### 1. Create a page machine class
+
+```javascript
+// my-flow.machine.svelte.js
+import PageMachine from '$lib/state/machines/PageMachine.svelte.js';
+
+export const STATE_INTRO = 'intro';
+export const STATE_STEP1 = 'step1';
+export const STATE_STEP2 = 'step2';
+
+export default class MyFlowPageMachine extends PageMachine {
+  constructor(initialData = {}) {
+    const routeMap = {
+      [STATE_INTRO]: '/my-flow/intro',
+      [STATE_STEP1]: '/my-flow/step1',
+      [STATE_STEP2]: '/my-flow/step2'
+    };
+
+    super(STATE_INTRO, routeMap, initialData);
+  }
+
+  // Computed properties for convenience
+  get inIntro() {
+    return this.current === STATE_INTRO;
+  }
+
+  get inStep1() {
+    return this.current === STATE_STEP1;
+  }
+}
+```
+
+### 2. Use in state container
+
+```javascript
+// my-flow.state.svelte.js
+import { RouteStateContext } from '$lib/state/context.js';
+import MyFlowPageMachine from './my-flow.machine.svelte.js';
+
+export class MyFlowState extends RouteStateContext {
+  #pageMachine;
+
+  constructor() {
+    super();
+    this.#pageMachine = new MyFlowPageMachine();
+  }
+
+  get pageMachine() {
+    return this.#pageMachine;
+  }
+}
+```
+
+### 3. Sync with route in +layout.svelte component
+
+**This is IMPORTANT for url path to be connected to the page machine**
+
+```svelte
+<script>
+  import { page } from '$app/stores';
+  import { getMyFlowState } from '../my-flow.state.svelte.js';
+
+  const flowState = getMyFlowState();
+  const pageMachine = flowState.pageMachine;
+
+  // Sync machine with URL changes
+  $effect(() => {
+    pageMachine.syncFromPath($page.url.pathname);
+  });
+</script>
+
+{#if pageMachine.inIntro}
+  <IntroView />
+{:else if pageMachine.inStep1}
+  <Step1View />
+{/if}
+```
+
+## Key Methods
+
+```javascript
+// Sync with URL path
+machine.syncFromPath(currentPath)
+
+// Get current state
+machine.current
+
+// Get route for state
+machine.getPathForState(stateName)
+
+// Data properties (for business logic)
+machine.setData('KEY', value)
+machine.getData('KEY')
+
+// Visited states tracking
+machine.hasVisited(stateName)
+machine.getVisitedStates()
+```
+
+## Important Notes
+
+- Not a finite state machine - allows free navigation
+- States map 1:1 with routes
+- Use state constants instead of magic strings
+- Always sync in `$effect` watching `$page.url.pathname`
+- Data properties are for business logic, not UI state

package/dist/state/machines.d.ts

@@ -1,2 +1,3 @@
 export * from "./machines/finite-state-machine/index.js";
 export * from "./machines/loading-state-machine/index.js";
+export { default as PageMachine } from "./machines/page-machine/PageMachine.svelte.js";

package/dist/state/machines.js

@@ -1,2 +1,4 @@
 export * from './machines/finite-state-machine/index.js';
 export * from './machines/loading-state-machine/index.js';
+
+export { default as PageMachine } from './machines/page-machine/PageMachine.svelte.js';

package/package.json

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