@sigmela/router 0.1.3 → 0.2.0

package/README.md

@@ -1,57 +1,55 @@
-# React Native Router
+# Sigmela Router (`@sigmela/router`)
 
-Modern, lightweight, and type-safe navigation for React Native and Web built on top of react-native-screens. Predictable stack-based architecture with tabs, global modals, sheets, controllers, and full Web History API integration.
+Modern, lightweight navigation for **React Native** and **Web**, built on top of [`react-native-screens`](https://github.com/software-mansion/react-native-screens).
+
+This library is **URL-first**: you navigate by **paths** (`/users/42?tab=posts`), and the router derives `params` and `query` for screens.
 
 ## Features
 
-- 🪶 **Lightweight**: minimal dependencies, small bundle size
-- ⚡ **Fast & performant**: optimized for performance with minimal re-renders
-- 🔗 **URL-first navigation**: path as source of truth, params in URL
-- 🛡️ **Type safety**: typed `useParams` and `useQueryParams`
-- ⛓️ **Chainable API**: `new NavigationStack().addScreen('/users/:id', User)`
-- 📱 **Sheets & modals**: native presentation styles including iOS/Android sheets
-- 🎯 **Bottom tabs**: native and web renderers, custom tab bars
-- 🌍 **Global stack**: modals and overlays on top of main navigation
-- 🎮 **Controllers**: async navigation with guards and data prefetch
-- 🌐 **Web History API**: full synchronization with pushState/replaceState/popstate
-- 🔗 **Deep linking**: automatic stack construction from nested URLs
-- 🔄 **Dynamic root**: switch between stacks at runtime (auth flows)
-- 🎨 **Appearance control**: customize tabs, headers and screens
-
-## 📦 Installation
+- **Stacks**: predictable stack-based navigation
+- **Tabs**: `TabBar` with native + web renderers (or custom tab bar)
+- **Split view**: master/details navigation (`SplitView`)
+- **Modals & sheets**: via `stackPresentation` (`modal`, `sheet`, …)
+- **Controllers**: async/guarded navigation (only present when ready)
+- **Web History integration**: keeps Router state in sync with `pushState`, `replaceState`, `popstate`
+- **Dynamic root**: swap root navigation tree at runtime (`router.setRoot`)
+- **Type-safe hooks**: `useParams`, `useQueryParams`, `useRoute`, `useCurrentRoute`
+
+## Installation
 
 ```bash
-yarn add @sigmela/router @sigmela/native-sheet react-native-screens
-# or
-npm i @sigmela/router @sigmela/native-sheet react-native-screens
+yarn add @sigmela/router react-native-screens
+# optional (required only if you use sheet presentation)
+yarn add @sigmela/native-sheet
 ```
 
-### 📋 Dependencies
+### Peer dependencies
 
-- `react-native-screens` >= 4.16.0
-- `@sigmela/native-sheet` >= 0.0.1 (optional, required for sheets)
-- `react` and `react-native` (matching your app versions)
+- `react`
+- `react-native`
+- `react-native-screens` (>= `4.18.0`)
+- `@sigmela/native-sheet` (>= `0.0.1`) — only if you use sheets
 
-### 🌐 Web CSS
+### Web CSS
 
-For web, import the bundled stylesheet once in your entry point:
+On web you must import the bundled stylesheet **once**:
 
 ```ts
 import '@sigmela/router/styles.css';
 ```
 
-## 🚀 Quick Start
+## Quick start
 
-### 📄 Simple Stack
+### Simple stack
 
 ```tsx
 import {
+  Navigation,
   NavigationStack,
   Router,
-  Navigation,
-  useRouter,
   useParams,
   useQueryParams,
+  useRouter,
 } from '@sigmela/router';
 
 function HomeScreen() {
@@ -81,910 +79,256 @@ export default function App() {
 }
 ```
 
-### 🎯 Tabs + Global Stack
+### Tabs
 
 ```tsx
-import { NavigationStack, Router, Navigation, TabBar } from '@sigmela/router';
+import { Navigation, NavigationStack, Router, TabBar } from '@sigmela/router';
 
-const homeStack = new NavigationStack().addScreen('/', HomeScreen, {
-  header: { title: 'Home' },
-});
+const homeStack = new NavigationStack().addScreen('/', HomeScreen);
 
 const catalogStack = new NavigationStack()
-  .addScreen('/catalog', CatalogScreen, { header: { title: 'Catalog' } })
-  .addScreen('/catalog/products/:productId', ProductScreen, {
-    header: { title: 'Product' },
-  });
+  .addScreen('/catalog', CatalogScreen)
+  .addScreen('/catalog/products/:productId', ProductScreen);
+
+const tabBar = new TabBar({ initialIndex: 0 })
+  .addTab({ key: 'home', stack: homeStack, title: 'Home' })
+  .addTab({ key: 'catalog', stack: catalogStack, title: 'Catalog' });
+
+const router = new Router({ root: tabBar });
+
+export default function App() {
+  return <Navigation router={router} />;
+}
+```
+
+### Tabs wrapped by a root stack (like `example/src/navigation/stacks.ts`)
 
-const globalStack = new NavigationStack()
-  .addModal('/auth', AuthScreen, { header: { title: 'Sign in' } });
+In the example app, tabs are mounted as a **screen** inside a root `NavigationStack`. This lets you keep tab navigation plus define modals/overlays at the root level.
+
+```tsx
+import { NavigationStack, TabBar } from '@sigmela/router';
+
+const homeStack = new NavigationStack().addScreen('/', HomeScreen);
+const catalogStack = new NavigationStack().addScreen('/catalog', CatalogScreen);
 
 const tabBar = new TabBar()
   .addTab({
     key: 'home',
     stack: homeStack,
     title: 'Home',
-    icon: { sfSymbolName: 'house' }, // iOS SF Symbols
+    icon: require('./assets/home.png'),
   })
   .addTab({
     key: 'catalog',
     stack: catalogStack,
     title: 'Catalog',
-    icon: { sfSymbolName: 'bag' },
+    icon: require('./assets/catalog.png'),
   });
 
-const router = new Router({ root: tabBar, global: globalStack });
-
-export default function App() {
-  return <Navigation router={router} />;
-}
+// Root stack hosts the tab bar AND top-level modals/overlays.
+export const rootStack = new NavigationStack()
+  .addScreen('/', tabBar)
+  .addModal('/auth', AuthScreen, { header: { title: 'Login', hidden: true } })
+  .addModal('*?modal=promo', PromoModal);
 ```
 
-## 🧩 Core Concepts
-
-### 📚 Navigation Stack
+## Core concepts
 
-A `NavigationStack` is a container for screens. Stacks can be used as the root, inside tabs, or as a global overlay.
+### `NavigationStack`
 
-```tsx
-const stack = new NavigationStack()
-  .addScreen('/path', Component, options)
-  .addModal('/modal', ModalComponent, options)
-  .addSheet('/sheet', SheetComponent, options);
-```
+A `NavigationStack` defines a set of routes and how to match them.
 
-**Constructor overloads:**
 ```tsx
-new NavigationStack()
-new NavigationStack(id: string)
-new NavigationStack(defaultOptions: ScreenOptions)
-new NavigationStack(id: string, defaultOptions: ScreenOptions)
+const stack = new NavigationStack({ header: { largeTitle: true } })
+  .addScreen('/feed', FeedScreen)
+  .addScreen('/feed/:id', FeedItemScreen)
+  .addModal('/auth', AuthScreen)
+  .addSheet('/settings', SettingsSheet);
 ```
 
-**Methods:**
-- `addScreen(path, component, options?)` — add a regular screen
-- `addModal(path, component, options?)` — add a modal (shorthand for `stackPresentation: 'modal'`)
-- `addSheet(path, component, options?)` — add a sheet (shorthand for `stackPresentation: 'sheet'`)
-- `getId()` — get the unique stack ID
-- `getRoutes()` — get all routes in the stack
-- `getFirstRoute()` — get the first route (used for initial seeding)
-- `getDefaultOptions()` — get default options for all screens in this stack
+Key methods:
+- `addScreen(pathPattern, componentOrNode, options?)`
+- `addModal(pathPattern, component, options?)` (shorthand for `stackPresentation: 'modal'`)
+- `addSheet(pathPattern, component, options?)` (shorthand for `stackPresentation: 'sheet'`)
+- `addStack(prefixOrStack, maybeStack?)` — compose nested stacks under a prefix
 
-### 🧭 Router
+### `Router`
 
-The `Router` manages navigation state and history.
+The `Router` holds navigation state and performs path matching.
 
-```tsx
+```ts
 const router = new Router({
-  root: tabBar | stack,        // TabBar or NavigationStack
-  global?: stack,               // Optional global overlay stack
-  screenOptions?: ScreenOptions // Global screen defaults
+  root, // NavigationNode (NavigationStack, TabBar, SplitView, ...)
+  screenOptions, // optional defaults
+  debug, // optional
 });
 ```
 
-**Navigation methods:**
-- `navigate(path: string)` — push a new screen
-- `replace(path: string, dedupe?: boolean)` — replace the top screen
-- `goBack()` — pop the current screen
-- `onTabIndexChange(index: number)` — switch to a specific tab
-- `setRoot(nextRoot, options?)` — dynamically switch root (e.g., login → main app)
+Navigation:
+- `router.navigate(path)` — push
+- `router.replace(path, dedupe?)` — replace top of the active stack
+- `router.goBack()` — pop top of the active stack
+- `router.reset(path)` — **web-only**: rebuild Router state as if app loaded at `path`
+- `router.setRoot(nextRoot, { transition? })` — swap root at runtime
 
-**State methods:**
-- `getVisibleRoute()` — get currently visible route with params and query
-- `getState()` — get the full router state
-- `subscribe(listener)` — subscribe to all navigation changes
-- `subscribeStack(stackId, listener)` — subscribe to specific stack changes
-- `subscribeRoot(listener)` — subscribe to root structure changes
-- `subscribeActiveTab(listener)` — subscribe to tab changes
+State/subscriptions:
+- `router.getState()` → `{ history: HistoryItem[] }`
+- `router.getActiveRoute()` → `ActiveRoute | null`
+- `router.subscribe(cb)` — notify on any history change
+- `router.subscribeStack(stackId, cb)` — notify when a particular stack slice changes
+- `router.subscribeRoot(cb)` — notify when root is replaced via `setRoot`
+- `router.getStackHistory(stackId)` — slice of history for a stack
 
-**Stack history methods:**
-- `getStackHistory(stackId)` — get history for a specific stack
-- `getRootStackId()` — get the root stack ID (if root is a stack)
-- `getGlobalStackId()` — get the global stack ID
-- `hasTabBar()` — check if root is a TabBar
+> Note: `router.getGlobalStackId()` exists but currently returns `undefined`.
 
-### 📑 TabBar
+### `TabBar`
 
-A `TabBar` manages multiple stacks as tabs.
+`TabBar` is a container node that renders one tab at a time.
 
 ```tsx
-const tabBar = new TabBar({ component?: CustomTabBarComponent })
-  .addTab({
-    key: string,
-    stack?: NavigationStack,
-    screen?: Component,
-    title?: string,
-    icon?: ImageSource | { sfSymbolName | imageSource | templateSource },
-    selectedIcon?: ImageSource | { sfSymbolName | imageSource | templateSource },
-  });
+const tabBar = new TabBar({ component: CustomTabBar, initialIndex: 0 })
+  .addTab({ key: 'home', stack: homeStack, title: 'Home' })
+  .addTab({ key: 'search', screen: SearchScreen, title: 'Search' });
 ```
 
-**Methods:**
-- `addTab(config)` — add a new tab
-- `setBadge(index, badge)` — set badge text on a tab
-- `onIndexChange(index)` — change active tab (usually called via router)
-- `getState()` — get current tab state
-- `subscribe(listener)` — subscribe to tab bar changes
+Key methods:
+- `addTab({ key, stack?, screen?, title?, icon?, selectedIcon?, ... })`
+- `onIndexChange(index)` — switch active tab
+- `setBadge(index, badge | null)`
+- `setTabBarConfig(partialConfig)`
+- `getState()` and `subscribe(cb)`
 
-**Tab configuration:**
-Each tab can have either a `stack` (NavigationStack) or a single `screen` (Component). If using a stack, the tab will support full navigation within that tab.
+Web behavior note:
+- The built-in **web** tab bar renderer resets Router history on tab switch (to keep URL and Router state consistent) using `router.reset(firstRoutePath)`.
 
-### ⚙️ Screen Options
+### `SplitView`
 
-Screen options control the appearance and behavior of individual screens:
+`SplitView` renders **two stacks**: `primary` and `secondary`.
 
-```tsx
-type ScreenOptions = {
-  // Header configuration (react-native-screens)
-  header?: {
-    title?: string;
-    hidden?: boolean;
-    backTitle?: string;
-    largeTitle?: boolean;
-    // ... all ScreenStackHeaderConfigProps
-  };
-
-  // Presentation style
-  stackPresentation?: 
-    | 'push'
-    | 'modal'
-    | 'transparentModal'
-    | 'containedModal'
-    | 'containedTransparentModal'
-    | 'fullScreenModal'
-    | 'formSheet'
-    | 'pageSheet'
-    | 'sheet';
-
-  // Animation style
-  stackAnimation?: 
-    | 'default'
-    | 'fade'
-    | 'flip'
-    | 'none'
-    | 'simple_push'
-    | 'slide_from_right'
-    | 'slide_from_left'
-    | 'slide_from_bottom'
-    | 'fade_from_bottom';
-
-  // Android: convert modals to sheets
-  convertModalToSheetForAndroid?: boolean;
-
-  // Web helper for default tab icon rendering
-  tabBarIcon?: string | { sfSymbolName?: string };
-
-  // All other react-native-screens Screen props
-  // ...
-};
-```
-
-### 📱 Sheets
-
-Sheets are a special presentation style that shows content in a bottom sheet on both iOS and Android.
+- On **native**, `secondary` overlays `primary` when it has at least one screen in its history.
+- On **web**, the layout becomes side-by-side at a fixed breakpoint (currently `>= 640px` in CSS).
 
 ```tsx
-const stack = new NavigationStack()
-  .addSheet('/settings', SettingsSheet, {
-    header: { title: 'Settings' },
-  });
+import { NavigationStack, SplitView } from '@sigmela/router';
 
-// Or using addScreen with explicit option:
-const stack = new NavigationStack()
-  .addScreen('/settings', SettingsSheet, {
-    stackPresentation: 'sheet',
-    header: { title: 'Settings' },
-  });
-
-// Convert modals to sheets on Android:
-const stack = new NavigationStack()
-  .addModal('/settings', SettingsSheet, {
-    convertModalToSheetForAndroid: true,
-    header: { title: 'Settings' },
-  });
-```
+const master = new NavigationStack().addScreen('/', ThreadsScreen);
+const detail = new NavigationStack().addScreen('/:threadId', ThreadScreen);
 
-**Sheet appearance:**
-```tsx
-const appearance: NavigationAppearance = {
-  sheet: {
-    backgroundColor: '#fff',
-    cornerRadius: 18,
-    androidFullScreenTopInset: 40,
-  },
-};
+const splitView = new SplitView({
+  minWidth: 640, // currently not used by the web renderer; kept for API compatibility
+  primary: master,
+  secondary: detail,
+  primaryMaxWidth: 390,
+});
 
-<Navigation router={router} appearance={appearance} />
+const root = new NavigationStack().addScreen('/mail', splitView);
 ```
 
-### 🎮 Controllers
+## Controllers
 
-Controllers run before a screen is presented. They're useful for:
-- Authentication guards
-- Data prefetching
-- Conditional redirects
-- Loading states
+Controllers let you delay/guard navigation. A route can be registered as:
 
 ```tsx
 import { createController } from '@sigmela/router';
 
 const UserDetails = {
   component: UserDetailsScreen,
-  controller: createController<
-    { userId: string },        // Path params type
-    { tab?: string }           // Query params type
-  >(async ({ params, query }, present) => {
-    // Check auth
-    const isAuthed = await checkAuth();
-    if (!isAuthed) {
-      router.navigate('/login');
-      return;
-    }
-
-    // Prefetch data
-    const userData = await fetchUser(params.userId);
-    
-    // Present screen with prefetched data
-    present({ userData });
-  }),
-};
-
-// Register with stack
-stack.addScreen('/users/:userId', UserDetails, {
-  header: { title: 'User' }
-});
-
-// In the component, receive passProps
-function UserDetailsScreen({ userData }) {
-  // userData is already loaded
-  return <Text>{userData.name}</Text>;
-}
-```
-
-**Controller signature:**
-```tsx
-type Controller<TParams, TQuery> = (
-  input: { params: TParams; query: TQuery },
-  present: (passProps?: any) => void
-) => void;
-```
-
-Controllers receive `params` and `query` parsed from the URL. Call `present(passProps)` to show the screen, passing any data as props. If you don't call `present()`, the screen won't be shown (useful for redirects).
-
-## 🪝 Hooks
-
-### useRouter
-
-Access the router instance:
-
-```tsx
-function MyScreen() {
-  const router = useRouter();
-  
-  return (
-    <Button 
-      onPress={() => router.navigate('/details')}
-      title="Go to details"
-    />
-  );
-}
-```
-
-### useParams
-
-Get typed path parameters:
-
-```tsx
-function UserScreen() {
-  const { userId } = useParams<{ userId: string }>();
-  return <Text>User ID: {userId}</Text>;
-}
-
-// Route: /users/:userId
-// URL: /users/123
-// Result: { userId: '123' }
-```
-
-### useQueryParams
-
-Get typed query parameters:
-
-```tsx
-function SearchScreen() {
-  const { q, sort } = useQueryParams<{ 
-    q?: string; 
-    sort?: 'asc' | 'desc' 
-  }>();
-  
-  return <Text>Query: {q}, Sort: {sort}</Text>;
-}
-
-// URL: /search?q=hello&sort=asc
-// Result: { q: 'hello', sort: 'asc' }
-```
-
-### useCurrentRoute
-
-Subscribe to the currently visible route:
-
-```tsx
-function NavigationObserver() {
-  const currentRoute = useCurrentRoute();
-  
-  useEffect(() => {
-    console.log('Current route:', currentRoute?.path);
-  }, [currentRoute]);
-  
-  return null;
-}
-
-// Returns: { scope, path, params, query, routeId, stackId, tabIndex? } | null
-```
-
-### useRoute
-
-Access the full route context for the current screen:
-
-```tsx
-function MyScreen() {
-  const route = useRoute();
-  
-  return (
-    <View>
-      <Text>Path: {route.path}</Text>
-      <Text>Pattern: {route.pattern}</Text>
-      <Text>Presentation: {route.presentation}</Text>
-    </View>
-  );
-}
-
-// Returns: { presentation, params, query, pattern, path }
-```
-
-### useTabBar
-
-Access the TabBar instance (only works inside a tab screen):
-
-```tsx
-function HomeScreen() {
-  const tabBar = useTabBar();
-  const router = useRouter();
-  
-  const handleSwitchTab = () => {
-    router.onTabIndexChange(1); // Switch to second tab
-  };
-  
-  const handleSetBadge = () => {
-    tabBar.setBadge(1, '5'); // Show badge on second tab
-  };
-  
-  return (
-    <View>
-      <Button title="Switch Tab" onPress={handleSwitchTab} />
-      <Button title="Set Badge" onPress={handleSetBadge} />
-    </View>
-  );
-}
-```
-
-## 🚀 Advanced Features
-
-### 🔄 Dynamic Root (Auth Flows)
-
-Switch between different root structures at runtime:
-
-```tsx
-const authStack = new NavigationStack()
-  .addScreen('/login', LoginScreen, { header: { title: 'Login' } });
-
-const mainTabBar = new TabBar()
-  .addTab({ key: 'home', stack: homeStack, title: 'Home' });
-
-const router = new Router({ root: authStack });
-
-// Later, after login:
-function handleLogin() {
-  router.setRoot(mainTabBar, { transition: 'fade' });
-}
-
-// Or logout:
-function handleLogout() {
-  router.setRoot(authStack, { transition: 'fade' });
-}
-```
-
-The `transition` option accepts any `stackAnimation` value (`'fade'`, `'slide_from_bottom'`, etc.).
-
-### 🎨 Custom Tab Bar
-
-Create a custom tab bar component:
-
-```tsx
-import { TabBar, type TabBarProps } from '@sigmela/router';
-
-function CustomTabBar({ tabs, activeIndex, onTabPress }: TabBarProps) {
-  return (
-    <View style={styles.tabBar}>
-      {tabs.map((tab, index) => (
-        <TouchableOpacity
-          key={tab.tabKey}
-          onPress={() => onTabPress(index)}
-          style={[
-            styles.tab,
-            index === activeIndex && styles.activeTab
-          ]}
-        >
-          {tab.icon && <Image source={tab.icon} />}
-          <Text style={styles.title}>{tab.title}</Text>
-          {tab.badgeValue && <Text style={styles.badge}>{tab.badgeValue}</Text>}
-        </TouchableOpacity>
-      ))}
-    </View>
-  );
-}
-
-const tabBar = new TabBar({ component: CustomTabBar })
-  .addTab({ key: 'home', stack: homeStack, title: 'Home' });
-```
-
-### 🎨 Appearance Customization
-
-Customize the appearance of tabs, headers, and screens:
-
-```tsx
-import type { NavigationAppearance } from '@sigmela/router';
-
-const appearance: NavigationAppearance = {
-  // Tab bar styling
-  tabBar: {
-    backgroundColor: '#ffffff',
-    iconColor: '#8e8e93',
-    iconColorActive: '#007aff',
-    badgeBackgroundColor: '#ff3b30',
-    androidRippleColor: 'rgba(0,0,0,0.1)',
-    androidActiveIndicatorEnabled: true,
-    androidActiveIndicatorColor: '#007aff',
-    iOSShadowColor: '#000',
-    labelVisibilityMode: 'labeled',
-    title: {
-      fontSize: 11,
-      fontFamily: 'System',
-      fontWeight: '500',
-      color: '#8e8e93',
-      activeColor: '#007aff',
-    },
-  },
-  
-  // Header styling (applied to all headers)
-  header: {
-    backgroundColor: '#ffffff',
-    tintColor: '#007aff',
-    largeTitleColor: '#000',
-  },
-  
-  // Screen styling
-  screen: {
-    backgroundColor: '#f2f2f7',
-  },
-  
-  // Sheet styling
-  sheet: {
-    backgroundColor: '#ffffff',
-    cornerRadius: 18,
-    androidFullScreenTopInset: 40,
-  },
-};
-
-export default function App() {
-  return <Navigation router={router} appearance={appearance} />;
-}
-```
-
-### 🔔 Tab Badges
-
-Show badges on tabs:
-
-```tsx
-function SomeScreen() {
-  const tabBar = useTabBar();
-  const router = useRouter();
-  
-  useEffect(() => {
-    // Show badge on second tab
-    tabBar.setBadge(1, '3');
-    
-    // Clear badge
-    // tabBar.setBadge(1, null);
-  }, []);
-}
-
-// Or directly via router instance
-router.tabBar?.setBadge(1, '3');
-```
-
-### 🎬 Standalone Stack Renderer
-
-Render a specific stack anywhere in your component tree:
-
-```tsx
-import { StackRenderer } from '@sigmela/router';
-
-function CustomLayout() {
-  const myStack = new NavigationStack()
-    .addScreen('/nested', NestedScreen);
-  
-  return (
-    <View>
-      <Header />
-      <StackRenderer stack={myStack} appearance={appearance} />
-      <Footer />
-    </View>
-  );
-}
-```
-
-## 🌐 Web Integration
-
-### 🔄 History API Sync
-
-On web, the router automatically synchronizes with the browser's History API:
-
-- `router.navigate('/path')` → `history.pushState()`
-- `router.replace('/path')` → `history.replaceState()`
-- `router.goBack()` → `history.back()`
-- Browser back/forward buttons → `popstate` event → router state update
-
-You can also call `history.pushState()` or `history.replaceState()` directly, and the router will stay in sync.
-
-### 🔗 Deep Linking
-
-On initial load, the router automatically expands deep URLs into a stack chain:
-
-```
-URL: /catalog/products/42
-
-Result stack:
-  1. /catalog          (CatalogScreen)
-  2. /catalog/products/42  (ProductScreen)
-```
-
-This only works for routes in the same stack. The router builds the longest possible chain of matching routes.
-
-### ♻️ Replace with Deduplication
-
-Avoid no-op replaces on web with the `dedupe` option:
-
-```tsx
-// Won't replace if already on /catalog with same params
-router.replace('/catalog', true);
-```
-
-This is useful when switching tabs on web to avoid creating duplicate history entries.
-
-## 🛡️ TypeScript
-
-### ✅ Type-Safe Params
-
-```tsx
-import { useParams, useQueryParams } from '@sigmela/router';
-
-// Define your param types
-type UserParams = {
-  userId: string;
-  tab?: string;
-};
-
-type UserQuery = {
-  ref?: string;
-  highlight?: string;
-};
-
-function UserScreen() {
-  const params = useParams<UserParams>();
-  const query = useQueryParams<UserQuery>();
-  
-  // TypeScript knows:
-  // params.userId is string
-  // params.tab is string | undefined
-  // query.ref is string | undefined
-}
-```
-
-### ✅ Type-Safe Controllers
-
-```tsx
-import { createController } from '@sigmela/router';
-
-type ProductParams = { productId: string };
-type ProductQuery = { variant?: string };
-
-const ProductDetails = {
-  component: ProductScreen,
-  controller: createController<ProductParams, ProductQuery>(
+  controller: createController<{ userId: string }, { tab?: string }>(
     async ({ params, query }, present) => {
-      // params.productId is typed as string
-      // query.variant is typed as string | undefined
-      
-      const product = await fetchProduct(params.productId);
-      present({ product });
+      const ok = await checkAuth();
+      if (!ok) {
+        router.replace('/login', true);
+        return;
+      }
+
+      const user = await fetchUser(params.userId);
+      present({ user, tab: query.tab });
     }
   ),
 };
-```
-
-## 📖 API Reference
-
-### 🧭 Router
-
-```tsx
-class Router {
-  constructor(config: {
-    root: TabBar | NavigationStack;
-    global?: NavigationStack;
-    screenOptions?: ScreenOptions;
-  });
-
-  // Navigation
-  navigate(path: string): void;
-  replace(path: string, dedupe?: boolean): void;
-  goBack(): void;
-  onTabIndexChange(index: number): void;
-  setRoot(nextRoot: TabBar | NavigationStack, options?: { transition?: RootTransition }): void;
-
-  // State
-  getState(): { history: HistoryItem[]; activeTabIndex?: number };
-  getVisibleRoute(): VisibleRoute | null;
-  getStackHistory(stackId: string): HistoryItem[];
-  getRootStackId(): string | undefined;
-  getGlobalStackId(): string | undefined;
-  getActiveTabIndex(): number;
-  hasTabBar(): boolean;
-  getRootTransition(): RootTransition | undefined;
-
-  // Subscriptions
-  subscribe(listener: () => void): () => void;
-  subscribeStack(stackId: string, listener: () => void): () => void;
-  subscribeActiveTab(listener: () => void): () => void;
-  subscribeRoot(listener: () => void): () => void;
-
-  // Sheet management (internal)
-  registerSheetDismisser(key: string, dismisser: () => void): void;
-  unregisterSheetDismisser(key: string): void;
-}
-```
 
-### 📚 NavigationStack
-
-```tsx
-class NavigationStack {
-  constructor();
-  constructor(id: string);
-  constructor(defaultOptions: ScreenOptions);
-  constructor(id: string, defaultOptions: ScreenOptions);
-
-  addScreen(
-    path: string,
-    component: Component | { component: Component; controller?: Controller },
-    options?: ScreenOptions
-  ): NavigationStack;
-
-  addModal(
-    path: string,
-    component: Component | { component: Component; controller?: Controller },
-    options?: ScreenOptions
-  ): NavigationStack;
-
-  addSheet(
-    path: string,
-    component: Component | { component: Component; controller?: Controller },
-    options?: ScreenOptions
-  ): NavigationStack;
-
-  getId(): string;
-  getRoutes(): BuiltRoute[];
-  getFirstRoute(): BuiltRoute | undefined;
-  getDefaultOptions(): ScreenOptions | undefined;
-}
+stack.addScreen('/users/:userId', UserDetails);
 ```
 
-### 📑 TabBar
+If you never call `present()`, the screen is not pushed/replaced.
 
-```tsx
-type TabConfig = {
-  key: string;
-  stack?: NavigationStack;
-  screen?: Component;
-  title?: string;
-  icon?: ImageSource | { 
-    sfSymbolName?: string;
-    imageSource?: ImageSource;
-    templateSource?: ImageSource;
-  };
-  selectedIcon?: ImageSource | { 
-    sfSymbolName?: string;
-    imageSource?: ImageSource;
-    templateSource?: ImageSource;
-  };
-};
+## Hooks
 
-class TabBar {
-  constructor(config?: { component?: ComponentType<TabBarProps> });
+### `useRouter()`
 
-  addTab(config: TabConfig): TabBar;
-  setBadge(tabIndex: number, badge: string | null): void;
-  onIndexChange(index: number): void;
-  getState(): { tabs: InternalTabItem[]; index: number; config: TabBarConfig };
-  subscribe(listener: () => void): () => void;
-}
-```
+Access the router instance.
 
-### 📝 Types
+### `useCurrentRoute()`
 
-```tsx
-type ScreenOptions = {
-  header?: ScreenStackHeaderConfigProps;
-  stackPresentation?: StackPresentationTypes;
-  stackAnimation?: 'default' | 'fade' | 'flip' | 'none' | 'simple_push' 
-    | 'slide_from_right' | 'slide_from_left' | 'slide_from_bottom' | 'fade_from_bottom';
-  convertModalToSheetForAndroid?: boolean;
-  tabBarIcon?: string | { sfSymbolName?: string };
-  // ... all react-native-screens Screen props
-};
+Subscribes to `router.getActiveRoute()`.
 
-type NavigationAppearance = {
-  tabBar?: {
-    backgroundColor?: ColorValue;
-    badgeBackgroundColor?: ColorValue;
-    iconColor?: ColorValue;
-    iconColorActive?: ColorValue;
-    androidActiveIndicatorEnabled?: boolean;
-    androidActiveIndicatorColor?: ColorValue;
-    androidRippleColor?: ColorValue;
-    labelVisibilityMode?: 'labeled' | 'hidden' | 'selected';
-    iOSShadowColor?: ColorValue;
-    title?: {
-      fontFamily?: string;
-      fontSize?: number;
-      fontWeight?: string;
-      fontStyle?: string;
-      color?: string;
-      activeColor?: string;
-    };
-  };
-  screen?: StyleProp<ViewStyle>;
-  header?: ScreenStackHeaderConfigProps;
-  sheet?: {
-    backgroundColor?: ColorValue;
-    cornerRadius?: number;
-    androidFullScreenTopInset?: number;
-  };
-};
+Returns `ActiveRoute | null` (shape from `src/types.ts`):
 
-type VisibleRoute = {
+```ts
+type ActiveRoute = {
   routeId: string;
   stackId?: string;
   tabIndex?: number;
-  scope: 'global' | 'tab' | 'root';
   path?: string;
   params?: Record<string, unknown>;
   query?: Record<string, unknown>;
 } | null;
-
-type TabBarProps = {
-  tabs: InternalTabItem[];
-  activeIndex: number;
-  onTabPress: (index: number) => void;
-};
-
-type Controller<TParams, TQuery> = (
-  input: { params: TParams; query: TQuery },
-  present: (passProps?: any) => void
-) => void;
 ```
 
-## 💡 Examples
+### `useParams<T>()` / `useQueryParams<T>()`
 
-### 🔐 Full Example with Auth Flow
+Returns params/query for the **current screen** (from route context).
 
-```tsx
-import {
-  NavigationStack,
-  Router,
-  Navigation,
-  TabBar,
-  createController,
-  useRouter,
-  useParams,
-} from '@sigmela/router';
-
-// Auth check controller
-const requireAuth = createController(async (input, present) => {
-  const isAuthed = await checkAuth();
-  if (!isAuthed) {
-    router.navigate('/login');
-    return;
-  }
-  present();
-});
+### `useRoute()`
 
-// Stacks
-const homeStack = new NavigationStack()
-  .addScreen('/', { component: HomeScreen, controller: requireAuth }, {
-    header: { title: 'Home' },
-  });
-
-const profileStack = new NavigationStack()
-  .addScreen('/profile', { component: ProfileScreen, controller: requireAuth }, {
-    header: { title: 'Profile' },
-  })
-  .addScreen('/profile/settings', SettingsScreen, {
-    header: { title: 'Settings' },
-  });
+Returns route-local context for the current screen:
 
-const authStack = new NavigationStack()
-  .addScreen('/login', LoginScreen, {
-    header: { title: 'Login', hidden: true },
-  });
+```ts
+type RouteLocalContextValue = {
+  presentation: StackPresentationTypes;
+  params?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  pattern?: string;
+  path?: string;
+};
+```
 
-const mainTabs = new TabBar()
-  .addTab({ key: 'home', stack: homeStack, title: 'Home', icon: { sfSymbolName: 'house' } })
-  .addTab({ key: 'profile', stack: profileStack, title: 'Profile', icon: { sfSymbolName: 'person' } });
+### `useTabBar()`
 
-const globalStack = new NavigationStack()
-  .addSheet('/settings-modal', SettingsModalScreen, {
-    convertModalToSheetForAndroid: true,
-    header: { title: 'Quick Settings' },
-  });
+Returns the nearest `TabBar` from context (only inside tab screens).
 
-// Router
-const router = new Router({
-  root: authStack, // Start with auth
-  global: globalStack,
-});
+```tsx
+import { useTabBar } from '@sigmela/router';
 
-// Login screen
-function LoginScreen() {
-  const router = useRouter();
-  
-  const handleLogin = async () => {
-    await login();
-    router.setRoot(mainTabs, { transition: 'fade' });
-  };
-  
-  return <Button title="Login" onPress={handleLogin} />;
-}
+function ScreenInsideTabs() {
+  const tabBar = useTabBar();
 
-// App
-export default function App() {
-  return <Navigation router={router} appearance={appearance} />;
+  return (
+    <Button
+      title="Go to second tab"
+      onPress={() => tabBar.onIndexChange(1)}
+    />
+  );
 }
 ```
 
-## 💡 Tips & Best Practices
-
-1. 🎯 **Use path-based navigation**: Always navigate with paths (`router.navigate('/path')`) rather than imperative methods. This keeps web and native in sync.
+## Web integration
 
-2. 🛡️ **Type your params**: Use TypeScript generics with `useParams` and `useQueryParams` for type safety.
+### History API syncing
 
-3. 🎮 **Controllers for guards**: Use controllers for auth checks, data prefetching, and conditional navigation instead of doing it in the component.
+On web, Router integrates with the browser History API using custom events:
 
-4. 🌍 **Global stack for overlays**: Use the global stack for modals/sheets that should appear on top of everything (auth, alerts, etc.).
+- `router.navigate('/x')` writes `history.pushState({ __srPath: ... })`
+- `router.replace('/x')` writes `history.replaceState({ __srPath: ... })`
+- Browser back/forward triggers `popstate` and Router updates its state accordingly
 
-5. 🏷️ **Stack IDs**: Optionally provide custom stack IDs for debugging: `new NavigationStack('my-stack-id')`.
+Important behavioral detail:
+- `router.goBack()` **does not call** `history.back()`. It pops Router state and updates the URL via `replaceState` (so it doesn’t grow/rewind the browser stack).
 
-6. ⚙️ **Default options**: Set default options at the stack level to avoid repetition:
-   ```tsx
-   const stack = new NavigationStack({ header: { largeTitle: true } });
-   ```
+### `syncWithUrl: false`
 
-7. 🌐 **Web CSS**: Don't forget to import `@sigmela/router/styles.css` in your web entry point.
+If a route has `screenOptions.syncWithUrl = false`, Router stores the “real” router path in `history.state.__srPath` while keeping the visible URL unchanged.
 
-8. 📱 **Sheet vs Modal**: Use `addSheet()` for bottom sheets, `addModal()` for full-screen modals. On Android, use `convertModalToSheetForAndroid: true` to convert modals to sheets automatically.
-
-## 📄 License
+## License
 
 MIT
-
----
-
-Built with ❤️ by [Sigmela](https://github.com/sigmela)