docs: fix inconsistencies between docs and implementation (#20)

Author: uhyo

README.md

@@ -46,7 +46,7 @@ pnpm test
 ## Quick Start
 
 ```tsx
-import { Router, Outlet, useParams } from "@funstack/router";
+import { Router, Outlet } from "@funstack/router";
 import type { RouteDefinition } from "@funstack/router";
 
 function Layout() {
@@ -70,9 +70,8 @@ function Users() {
   return <h1>Users</h1>;
 }
 
-function UserDetail() {
-  const { id } = useParams<{ id: string }>();
-  return <h1>User {id}</h1>;
+function UserDetail({ params }: { params: { id: string } }) {
+  return <h1>User {params.id}</h1>;
 }
 
 const routes: RouteDefinition[] = [
@@ -104,10 +103,11 @@ The root component that provides routing context.
 <Router routes={routes} />
 ```
 
-| Prop       | Type                | Description                                 |
-| ---------- | ------------------- | ------------------------------------------- |
-| `routes`   | `RouteDefinition[]` | Array of route definitions                  |
-| `children` | `ReactNode`         | Optional children rendered alongside routes |
+| Prop         | Type                 | Description                                                          |
+| ------------ | -------------------- | -------------------------------------------------------------------- |
+| `routes`     | `RouteDefinition[]`  | Array of route definitions                                           |
+| `onNavigate` | `OnNavigateCallback` | Optional callback invoked before navigation is intercepted           |
+| `fallback`   | `FallbackMode`       | Fallback mode when Navigation API is unavailable (default: `"none"`) |
 
 #### `<Outlet>`
 
@@ -151,7 +151,7 @@ const location = useLocation();
 
 #### `useParams()`
 
-Returns the current route's path parameters.
+Returns the current route's path parameters. Note that route components also receive `params` as a prop, so this hook is mainly useful for non-route components that need access to params.
 
 ```tsx
 // Route: /users/:id
@@ -182,10 +182,31 @@ setSearchParams((prev) => {
 
 #### `RouteDefinition`
 
+Route components receive a `params` prop with the matched path parameters. Use the `route()` helper for type-safe route definitions:
+
+```typescript
+import { route } from "@funstack/router";
+
+// Route without loader - component receives params prop
+route({
+  path: "users/:id",
+  component: UserDetail, // receives { params: { id: string } }
+});
+
+// Route with loader - component receives both data and params props
+route({
+  path: "users/:id",
+  loader: async ({ params }) => fetchUser(params.id),
+  component: UserDetail, // receives { data: Promise<User>, params: { id: string } }
+});
+```
+
+You can also define routes as plain objects (without type inference):
+
 ```typescript
 type RouteDefinition = {
   path: string;
-  component?: React.ComponentType;
+  component?: React.ComponentType<{ params: Record<string, string> }>;
   children?: RouteDefinition[];
 };
 ```

docs/DATA_LOADER_ARCHITECTURE.md

@@ -13,19 +13,19 @@ The router passes whatever the loader returns (Promise or value) to the componen
 ### Route Definition
 
 ```typescript
-type RouteDefinition<TData = unknown> = {
-  path: string;
+type RouteDefinition<TPath extends string = string, TData = unknown> = {
+  path: TPath;
   children?: RouteDefinition[];
 } & (
   | {
-      // Route with loader - component receives data prop
+      // Route with loader - component receives data and params props
       loader: (args: LoaderArgs) => TData;
-      component: ComponentType<{ data: TData }>;
+      component: ComponentType<{ data: TData; params: PathParams<TPath> }>;
     }
   | {
-      // Route without loader - component receives no data prop
+      // Route without loader - component receives params prop only
       loader?: never;
-      component?: ComponentType;
+      component?: ComponentType<{ params: PathParams<TPath> }>;
     }
 );
 
@@ -38,25 +38,25 @@ type LoaderArgs = {
 
 ### Route Definition Helper
 
-Using `RouteDefinition[]` directly loses type inference for each route's `TData`. A helper function preserves the inferred types:
+Using `RouteDefinition[]` directly loses type inference for each route's `TData` and params. A helper function preserves the inferred types:
 
 ```typescript
-// Helper for routes with loader - infers TData from loader return type
-function route<TData>(definition: {
-  path: string;
+// Helper for routes with loader - infers TData from loader return type, params from path
+function route<TPath extends string, TData>(definition: {
+  path: TPath;
   loader: (args: LoaderArgs) => TData;
-  component: ComponentType<{ data: TData }>;
+  component: ComponentType<{ data: TData; params: PathParams<TPath> }>;
   children?: RouteDefinition[];
-}): RouteDefinition<TData> {
+}): RouteDefinition<TPath, TData> {
   return definition;
 }
 
-// Helper for routes without loader
-function route(definition: {
-  path: string;
-  component?: ComponentType;
+// Helper for routes without loader - infers params from path
+function route<TPath extends string>(definition: {
+  path: TPath;
+  component?: ComponentType<{ params: PathParams<TPath> }>;
   children?: RouteDefinition[];
-}): RouteDefinition {
+}): RouteDefinition<TPath> {
   return definition;
 }
 ```
@@ -72,45 +72,50 @@ const routes = [
       const res = await fetch(`/api/users/${params.userId}`, { signal });
       return res.json() as User;
     },
-    // ✅ TypeScript knows component must accept { data: Promise<User> }
+    // ✅ TypeScript knows component must accept { data: Promise<User>, params: { userId: string } }
   }),
   route({
     path: "settings",
     component: SettingsPage,
     loader: () => getSettingsFromLocalStorage(),
-    // ✅ TypeScript infers TData from loader return type
+    // ✅ TypeScript infers TData from loader return type, params from path
   }),
   route({
     path: "about",
     component: AboutPage,
-    // ✅ No loader, no data prop required
+    // ✅ No loader, component receives { params: {} }
   }),
 ];
 ```
 
-Without the helper, all routes would have `TData = unknown`, breaking type safety between loader and component.
+Without the helper, all routes would have `TData = unknown` and `params = Record<string, string>`, breaking type safety between loader and component.
 
 ### Component Access
 
-Components receive the loader result directly as a `data` prop:
+Components receive the loader result directly as a `data` prop, along with a `params` prop containing the matched path parameters:
 
 ```typescript
