@hkdigital/lib-core 0.5.57 → 0.5.59

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

@@ -1,144 +1,108 @@
 /**
- * Base class for page state machines with URL route mapping
+ * Route-aware data manager for page groups
  *
- * 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).
+ * Tracks navigation within a route group and manages business/domain data.
+ * Does NOT enforce transitions - allows free navigation via browser.
  *
  * Features:
- * - State-to-route mapping and sync
+ * - Current route tracking and synchronization
  * - Start path management
- * - Data properties for business/domain state
- * - Visited states tracking
- * - onEnter hooks with abort/complete handlers for animations
+ * - Data properties for business/domain state (using SvelteMap)
+ * - Visited routes tracking (using SvelteSet)
+ * - Fine-grained reactivity without manual revision tracking
+ *
+ * Best practices:
+ * - Use constants for routes: `const ROUTE_INTRO = '/intro/start'`
+ * - Use KEY_ constants for data: `const KEY_SCORE = 'score'`
  *
  * Basic usage:
  * ```javascript
+ * // Define constants
+ * const ROUTE_INTRO = '/intro/start';
+ * const KEY_SCORE = 'score';
+ * const KEY_TUTORIAL_SEEN = 'tutorial-seen';
+ *
  * const machine = new PageMachine({
- *   startPath: '/intro/start',
- *   routeMap: {
- *     [STATE_START]: '/intro/start',
- *     [STATE_PROFILE]: '/intro/profile'
+ *   startPath: ROUTE_INTRO,
+ *   routes: [ROUTE_INTRO, '/intro/profile', '/intro/complete'],
+ *   initialData: {
+ *     [KEY_SCORE]: 0,
+ *     [KEY_TUTORIAL_SEEN]: false
  *   }
  * });
  *
- * // Sync machine state with URL changes
+ * // Sync machine with URL changes
  * $effect(() => {
  *   machine.syncFromPath($page.url.pathname);
  * });
+ *
+ * // Check current route (reactive)
+ * $effect(() => {
+ *   if (machine.current === ROUTE_INTRO) {
+ *     console.log('On intro page');
+ *   }
+ * });
+ *
+ * // Access data (reactive, fine-grained)
+ * $effect(() => {
+ *   const score = machine.getData(KEY_SCORE);
+ *   console.log('Score changed:', score);
+ * });
  * ```
  *
- * With onEnter hooks (for animations):
+ * Animations and page-specific logic should use $effect in pages:
  * ```javascript
- * const machine = new PageMachine({
- *   startPath: '/game/animate',
- *   routeMap: {
- *     [STATE_ANIMATE]: '/game/animate',
- *     [STATE_PLAY]: '/game/play'
- *   },
- *   onEnterHooks: {
- *     [STATE_ANIMATE]: (done) => {
- *       const animation = playAnimation(1000);
- *       animation.finished.then(() => done(STATE_PLAY));
+ * // In +page.svelte
+ * const animations = new PageAnimations();
  *
- *       return {
- *         abort: () => animation.cancel(),
- *         complete: () => animation.finish()
- *       };
- *     }
+ * $effect(() => {
+ *   if (someCondition) {
+ *     animations.start();
  *   }
  * });
- *
- * // Fast-forward animation
- * machine.completeTransitions();
- *
- * // Cancel animation
- * machine.abortTransitions();
  * ```
  */
