@funstack/router 0.0.7-alpha.0 → 0.0.8

package/dist/docs/ApiComponentsPage.tsx

@@ -55,6 +55,38 @@ export function ApiComponentsPage() {
                 the router will intercept the navigation.
               </td>
             </tr>
+            <tr>
+              <td>
+                <code>fallback</code>
+              </td>
+              <td>
+                <code>{'"none" | "static"'}</code>
+              </td>
+              <td>
+                Fallback mode when Navigation API is unavailable.{" "}
+                <code>"none"</code> (default) renders nothing;{" "}
+                <code>"static"</code> renders matched routes using{" "}
+                <code>window.location</code> without navigation interception
+                (MPA behavior).
+              </td>
+            </tr>
+            <tr>
+              <td>
+                <code>ssrPathname</code>
+              </td>
+              <td>
+                <code>string</code>
+              </td>
+              <td>
+                Pathname to use for route matching during SSR. When provided,
+                path-based routes match against this pathname on the server.
+                Routes with loaders are always skipped during SSR. Once the
+                client hydrates, the real URL from the Navigation API takes
+                over. See the{" "}
+                <a href="/learn/server-side-rendering">SSR guide</a> for
+                details.
+              </td>
+            </tr>
           </tbody>
         </table>
       </article>

package/dist/docs/ApiHooksPage.tsx

@@ -163,9 +163,14 @@ function MyComponent() {
         <ul>
           <li>
             This hook is powered by React's <code>useTransition</code>. The
-            router wraps navigation state updates in{" "}
-            <code>startTransition</code>, so React defers rendering suspended
-            routes and keeps the current UI visible.
+            router wraps navigations in <code>startTransition</code>, so React
+            defers rendering suspended routes and keeps the current UI visible.
+          </li>
+          <li>
+            Sync state updates via <code>setStateSync</code> and{" "}
+            <code>resetStateSync</code> bypass transitions entirely, so{" "}
+            <code>isPending</code> will <strong>not</strong> become{" "}
+            <code>true</code> for those updates.
           </li>
           <li>
             The same <code>isPending</code> value is also available as a prop on

package/dist/docs/ApiTypesPage.tsx

@@ -37,7 +37,10 @@ type Props = {
     state: { scrollPosition: number } |
            ((prev: { scrollPosition: number } | undefined) => { scrollPosition: number })
   ) => void;
-  resetState: () => void;
+  // Async reset via replace navigation
+  resetState: () => Promise<void>;
+  // Sync reset via updateCurrentEntry
+  resetStateSync: () => void;
   info: unknown; // Ephemeral navigation info
   isPending: boolean; // Whether a navigation transition is pending
 };`}</CodeBlock>
@@ -48,11 +51,27 @@ type Props = {
           <li>
             <code>setState</code> - Async method that returns a Promise. Uses
             replace navigation internally, ensuring the state update goes
-            through the full navigation cycle.
+            through the full navigation cycle. Because it performs a navigation,
+            it is wrapped in a React transition and may set{" "}
+            <code>isPending</code> to <code>true</code>.
           </li>
           <li>
             <code>setStateSync</code> - Synchronous method that updates state
-            immediately using <code>navigation.updateCurrentEntry()</code>.
+            immediately using <code>navigation.updateCurrentEntry()</code>. This
+            is <strong>not</strong> a navigation, so it bypasses React
+            transitions and will never set <code>isPending</code> to{" "}
+            <code>true</code>.
+          </li>
+          <li>
+            <code>resetState</code> - Async method that clears navigation state
+            via replace navigation. Like <code>setState</code>, it goes through
+            a React transition and may set <code>isPending</code> to{" "}
+            <code>true</code>.
+          </li>
+          <li>
+            <code>resetStateSync</code> - Clears navigation state synchronously.
+            Like <code>setStateSync</code>, this bypasses React transitions and
+            will never set <code>isPending</code> to <code>true</code>.
           </li>
         </ul>
       </article>
@@ -80,7 +99,8 @@ type Props = {
   state: { selectedTab: string } | undefined;
   setState: (state: ...) => Promise<void>;  // async
   setStateSync: (state: ...) => void;       // sync
-  resetState: () => void;
+  resetState: () => Promise<void>;          // async
+  resetStateSync: () => void;               // sync
   info: unknown; // Ephemeral navigation info
   isPending: boolean; // Whether a navigation transition is pending
 };`}</CodeBlock>
