feat(router): wrapNavigation + wrapUpdate hooks to animate navigations

[sbesh91]

Problem

Animating navigations with the View Transition API needs two things preact-iso doesn't currently expose:

1. Capture the old route before it swaps. document.startViewTransition must run before the navigation re-renders, so the browser snapshots the outgoing route (this is what makes shared-element morphs work). But link clicks / popstate / route() all go straight into the reducer and the swap happens in an async re-render — there's no point at which a consumer can wrap the navigation while the old route is still mounted.
2. Wrap the async content commit. For a route that suspends (lazy import() / async data), the destination's content is committed via an internal post-suspense update (RESOLVED.then(update)) with no hook around it, so the transition can't be resolved when the content is ready.

Together these mean navigations can't be animated old→new: warm routes have no capture point, and cold routes also have no commit hook.

Change

Two small, optional, complementary hooks:

wrapNavigation on <LocationProvider> — wraps the commit of a navigation (the history update + the state change that drives the re-render). Split the reducer's handleNav into resolveNav (detection only, plus the synchronous preventDefault for link clicks) and a separately-invoked commit, so the commit can be deferred:

<LocationProvider
  wrapNavigation={commit =>
    document.startViewTransition(() => flushSync(commit))}
>

The browser captures the current route as the old snapshot before commit() swaps in the new one. Covers clicks, popstate, and programmatic route().

wrapUpdate on <Router> — wraps the post-suspense content commit, so a navigation to an async route can resolve its transition once the content lands:

<Router wrapUpdate={commit => /* resolve the in-flight transition */ commit()}>

Used together: wrapNavigation starts the transition and runs the route change; for a suspending route the consumer awaits wrapUpdate before completing it.

Backwards compatibility

Fully backward compatible. Both props are optional; with them omitted, resolveNav + immediate commit reproduces the previous reducer behavior exactly, and the Router's else RESOLVED.then(update) path is unchanged.

Tests

test/router.test.js, full suite green (41 router + node + lazy):

• a suspending route's commit is routed through wrapUpdate, and content swaps in when the commit runs; omitting it still commits;
• programmatic and link-click navigations are routed through wrapNavigation with the old route still mounted when it's called (the capture window), and preventDefault still fires; omitting it navigates normally.

Context / motivation

Surfaced building a view-transitions toolkit on top of preact-iso. With just wrapUpdate, async routes stopped throwing but still didn't morph, because the old element was already gone by the time any hook fired. wrapNavigation is the missing "navigation is starting" moment; the two hooks together make warm and cold navigations animate old→new.

Happy to adjust API/naming (prop vs. context, wrapNavigation/wrapUpdate vs. alternatives) — these are the smallest hooks that unblock animating navigations.

[JoviDeCroock]

This can probably be done with options.debounceRendering on the framework site. See flushSync in compat