@hkdigital/lib-core 0.5.46 → 0.5.48

package/dist/state/context/README.md

@@ -1,68 +1,72 @@
-# RouteStateContext
+# State Context Utilities
 
-Base class for route-level state containers.
+Helper functions for managing Svelte context in route-level state containers.
 
-## How it connects
+## defineStateContext
 
+Creates context helper functions for a state container class.
+
+```javascript
+import { defineStateContext } from '@hkdigital/lib-core/state/context.js';
+
+class PuzzleState {
+  #pageMachine;
+
+  constructor() {
+    this.#pageMachine = new PuzzlePageMachine();
+  }
+
+  get pageMachine() {
+    return this.#pageMachine;
+  }
+}
+
+// Export helper functions
+export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
+  defineStateContext(PuzzleState);
 ```
-┌─────────────────────────────────────────────────────────┐
-│ 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()
+
+## Helper Functions
+
+The `defineStateContext` helper creates three functions:
+
+### createOrGetPuzzleState()
+
+Get existing instance or create new one. Use in `+layout.svelte`.
+
+```javascript
+// routes/puzzle/+layout.svelte
+const state = createOrGetPuzzleState();
 ```
 
-## Main Purposes
+### createPuzzleState()
 
-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
+Force create new instance (discards existing).
 
-## Key Features
+```javascript
+const state = createPuzzleState();
+```
 
-- 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)
+### getPuzzleState()
 
-## Basic Usage
+Get existing instance. Throws error if not found. Use in pages/components.
 
-### 1. Create state container class
+```javascript
+// routes/puzzle/level1/+page.svelte
+const state = getPuzzleState();
+```
+
+## Complete Example
 
 ```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 {
+export class PuzzleState {
   #pageMachine;
 
   constructor() {
-    super({
-      startPath: '/puzzle',
-      enforceStartPath: true  // Optional: enforce route protection
-    });
     this.#pageMachine = new PuzzlePageMachine();
   }
 
@@ -81,34 +85,26 @@ export class PuzzleState extends RouteStateContext {
   }
 
   reset() {
-    // Reset state when needed
+    this.#pageMachine = new PuzzlePageMachine();
   }
 }
 
-// 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();
+  const pageMachine = puzzleState.pageMachine;
 
   // 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);
+    pageMachine.syncFromPath($page.url.pathname);
   });
 
   // Optional: Preload assets
@@ -120,8 +116,6 @@ export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
 <slot />
 ```
 