-import { switchToPage } from '../../../util/sveltekit.js';
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 
 export default class PageMachine {
 	/**
-	 * Logger instance for state machine
+	 * Logger instance
 	 * @type {import('../../../logging/client.js').Logger}
 	 */
 	logger;
+
 	/**
-	 * Current state
+	 * Current route path
 	 * @type {string}
 	 */
 	// @ts-ignore
 	#current = $state();
 
 	/**
-	 * Start path for this page machine
+	 * Start path for this route group
 	 * @type {string}
 	 */
 	#startPath = '';
 
 	/**
-	 * Initial/start state (derived from startPath)
-	 * @type {string}
-	 */
-	#startState = '';
-
-	/**
-	 * 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);
-
-	/**
-	 * Map of state names to onEnter hook configurations
-	 * @type {Record<string, {onEnter: Function}>}
+	 * Optional list of valid routes for this group
+	 * @type {string[]}
 	 */
-	#onEnterHooks = {};
+	#routes = [];
 
 	/**
-	 * Current state's onEnter handler (abort/complete functions)
-	 * @type {{abort?: Function, complete?: Function} | null}
+	 * Reactive map for business/domain data
+	 * Uses SvelteMap for fine-grained reactivity
+	 * @type {SvelteMap<string, any>}
 	 */
-	#currentOnEnterHandler = null;
+	#data;
 
 	/**
-	 * Current state's done callback
-	 * @type {Function | null}
+	 * Reactive set for visited routes
+	 * Uses SvelteSet for automatic reactivity
+	 * @type {SvelteSet<string>}
 	 */
-	#currentOnEnterDone = null;
-
-	/**
-	 * Flag to prevent concurrent state transitions
-	 * @type {boolean}
-	 */
-	#isTransitioning = false;
+	#visitedRoutes;
 
 	/**
 	 * Constructor
@@ -146,129 +110,74 @@ export default class PageMachine {
 	 * @param {Object} config - Configuration object
 	 * @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 {string[]} [config.routes=[]]
+	 *   Optional list of valid routes (for validation/dev tools)
 	 * @param {Record<string, any>} [config.initialData={}]
-	 *   Initial data properties (from server)
-	 * @param {Record<string, Function>} [config.onEnterHooks={}]
-	 *   Map of states to onEnter hook functions
+	 *   Initial data properties (use KEY_ constants for keys)
 	 * @param {import('../../../logging/client.js').Logger} [config.logger]
-	 *   Logger instance (optional, if not provided no logging occurs)
+	 *   Logger instance (optional)
 	 *
 	 * @example
 	 * ```javascript
+	 * const ROUTE_INTRO = '/intro/start';
+	 * const KEY_INTRO_COMPLETED = 'intro-completed';
+	 * const KEY_SCORE = 'score';
+	 *
 	 * const machine = new PageMachine({
-	 *   startPath: '/intro/start',
-	 *   routeMap: {
-	 *     [STATE_START]: '/intro/start',
-	 *     [STATE_ANIMATE]: '/intro/animate'
-	 *   },
+	 *   startPath: ROUTE_INTRO,
+	 *   routes: [ROUTE_INTRO, '/intro/profile'],
 	 *   initialData: {
-	 *     INTRO_COMPLETED: false
-	 *   },
-	 *   onEnterHooks: {
-	 *     [STATE_ANIMATE]: (done) => {
-	 *       setTimeout(() => done(STATE_START), 1000);
-	 *       return {
-	 *         abort: () => clearTimeout(...),
-	 *         complete: () => done(STATE_START)
-	 *       };
-	 *     }
+	 *     [KEY_INTRO_COMPLETED]: false,
+	 *     [KEY_SCORE]: 0
 	 *   }
 	 * });
 	 * ```
 	 */
-	constructor({
-		startPath,
-		routeMap = {},
-		initialData = {},
-		onEnterHooks = {},
-		logger = null
-	}) {
+	constructor({ startPath, routes = [], initialData = {}, logger = null }) {
 		if (!startPath) {
 			throw new Error('PageMachine requires startPath parameter');
 		}
 
 		this.logger = logger;
 		this.#startPath = startPath;
-		this.#routeMap = routeMap;
-		this.#data = initialData;
-		this.#onEnterHooks = this.#normalizeOnEnterHooks(onEnterHooks);
-
-		// Build reverse map (path -> state) and validate no duplicates
-		for (const [state, path] of Object.entries(routeMap)) {
-			// Check if this path is already mapped to a different state
-			const existingState = this.#pathToStateMap[path];
-			if (existingState && existingState !== state) {
-				throw new Error(
-					`PageMachine: Duplicate route mapping detected. ` +
-					`Path "${path}" is mapped to both "${existingState}" and "${state}". ` +
-					`Each route path must map to exactly one state.`
-				);
-			}
-			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.#routes = routes;
+		this.#current = startPath;
 
-		this.#startState = initialState;
-		this.#current = initialState;
+		// Initialize reactive data structures
+		this.#data = new SvelteMap();
+		this.#visitedRoutes = new SvelteSet();
 
-		// Mark initial state as visited
-		this.#visitedStates.add(initialState);
-	}
-
-	/**
-	 * Normalize onEnterHooks to ensure consistent format
-	 * Converts function to {onEnter: function} object
-	 *
-	 * @param {Record<string, Function|{onEnter: Function}>} hooks - Raw hooks configuration
-	 * @returns {Record<string, {onEnter: Function}>} Normalized hooks
-	 */
-	#normalizeOnEnterHooks(hooks) {
-		/** @type {Record<string, {onEnter: Function} */
-		const normalized = {};
-
-		for (const [state, hook] of Object.entries(hooks)) {
-			if (typeof hook === 'function') {
-				// Simple function -> wrap in object
-				normalized[state] = { onEnter: hook };
-			} else if (hook?.onEnter) {
-				// Already an object with onEnter
-				normalized[state] = hook;
-			}
+		// Populate initial data
+		for (const [key, value] of Object.entries(initialData)) {
+			this.#data.set(key, value);
 		}
 
-		return normalized;
+		// Mark start path as visited
+		this.#visitedRoutes.add(startPath);
 	}
 
 	/**
-	 * Synchronize machine state with URL path
+	 * Synchronize machine with URL path
 	 *
-	 * Call this in a $effect that watches $page.url.pathname
-	 * Automatically tracks visited states and triggers onEnter hooks
+	 * Call this in a $effect that watches $page.url.pathname.
+	 * Automatically tracks visited routes.
 	 *
 	 * @param {string} currentPath - Current URL pathname
 	 *
-	 * @returns {boolean} True if state was changed
+	 * @returns {boolean} True if route was changed
 	 */
 	syncFromPath(currentPath) {
-		const targetState = this.#getStateFromPath(currentPath);
+		// Find matching route
+		const matchedRoute = this.#findMatchingRoute(currentPath);
+
+		if (matchedRoute && matchedRoute !== this.#current) {
+			this.logger?.debug(`syncFromPath: ${currentPath} → ${matchedRoute}`);
 
-		if (targetState && targetState !== this.#current) {
-			// Log state transition from URL sync
-			this.logger?.debug(
-				`syncFromPath: ${currentPath} → targetState: ${targetState}`
-			);
+			const oldRoute = this.#current;
+			this.#current = matchedRoute;
+			this.#visitedRoutes.add(matchedRoute);
 
-			// Use #setState to handle onEnter hooks
-			this.#setState(targetState);
+			this.logger?.debug(`Route changed: ${oldRoute} → ${matchedRoute}`);
 
 			return true;
 		}
@@ -277,154 +186,50 @@ export default class PageMachine {
 	}
 
 	/**
-	 * Set the current state directly (internal use only)
-	 * Handles onEnter hooks and auto-transitions
-	 *
-	 * Note: This is private to enforce URL-first navigation.
-	 * To change state, navigate to the URL using switchToPage()
-	 * and let syncFromPath() update the state.
-	 *
-	 * @param {string} newState - Target state
-	 */
-	async #setState(newState) {
-		if (newState === this.#current || this.#isTransitioning) {
-			return;
-		}
-
-		// Abort previous state's onEnter handler
-		if (this.#currentOnEnterHandler?.abort) {
-			this.#currentOnEnterHandler.abort();
-		}
-		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(`setState: ${oldState} → ${newState}`);
-
-		// Check if this state has an onEnter hook
-		const hookConfig = this.#onEnterHooks[newState];
-		if (hookConfig?.onEnter) {
-			// Create done callback for auto-transition
-			let doneCalled = false;
-
-			const done = (/** @type {string} */ nextState) => {
-				if (!doneCalled && nextState && nextState !== newState) {
-					doneCalled = true;
-					this.#isTransitioning = false;
-					this.#setState(nextState);
-				}
-			};
-
-			this.#currentOnEnterDone = done;
-
-			// Call the onEnter hook
-			try {
-				const handler = hookConfig.onEnter(done);
-
-				// Store abort/complete handlers if provided
-				if (handler && typeof handler === 'object') {
-					if (handler.abort || handler.complete) {
-						this.#currentOnEnterHandler = {
-							abort: handler.abort,
-							complete: handler.complete
-						};
-					}
-				}
-
-				// If hook returned a promise, await it
-				if (handler?.then) {
-					await handler;
-				}
-			} catch (error) {
-				const logger = this.logger ?? console;
-				logger.error(`Error in onEnter hook for state ${newState}:`, error);
-			}
-		}
-
-		this.#isTransitioning = false;
-		this.#revision++;
-	}
-
-	/**
-	 * Get state name from URL path
+	 * Find matching route from path
 	 *
 	 * @param {string} path - URL pathname
 	 *
-	 * @returns {string|null} State name or null
+	 * @returns {string|null} Matched route 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;
+	#findMatchingRoute(path) {
+		// If routes list provided, try to match against it
+		if (this.#routes.length > 0) {
+			// Try exact match first
+			if (this.#routes.includes(path)) {
+				return path;
 			}
-		}
-
-		return null;
-	}
 
-	/**
-	 * Get route path for a given state
-	 *
-	 * @param {string} state - State name
-	 *
-	 * @returns {string} Route path or null if no mapping
-	 */
-	getPathForState(state) {
-		const path = this.#routeMap[state];
+			// Try partial match (path starts with route)
+			for (const route of this.#routes) {
+				if (path.startsWith(route)) {
+					return route;
+				}
+			}
 
-		if (!path) {
-			throw new Error(`No path found for state [${state}]`);
+			return null;
 		}
 
+		// No routes list - accept any path
 		return path;
 	}
 
 	/**
-	 * Navigate to the route path for a given state
-	 *
-	 * @param {string} state - State name
-	 */
-	navigateToState(state) {
-		const path = this.getPathForState(state);
-		switchToPage(path);
-	}
-
-	/**
-	 * Get route path for current state
+	 * Get current route
 	 *
-	 * @returns {string|null} Route path or null if no mapping
-	 */
-	getCurrentPath() {
-		return this.getPathForState(this.#current);
-	}
-
-	/**
-	 * Get current state
-	 *
-	 * @returns {string} Current state name
+	 * @returns {string} Current route path
 	 */
 	get current() {
 		return this.#current;
 	}
 
 	/**
-	 * Get the route map
+	 * Get the routes list
 	 *
-	 * @returns {Record<string, string>} Copy of route map
+	 * @returns {string[]} Copy of routes list
 	 */
-	get routeMap() {
-		return { ...this.#routeMap };
+	get routes() {
+		return [...this.#routes];
 	}
 
 	/* ===== Data Properties (Business/Domain State) ===== */
@@ -432,43 +237,59 @@ export default class PageMachine {
 	/**
 	 * Set a data property value
 	 *
-	 * @param {string} key - Property key
+	 * 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
-	 * machine.setData('HAS_STRONG_PROFILE', true);
-	 * machine.setData('PROFILE_SCORE', 85);
+	 * 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[key] = value;
-		this.#revision++;
+		this.#data.set(key, value);
 	}
 
 	/**
 	 * Get a data property value
 	 *
-	 * @param {string} key - Property key
+	 * 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
 	 *
 	 * @example
 	 * ```javascript
-	 * const hasProfile = machine.getData('HAS_STRONG_PROFILE');
-	 * const score = machine.getData('PROFILE_SCORE');
+	 * const KEY_SCORE = 'score';
+	 *
+	 * // Reactive - re-runs only when KEY_SCORE changes
+	 * $effect(() => {
+	 *   const score = machine.getData(KEY_SCORE);
+	 *   console.log('Score:', score);
+	 * });
 	 * ```
 	 */
 	getData(key) {
-		// Access revision to ensure reactivity
-		this.#revision;
-		return this.#data[key];
+		return this.#data.get(key);
 	}
 
 	/**
-	 * Get all data properties
+	 * 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>} Copy of all data
+	 * @returns {Record<string, any>} Plain object with all data
 	 *
 	 * @example
 	 * ```javascript
@@ -477,58 +298,124 @@ export default class PageMachine {
 	 * ```
 	 */
 	getAllData() {
-		// Access revision to ensure reactivity
-		this.#revision;
-		return { ...this.#data };
+		return Object.fromEntries(this.#data);
 	}
 
 	/**
 	 * Update multiple data properties at once
 	 *
-	 * @param {Record<string, any>} dataUpdates - Object with key-value pairs
+	 * 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({
-	 *   HAS_STRONG_PROFILE: true,
-	 *   PROFILE_SCORE: 85,
-	 *   MATCHED_SECTOR: 'technology'
+	 *   [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[key] = value;
+			this.#data.set(key, value);
 		}
-		this.#revision++;
 	}
 
-	/* ===== Visited States Tracking ===== */
+	/**
+	 * 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);
+	 * ```
+	 */
+	deleteData(key) {
+		return this.#data.delete(key);
+	}
 
 	/**
-	 * Check if a state has been visited
+	 * Check if data property exists
 	 *
-	 * @param {string} state - State name to check
+	 * @param {string} key - Property key to check (use KEY_ constant)
 	 *
-	 * @returns {boolean} True if the state has been visited
+	 * @returns {boolean} True if the key exists
 	 *
 	 * @example
 	 * ```javascript
-	 * if (machine.hasVisited(STATE_PROFILE)) {
-	 *   // User has seen profile page, skip intro
+	 * const KEY_TUTORIAL_SEEN = 'tutorial-seen';
+	 *
+	 * if (machine.hasData(KEY_TUTORIAL_SEEN)) {
+	 *   // Skip tutorial
 	 * }
 	 * ```
 	 */
-	hasVisited(state) {
-		// Access revision to ensure reactivity
-		this.#revision;
-		return this.#visitedStates.has(state);
+	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;
+	}
+
+	/* ===== Visited Routes Tracking ===== */
+
+	/**
+	 * Check if a route has been visited
+	 *
+	 * Automatically reactive - creates a dependency on the visited routes set.
+	 *
+	 * @param {string} route - Route path to check
+	 *
+	 * @returns {boolean} True if the route has been visited
+	 *
+	 * @example
+	 * ```javascript
+	 * // Reactive - re-runs when visited routes change
+	 * $effect(() => {
+	 *   if (machine.hasVisited('/intro/profile')) {
+	 *     console.log('User has seen profile page');
+	 *   }
+	 * });
+	 * ```
+	 */
+	hasVisited(route) {
+		return this.#visitedRoutes.has(route);
 	}
 
 	/**
-	 * Check if the start state has been visited
+	 * Check if the start route has been visited
 	 *
-	 * @returns {boolean} True if the start state has been visited
+	 * @returns {boolean} True if the start route has been visited
 	 *
 	 * @example
 	 * ```javascript
@@ -538,28 +425,42 @@ export default class PageMachine {
 	 * ```
 	 */
 	get hasVisitedStart() {
-		return this.hasVisited(this.#startState);
+		return this.hasVisited(this.#startPath);
 	}
 
 	/**
-	 * Get all visited states
+	 * Get all visited routes as array
+	 *
+	 * Note: Returns a snapshot (plain array), not reactive.
 	 *
-	 * @returns {string[]} Array of visited state names
+	 * @returns {string[]} Array of visited route paths
 	 */
-	getVisitedStates() {
-		// Access revision to ensure reactivity
-		this.#revision;
-		return Array.from(this.#visitedStates);
+	getVisitedRoutes() {
+		return Array.from(this.#visitedRoutes);
 	}
 
 	/**
-	 * Reset visited states tracking
-	 * Useful for testing or resetting experience
+	 * Reset visited routes tracking
+	 *
+	 * Clears all visited routes and marks only the current route as visited.
+	 *
+	 * @example
+	 * ```javascript
+	 * machine.resetVisitedRoutes();  // Reset progress tracking
+	 * ```
 	 */
-	resetVisitedStates() {
-		this.#visitedStates.clear();
-		this.#visitedStates.add(this.#current);
-		this.#revision++;
+	resetVisitedRoutes() {
+		this.#visitedRoutes.clear();
+		this.#visitedRoutes.add(this.#current);
+	}
+
+	/**
+	 * Get number of visited routes
+	 *
+	 * @returns {number} Number of routes visited
+	 */
+	get visitedRoutesCount() {
+		return this.#visitedRoutes.size;
 	}
 
 	/* ===== Start Path Methods ===== */
@@ -573,15 +474,6 @@ export default class PageMachine {
 		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
 	 *
@@ -601,19 +493,19 @@ export default class PageMachine {
 	}
 
 	/**
-	 * Check if currently on the start state
+	 * Check if currently on the start path
 	 *
-	 * @returns {boolean} True if current state is the start state
+	 * @returns {boolean} True if current route is the start path
 	 *
 	 * @example
 	 * ```javascript
-	 * if (machine.isOnStartState) {
+	 * if (machine.isOnStartPath) {
 	 *   // Show onboarding
 	 * }
 	 * ```
 	 */
-	get isOnStartState() {
-		return this.#current === this.#startState;
+	get isOnStartPath() {
+		return this.#current === this.#startPath;
 	}
 
 	/**
@@ -631,78 +523,4 @@ export default class PageMachine {
 			switchToPage(this.#startPath);
 		});
 	}
-
-	/* ===== Transition Control Methods ===== */
-
-	/**
-	 * Abort current state's transitions
-	 * Cancels animations/operations immediately (incomplete state)
-	 *
-	 * @example
-	 * ```javascript
-	 * // User clicks "Cancel" button
-	 * machine.abortTransitions();
-	 * ```
-	 */
-	abortTransitions() {
-		if (this.#currentOnEnterHandler?.abort) {
-			this.#currentOnEnterHandler.abort();
-			this.#currentOnEnterHandler = null;
-			this.#currentOnEnterDone = null;
-			this.#revision++;
-		}
-	}
-
-	/**
-	 * Complete current state's transitions immediately
-	 * Fast-forwards animations/operations to completion (complete state)
-	 *
-	 * @example
-	 * ```javascript
-	 * // User clicks "Skip" or "Next" button
-	 * machine.completeTransitions();
-	 * ```
-	 */
-	completeTransitions() {
-		if (this.#currentOnEnterHandler?.complete) {
-			this.#currentOnEnterHandler.complete();
-			this.#currentOnEnterHandler = null;
-			this.#currentOnEnterDone = null;
-			this.#revision++;
-		}
-	}
-
-	/**
-	 * Check if current state has transitions that can be completed
-	 *
-	 * @returns {boolean} True if completeTransitions() can be called
-	 *
-	 * @example
-	 * ```svelte
-	 * {#if machine.canCompleteTransitions}
-	 *   <button onclick={() => machine.completeTransitions()}>Skip</button>
-	 * {/if}
-	 * ```
-	 */
-	get canCompleteTransitions() {
-		this.#revision; // Ensure reactivity
-		return !!this.#currentOnEnterHandler?.complete;
-	}
-
-	/**
-	 * Check if current state has transitions that can be aborted
-	 *
-	 * @returns {boolean} True if abortTransitions() can be called
-	 *
-	 * @example
-	 * ```svelte
-	 * {#if machine.canAbortTransitions}
-	 *   <button onclick={() => machine.abortTransitions()}>Cancel</button>
-	 * {/if}
-	 * ```
-	 */
-	get canAbortTransitions() {
-		this.#revision; // Ensure reactivity
-		return !!this.#currentOnEnterHandler?.abort;
-	}
 }