[uhyo]

Summary

File-system routing currently always produces an SPA: pages render with FUNSTACK Router's <Router>, and link clicks are intercepted for soft client-side navigation. Some users prefer a classic multi-page site without soft navigation. This PR adds a required mode field to fsRoutes with two values:

• "spa" — the existing behavior.
• "mpa" — pages render with <RouteDisplay> from @funstack/router 1.6, which never intercepts navigations, so every link loads the destination's own HTML.

funstackStatic({
  fsRoutes: {
    dir: "./src/pages",
    root: "./src/root.tsx",
    adapter: "@funstack/static/fs-routes/next-adapter",
    mode: "mpa", // or "spa"
  },
});

mode is required like the other fsRoutes fields, so the choice is explicit in every config; the plugin fails with a clear error when it is missing. File-system routing is experimental, so existing configs adding the field is within the feature's stability contract. The lower-level createFsRoutesEntries keeps a "spa" default, mirroring how adapter is optional there.

How MPA mode works

• FsRoutesApp renders <RouteDisplay routes ssr={{ path }}> instead of <Router>.
• Each page's route definitions cover only its own route chain (nested root-first). Since the document never outlives its URL, sibling routes can never match and are left out.
• Server Components on the chain are inlined directly with their params and route object; no FsRouteSlot is involved. Client Components are still passed as component types so the router renders them with the matched params.
• Chunk registration is skipped entirely: nothing is fetched on navigation, so the build emits exactly one RSC payload per page. (The e2e fixture emits 11 payload files in MPA mode versus 29 for the equivalent SPA fixture.)
• Route ids are identical to SPA mode, so route objects stay portable between the two.

FsRoutesMode is exported from @funstack/static/fs-routes.

Tests

• Unit: 7 new runtime tests (RouteDisplay usage, chain-only definitions, inlined Server Components, Client Component pass-through, no chunks, id parity with SPA mode) and 3 new plugin tests (mode emission for both values, missing mode, invalid mode).
• E2E: new fixture-fs-routing-mpa fixture with build and dev-server specs (ports 4181/4182). Navigation tests assert a full document replacement by planting a window marker before each click and checking it is gone afterwards; shell client state is also checked to reset. Both the new MPA projects and the existing SPA projects pass in build and dev mode.

Docs and example

• New "SPA or MPA" section in the File-System Routing guide, with a note at the top of the SPA-only "Params on Client-Side Navigation" section. All fsRoutes snippets now include mode.
• mode documented in the funstackStatic() API reference.
• New example-fs-routing-mpa package showing full page loads on links, useSearchParams's setter performing a full navigation under <RouteDisplay>, and a dynamic Server Component page in MPA mode.

Notes for review

• The remote also has an older feat/fs-routes-mpa-mode branch taking a different approach (JavaScript-free pages via SSR/RSC entry changes). This PR is independent of it.

🤖 Generated with Claude Code

https://claude.ai/code/session_014ERdZEFjZXcbrh8pQttyc4