-### 3. Consume context in pages
-
 ```svelte
 <!-- routes/puzzle/level1/+page.svelte -->
 <script>
@@ -134,81 +128,12 @@ export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
 <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.
+## Key Features
 
-**Custom redirect URL:**
-```javascript
-// Redirect to a different URL instead of startPath
-puzzleState.validateAndRedirect($page.url.pathname, '/puzzle/welcome');
-```
+- 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)
+- PageMachine integration for route/state management
 
 ## Separation of Concerns
 
@@ -222,5 +147,6 @@ puzzleState.validateAndRedirect($page.url.pathname, '/puzzle/welcome');
 **PageMachine** = Page/view state ONLY (SINGLE responsibility)
 - Current page state
 - Route mapping
+- Start path management
 - Visited states
 - Computed properties for state checks

package/dist/state/context.d.ts

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

package/dist/state/context.js

@@ -1,2 +1 @@
-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

@@ -7,6 +7,7 @@
  *
  * Features:
  * - State-to-route mapping and sync
+ * - Start path management
  * - Data properties for business/domain state
  * - Visited states tracking
  * - onEnter hooks with abort/complete handlers for animations
@@ -14,7 +15,7 @@
  * Basic usage:
  * ```javascript
  * const machine = new PageMachine({
- *   initialState: STATE_START,
+ *   startPath: '/intro/start',
  *   routeMap: {
  *     [STATE_START]: '/intro/start',
  *     [STATE_PROFILE]: '/intro/profile'
@@ -30,7 +31,7 @@
  * With onEnter hooks (for animations):
  * ```javascript
  * const machine = new PageMachine({
- *   initialState: STATE_ANIMATE,
+ *   startPath: '/game/animate',
  *   routeMap: {
  *     [STATE_ANIMATE]: '/game/animate',
  *     [STATE_PLAY]: '/game/play'
@@ -60,15 +61,23 @@ export default class PageMachine {
      * Constructor
      *
      * @param {Object} config - Configuration object
-     * @param {string} config.initialState - Initial state name
-     * @param {Record<string, string>} [config.routeMap={}] - Map of states to route paths
-     * @param {Record<string, any>} [config.initialData={}] - Initial data properties (from server)
-     * @param {Record<string, Function>} [config.onEnterHooks={}] - Map of states to onEnter hook functions
+     * @param {string} config.startPath
+     *   Start path for this route group (e.g., '/game/play')
+     * @param {Record<string, string>} [config.routeMap={}]
+     *   Map of states to route paths
+     * @param {Record<string, any>} [config.initialData={}]
+     *   Initial data properties (from server)
+     * @param {Record<string, Function>} [config.onEnterHooks={}]
+     *   Map of states to onEnter hook functions
+     * @param {string} [config.name='PageMachine']
+     *   Name for logger identification
+     * @param {import('../../../logging/typedef.js').LogLevel} [config.logLevel]
+     *   Log level (defaults to INFO for state transitions)
      *
      * @example
      * ```javascript
      * const machine = new PageMachine({
-     *   initialState: STATE_START,
+     *   startPath: '/intro/start',
      *   routeMap: {
      *     [STATE_START]: '/intro/start',
      *     [STATE_ANIMATE]: '/intro/animate'
@@ -88,12 +97,19 @@ export default class PageMachine {
      * });
      * ```
      */
-    constructor({ initialState, routeMap, initialData, onEnterHooks }: {
-        initialState: string;
+    constructor({ startPath, routeMap, initialData, onEnterHooks, name, logLevel }: {
+        startPath: string;
         routeMap?: Record<string, string> | undefined;
         initialData?: Record<string, any> | undefined;
         onEnterHooks?: Record<string, Function> | undefined;
+        name?: string | undefined;
+        logLevel?: import("../../../logging/typedef.js").LogLevel | undefined;
     });
+    /**
+     * Logger instance for state machine
+     * @type {Logger}
+     */
+    logger: Logger;
     /**
      * Synchronize machine state with URL path
      *
@@ -218,6 +234,56 @@ export default class PageMachine {
      * Useful for testing or resetting experience
      */
     resetVisitedStates(): void;
+    /**
+     * Get the start path
+     *
+     * @returns {string} Start path
+     */
+    get startPath(): string;
+    /**
+     * Get the start state
+     *
+     * @returns {string} Start state name
+     */
+    get startState(): string;
+    /**
+     * Check if the supplied path matches the start path
+     *
+     * @param {string} path - Path to check
+     *
+     * @returns {boolean} True if path matches start path
+     *
+     * @example
+     * ```javascript
+     * if (machine.isStartPath('/game/play')) {
+     *   // User is on the start page
+     * }
+     * ```
+     */
+    isStartPath(path: string): boolean;
+    /**
+     * Check if currently on the start state
+     *
+     * @returns {boolean} True if current state is the start state
+     *
+     * @example
+     * ```javascript
+     * if (machine.isOnStartState) {
+     *   // Show onboarding
+     * }
+     * ```
+     */
+    get isOnStartState(): boolean;
+    /**
+     * Navigate to the start path
+     *
+     * @example
+     * ```javascript
+     * // Redirect user to start
+     * machine.redirectToStartPath();
+     * ```
+     */
+    redirectToStartPath(): void;
     /**
      * Abort current state's transitions
      * Cancels animations/operations immediately (incomplete state)
@@ -268,3 +334,4 @@ export default class PageMachine {
     get canAbortTransitions(): boolean;
     #private;
 }
+import { Logger } from '../../../logging/common.js';

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

@@ -1,3 +1,5 @@
+import { Logger, INFO } from '../../../logging/common.js';
+
 /**
  * Base class for page state machines with URL route mapping
  *
@@ -7,6 +9,7 @@
  *
  * Features:
  * - State-to-route mapping and sync
+ * - Start path management
  * - Data properties for business/domain state
  * - Visited states tracking
  * - onEnter hooks with abort/complete handlers for animations
@@ -14,7 +17,7 @@
  * Basic usage:
  * ```javascript
  * const machine = new PageMachine({
- *   initialState: STATE_START,
+ *   startPath: '/intro/start',
  *   routeMap: {
  *     [STATE_START]: '/intro/start',
  *     [STATE_PROFILE]: '/intro/profile'
@@ -30,7 +33,7 @@
  * With onEnter hooks (for animations):
  * ```javascript
  * const machine = new PageMachine({
- *   initialState: STATE_ANIMATE,
+ *   startPath: '/game/animate',
  *   routeMap: {
  *     [STATE_ANIMATE]: '/game/animate',
  *     [STATE_PLAY]: '/game/play'
@@ -56,6 +59,11 @@
  * ```
  */
 export default class PageMachine {
+	/**
+	 * Logger instance for state machine
+	 * @type {Logger}
+	 */
+	logger;
 	/**
 	 * Current state
 	 * @type {string}
@@ -63,6 +71,18 @@ export default class PageMachine {
 	// @ts-ignore
 	#current = $state();
 
+	/**
+	 * Start path for this page machine
+	 * @type {string}
+	 */
+	#startPath = '';
+
+	/**
+	 * Initial/start state (derived from startPath)
+	 * @type {string}
+	 */
+	#startState = '';
+
 	/**
 	 * Map of states to route paths
 	 * @type {Record<string, string>}
@@ -124,15 +144,23 @@ export default class PageMachine {
 	 * Constructor
 	 *
 	 * @param {Object} config - Configuration object
-	 * @param {string} config.initialState - Initial state name
-	 * @param {Record<string, string>} [config.routeMap={}] - Map of states to route paths
-	 * @param {Record<string, any>} [config.initialData={}] - Initial data properties (from server)
-	 * @param {Record<string, Function>} [config.onEnterHooks={}] - Map of states to onEnter hook functions
+	 * @param {string} config.startPath
+	 *   Start path for this route group (e.g., '/game/play')
+	 * @param {Record<string, string>} [config.routeMap={}]
+	 *   Map of states to route paths
+	 * @param {Record<string, any>} [config.initialData={}]
+	 *   Initial data properties (from server)
+	 * @param {Record<string, Function>} [config.onEnterHooks={}]
+	 *   Map of states to onEnter hook functions
+	 * @param {string} [config.name='PageMachine']
+	 *   Name for logger identification
+	 * @param {import('../../../logging/typedef.js').LogLevel} [config.logLevel]
+	 *   Log level (defaults to INFO for state transitions)
 	 *
 	 * @example
 	 * ```javascript
 	 * const machine = new PageMachine({
-	 *   initialState: STATE_START,
+	 *   startPath: '/intro/start',
 	 *   routeMap: {
 	 *     [STATE_START]: '/intro/start',
 	 *     [STATE_ANIMATE]: '/intro/animate'
@@ -152,12 +180,20 @@ export default class PageMachine {
 	 * });
 	 * ```
 	 */
-	constructor({ initialState, routeMap = {}, initialData = {}, onEnterHooks = {} }) {
-		if (!initialState) {
-			throw new Error('PageMachine requires initialState parameter');
+	constructor({
+		startPath,
+		routeMap = {},
+		initialData = {},
+		onEnterHooks = {},
+		name = 'PageMachine',
+		logLevel = INFO
+	}) {
+		if (!startPath) {
+			throw new Error('PageMachine requires startPath parameter');
 		}
 
-		this.#current = initialState;
+		this.logger = new Logger(name, logLevel);
+		this.#startPath = startPath;
 		this.#routeMap = routeMap;
 		this.#data = initialData;
 		this.#onEnterHooks = this.#normalizeOnEnterHooks(onEnterHooks);
@@ -167,6 +203,17 @@ export default class PageMachine {
 			this.#pathToStateMap[path] = state;
 		}
 
+		// Derive initial state from startPath
+		const initialState = this.#pathToStateMap[startPath];
+		if (!initialState) {
+			throw new Error(
+				`PageMachine: startPath "${startPath}" not found in routeMap`
+			);
+		}
+
+		this.#startState = initialState;
+		this.#current = initialState;
+
 		// Mark initial state as visited
 		this.#visitedStates.add(initialState);
 	}
@@ -235,10 +282,14 @@ export default class PageMachine {
 		this.#currentOnEnterHandler = null;
 		this.#currentOnEnterDone = null;
 
+		const oldState = this.#current;
 		this.#isTransitioning = true;
 		this.#current = newState;
 		this.#visitedStates.add(newState);
 
+		// Log state transition
+		this.logger.debug(`${oldState} → ${newState}`);
+
 		// Check if this state has an onEnter hook
 		const hookConfig = this.#onEnterHooks[newState];
 		if (hookConfig?.onEnter) {
@@ -461,6 +512,76 @@ export default class PageMachine {
 		this.#revision++;
 	}
 
+	/* ===== Start Path Methods ===== */
+
+	/**
+	 * Get the start path
+	 *
+	 * @returns {string} Start path
+	 */
+	get startPath() {
+		return this.#startPath;
+	}
+
+	/**
+	 * Get the start state
+	 *
+	 * @returns {string} Start state name
+	 */
+	get startState() {
+		return this.#startState;
+	}
+
+	/**
+	 * Check if the supplied path matches the start path
+	 *
+	 * @param {string} path - Path to check
+	 *
+	 * @returns {boolean} True if path matches start path
+	 *
+	 * @example
+	 * ```javascript
+	 * if (machine.isStartPath('/game/play')) {
+	 *   // User is on the start page
+	 * }
+	 * ```
+	 */
+	isStartPath(path) {
+		return path === this.#startPath;
+	}
+
+	/**
+	 * Check if currently on the start state
+	 *
+	 * @returns {boolean} True if current state is the start state
+	 *
+	 * @example
+	 * ```javascript
+	 * if (machine.isOnStartState) {
+	 *   // Show onboarding
+	 * }
+	 * ```
+	 */
+	get isOnStartState() {
+		return this.#current === this.#startState;
+	}
+
+	/**
+	 * Navigate to the start path
+	 *
+	 * @example
+	 * ```javascript
+	 * // Redirect user to start
+	 * machine.redirectToStartPath();
+	 * ```
+	 */
+	redirectToStartPath() {
+		// Import dynamically to avoid circular dependencies
+		import('../../../util/sveltekit.js').then(({ switchToPage }) => {
+			switchToPage(this.#startPath);
+		});
+	}
+
 	/* ===== Transition Control Methods ===== */
 
 	/**

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

@@ -6,17 +6,13 @@ State machine for managing page view states with URL route mapping.
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│ MyFlowPageMachine (extends PageMachine)                 │
+│ PuzzleState (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; }         │
+│ - Manages start path and navigation                     │
+│ - Provides computed properties (inIntro, inLevel1, etc.)│
+│ - Contains GameLogic for reactive game state            │
+│ - Optional: services, preload, reset, etc.              │
 └────────────────┬────────────────────────────────────────┘
                  │
                  │ Context provided to layout
@@ -25,11 +21,11 @@ State machine for managing page view states with URL route mapping.
 │ +layout.svelte                                          │
 │ IMPORTANT: Must sync URL with state:                    │
 │   $effect(() => {                                       │
-│     pageMachine.syncFromPath($page.url.pathname);       │
+│     puzzleState.syncFromPath($page.url.pathname);       │
 │   });                                                   │
 └────────────────┬────────────────────────────────────────┘
                  │
-                 │ Pages use machine state
+                 │ Pages use state directly
                  │
         ┌────────┴─────────┬────────────────┐
         ▼                  ▼                ▼
@@ -37,37 +33,71 @@ State machine for managing page view states with URL route mapping.
   │ +page    │      │ +page    │    │ Component│
   │          │      │          │    │          │
   └──────────┘      └──────────┘    └──────────┘
-  Access via: pageMachine.current, pageMachine.inIntro, etc.
+  Access via: puzzleState.current, puzzleState.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
+3. **Manage start path** - Define and navigate to the entry point
+4. **Sync with browser navigation** - Keep state in sync with URL
+5. **Track visited states** - Know which pages user has seen
 
 ## Basic Usage
 
-### 1. Create a page machine class
+### 1. Define state constants
+
+```javascript
+// puzzle.constants.js
+export const STATE_INTRO = 'intro';
+export const STATE_TUTORIAL = 'tutorial';
+export const STATE_LEVEL1 = 'level1';
+export const STATE_LEVEL2 = 'level2';
+export const STATE_COMPLETE = 'complete';
+```
+
+### 2. Create state class (extends PageMachine)
 
 ```javascript
-// my-flow.machine.svelte.js
+// puzzle.state.svelte.js
+import { defineStateContext } from '@hkdigital/lib-core/state/context.js';
 import PageMachine from '$lib/state/machines/PageMachine.svelte.js';
+import PuzzleGameLogic from './puzzle.game-logic.svelte.js';
+import {
+  STATE_INTRO,
+  STATE_TUTORIAL,
+  STATE_LEVEL1,
+  STATE_LEVEL2,
+  STATE_COMPLETE
+} from './puzzle.constants.js';
+
+// Data keys for persistent data
+const KEY_TUTORIAL_SEEN = 'tutorial-seen';
+const KEY_HIGHEST_LEVEL = 'highest-level';
+const KEY_DIFFICULTY = 'difficulty';
+
+export class PuzzleState extends PageMachine {
+  #gameLogic;
 
-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);
+  constructor() {
+    // Call PageMachine constructor with route config
+    super({
+      startPath: '/puzzle/intro',
+      routeMap: {
+        [STATE_INTRO]: '/puzzle/intro',
+        [STATE_TUTORIAL]: '/puzzle/tutorial',
+        [STATE_LEVEL1]: '/puzzle/level1',
+        [STATE_LEVEL2]: '/puzzle/level2',
+        [STATE_COMPLETE]: '/puzzle/complete'
+      }
+    });
+
+    this.#gameLogic = new PuzzleGameLogic();
+  }
+
+  get gameLogic() {
+    return this.#gameLogic;
   }
 
   // Computed properties for convenience
@@ -75,31 +105,63 @@ export default class MyFlowPageMachine extends PageMachine {
     return this.current === STATE_INTRO;
   }
 
-  get inStep1() {
-    return this.current === STATE_STEP1;
+  get inTutorial() {
+    return this.current === STATE_TUTORIAL;
   }
-}
-```
 
-### 2. Use in state container
+  get inLevel1() {
+    return this.current === STATE_LEVEL1;
+  }
 
-```javascript
-// my-flow.state.svelte.js
-import { RouteStateContext } from '$lib/state/context.js';
-import MyFlowPageMachine from './my-flow.machine.svelte.js';
+  get inLevel2() {
+    return this.current === STATE_LEVEL2;
+  }
 
-export class MyFlowState extends RouteStateContext {
-  #pageMachine;
+  get isComplete() {
+    return this.current === STATE_COMPLETE;
+  }
 
-  constructor() {
-    super();
-    this.#pageMachine = new MyFlowPageMachine();
+  // Persistent settings/progress (use getData/setData)
+  get hasSeenTutorial() {
+    return this.getData(KEY_TUTORIAL_SEEN) || false;
+  }
+
+  markTutorialComplete() {
+    this.setData(KEY_TUTORIAL_SEEN, true);
+  }
+
+  get highestLevel() {
+    return this.getData(KEY_HIGHEST_LEVEL) || 1;
+  }
+
+  updateHighestLevel(level) {
+    const current = this.highestLevel;
+    if (level > current) {
+      this.setData(KEY_HIGHEST_LEVEL, level);
+    }
+  }
+
+  get difficulty() {
+    return this.getData(KEY_DIFFICULTY) || 'normal';
   }
 
-  get pageMachine() {
-    return this.#pageMachine;
+  setDifficulty(level) {
+    this.setData(KEY_DIFFICULTY, level);
+  }
+
+  // Optional: Lifecycle methods
+  preload(onProgress) {
+    return loadPuzzleAssets(onProgress);
+  }
+
+  reset() {
+    this.#gameLogic = new PuzzleGameLogic();
   }
 }
+
+// Export context helpers
+export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
+  defineStateContext(PuzzleState);
 ```
 
 ### 3. Sync with route in +layout.svelte component
@@ -109,43 +171,126 @@ export class MyFlowState extends RouteStateContext {
 ```svelte
 <script>
   import { page } from '$app/stores';
-  import { getMyFlowState } from '../my-flow.state.svelte.js';
+  import { createOrGetPuzzleState } from '../puzzle.state.svelte.js';
+
+  const puzzleState = createOrGetPuzzleState();
 
-  const flowState = getMyFlowState();
-  const pageMachine = flowState.pageMachine;
+  // Sync state with URL changes
+  $effect(() => {
+    puzzleState.syncFromPath($page.url.pathname);
+  });
 
-  // Sync machine with URL changes
+  // Optional: Enforce that users must visit intro before playing
   $effect(() => {
-    pageMachine.syncFromPath($page.url.pathname);
+    const currentPath = $page.url.pathname;
+
+    if (!puzzleState.isStartPath(currentPath) &&
+        currentPath.startsWith('/puzzle') &&
+        !puzzleState.hasVisited('intro')) {
+      puzzleState.redirectToStartPath();
+    }
+  });
+
+  // Optional: Preload assets
+  puzzleState.preload((progress) => {
+    console.log('Loading:', progress);
   });
 </script>
 
-{#if pageMachine.inIntro}
-  <IntroView />
-{:else if pageMachine.inStep1}
-  <Step1View />
+{#if puzzleState.inIntro}
+  <IntroView onComplete={() => puzzleState.markTutorialComplete()} />
+{:else if puzzleState.inTutorial}
+  <TutorialView />
+{:else if puzzleState.inLevel1}
+  <Level1View gameLogic={puzzleState.gameLogic} />
+{:else if puzzleState.inLevel2}
+  <Level2View gameLogic={puzzleState.gameLogic} />
+{:else if puzzleState.isComplete}
+  <CompleteView
+    score={puzzleState.gameLogic.score}
+    highestLevel={puzzleState.highestLevel} />
 {/if}
 ```
 
 ## Key Methods
 
+All PageMachine methods are directly available on your state class:
+
 ```javascript
 // Sync with URL path
-machine.syncFromPath(currentPath)
+puzzleState.syncFromPath(currentPath)
 
 // Get current state
-machine.current
+puzzleState.current
+
+// Start path management
+puzzleState.startPath                 // Get start path
+puzzleState.startState                // Get start state
+puzzleState.isStartPath(path)         // Check if path is start path
+puzzleState.isOnStartState            // Check if on start state
+puzzleState.redirectToStartPath()     // Navigate to start path
 
 // Get route for state
-machine.getPathForState(stateName)
+puzzleState.getPathForState(stateName)
 
-// Data properties (for business logic)
-machine.setData('KEY', value)
-machine.getData('KEY')
+// Persistent data properties
+puzzleState.setData(KEY_NAME, value)
+puzzleState.getData(KEY_NAME)
 
 // Visited states tracking
-machine.hasVisited(stateName)
-machine.getVisitedStates()
+puzzleState.hasVisited(stateName)
+puzzleState.getVisitedStates()
+
+// Custom computed properties (from your class)
+puzzleState.inIntro
+puzzleState.inLevel1
+puzzleState.hasSeenTutorial
+```
+
+## Data Storage Guidelines
+
+### When to use `getData/setData` (PageMachine)
+
+Use PageMachine's data properties for **persistent settings and progress**:
+
+- ✅ Tutorial completion flags
+- ✅ User preferences (difficulty, language, sound)
+- ✅ Progress tracking (highest level reached)
+- ✅ Settings that survive page navigation
+- ✅ Data that might be saved to server
+
+```javascript
+const KEY_TUTORIAL_SEEN = 'tutorial-seen';
+const KEY_DIFFICULTY = 'difficulty';
+const KEY_HIGHEST_LEVEL = 'highest-level';
+
+// Persistent data
+pageMachine.setData(KEY_TUTORIAL_SEEN, true);
+pageMachine.setData(KEY_DIFFICULTY, 'hard');
+pageMachine.setData(KEY_HIGHEST_LEVEL, 5);
+```
+
+### When to use GameLogic with `$state`
+
+Use a separate GameLogic class with `$state` fields for **reactive game state**:
+
+- ✅ Live scores, lives, health
+- ✅ Current player, selected items
+- ✅ Complex objects (cards, inventory, enemies)
+- ✅ Temporary turn/round state
+- ✅ Reactive UI state that changes frequently
+
+```javascript
+// puzzle.game-logic.svelte.js
+export class PuzzleGameLogic {
+  #score = $state(0);
+  #lives = $state(3);
+  #selectedCards = $state([]);
+  #currentPuzzle = $state(null);
+
+  get score() { return this.#score; }
+  incrementScore(points) { this.#score += points; }
+}
 ```
 
 ## Important Notes
@@ -154,4 +299,5 @@ machine.getVisitedStates()
 - 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
+- Use constants for data keys (e.g., `KEY_TUTORIAL_SEEN = 'tutorial-seen'`)
+- Separate persistent data (PageMachine) from reactive game state (GameLogic)

package/dist/ui/components/game-box/GameBox.svelte

@@ -461,6 +461,7 @@
 
 {#if gameHeight}
   <div
+    data-about="game-box-centering"
     class:center
     style:height={center ? `${iosWindowHeight ?? windowHeight}px` : undefined}
   >

package/dist/ui/components/game-box/ScaledContainer.svelte

@@ -60,6 +60,7 @@
 
 {#if snippet && snippetParams}
   <div
+    data-component="scaled-container"
     bind:this={container}
     class:hidden
     style:width="{width}px"

package/dist/util/sveltekit/navigation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Navigate to an internal path
+ * - Replaces the current url
+ *
+ * @param {string} path - Pathname to navigate to
+ */
+export function switchToPage(path: string): void;

package/dist/util/sveltekit/navigation.js

@@ -0,0 +1,12 @@
+import { goto } from '$app/navigation';
+
+/**
+ * Navigate to an internal path
+ * - Replaces the current url
+ *
+ * @param {string} path - Pathname to navigate to
+ */
+export function switchToPage( path ) {
+  // eslint-disable-next-line svelte/no-navigation-without-resolve
+  goto( path, { replaceState: true } );
+}

package/dist/util/sveltekit.d.ts

@@ -0,0 +1 @@
+export * from "./sveltekit/navigation.js";

package/dist/util/sveltekit.js

@@ -0,0 +1 @@
+export * from './sveltekit/navigation.js';

package/package.json

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

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

@@ -1,44 +0,0 @@
-/**
- * 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

@@ -1,119 +0,0 @@
-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 });
-		}
-	}
-}