docs: add design document for lazy route definitions (#138)

* docs: add design document for lazy route definitions

https://claude.ai/code/session_01HqWiPByktzUpdesqZbNcHp

* docs: redesign lazy route definitions to use Suspense

Replace the useEffect + resolveLazyChildren tree-walker approach with
a Suspense-based design where <Outlet /> suspends via a PendingOutlet
component while lazy children are being resolved.

Key changes:
- PendingOutlet component throws a promise (React Suspense pattern)
- startTransition keeps old page visible during navigation
- Suspense fallback shown only on initial page load
- No separate resolveLazyChildren function needed
- Error handling via React error boundaries
- NavigationAPIAdapter needs no changes

https://claude.ai/code/session_01HqWiPByktzUpdesqZbNcHp

* docs: use React 19 use() API and polish for fresh readers

- Replace throw promise with use(promise) in PendingOutlet
- Rewrite "nested lazy subtrees" section without referencing
  the rejected resolveLazyChildren approach
- Update all flow diagrams to reference use() instead of throw

https://claude.ai/code/session_01HqWiPByktzUpdesqZbNcHp

* docs: replace global cache + lazyVersion with state-based lazyCache

Replace the module-level WeakMap and lazyVersion counter with a single
Map stored in Router's useState. The cache is scoped to the Router
instance, cleared when routes prop changes, and safe under concurrent
rendering. PendingOutlet uses setState-during-render to register
promises and setLazyCache to trigger re-render on resolution.

https://claude.ai/code/session_01HqWiPByktzUpdesqZbNcHp

* docs: fix PendingOutlet setState-during-render issue

Move promise creation into PendingOutlet's own useState initializer
instead of reading from Router's lazyCache during render. The
setState-during-render pattern only works for the component that owns
the state — PendingOutlet can't call Router's setLazyCache during
render. Instead, setLazyCache is called from the .then() callback
(outside render) as a normal async state update.

https://claude.ai/code/session_01HqWiPByktzUpdesqZbNcHp

* docs: move promise creation from PendingOutlet to Router

useState data is not retained in components that suspend before
committing — React discards the in-progress fiber. Move promise
creation into Router (which is already committed) using
setState-during-render on its own state. PendingOutlet becomes a
thin wrapper that just receives a promise prop and calls use().

https://claude.ai/code/session_01HqWiPByktzUpdesqZbNcHp

* docs: allow sync return from lazy children, add caching contract

Allow the children function to return either synchronously or as a
promise. matchRoutes now calls the function — sync results are
resolved in-place immediately, async results cause a partial match.

This handles the edge case where Router can't commit (state lost):
on re-render, the user's cache returns sync and matchRoutes resolves
it without any suspension. Add caching contract section explaining
the user's responsibility to cache the Promise and resolved result.

Also add Router suspension edge case, updated detailed behavior
flows, and test cases for sync resolution.

https://claude.ai/code/session_01HqWiPByktzUpdesqZbNcHp

* docs: remove in-place mutation of route objects

Route objects are never mutated. matchRoutes uses the sync result as a
local variable for matching; Router's .then() handler only triggers a
re-render via setLazyCache (no route.children assignment). After
resolution, subsequent matchRoutes calls invoke the user's function
which returns the cached array synchronously.

This keeps route definitions immutable — the user's caching function
is the single source of truth for resolution state.

https://claude.ai/code/session_01HqWiPByktzUpdesqZbNcHp

* docs: clarify why .then() handler is needed in Router

The setLazyCache call in the .then() handler is specifically needed
for the initial page load case. During navigation, startTransition
retries the entire transition (including Router) automatically. But
on initial page load there is no transition — only the Suspense
subtree retries, and Router is above the Suspense boundary. Without
the .then(), PendingOutlet returns null after resolution, leaving an
empty outlet.

https://claude.ai/code/session_01HqWiPByktzUpdesqZbNcHp

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: uhyo