@atelic-action/ui 0.17.2 → 1.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.17.2",
-	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, and the access gate they install",
+	"version": "1.0.0",
+	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, the access gate, and the app shell they install",
 	"type": "module",
 	"license": "UNLICENSED",
 	"repository": {
@@ -18,8 +18,11 @@
 	],
 	"bin": {
 		"atelic-check-access": "./bin/atelic-check-access.ts",
+		"atelic-check-base-path": "./bin/atelic-check-base-path.ts",
 		"atelic-check-links": "./bin/atelic-check-links.ts",
 		"atelic-check-wall": "./bin/atelic-check-wall.ts",
+		"atelic-clean-sitemap": "./bin/atelic-clean-sitemap.ts",
+		"atelic-contact-canary": "./bin/atelic-contact-canary.ts",
 		"atelic-print-sheets": "./bin/atelic-print-sheets.sh",
 		"atelic-reader-link": "./bin/atelic-reader-link.ts",
 		"atelic-seal-document": "./bin/atelic-seal-document.mjs",
@@ -30,6 +33,8 @@
 		"**/*.css"
 	],
 	"exports": {
+		"./app": "./src/app/index.ts",
+		"./app/ui": "./src/app/ui/index.ts",
 		"./artifact": "./src/artifact/index.ts",
 		"./artifact/readers": {
 			"types": "./dist/artifact/readers.d.ts",
@@ -42,13 +47,20 @@
 		"./hooks": "./src/hooks/index.ts",
 		"./primitives": "./src/primitives/index.ts",
 		"./routing": "./src/routing/index.ts",
+		"./routing/base-path": {
+			"types": "./dist/routing/basePath.d.ts",
+			"default": "./dist/routing/basePath.js"
+		},
+		"./sections": "./src/sections/index.ts",
 		"./tokens": "./src/tokens/index.ts",
+		"./styles/app.css": "./src/styles/app.css",
 		"./styles/artifact.css": "./src/styles/artifact.css",
 		"./styles/base.css": "./src/styles/base.css",
 		"./styles/chrome.css": "./src/styles/chrome.css",
 		"./styles/components.css": "./src/styles/components.css",
 		"./styles/gate.css": "./src/styles/gate.css",
 		"./styles/primitives.css": "./src/styles/primitives.css",
+		"./styles/sections.css": "./src/styles/sections.css",
 		"./styles/star-rating.css": "./src/styles/star-rating.css",
 		"./gate": {
 			"types": "./dist/gate/index.d.ts",
@@ -70,11 +82,15 @@
 			"types": "./dist/vite/index.d.ts",
 			"default": "./dist/vite/index.js"
 		},
+		"./vite/private-chunks": {
+			"types": "./dist/vite/private-chunks.d.ts",
+			"default": "./dist/vite/private-chunks.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"scripts": {
 		"build": "rm -rf dist && tsc -p tsconfig.server.json",
-		"build:smoke": "node --input-type=module -e \"for (const entry of ['gate', 'gate/middleware', 'gate/request-link', 'gate/verify', 'vite', 'artifact/readers']) await import('@atelic-action/ui/' + entry)\"",
+		"build:smoke": "node --input-type=module -e \"for (const entry of ['gate', 'gate/middleware', 'gate/request-link', 'gate/verify', 'vite', 'vite/private-chunks', 'artifact/readers', 'routing/base-path']) await import('@atelic-action/ui/' + entry)\"",
 		"prepack": "bun run build",
 		"lint": "biome check .",
 		"lint:fix": "biome check . --write",
@@ -88,42 +104,185 @@
 		"qrcode": "^1.5.4"
 	},
 	"peerDependencies": {
+		"@radix-ui/react-accordion": "^1.2.12",
+		"@radix-ui/react-alert-dialog": "^1.1.15",
+		"@radix-ui/react-avatar": "^1.1.11",
+		"@radix-ui/react-checkbox": "^1.1.2",
+		"@radix-ui/react-dialog": "^1.1.15",
+		"@radix-ui/react-dropdown-menu": "^2.1.16",
+		"@radix-ui/react-label": "^2.1.8",
+		"@radix-ui/react-popover": "^1.1.15",
+		"@radix-ui/react-progress": "^1.1.8",
+		"@radix-ui/react-select": "^2.2.6",
+		"@radix-ui/react-separator": "^1.1.0",
+		"@radix-ui/react-slider": "^1.3.6",
+		"@radix-ui/react-slot": "^1.2.4",
+		"@radix-ui/react-switch": "^1.2.6",
+		"@radix-ui/react-tooltip": "^1.2.8",
+		"@tanstack/react-query": "^5.59.0",
+		"@tanstack/react-router": "^1.81.4",
 		"@tanstack/react-start": "^1.168.0",
 		"@vitejs/plugin-react": "^5.0.0 || ^6.0.0",
+		"class-variance-authority": "^0.7.0",
+		"clsx": "^2.1.1",
+		"cmdk": "^1.1.1",
+		"country-data-list": "^1.6.0",
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0",
+		"react-circle-flags": "^0.0.25",
 		"react-dom": "^19.0.0",
-		"vite": "^7.0.0 || ^8.0.0"
+		"react-hook-form": "^7.71.1",
+		"sonner": "^2.0.7",
+		"tailwind-merge": "^3.0.0",
+		"tailwindcss": "^4.1.17",
+		"vite": "^7.0.0 || ^8.0.0",
+		"zod": "^4.3.5",
+		"zustand": "^5.0.1"
 	},
 	"peerDependenciesMeta": {
+		"@radix-ui/react-accordion": {
+			"optional": true
+		},
+		"@radix-ui/react-alert-dialog": {
+			"optional": true
+		},
+		"@radix-ui/react-avatar": {
+			"optional": true
+		},
+		"@radix-ui/react-checkbox": {
+			"optional": true
+		},
+		"@radix-ui/react-dialog": {
+			"optional": true
+		},
+		"@radix-ui/react-dropdown-menu": {
+			"optional": true
+		},
+		"@radix-ui/react-label": {
+			"optional": true
+		},
+		"@radix-ui/react-popover": {
+			"optional": true
+		},
+		"@radix-ui/react-progress": {
+			"optional": true
+		},
+		"@radix-ui/react-select": {
+			"optional": true
+		},
+		"@radix-ui/react-separator": {
+			"optional": true
+		},
+		"@radix-ui/react-slider": {
+			"optional": true
+		},
+		"@radix-ui/react-slot": {
+			"optional": true
+		},
+		"@radix-ui/react-switch": {
+			"optional": true
+		},
+		"@radix-ui/react-tooltip": {
+			"optional": true
+		},
+		"@tanstack/react-query": {
+			"optional": true
+		},
+		"@tanstack/react-router": {
+			"optional": true
+		},
 		"@tanstack/react-start": {
 			"optional": true
 		},
 		"@vitejs/plugin-react": {
 			"optional": true
 		},
+		"class-variance-authority": {
+			"optional": true
+		},
+		"clsx": {
+			"optional": true
+		},
+		"cmdk": {
+			"optional": true
+		},
+		"country-data-list": {
+			"optional": true
+		},
+		"react-circle-flags": {
+			"optional": true
+		},
+		"react-hook-form": {
+			"optional": true
+		},
+		"sonner": {
+			"optional": true
+		},
+		"tailwind-merge": {
+			"optional": true
+		},
+		"tailwindcss": {
+			"optional": true
+		},
 		"vite": {
 			"optional": true
+		},
+		"zod": {
+			"optional": true
+		},
+		"zustand": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.13",
+		"@radix-ui/react-accordion": "^1.2.12",
+		"@radix-ui/react-alert-dialog": "^1.1.15",
+		"@radix-ui/react-avatar": "^1.1.11",
+		"@radix-ui/react-checkbox": "^1.1.2",
+		"@radix-ui/react-dialog": "^1.1.15",
+		"@radix-ui/react-dropdown-menu": "^2.1.16",
+		"@radix-ui/react-label": "^2.1.8",
+		"@radix-ui/react-popover": "^1.1.15",
+		"@radix-ui/react-progress": "^1.1.8",
+		"@radix-ui/react-select": "^2.2.6",
+		"@radix-ui/react-separator": "^1.1.0",
+		"@radix-ui/react-slider": "^1.3.6",
+		"@radix-ui/react-slot": "^1.2.4",
+		"@radix-ui/react-switch": "^1.2.6",
+		"@radix-ui/react-tooltip": "^1.2.8",
+		"@tailwindcss/vite": "^4.1.17",
+		"@tanstack/react-query": "^5.59.0",
+		"@tanstack/react-router": "^1.81.4",
 		"@tanstack/react-start": "^1.168.60",
 		"@testing-library/jest-dom": "^6.6.2",
 		"@testing-library/react": "^16.0.1",
+		"@testing-library/user-event": "^14.6.1",
 		"@types/bun": "^1.4.2",
 		"@types/node": "^24.0.0",
 		"@types/qrcode": "^1.5.6",
 		"@types/react": "^19.0.0",
 		"@types/react-dom": "^19.0.0",
 		"@vitejs/plugin-react": "^6.1.1",
+		"class-variance-authority": "^0.7.0",
+		"clsx": "^2.1.1",
+		"cmdk": "^1.1.1",
+		"country-data-list": "^1.6.0",
 		"jsdom": "^25.0.1",
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0",
+		"react-circle-flags": "^0.0.25",
 		"react-dom": "^19.0.0",
+		"react-hook-form": "^7.71.1",
+		"sonner": "^2.0.7",
+		"tailwind-merge": "^3.0.0",
+		"tailwindcss": "^4.1.17",
+		"tailwindcss-animate": "^1.0.7",
 		"typescript": "^5.6.3",
 		"vite": "^8.3.2",
-		"vitest": "^4.0.0"
+		"vitest": "^4.0.0",
+		"zod": "^4.3.5",
+		"zustand": "^5.0.1"
 	},
 	"trustedDependencies": [
 		"@biomejs/biome"

package/src/app/AppProvider.tsx

@@ -0,0 +1,41 @@
+import { type QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { Toaster } from "sonner";
+import { AppConfigProvider, type AppConfigProviderProps } from "./context/AppContext";
+import { SidebarProvider } from "./context/SidebarContext";
+import { UserProvider } from "./context/UserContext";
+import { queryClient as defaultQueryClient } from "./lib/queryClient";
+
+export interface AppProviderProps extends AppConfigProviderProps {
+	/** The query client. Defaults to the shell's, whose mutation cache raises `meta.toast`. */
+	queryClient?: QueryClient;
+	/** The toaster the shell's toasts land in. Defaults to sonner's, top right; `false` renders none. */
+	toaster?: ReactNode | false;
+}
+
+/**
+ * Everything the shell needs above the router: the app's config and nav, the
+ * query client, the rail state, the signed in user, and the toaster. Render
+ * it once, around the `RouterProvider`, so the stores are hydrated before the
+ * first route loads; the root route then renders `AuthGuard` and `AppLayout`.
+ */
+export function AppProvider({
+	config,
+	nav,
+	queryClient = defaultQueryClient,
+	toaster,
+	children,
+}: AppProviderProps) {
+	return (
+		<AppConfigProvider config={config} nav={nav}>
+			<QueryClientProvider client={queryClient}>
+				<SidebarProvider>
+					<UserProvider>
+						{children}
+						{toaster === undefined ? <Toaster position="top-right" richColors /> : toaster || null}
+					</UserProvider>
+				</SidebarProvider>
+			</QueryClientProvider>
+		</AppConfigProvider>
+	);
+}

package/src/app/AuthGuard.tsx

@@ -0,0 +1,27 @@
+import { Navigate, useLocation } from "@tanstack/react-router";
+import type { ReactNode } from "react";
+
+import { isPublicRoute } from "./lib/publicRoutes";
+import { useAuthStore } from "./stores/authStore";
+
+interface AuthGuardProps {
+	children: ReactNode;
+}
+
+/**
+ * Protects routes that require authentication. What a signed out visitor may
+ * load is the app's call, read through publicRoutes.ts: the exact public
+ * routes ("/" doubles as the sign in surface, "/oauth/callback" lands the
+ * redirect) and the public page patterns. Everything else redirects to "/",
+ * which renders the adaptive auth page.
+ */
+export function AuthGuard({ children }: AuthGuardProps) {
+	const isAuthenticated = useAuthStore((state) => state.isAuthenticated);
+	const pathname = useLocation({ select: (location) => location.pathname });
+
+	if (!isAuthenticated && !isPublicRoute(pathname)) {
+		return <Navigate to="/" />;
+	}
+
+	return <>{children}</>;
+}

package/src/app/CardErrorBoundary.tsx

@@ -0,0 +1,39 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+import { Card, CardContent } from "./ui/card";
+
+interface Props {
+	children: ReactNode;
+}
+
+interface State {
+	hasError: boolean;
+}
+
+export class CardErrorBoundary extends Component<Props, State> {
+	constructor(props: Props) {
+		super(props);
+		this.state = { hasError: false };
+	}
+
+	static getDerivedStateFromError(): State {
+		return { hasError: true };
+	}
+
+	componentDidCatch(error: Error, info: ErrorInfo) {
+		console.error("CardErrorBoundary caught:", error, info.componentStack);
+	}
+
+	render() {
+		if (this.state.hasError) {
+			return (
+				<Card className="border-destructive/30">
+					<CardContent className="py-6 text-center text-sm text-muted-foreground">
+						Unable to display this item
+					</CardContent>
+				</Card>
+			);
+		}
+
+		return this.props.children;
+	}
+}

package/src/app/ErrorFallback.tsx

@@ -0,0 +1,39 @@
+import { Button } from "./ui/button";
+
+export interface ErrorFallbackProps {
+	error: unknown;
+	resetError: () => void;
+	/**
+	 * Show the error's message under the apology. The package reads no
+	 * environment, so an app passes `import.meta.env.DEV` here to see it while
+	 * developing and never in production.
+	 */
+	showDetails?: boolean;
+}
+
+/**
+ * Fallback UI displayed when an error boundary catches an error.
+ * Provides user feedback and a way to recover.
+ */
+export function ErrorFallback({ error, resetError, showDetails = false }: ErrorFallbackProps) {
+	const errorMessage = error instanceof Error ? error.message : "Unknown error";
+
+	return (
+		<div className="flex min-h-screen items-center justify-center bg-background p-4">
+			<div className="max-w-md text-center">
+				<h1 className="text-2xl font-semibold text-foreground">Something went wrong</h1>
+				<p className="mt-2 text-sm text-muted-foreground">
+					An unexpected error occurred. Please try again.
+				</p>
+				{showDetails && (
+					<pre className="mt-4 max-h-40 overflow-auto rounded bg-muted p-3 text-left text-xs text-muted-foreground">
+						{errorMessage}
+					</pre>
+				)}
+				<Button onClick={resetError} className="mt-6">
+					Try Again
+				</Button>
+			</div>
+		</div>
+	);
+}

package/src/app/GoogleGlyph.tsx

@@ -0,0 +1,22 @@
+export function GoogleGlyph({ className }: { className?: string }) {
+	return (
+		<svg className={className} viewBox="0 0 48 48" aria-hidden="true">
+			<path
+				fill="#FFC107"
+				d="M43.611 20.083H42V20H24v8h11.303c-1.649 4.657-6.08 8-11.303 8-6.627 0-12-5.373-12-12s5.373-12 12-12c3.059 0 5.842 1.154 7.961 3.039l5.657-5.657C34.046 6.053 29.268 4 24 4 12.955 4 4 12.955 4 24s8.955 20 20 20 20-8.955 20-20c0-1.341-.138-2.65-.389-3.917z"
+			/>
+			<path
+				fill="#FF3D00"
+				d="M6.306 14.691l6.571 4.819C14.655 15.108 18.961 12 24 12c3.059 0 5.842 1.154 7.961 3.039l5.657-5.657C34.046 6.053 29.268 4 24 4 16.318 4 9.656 8.337 6.306 14.691z"
+			/>
+			<path
+				fill="#4CAF50"
+				d="M24 44c5.166 0 9.86-1.977 13.409-5.192l-6.19-5.238C29.211 35.091 26.715 36 24 36c-5.202 0-9.619-3.317-11.283-7.946l-6.522 5.025C9.505 39.556 16.227 44 24 44z"
+			/>
+			<path
+				fill="#1976D2"
+				d="M43.611 20.083H42V20H24v8h11.303c-.792 2.237-2.231 4.166-4.094 5.571.001-.001.002-.001.003-.002l6.19 5.238C36.971 39.205 44 34 44 24c0-1.341-.138-2.65-.389-3.917z"
+			/>
+		</svg>
+	);
+}

package/src/app/config.ts

@@ -0,0 +1,54 @@
+/**
+ * What makes an app that app, as the shell reads it: the name on the mark and
+ * in aria labels, the prefix on every browser storage key, the routes a signed
+ * out visitor may see, and the api the transport talks to. The app owns the
+ * values and hands them to `AppProvider`, which records them here, since the
+ * transport and the stores run outside React and read them by function.
+ */
+export interface AppConfig {
+	/** Display name, used in aria labels. */
+	name: string;
+	/** The lowercase wordmark the shell renders beside the brand dot. */
+	mark: string;
+	/** Prefix for every localStorage key and cookie the shell writes. */
+	storagePrefix: string;
+	/** Exact routes a signed out visitor can load bare; everything else redirects home. */
+	publicRoutes: readonly string[];
+	/**
+	 * Pages that stand on their own signed out, as prefix patterns ending in
+	 * "/*". They render inside the public chrome (brand bar, sign in link) for
+	 * a visitor and inside the app shell for the signed in owner. The
+	 * convention is a person's public records under /u/<username>/...
+	 */
+	publicPages?: readonly string[];
+	/**
+	 * The api's base URL, resolved by the app (typically
+	 * `import.meta.env.VITE_API_BASE_URL ?? "https://api.example.com"`), so the
+	 * package never reads the app's environment itself.
+	 */
+	apiBaseUrl: string;
+	/** Where the Profile link in the rail menu and the mobile menu goes. Defaults to "/profile". */
+	profileHref?: string;
+}
+
+let current: AppConfig | null = null;
+
+/** Record the app's config. `configureApp` (or `AppProvider`) calls this; the stores rehydrate there. */
+export function setAppConfig(config: AppConfig): void {
+	current = config;
+}
+
+/** The app's config, or null before `configureApp` has run. */
+export function peekAppConfig(): AppConfig | null {
+	return current;
+}
+
+/** The app's config. Throws when the app has not configured the shell yet. */
+export function getAppConfig(): AppConfig {
+	if (!current) {
+		throw new Error(
+			"The app shell is not configured: render AppProvider (or call configureApp) before using the transport.",
+		);
+	}
+	return current;
+}

package/src/app/configure.ts

@@ -0,0 +1,18 @@
+import { type AppConfig, peekAppConfig, setAppConfig } from "./config";
+import { useAuthStore } from "./stores/authStore";
+import { useUnitsStore } from "./stores/unitsStore";
+
+/**
+ * Hand the shell the app's config, and hydrate the persisted stores under its
+ * storage prefix. `AppProvider` calls this on its first render, which covers
+ * an app that renders it above its router. Call it yourself only where shell
+ * code runs before that render: a module that calls the api at import, or a
+ * test. Safe to call again; the stores rehydrate only when the prefix changes.
+ */
+export function configureApp(config: AppConfig): void {
+	const previous = peekAppConfig();
+	setAppConfig(config);
+	if (previous?.storagePrefix === config.storagePrefix) return;
+	void useAuthStore.persist.rehydrate();
+	void useUnitsStore.persist.rehydrate();
+}

package/src/app/context/AppContext.tsx

@@ -0,0 +1,52 @@
+import { createContext, type ReactNode, useContext, useMemo, useRef } from "react";
+import { type AppConfig, getAppConfig } from "../config";
+import { configureApp } from "../configure";
+import type { NavItem } from "../layout/nav";
+
+interface AppContextValue {
+	config: AppConfig;
+	nav: NavItem[];
+}
+
+const AppContext = createContext<AppContextValue | null>(null);
+
+export interface AppConfigProviderProps {
+	/** The app's facts: name, mark, storage prefix, public routes, api base URL. */
+	config: AppConfig;
+	/** The sections and sub pages, in nav order: the one place a destination is declared. */
+	nav: NavItem[];
+	children: ReactNode;
+}
+
+/**
+ * The app's config and nav, and nothing else: what the frame (the rail, the
+ * tab bar, the menu sheet, a section's cards) reads. `AppProvider` wraps it
+ * with the query client, the rail state, the signed in user, and the toaster;
+ * a test that mounts one surface can use it alone.
+ */
+export function AppConfigProvider({ config, nav, children }: AppConfigProviderProps) {
+	// Configure synchronously on the first render, and again if the config
+	// object changes, so the stores hydrate under the app's prefix before any
+	// child reads them.
+	const configured = useRef<AppConfig | null>(null);
+	if (configured.current !== config) {
+		configureApp(config);
+		configured.current = config;
+	}
+	const value = useMemo(() => ({ config, nav }), [config, nav]);
+	return <AppContext.Provider value={value}>{children}</AppContext.Provider>;
+}
+
+/** The app's config, from the nearest provider, or as configured with `configureApp`. */
+export function useAppConfig(): AppConfig {
+	return useContext(AppContext)?.config ?? getAppConfig();
+}
+
+/** The app's nav items. Throws outside an `AppProvider` or `AppConfigProvider`. */
+export function useNav(): NavItem[] {
+	const context = useContext(AppContext);
+	if (!context) {
+		throw new Error("useNav must be used within an AppProvider");
+	}
+	return context.nav;
+}

package/src/app/context/SidebarContext.tsx

@@ -0,0 +1,124 @@
+import {
+	createContext,
+	type ReactNode,
+	useCallback,
+	useContext,
+	useEffect,
+	useMemo,
+	useState,
+} from "react";
+import { peekAppConfig } from "../config";
+
+interface SidebarContextType {
+	isCollapsed: boolean;
+	toggleSidebar: () => void;
+	setCollapsed: (collapsed: boolean) => void;
+	/** Right (AppPage) rail collapse — mirrors the left nav rail. */
+	isRailCollapsed: boolean;
+	toggleRail: () => void;
+	setRailCollapsed: (collapsed: boolean) => void;
+}
+
+const SidebarContext = createContext<SidebarContextType | undefined>(undefined);
+
+interface SidebarProviderProps {
+	children: ReactNode;
+}
+
+const SIDEBAR_KEY = "sidebarCollapsed";
+const RAIL_KEY = "railCollapsed";
+
+/** localStorage under the app's prefix; a no op before the app is configured or where storage is refused. */
+function readSaved(name: string): boolean {
+	const config = peekAppConfig();
+	if (!config) return false;
+	try {
+		return localStorage.getItem(config.storagePrefix + "-" + name) === "true";
+	} catch {
+		return false;
+	}
+}
+
+function writeSaved(name: string, value: boolean) {
+	const config = peekAppConfig();
+	if (!config) return;
+	try {
+		localStorage.setItem(config.storagePrefix + "-" + name, String(value));
+	} catch {
+		// Storage refused; the state lives in memory for this visit.
+	}
+}
+
+export function SidebarProvider({ children }: SidebarProviderProps) {
+	// Both start open so a prerender and the first client render agree; the
+	// saved choice is read in an effect, then written back on every change.
+	const [isCollapsed, setIsCollapsed] = useState(false);
+	const [isRailCollapsed, setIsRailCollapsed] = useState(false);
+	const [ready, setReady] = useState(false);
+
+	useEffect(() => {
+		setIsCollapsed(readSaved(SIDEBAR_KEY));
+		setIsRailCollapsed(readSaved(RAIL_KEY));
+		setReady(true);
+	}, []);
+
+	useEffect(() => {
+		if (ready) writeSaved(SIDEBAR_KEY, isCollapsed);
+	}, [ready, isCollapsed]);
+
+	useEffect(() => {
+		if (ready) writeSaved(RAIL_KEY, isRailCollapsed);
+	}, [ready, isRailCollapsed]);
+
+	const toggleSidebar = useCallback(() => {
+		setIsCollapsed((prev) => !prev);
+	}, []);
+
+	const setCollapsed = useCallback((collapsed: boolean) => {
+		setIsCollapsed(collapsed);
+	}, []);
+
+	const toggleRail = useCallback(() => {
+		setIsRailCollapsed((prev) => !prev);
+	}, []);
+
+	const setRailCollapsed = useCallback((collapsed: boolean) => {
+		setIsRailCollapsed(collapsed);
+	}, []);
+
+	const value = useMemo(
+		() => ({
+			isCollapsed,
+			toggleSidebar,
+			setCollapsed,
+			isRailCollapsed,
+			toggleRail,
+			setRailCollapsed,
+		}),
+		[isCollapsed, toggleSidebar, setCollapsed, isRailCollapsed, toggleRail, setRailCollapsed],
+	);
+
+	return <SidebarContext.Provider value={value}>{children}</SidebarContext.Provider>;
+}
+
+export function useSidebar() {
+	const context = useContext(SidebarContext);
+	if (context === undefined) {
+		throw new Error("useSidebar must be used within a SidebarProvider");
+	}
+	return context;
+}
+
+/**
+ * Tolerant accessor for the right-rail collapse state. Unlike `useSidebar`, it
+ * does NOT throw when used outside a `SidebarProvider`: AppPage surfaces are
+ * mounted bare in unit tests, so the rail toggle simply degrades to a no-op
+ * there rather than blowing up the render.
+ */
+export function useRail() {
+	const context = useContext(SidebarContext);
+	return {
+		isRailCollapsed: context?.isRailCollapsed ?? false,
+		toggleRail: context?.toggleRail ?? (() => {}),
+	};
+}