@@ -238,8 +258,9 @@ type SettingsPageProps = RouteComponentPropsOf<typeof settingsRoute>;
             <code>component: UserPage</code>): Router automatically injects
             props (<code>params</code>, <code>state</code>,{" "}
             <code>setState</code>, <code>setStateSync</code>,{" "}
-            <code>resetState</code>, <code>info</code>, <code>isPending</code>,
-            and <code>data</code> when a loader is defined).
+            <code>resetState</code>, <code>resetStateSync</code>,{" "}
+            <code>info</code>, <code>isPending</code>, and <code>data</code>{" "}
+            when a loader is defined).
           </li>
           <li>
             <strong>JSX element</strong> (e.g.,{" "}
@@ -268,15 +289,42 @@ routeState<{ tab: string }>()({
 });`}</CodeBlock>
       </article>
 
+      <article className="api-item">
+        <h3>
+          <code>ActionArgs</code>
+        </h3>
+        <p>
+          Arguments passed to route action functions. The <code>request</code>{" "}
+          carries the POST method and <code>FormData</code> body from the form
+          submission.
+        </p>
+        <CodeBlock language="typescript">{`interface ActionArgs<Params> {
+  params: Params;
+  request: Request;  // method: "POST", body: FormData
+  signal: AbortSignal;
+}`}</CodeBlock>
+      </article>
+
       <article className="api-item">
         <h3>
           <code>LoaderArgs</code>
         </h3>
-        <CodeBlock language="typescript">{`interface LoaderArgs {
-  params: Record<string, string>;
+        <p>
+          Arguments passed to route loader functions. The optional{" "}
+          <code>actionResult</code> parameter contains the return value of the
+          route's action when the loader runs after a form submission.
+        </p>
+        <CodeBlock language="typescript">{`interface LoaderArgs<Params, ActionResult = undefined> {
+  params: Params;
   request: Request;
   signal: AbortSignal;
+  actionResult: ActionResult | undefined;
 }`}</CodeBlock>
+        <p>
+          On normal navigations, <code>actionResult</code> is{" "}
+          <code>undefined</code>. After a form submission, it contains the
+          action's return value (awaited if the action is async).
+        </p>
       </article>
 
       <article className="api-item">

package/dist/docs/ApiUtilitiesPage.tsx

@@ -17,8 +17,9 @@ export function ApiUtilitiesPage() {
           always receives a <code>params</code> prop with types inferred from
           the path pattern. When a <code>loader</code> is defined, the component
           also receives a <code>data</code> prop. Components also receive{" "}
-          <code>state</code>, <code>setState</code>, <code>setStateSync</code>,
-          and <code>resetState</code> props for navigation state management.
+          <code>state</code>, <code>setState</code>, <code>setStateSync</code>,{" "}
+          <code>resetState</code>, and <code>resetStateSync</code> props for
+          navigation state management.
         </p>
         <CodeBlock language="tsx">{`import { route } from "@funstack/router";
 
@@ -84,6 +85,20 @@ const myRoute = route({
                 (and <code>data</code> prop if loader is defined)
               </td>
             </tr>
+            <tr>
+              <td>
+                <code>action</code>
+              </td>
+              <td>
+                <code>(args: ActionArgs) =&gt; T</code>
+              </td>
+              <td>
+                Function to handle form submissions (POST navigations). Receives
+                a <code>Request</code> with <code>FormData</code> body. The
+                return value is passed to the loader as{" "}
+                <code>actionResult</code>.
+              </td>
+            </tr>
             <tr>
               <td>
                 <code>loader</code>
@@ -204,11 +219,15 @@ const productRoute = routeState<{ filter: string }>()({
           <li>
             <code>setState</code> - Async method that uses replace navigation.
             Returns a Promise that resolves when the navigation completes.
+            Because it performs a navigation, the update is wrapped in a React
+            transition (may set <code>isPending</code> to <code>true</code>).
           </li>
           <li>
             <code>setStateSync</code> - Sync method that uses{" "}
             <code>navigation.updateCurrentEntry()</code>. Updates state
-            immediately without waiting.
+            immediately without waiting. This is not a navigation, so it
+            bypasses React transitions entirely (<code>isPending</code> stays{" "}
+            <code>false</code>).
           </li>
         </ul>
         <p>Navigation state characteristics:</p>
@@ -276,8 +295,9 @@ const routes = [
             <code>routeState</code> - Route definition helper with typed state
           </li>
           <li>
-            Types: <code>LoaderArgs</code>, <code>RouteDefinition</code>,{" "}
-            <code>PathParams</code>, <code>RouteComponentProps</code>,{" "}
+            Types: <code>ActionArgs</code>, <code>LoaderArgs</code>,{" "}
+            <code>RouteDefinition</code>, <code>PathParams</code>,{" "}
+            <code>RouteComponentProps</code>,{" "}
             <code>RouteComponentPropsWithData</code>
           </li>
         </ul>
@@ -287,9 +307,7 @@ const routes = [
         </p>
         <p>
           See the{" "}
-          <a href="/funstack-router/learn/react-server-components">
-            React Server Components
-          </a>{" "}
+          <a href="/learn/react-server-components">React Server Components</a>{" "}
           guide for a full walkthrough of using the server entry point.
         </p>
       </article>

package/dist/docs/GettingStartedPage.tsx

@@ -15,6 +15,21 @@ pnpm add @funstack/router
 yarn add @funstack/router`}</CodeBlock>
       </section>
 
+      <section>
+        <h2>AI Coding Agent Support</h2>
+        <p>
+          <code>@funstack/router</code> ships with an Agent skill that gives
+          your coding assistant (Claude Code, Cursor, GitHub Copilot, etc.)
+          knowledge about the router's API and best practices. After installing
+          the package, run:
+        </p>
+        <CodeBlock language="bash">{`npx funstack-router-skill-installer`}</CodeBlock>
+        <p>
+          The installer will guide you through setting up the skill for your
+          preferred AI agent.
+        </p>
+      </section>
+
       <section>
         <h2>Browser Support</h2>
         <p>
@@ -27,7 +42,7 @@ yarn add @funstack/router`}</CodeBlock>
             Navigation API
           </a>{" "}
           which is supported in Chrome 102+, Edge 102+, Firefox 147+, Safari
-          26.2+, and Opera 88+.
+          26.2+.
         </p>
       </section>
 

package/dist/docs/LearnNestedRoutesPage.tsx

@@ -439,10 +439,8 @@ function TeamLayout(props: {
           Pathless routes also play a key role in server-side rendering. During
           SSR, only pathless routes render (since no URL is available on the
           server), making them ideal for defining the app shell. See the{" "}
-          <a href="/funstack-router/learn/server-side-rendering">
-            Server-Side Rendering
-          </a>{" "}
-          page for details.
+          <a href="/learn/server-side-rendering">Server-Side Rendering</a> page
+          for details.
         </p>
       </section>
 

package/dist/docs/LearnRscPage.tsx

@@ -252,6 +252,21 @@ export default function App() {
           components. The route definitions are constructed on the server and
           passed into <code>Router</code>, which acts as the client boundary.
         </p>
+        <p>
+          If the server knows the requested pathname, you can pass it via the{" "}
+          <code>ssrPathname</code> prop so that path-based routes render during
+          SSR (see the <a href="/learn/server-side-rendering">SSR guide</a> for
+          details):
+        </p>
+        <CodeBlock language="tsx">{`export default function App({ pathname }: { pathname: string }) {
+  return (
+    <Router
+      routes={routes}
+      fallback="static"
+      ssrPathname={pathname}
+    />
+  );
+}`}</CodeBlock>
       </section>
 
       <section>
@@ -281,9 +296,7 @@ export default function App() {
           </li>
           <li>
             See also the{" "}
-            <a href="/funstack-router/learn/server-side-rendering">
-              Server-Side Rendering
-            </a>{" "}
+            <a href="/learn/server-side-rendering">Server-Side Rendering</a>{" "}
             guide for how the router handles SSR and hydration
           </li>
         </ul>

package/dist/docs/LearnSsrPage.tsx

@@ -9,7 +9,9 @@ export function LearnSsrPage() {
         FUNSTACK Router supports server-side rendering with a two-stage model.
         During SSR, pathless (layout) routes without loaders render to produce
         an app shell, while path-based routes and loaders activate only after
-        client hydration.
+        client hydration. You can optionally provide an <code>ssrPathname</code>{" "}
+        prop to match path-based routes during SSR for richer server-rendered
+        output.
       </p>
 
       <section>
@@ -19,12 +21,15 @@ export function LearnSsrPage() {
           renders on the server from what renders on the client:
         </p>
         <p>
-          <strong>Stage 1 &mdash; Server:</strong> No URL is available on the
-          server. The router matches only pathless routes (routes without a{" "}
-          <code>path</code> property) that do not have a loader. Pathless routes
-          with loaders are skipped because there is no request context to run
-          them. This produces the app shell &mdash; layouts, headers, navigation
-          chrome, and other structural markup.
+          <strong>Stage 1 &mdash; Server:</strong> By default, no URL is
+          available on the server. The router matches only pathless routes
+          (routes without a <code>path</code> property) that do not have a
+          loader. This produces the app shell &mdash; layouts, headers,
+          navigation chrome, and other structural markup. When{" "}
+          <code>ssrPathname</code> is provided, the router also matches
+          path-based routes against that pathname, enabling richer
+          server-rendered content. In both cases, routes with loaders are always
+          skipped during SSR.
         </p>
         <p>
           <strong>Stage 2 &mdash; Client hydration:</strong> Once the browser
@@ -34,13 +39,13 @@ export function LearnSsrPage() {
         </p>
         <CodeBlock language="tsx">{`// What renders at each stage:
 
-// Stage 1 (Server)         Stage 2 (Client)
-// ─────────────────        ─────────────────
-// App shell (pathless      App shell (pathless)
-//   without loader)
-// ✗ No path routes         ✓ Path routes match
-// ✗ No loaders             ✓ Loaders execute
-// ✗ No URL available       ✓ URL from Navigation API`}</CodeBlock>
+// Stage 1 (Server)                   Stage 2 (Client)
+// ───────────────────────────        ─────────────────
+// App shell (pathless routes)        App shell (pathless)
+// + path routes if ssrPathname       ✓ Path routes match
+//   is provided (no loaders)
+// ✗ No loaders                       ✓ Loaders execute
+// ✗ No URL available                 ✓ URL from Navigation API`}</CodeBlock>
       </section>
 
       <section>
@@ -73,6 +78,76 @@ export function LearnSsrPage() {
         </p>
       </section>
 
+      <section>
+        <h3>
+          Path-Based SSR with <code>ssrPathname</code>
+        </h3>
+        <p>
+          By default, only pathless routes render during SSR because the server
+          has no URL. The <code>ssrPathname</code> prop lets you provide a
+          pathname so path-based routes can also match during SSR, producing
+          fuller server-rendered HTML.
+        </p>
+        <CodeBlock language="tsx">{`// Server knows the requested URL and passes it to the router
+<Router routes={routes} ssrPathname="/about" />`}</CodeBlock>
+        <p>
+          When <code>ssrPathname</code> is provided, the router matches
+          path-based routes against it just as it would match against the real
+          URL on the client. Route params are extracted normally. However,
+          routes with loaders are always skipped during SSR regardless of this
+          setting &mdash; there is no request context available to run them.
+        </p>
+        <p>
+          Once the client hydrates, the real URL from the Navigation API takes
+          over and <code>ssrPathname</code> is ignored.
+        </p>
+        <CodeBlock language="tsx">{`const routes = [
+  route({
+    component: AppShell,
+    children: [
+      route({ path: "/", component: HomePage }),      // Matches ssrPathname="/"
+      route({ path: "/about", component: AboutPage }),// Matches ssrPathname="/about"
+      route({
+        path: "/dashboard",
+        component: DashboardPage,
+        loader: dashboardLoader, // Skipped during SSR (has loader)
+      }),
+    ],
+  }),
+];
+
+// With ssrPathname="/about":
+// - AppShell renders (pathless, no loader) ✓
+// - AboutPage renders (path matches, no loader) ✓
+// - DashboardPage would NOT render even with ssrPathname="/dashboard"
+//   because it has a loader`}</CodeBlock>
+        <h4>When to use ssrPathname</h4>
+        <p>
+          Use <code>ssrPathname</code> when your server or static site generator
+          knows the URL being rendered and you want to include page-specific
+          content in the SSR output. This is particularly useful for:
+        </p>
+        <ul>
+          <li>
+            Improving perceived performance by showing page content immediately
+            instead of a blank shell
+          </li>
+          <li>
+            SEO &mdash; search engine crawlers see the full page content rather
+            than just the app shell
+          </li>
+          <li>
+            Static site generation where each page is pre-rendered at a known
+            path
+          </li>
+        </ul>
+        <p>
+          If your routes have loaders, those routes will still be skipped during
+          SSR. The parent route renders as a shell, and the loader content fills
+          in after hydration.
+        </p>
+      </section>
+
       <section>
         <h3>Hooks and SSR</h3>
         <p>
@@ -152,12 +227,16 @@ function HomePage() {
         <h3>Key Takeaways</h3>
         <ul>
           <li>
-            During SSR, only pathless routes without loaders render (no URL or
-            request context is available on the server)
+            By default, only pathless routes without loaders render during SSR
+            (no URL is available on the server)
+          </li>
+          <li>
+            Use <code>ssrPathname</code> to enable path-based route matching
+            during SSR for richer server-rendered output
           </li>
           <li>
-            Path-based routes, loaders, and pathless routes with loaders
-            activate after client hydration
+            Routes with loaders are always skipped during SSR, regardless of{" "}
+            <code>ssrPathname</code>
           </li>
           <li>
             Pathless routes are ideal for app shell markup (headers, footers,
@@ -170,8 +249,8 @@ function HomePage() {
             app shell
           </li>
           <li>
-            This two-stage model keeps SSR output lightweight while enabling
-            full interactivity on the client
+            Once the client hydrates, the real URL from the Navigation API takes
+            over
           </li>
         </ul>
       </section>

package/dist/docs/LearnTransitionsPage.tsx

@@ -6,7 +6,7 @@ export function LearnTransitionsPage() {
       <h2>Controlling Transitions</h2>
 
       <p className="page-intro">
-        FUNSTACK Router wraps every navigation in React's{" "}
+        FUNSTACK Router wraps navigations in React's{" "}
         <code>startTransition</code>, which means the old UI may stay visible
         while the new route loads. This page explains how this works and how to
         control it.
@@ -16,11 +16,11 @@ export function LearnTransitionsPage() {
         <h3>Navigations as Transitions</h3>
         <p>
           When the user navigates, the Router updates its location state inside{" "}
-          <code>startTransition()</code>. This means React treats every
-          navigation as a transition: if an existing Suspense boundary suspends
-          (e.g., a component loading data with <code>use()</code>), React keeps
-          the old UI visible instead of immediately showing the fallback. This
-          behavior is{" "}
+          <code>startTransition()</code>. This means React treats navigations as
+          transitions: if an existing Suspense boundary suspends (e.g., a
+          component loading data with <code>use()</code>), React keeps the old
+          UI visible instead of immediately showing the fallback. This behavior
+          is{" "}
           <a href="https://react.dev/reference/react/useTransition#building-a-suspense-enabled-router">
             what React recommends for Suspense-enabled routers
           </a>
@@ -141,6 +141,80 @@ function UserDetailPage({
           transition behavior is usually the better experience.
         </p>
       </section>
+
+      <section>
+        <h3>Sync State Updates Bypass Transitions</h3>
+        <p>
+          FUNSTACK Router allows you to save state in a navigation entry, which
+          is useful for form state or other UI state that should persist when
+          the user navigates back and forth. You can update this state using the{" "}
+          <code>setState</code> and <code>resetState</code> functions passed to
+          route components. These functions use a replace navigation internally,
+          so they trigger a transition.
+        </p>
+        <p>
+          In rare cases, you may want to update navigation state without
+          triggering a transition. <code>setStateSync</code> and{" "}
+          <code>resetStateSync</code> are designed for this purpose. When you
+          call them, the Router updates the current history entry using the
+          Navigation API's <code>updateCurrentEntry()</code> method, which does
+          not trigger a navigation. The Router detects this and applies the
+          update synchronously, outside of <code>startTransition</code>. As a
+          result:
+        </p>
+        <ul>
+          <li>
+            The update is reflected in the UI immediately &mdash; there is no
+            pending phase.
+          </li>
+          <li>
+            <code>useIsPending()</code> (and the <code>isPending</code> prop)
+            will <strong>not</strong> become <code>true</code>.
+          </li>
+          <li>
+            If the update causes a component to suspend, React will show the
+            fallback immediately instead of waiting for the transition to end.
+          </li>
+        </ul>
+        <h4>When to Use Sync State Updates</h4>
+        <p>
+          When it comes to `setState` vs `setStateSync`, you can think in the
+          same way as you would with wrapping state updates in `startTransition`
+          or not. A general guideline is to{" "}
+          <strong>
+            just use <code>setState</code> (with transition)
+          </strong>{" "}
+          when you don't have a specific reason to avoid it. The exception is
+          when the state change <em>already happened</em> on the screen and you
+          just want to reflect it in the navigation entry state.
+        </p>
+        <p>
+          A typical example of this is a form where you want to save the current
+          input value in the navigation state, so that if the user navigates
+          away and then back, their input is preserved. In this case, you would
+          call <code>setStateSync</code> in the input's <code>onChange</code>{" "}
+          handler, because the state update is already reflected in the input's
+          value and you don't want to trigger a transition for this:
+        </p>
+        <CodeBlock language="tsx">{`function MyForm({ state, setStateSync }: { state: State; setStateSync: (state: State) => void }) {
+  const [inputValue, setInputValue] = useState(state.inputValue ?? "");
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newValue = e.target.value;
+    setInputValue(newValue);
+    setStateSync({ inputValue: newValue }); // Save to navigation state without transition
+  };
+
+  return <input value={inputValue} onChange={handleChange} />;
+}`}</CodeBlock>
+        <p>
+          In this example, using <code>setState</code> (with transition) would
+          cause the UI to enter a pending state on every keystroke, which would
+          be a poor user experience. By using <code>setStateSync</code>, the
+          navigation state updates seamlessly without triggering transitions or
+          pending states.
+        </p>
+      </section>
     </div>
   );
 }

package/dist/docs/LearnTypeSafetyPage.tsx

@@ -225,14 +225,24 @@ const productListRoute = routeState<ProductListState>()(
           </li>
           <li>
             <code>setState</code> &mdash; Navigate to the same URL with new
-            state (creates a new history entry)
+            state (creates a new history entry). Goes through a React
+            transition, so it may set <code>isPending</code> to{" "}
+            <code>true</code>.
           </li>
           <li>
             <code>setStateSync</code> &mdash; Update state synchronously without
-            creating a new history entry
+            creating a new history entry. Bypasses React transitions, so{" "}
+            <code>isPending</code> stays <code>false</code>.
           </li>
           <li>
             <code>resetState</code> &mdash; Clear the navigation state
+            asynchronously via replace navigation. Like <code>setState</code>,
+            goes through React transitions.
+          </li>
+          <li>
+            <code>resetStateSync</code> &mdash; Clear the navigation state
+            synchronously. Like <code>setStateSync</code>, bypasses React
+            transitions.
           </li>
         </ul>
 

package/dist/docs/index.md

@@ -16,6 +16,6 @@
 - [Navigation API](./LearnNavigationApiPage.tsx) - FUNSTACK Router is built on the Navigation API , a modern browser API that provides a unified way to handle navigation. This guide explains the key differences from the older History API and the benefits this brings to your application.
 - [Nested Routes](./LearnNestedRoutesPage.tsx) - Nested routes let you build complex page layouts where parts of the UI persist across navigation while other parts change. Think of a dashboard with a sidebar that stays in place while the main content area updates—that's nested routing in action.
 - [React Server Components](./LearnRscPage.tsx) - FUNSTACK Router is designed to work with React Server Components (RSC). The package provides a dedicated server entry point so that route definitions can live in server modules, keeping client bundle sizes small.
-- [Server-Side Rendering](./LearnSsrPage.tsx) - FUNSTACK Router supports server-side rendering with a two-stage model. During SSR, pathless (layout) routes without loaders render to produce an app shell, while path-based routes and loaders activate only after client hydration.
-- [Controlling Transitions](./LearnTransitionsPage.tsx) - FUNSTACK Router wraps every navigation in React's startTransition, which means the old UI may stay visible while the new route loads. This page explains how this works and how to control it.
+- [Server-Side Rendering](./LearnSsrPage.tsx) - FUNSTACK Router supports server-side rendering with a two-stage model. During SSR, pathless (layout) routes without loaders render to produce an app shell, while path-based routes and loaders activate only after client hydration. You can optionally provide an ssrPathname prop to match path-based routes during SSR for richer server-rendered output.
+- [Controlling Transitions](./LearnTransitionsPage.tsx) - FUNSTACK Router wraps navigations in React's startTransition, which means the old UI may stay visible while the new route loads. This page explains how this works and how to control it.
 - [Type Safety](./LearnTypeSafetyPage.tsx) - FUNSTACK Router provides first-class TypeScript support, allowing you to access route params, navigation state, and loader data with full type safety. This guide covers two approaches: receiving typed data through component props (recommended) and accessing it through hooks.