@xmachines/play-tanstack-react-router 1.0.0-beta.1

package/examples/demo/test/browser/login-flow.browser.test.tsx

@@ -0,0 +1,34 @@
+import { test, expect, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import App from "../../src/App.js";
+
+afterEach(async () => {
+	cleanup();
+});
+
+test("E2E: User can log in and see dashboard", async () => {
+	render(<App />);
+
+	// App starts at home page, navigate to login
+	const user = userEvent.setup();
+	await user.click(screen.getByRole("button", { name: /login/i }));
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	// Should now be at login page
+	expect(screen.getByLabelText(/username/i)).toBeInTheDocument();
+	expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
+
+	// Fill in login form
+	await user.type(screen.getByLabelText(/username/i), "testuser");
+	await user.type(screen.getByLabelText(/password/i), "password123");
+
+	// Submit login
+	await user.click(screen.getByRole("button", { name: /log in/i }));
+
+	// Wait for navigation
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// Should see dashboard heading (more specific than button or description)
+	expect(screen.getByRole("heading", { name: /Welcome to the Dashboard/i })).toBeInTheDocument();
+});

package/examples/demo/test/browser/navigation.browser.test.tsx

@@ -0,0 +1,34 @@
+import { test, expect, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import App from "../../src/App.js";
+
+afterEach(async () => {
+	cleanup();
+});
+
+test("E2E: Navigation reflects actor state transitions", async () => {
+	render(<App />);
+
+	// App starts at home page, navigate to login
+	const user = userEvent.setup();
+	await user.click(screen.getByRole("button", { name: /login/i }));
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	// Login first
+	await user.type(screen.getByLabelText(/username/i), "testuser");
+	await user.type(screen.getByLabelText(/password/i), "password123");
+	await user.click(screen.getByRole("button", { name: /log in/i }));
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// Verify we're at dashboard heading (actor state transitioned)
+	expect(screen.getByRole("heading", { name: /Welcome to the Dashboard/i })).toBeInTheDocument();
+
+	// Logout
+	const logoutButton = screen.getByRole("button", { name: /logout/i });
+	await user.click(logoutButton);
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// Should be back at home page (logout transitions to home state)
+	expect(screen.getByRole("heading", { name: /Welcome/i })).toBeInTheDocument();
+});

package/examples/demo/test/browser/protected-route-navigation.browser.test.tsx

@@ -0,0 +1,161 @@
+/**
+ * TDD: Browser Back/Forward Navigation on Protected Routes
+ *
+ * Test Case: Login → Dashboard → Settings → Back to Dashboard → Browser Back
+ * Expected: Browser back should navigate to /settings
+ * Actual: Stays on / (dashboard)
+ *
+ * This reproduces the reported issue: "I can't use forward/back on protected routes"
+ */
+
+import { test, expect, afterEach } from "vitest";
+import { render, screen, cleanup, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import App from "../../src/App.js";
+
+afterEach(async () => {
+	cleanup();
+});
+
+test("Browser back navigates from dashboard to settings (protected route)", async () => {
+	// Reset URL BEFORE rendering
+	window.history.pushState({}, "", "/");
+
+	render(<App />);
+	const user = userEvent.setup();
+
+	console.log("\n=== Step 1: Login ===");
+	// Navigate to login if needed
+	if (!screen.queryByLabelText(/username/i)) {
+		await user.click(screen.getByRole("button", { name: /login/i }));
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+
+	// Fill and submit login form
+	await user.type(screen.getByLabelText(/username/i), "testuser");
+	await user.type(screen.getByLabelText(/password/i), "password123");
+	await user.click(screen.getByRole("button", { name: /log in/i }));
+
+	console.log("1. After login, URL:", window.location.pathname);
+	await waitFor(
+		() => {
+			expect(window.location.pathname).toBe("/"); // Dashboard
+		},
+		{ timeout: 2000 },
+	);
+
+	console.log("\n=== Step 2: Navigate to Settings ===");
+	const settingsButton = screen
+		.getAllByRole("button")
+		.find((btn) => btn.textContent?.includes("Settings") && !btn.textContent?.includes("›"));
+	expect(settingsButton).toBeDefined();
+
+	await user.click(settingsButton!);
+
+	console.log("2. After clicking Settings, URL:", window.location.pathname);
+	await waitFor(
+		() => {
+			expect(window.location.pathname).toMatch(/\/settings/);
+		},
+		{ timeout: 2000 },
+	);
+
+	console.log("\n=== Step 3: Click Back to Home ===");
+	const backButton = screen
+		.getAllByRole("button")
+		.find((btn) => btn.textContent?.includes("Back to Home"));
+	expect(backButton).toBeDefined();
+
+	await user.click(backButton!);
+
+	console.log("3. After Back to Home, URL:", window.location.pathname);
+	await waitFor(
+		() => {
+			expect(window.location.pathname).toBe("/");
+		},
+		{ timeout: 2000 },
+	);
+
+	console.log("\n=== Step 4: Browser Back (FIXED) ===");
+	window.history.back();
+
+	console.log("4. After browser back(), URL:", window.location.pathname);
+	console.log("   EXPECTED: /settings");
+	await waitFor(
+		() => {
+			console.log("   ACTUAL:", window.location.pathname);
+			expect(window.location.pathname).toMatch(/\/settings/);
+		},
+		{ timeout: 2000 },
+	);
+
+	// This should work now with pattern matching
+});
+
+test("Browser back/forward through multiple protected routes", async () => {
+	// Reset URL BEFORE rendering
+	window.history.pushState({}, "", "/");
+
+	render(<App />);
+	const user = userEvent.setup();
+
+	// Login
+	if (!screen.queryByLabelText(/username/i)) {
+		await user.click(screen.getByRole("button", { name: /login/i }));
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+
+	await user.type(screen.getByLabelText(/username/i), "testuser");
+	await user.type(screen.getByLabelText(/password/i), "password123");
+	await user.click(screen.getByRole("button", { name: /log in/i }));
+
+	await waitFor(
+		() => {
+			expect(window.location.pathname).toBe("/");
+		},
+		{ timeout: 2000 },
+	);
+
+	// Navigate: Dashboard → Settings → Dashboard
+	const settingsButton = screen
+		.getAllByRole("button")
+		.find((btn) => btn.textContent?.includes("Settings") && !btn.textContent?.includes("›"));
+	await user.click(settingsButton!);
+	await waitFor(
+		() => {
+			expect(window.location.pathname).toMatch(/\/settings/);
+		},
+		{ timeout: 2000 },
+	);
+
+	const backButton = screen
+		.getAllByRole("button")
+		.find((btn) => btn.textContent?.includes("Back to Home"));
+	await user.click(backButton!);
+	await waitFor(
+		() => {
+			expect(window.location.pathname).toBe("/");
+		},
+		{ timeout: 2000 },
+	);
+
+	// Browser back should go to /settings
+	window.history.back();
+	console.log("After back(), URL:", window.location.pathname);
+	await waitFor(
+		() => {
+			expect(window.location.pathname).toMatch(/\/settings/);
+		},
+		{ timeout: 2000 },
+	);
+
+	// Browser forward should return to /
+	window.history.forward();
+	console.log("After forward(), URL:", window.location.pathname);
+	await waitFor(
+		() => {
+			expect(window.location.pathname).toBe("/");
+		},
+		{ timeout: 2000 },
+	);
+});

package/examples/demo/test/browser/redirect-url-update.browser.test.tsx

@@ -0,0 +1,140 @@
+/**
+ * Test: URL updates when browser back triggers always-guard redirect
+ *
+ * Bug: When logged in, pressing back to /login causes a redirect to / (dashboard).
+ * The screen updates correctly, but the URL stays at /login instead of updating to /.
+ *
+ * Root cause: The queueMicrotask in syncActorFromUrl() was calling baseHistory.replace()
+ * without the recursion guard (isInsideSyncActorFromUrl), and the isProcessingBrowserNavigation
+ * flag was cleared too early. This caused syncUrlFromActor() (from signal watcher) to race
+ * with the queueMicrotask and interfere with the URL update.
+ *
+ * Fix:
+ * 1. Add recursion guard around replace() in queueMicrotask
+ * 2. Clear isProcessingBrowserNavigation flag AFTER queueMicrotask completes
+ * This ensures the queueMicrotask handles the URL update, not syncUrlFromActor().
+ */
+
+import { test, expect, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import App from "../../src/App.js";
+
+afterEach(async () => {
+	cleanup();
+});
+
+test("URL updates when back button triggers always-guard redirect from /login to /", async () => {
+	render(<App />);
+	const user = userEvent.setup();
+
+	// Step 1: Go to /login
+	await user.click(screen.getByRole("button", { name: /login/i }));
+	await new Promise((resolve) => setTimeout(resolve, 50));
+	expect(window.location.pathname).toBe("/login");
+
+	// Step 2: Log in (redirects to /)
+	await user.type(screen.getByLabelText(/username/i), "testuser");
+	await user.type(screen.getByLabelText(/password/i), "password123");
+	await user.click(screen.getByRole("button", { name: /log in/i }));
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// Verify we're at dashboard
+	expect(screen.getByRole("heading", { name: /Welcome to the Dashboard/i })).toBeInTheDocument();
+	expect(window.location.pathname).toBe("/");
+
+	// Step 3: Press back (browser goes back to /login)
+	// This should trigger: /login → always-guard → /dashboard (/)
+	// BOTH the screen AND URL should show /
+	window.history.back();
+	await new Promise((resolve) => setTimeout(resolve, 150));
+
+	// Step 4: Verify URL was updated to / (not stuck at /login)
+	expect(window.location.pathname).toBe("/");
+	expect(screen.getByRole("heading", { name: /Welcome to the Dashboard/i })).toBeInTheDocument();
+});
+
+test("URL updates when back button triggers always-guard redirect from /register to /", async () => {
+	render(<App />);
+	const user = userEvent.setup();
+
+	// Step 1: Go to /register
+	// (Navigate via URL since there's no register button)
+	window.history.pushState({}, "", "/register");
+	window.dispatchEvent(new PopStateEvent("popstate"));
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// Step 2: Register (redirects to /)
+	await user.type(screen.getByLabelText(/username/i), "testuser");
+	await user.type(screen.getByLabelText(/email/i), "test@example.com");
+	await user.type(screen.getByLabelText(/password/i), "password123");
+	await user.click(screen.getByRole("button", { name: /create account/i }));
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// Verify we're at dashboard
+	expect(screen.getByRole("heading", { name: /Welcome to the Dashboard/i })).toBeInTheDocument();
+	expect(window.location.pathname).toBe("/");
+
+	// Step 3: Press back (browser goes back to /register)
+	window.history.back();
+	await new Promise((resolve) => setTimeout(resolve, 150));
+
+	// Step 4: Verify URL was updated to / (not stuck at /register)
+	expect(window.location.pathname).toBe("/");
+	expect(screen.getByRole("heading", { name: /Welcome to the Dashboard/i })).toBeInTheDocument();
+});
+
+test("URL updates when redirecting from /login to / via always-guard", async () => {
+	render(<App />);
+	const user = userEvent.setup();
+
+	// 1. Log in first
+	await user.click(screen.getByRole("button", { name: /login/i }));
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	await user.type(screen.getByLabelText(/username/i), "testuser");
+	await user.type(screen.getByLabelText(/password/i), "password123");
+	await user.click(screen.getByRole("button", { name: /log in/i }));
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// 2. Verify we're at dashboard
+	expect(screen.getByRole("heading", { name: /Welcome to the Dashboard/i })).toBeInTheDocument();
+	expect(window.location.pathname).toBe("/");
+
+	// 3. Try to navigate to /login while authenticated
+	// This should trigger: /login → always-guard → /dashboard (/)
+	// The screen AND URL should both update to /
+	window.history.pushState({}, "", "/login");
+	window.dispatchEvent(new PopStateEvent("popstate"));
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// 4. Verify URL was corrected to / (not stuck at /login)
+	expect(window.location.pathname).toBe("/");
+	expect(screen.getByRole("heading", { name: /Welcome to the Dashboard/i })).toBeInTheDocument();
+});
+
+test("URL updates when redirecting from /register to / via always-guard", async () => {
+	render(<App />);
+	const user = userEvent.setup();
+
+	// 1. Log in first
+	await user.click(screen.getByRole("button", { name: /login/i }));
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	await user.type(screen.getByLabelText(/username/i), "testuser");
+	await user.type(screen.getByLabelText(/password/i), "password123");
+	await user.click(screen.getByRole("button", { name: /log in/i }));
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// 2. Verify we're at dashboard
+	expect(screen.getByRole("heading", { name: /Welcome to the Dashboard/i })).toBeInTheDocument();
+
+	// 3. Try to navigate to /register while authenticated
+	window.history.pushState({}, "", "/register");
+	window.dispatchEvent(new PopStateEvent("popstate"));
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// 4. Verify URL was corrected to / (not stuck at /register)
+	expect(window.location.pathname).toBe("/");
+	expect(screen.getByRole("heading", { name: /Welcome to the Dashboard/i })).toBeInTheDocument();
+});

package/examples/demo/test/browser/settings-parameter.browser.test.tsx

@@ -0,0 +1,164 @@
+/**
+ * Settings Parameter Browser Test
+ *
+ * Verifies that settings route displays correct section parameter from URL.
+ * This is a regression test for the bug where /settings/profile showed "general"
+ * instead of "profile".
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import App from "../../src/App.js";
+
+describe("Settings Parameter Display", () => {
+	beforeEach(() => {
+		// Clear any auth state between tests
+		window.history.pushState({}, "", "/");
+	});
+
+	afterEach(() => {
+		cleanup();
+	});
+
+	it("should display 'profile' section when navigating to /settings/profile", async () => {
+		const user = userEvent.setup();
+
+		// Start at login page
+		window.history.pushState({}, "", "/login");
+		render(<App />);
+
+		// Wait for login form to appear
+		await waitFor(() => {
+			expect(screen.getByLabelText(/username/i)).toBeInTheDocument();
+		});
+
+		// Log in
+		const usernameInput = screen.getByLabelText(/username/i);
+		const passwordInput = screen.getByLabelText(/password/i);
+		const loginButton = screen.getByRole("button", { name: /log in/i });
+
+		await user.type(usernameInput, "testuser");
+		await user.type(passwordInput, "password123");
+		await user.click(loginButton);
+
+		// Wait for dashboard
+		await waitFor(() => {
+			expect(screen.getByText(/welcome to the dashboard/i)).toBeInTheDocument();
+		});
+
+		// Navigate to settings/profile by clicking the Settings › Profile button
+		const settingsProfileButton = screen.getByRole("button", { name: /settings › profile/i });
+		await user.click(settingsProfileButton);
+
+		// Small delay to allow routing to process
+		await new Promise((resolve) => setTimeout(resolve, 100));
+
+		await waitFor(
+			() => {
+				const sectionText = screen.getByText(/current section:/i);
+				expect(sectionText.textContent).toContain("profile");
+				expect(sectionText.textContent).not.toContain("general");
+			},
+			{ timeout: 3000 },
+		);
+	});
+
+	it("should display 'general' section when navigating to /settings (no parameter)", async () => {
+		const user = userEvent.setup();
+
+		// Start at login page
+		window.history.pushState({}, "", "/login");
+		render(<App />);
+
+		// Wait for login form
+		await waitFor(() => {
+			expect(screen.getByLabelText(/username/i)).toBeInTheDocument();
+		});
+
+		const usernameInput = screen.getByLabelText(/username/i);
+		const passwordInput = screen.getByLabelText(/password/i);
+		const loginButton = screen.getByRole("button", { name: /log in/i });
+
+		await user.type(usernameInput, "testuser");
+		await user.type(passwordInput, "password123");
+		await user.click(loginButton);
+
+		// Wait for dashboard
+		await waitFor(() => {
+			expect(screen.getByText(/welcome to the dashboard/i)).toBeInTheDocument();
+		});
+
+		// Navigate to settings (no section) by clicking the Settings button
+		const settingsButton = screen.getByRole("button", { name: /^settings$/i });
+		await user.click(settingsButton);
+
+		// Small delay to allow routing to process
+		await new Promise((resolve) => setTimeout(resolve, 100));
+
+		await waitFor(() => {
+			const sectionText = screen.getByText(/current section:/i);
+			expect(sectionText.textContent).toContain("general");
+		});
+	});
+
+	it("should update section display when clicking section navigation buttons", async () => {
+		const user = userEvent.setup();
+
+		// Start at login page
+		window.history.pushState({}, "", "/login");
+		render(<App />);
+
+		// Wait for login form
+		await waitFor(() => {
+			expect(screen.getByLabelText(/username/i)).toBeInTheDocument();
+		});
+
+		// Log in
+		const usernameInput = screen.getByLabelText(/username/i);
+		const passwordInput = screen.getByLabelText(/password/i);
+		const loginButton = screen.getByRole("button", { name: /log in/i });
+
+		await user.type(usernameInput, "testuser");
+		await user.type(passwordInput, "password123");
+		await user.click(loginButton);
+
+		// Navigate to settings
+		await waitFor(() => {
+			expect(screen.getByText(/welcome to the dashboard/i)).toBeInTheDocument();
+		});
+
+		// Navigate to settings by clicking the Settings button
+		const settingsButton = screen.getByRole("button", { name: /^settings$/i });
+		await user.click(settingsButton);
+
+		// Small delay to allow routing to process
+		await new Promise((resolve) => setTimeout(resolve, 100));
+
+		// Wait for settings page
+		await waitFor(() => {
+			expect(screen.getByText(/current section:/i)).toBeInTheDocument();
+		});
+
+		// Initial section should be "general"
+		expect(screen.getByText(/current section: general/i)).toBeInTheDocument();
+
+		// Click "Account" button
+		const accountButton = screen.getByRole("button", { name: /account/i });
+		await user.click(accountButton);
+
+		// Should update to show "account"
+		await waitFor(() => {
+			expect(screen.getByText(/current section: account/i)).toBeInTheDocument();
+		});
+
+		// Click "Privacy" button
+		const privacyButton = screen.getByRole("button", { name: /privacy/i });
+		await user.click(privacyButton);
+
+		// Should update to show "privacy"
+		await waitFor(() => {
+			expect(screen.getByText(/current section: privacy/i)).toBeInTheDocument();
+		});
+	});
+});

package/examples/demo/test/browser/settings-query-freeze.browser.test.ts

@@ -0,0 +1,141 @@
+/**
+ * TDD Test: Settings with Query String Freeze
+ *
+ * GAP: Navigating to /settings/? causes infinite loop and app freeze
+ *
+ * This test validates that the app handles settings URLs with:
+ * - Trailing slashes (/settings/)
+ * - Empty query strings (/settings/?)
+ * - Query parameters (/settings?tab=profile)
+ *
+ * Without causing infinite render loops or freezing.
+ */
+
+import { test, expect } from "vitest";
+import { definePlayer } from "@xmachines/play-xstate";
+import { authMachine } from "../../src/machines/auth-machine.js";
+import { catalog } from "../../src/machines/catalog.js";
+import { SignalSyncedHistory } from "@xmachines/play-tanstack-react-router";
+import { extractMachineRoutes } from "@xmachines/play-router";
+
+test("Settings with trailing slash and empty query string does not freeze", async () => {
+	// Create authenticated actor
+	const createPlayer = definePlayer({ machine: authMachine, catalog });
+	const actor = createPlayer();
+	actor.start();
+
+	// Login to access protected routes
+	actor.send({ type: "auth.login", username: "test", password: "pass" } as any);
+	await new Promise((resolve) => setTimeout(resolve, 50));
+	expect(actor.getSnapshot().matches("dashboard")).toBe(true);
+
+	// Extract route tree for proper route matching
+	const routeTree = extractMachineRoutes(authMachine);
+
+	// Initialize history with route tree
+	const history = new SignalSyncedHistory(actor, routeTree, "/dashboard");
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	// Navigate to settings with trailing slash and empty query
+	// This is the problematic URL that causes the freeze
+	actor.send({ type: "play.route", to: "#settings" } as any);
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// Should be in settings state
+	expect(actor.getSnapshot().matches("settings")).toBe(true);
+
+	// Current route should be normalized (no trailing slash, no empty query)
+	const currentRoute = actor.currentRoute.get();
+	expect(currentRoute).toBe("/settings");
+
+	// Should NOT have caused infinite loop (if we got here, test passed)
+	expect(actor.getSnapshot().context.isAuthenticated).toBe(true);
+
+	history.dispose();
+	actor.stop();
+});
+
+test("Settings with query parameters works correctly", async () => {
+	const createPlayer = definePlayer({ machine: authMachine, catalog });
+	const actor = createPlayer();
+	actor.start();
+
+	actor.send({ type: "auth.login", username: "test", password: "pass" } as any);
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	const routeTree = extractMachineRoutes(authMachine);
+	const history = new SignalSyncedHistory(actor, routeTree, "/dashboard");
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	// Navigate to settings with query parameter
+	actor.send({
+		type: "play.route",
+		to: "#settings",
+		query: { tab: "profile" },
+	} as any);
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	expect(actor.getSnapshot().matches("settings")).toBe(true);
+	expect(actor.currentRoute.get()).toBe("/settings");
+	expect(actor.getSnapshot().context.queryParams).toEqual({ tab: "profile" });
+
+	history.dispose();
+	actor.stop();
+});
+
+test("Settings with section parameter works correctly", async () => {
+	const createPlayer = definePlayer({ machine: authMachine, catalog });
+	const actor = createPlayer();
+	actor.start();
+
+	actor.send({ type: "auth.login", username: "test", password: "pass" } as any);
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	const routeTree = extractMachineRoutes(authMachine);
+	const history = new SignalSyncedHistory(actor, routeTree, "/dashboard");
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	// Navigate to settings with section parameter
+	actor.send({
+		type: "play.route",
+		to: "#settings",
+		params: { section: "profile" },
+	} as any);
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	expect(actor.getSnapshot().matches("settings")).toBe(true);
+	expect(actor.currentRoute.get()).toBe("/settings/profile");
+	expect(actor.getSnapshot().context.routeParams).toEqual({ section: "profile" });
+
+	history.dispose();
+	actor.stop();
+});
+
+test("Direct navigation to /settings/? URL normalizes correctly", async () => {
+	const createPlayer = definePlayer({ machine: authMachine, catalog });
+	const actor = createPlayer();
+	actor.start();
+
+	actor.send({ type: "auth.login", username: "test", password: "pass" } as any);
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	const routeTree = extractMachineRoutes(authMachine);
+	const history = new SignalSyncedHistory(actor, routeTree, "/dashboard");
+	const baseHistory = history.getHistory();
+	await new Promise((resolve) => setTimeout(resolve, 50));
+
+	// Simulate browser direct navigation to problematic URL
+	// This is what happens when user types /settings/? in address bar
+	baseHistory.push("/settings/?");
+	await new Promise((resolve) => setTimeout(resolve, 150));
+
+	// Should navigate to settings state
+	expect(actor.getSnapshot().matches("settings")).toBe(true);
+
+	// URL should be normalized to /settings (no trailing slash, no empty query)
+	const currentRoute = actor.currentRoute.get();
+	expect(currentRoute).toBe("/settings");
+
+	history.dispose();
+	actor.stop();
+});