-// Async loader - component receives Promise
-function UserDetail({ data }: { data: Promise<User> }) {
+// Async loader - component receives Promise and params
+function UserDetail({ data, params }: { data: Promise<User>; params: { userId: string } }) {
   const user = use(data); // Suspends until resolved
-  return <div>{user.name}</div>;
+  return <div>{user.name} (ID: {params.userId})</div>;
 }
 
-// Sync loader - component receives value directly
-function SettingsPage({ data }: { data: Settings }) {
+// Sync loader - component receives value and params directly
+function SettingsPage({ data, params }: { data: Settings; params: {} }) {
   return <div>{data.theme}</div>;
 }
+
+// No loader - component receives only params
+function AboutPage({ params }: { params: {} }) {
+  return <div>About</div>;
+}
 ```
 
 **Advantages of props over hooks**:
 
 1. Explicit dependency - component signature shows what it receives
-2. Better TypeScript inference - prop type tied to loader's return type
+2. Better TypeScript inference - prop types tied to loader's return type and path pattern
 3. No context lookup overhead
 4. Simpler implementation
 5. Flexible - works with both sync and async loaders
@@ -139,10 +144,20 @@ function App() {
   );
 }
 
-// Component receives Promise, uses `use()` to suspend
-function UserDetail({ data }: { data: Promise<User> }) {
+// Component receives Promise and params, uses `use()` to suspend
+function UserDetail({
+  data,
+  params,
+}: {
+  data: Promise<User>;
+  params: { userId: string };
+}) {
   const user = use(data);
-  return <div>{user.name}</div>;
+  return (
+    <div>
+      {user.name} (ID: {params.userId})
+    </div>
+  );
 }
 ```
 
@@ -157,7 +172,7 @@ const routes: RouteDefinition[] = [
 ];
 
 // No Suspense needed for sync loaders
-function SettingsPage({ data }: { data: Settings }) {
+function SettingsPage({ data, params }: { data: Settings; params: {} }) {
   return <div>{data.theme}</div>;
 }
 ```
@@ -227,12 +242,18 @@ type MatchedRouteWithData = MatchedRoute & {
 type LoaderFunction<TData = unknown> = (args: LoaderArgs) => TData;
 
 // Component prop type (when loader is defined)
-type RouteComponentProps<TData = unknown> = {
+type RouteComponentProps<TPath extends string, TData = unknown> = {
   data: TData;
+  params: PathParams<TPath>;
+};
+
+// Component prop type (when loader is not defined)
+type RouteComponentPropsNoLoader<TPath extends string> = {
+  params: PathParams<TPath>;
 };
 ```
 
-Note: RouteContext remains unchanged - it doesn't need to store the data since it's passed directly as a prop.
+Note: RouteContext remains unchanged - it doesn't need to store the data since it's passed directly as a prop. Params are also passed as props for consistency and type safety.
 
 ### 3. Loader Execution Strategy
 
@@ -279,8 +300,12 @@ function RouteRenderer({
   return (
     <RouteContext.Provider value={routeContextValue}>
       {Component ? (
-        // Pass data as prop if loader exists
-        data !== undefined ? <Component data={data} /> : <Component />
+        // Always pass params, pass data only if loader exists
+        route.loader ? (
+          <Component data={data} params={params} />
+        ) : (
+          <Component params={params} />
+        )
       ) : (
         outlet
       )}
@@ -488,19 +513,24 @@ const data = useLoaderData(); // Returns resolved data
 
 ### FUNSTACK Router (This Design)
 
-FUNSTACK passes loader result as a prop, component handles it:
+FUNSTACK passes loader result and params as props, component handles them:
 
 ```typescript
-// FUNSTACK - async loader, component receives Promise
-function UserDetail({ data }: { data: Promise<User> }) {
+// FUNSTACK - async loader, component receives Promise and params
+function UserDetail({ data, params }: { data: Promise<User>; params: { userId: string } }) {
   const user = use(data); // Component chooses when to suspend
-  return <div>{user.name}</div>;
+  return <div>{user.name} (ID: {params.userId})</div>;
 }
 
-// FUNSTACK - sync loader, component receives value directly
-function SettingsPage({ data }: { data: Settings }) {
+// FUNSTACK - sync loader, component receives value and params directly
+function SettingsPage({ data, params }: { data: Settings; params: {} }) {
   return <div>{data.theme}</div>;
 }
+
+// FUNSTACK - no loader, component receives only params
+function AboutPage({ params }: { params: {} }) {
+  return <div>About</div>;
+}
 ```
 
 **Advantages of our approach**:
@@ -517,7 +547,8 @@ function SettingsPage({ data }: { data: Settings }) {
 The data loader feature adds:
 
 1. `loader` property on route definitions (can return Promise or value)
-2. `data` prop passed to route components
-3. Loader result caching to prevent duplicate execution
+2. `data` prop passed to route components (when loader is defined)
+3. `params` prop passed to all route components (with types inferred from path pattern)
+4. Loader result caching to prevent duplicate execution
 
-Components receive loader results as props and handle Promises with React's `use()` hook when needed, giving maximum flexibility while keeping the router simple.
+Components receive loader results and params as props and handle Promises with React's `use()` hook when needed, giving maximum flexibility while keeping the router simple.

docs/architecture.md

@@ -206,8 +206,10 @@ const page = searchParams.get("page");
 ```typescript
 // Main router context
 type RouterContextValue = {
-  // Current navigation state
-  currentEntry: NavigationHistoryEntry;
+  // Current location entry (abstracted for fallback mode compatibility)
+  locationEntry: LocationEntry;
+  // Current URL
+  url: URL;
   // Navigation function
   navigate: (to: string, options?: NavigateOptions) => void;
 };
@@ -278,6 +280,8 @@ src/
 ├── index.ts                 # Public exports
 ├── Router.tsx               # <Router> provider component
 ├── Outlet.tsx               # <Outlet> component
+├── route.ts                 # Route definition helper with type inference
+├── types.ts                 # Shared type definitions
 ├── hooks/
 │   ├── useNavigate.ts
 │   ├── useLocation.ts
@@ -286,10 +290,14 @@ src/
 ├── context/
 │   ├── RouterContext.ts     # Main router context
 │   └── RouteContext.ts      # Route matching context
-├── core/
-│   ├── matchRoutes.ts       # Route matching logic
-│   └── pathPattern.ts       # Path pattern parsing
-└── types.ts                 # Shared type definitions
+└── core/
+    ├── matchRoutes.ts       # Route matching logic
+    ├── loaderCache.ts       # Loader result caching
+    ├── RouterAdapter.ts     # Adapter interface for navigation modes
+    ├── NavigationAPIAdapter.ts  # Navigation API implementation
+    ├── StaticAdapter.ts     # Fallback static mode implementation
+    ├── NullAdapter.ts       # Null adapter (no-op)
+    └── createAdapter.ts     # Adapter factory
 ```
 
 ## Browser Support
@@ -298,19 +306,15 @@ The Navigation API is supported in:
 
 - Chrome 102+
 - Edge 102+
+- Safari 26.2+
 - Opera 88+
 
-For unsupported browsers (Firefox, Safari), a polyfill or fallback strategy will be needed. Options:
+Firefox does not yet support the Navigation API.
 
-1. Use the `navigation-api-polyfill` package
-2. Provide a History API fallback mode
-3. Require polyfill as peer dependency
-
-**Initial implementation will target Navigation API-supporting browsers only.**
+For unsupported browsers, use the `fallback="static"` option on the Router component, which renders matched routes without SPA navigation capabilities (links cause full page loads).
 
 ## Future Considerations
 
-- **Data loading**: Route-based data fetching (loaders)
 - **Pending UI**: Navigation state for loading indicators
 - **View Transitions**: Integration with View Transitions API
 - **Scroll restoration**: Automatic scroll position management