@fluixi/core 1.0.0-alpha.83 → 1.0.0-alpha.85

package/dist/src/lib/router/index.d.ts

@@ -1,17 +1,4 @@
-/**
- * @fileoverview Fluixi adapter for the framework-agnostic @fluixi/router core.
- *
- * Renders the resolved match tree TOP-DOWN. Each layer's component is rendered
- * inside the PARENT layer's <Outlet/> scope, so a child route inherits whatever
- * context a parent layout provides. <Outlet/> is reactive but keyed on the child's
- * component reference, so it only re-renders when the child route at that depth
- * actually changes — sibling navigation reuses the layout, deeper navigation
- * leaves shallower layouts untouched.
- *
- * No parentGate, no deferred content memo: a child is rendered straight from the
- * matched array, never by re-entering a still-building parent, so deeply nested
- * <Outlet/> works at any depth.
- */
+import { type TransitionMode } from './transition.js';
 import { type GetAtPath } from '@fluixi/utils/object';
 import type { IsUndefined } from '@fluixi/utils/primitive';
 import { type RouteDefinition, type Router as CoreRouter, type HistoryAdapter, type RouterLocation, type NavigateOptions } from '@fluixi/router';
@@ -25,12 +12,36 @@ export interface RouterProps<C = any> {
     base?: string;
     history?: HistoryAdapter;
     /**
-     * Rendered when the current URL matches no route — a component, an element, or any renderable.
+     * Rendered when the current URL matches no route, a component, an element, or any renderable.
      * Defaults to a minimal built-in 404 so an unmatched URL never renders a blank page. For a 404
-     * that keeps your layout/chrome, add a catch-all file route instead (`[...slug].tsx` → `*`).
+     * that keeps your layout/chrome, add a catch-all file route instead (`[...slug].tsx` -> `*`).
      */
     notFound?: any;
+    /**
+     * How route changes are presented. `'auto'` (the default) hands the DOM swap to the
+     * browser's View Transition API where there is one, and navigates directly where
+     * there is not; `'none'` always navigates directly.
+     *
+     * A reader who asked for reduced motion never gets an animation either way. Styling
+     * is the native mechanism: `::view-transition-old(root)` and
+     * `::view-transition-new(root)`: so the router imposes no visual style of its own.
+     */
+    transition?: TransitionMode;
 }
+/**
+ * The router. Matches the current URL against `routes` and renders what matches.
+ *
+ * Supplies the router context everything below reaches through `useRouter`,
+ * `useNavigate` and `Link`, so those only work inside it. `history` defaults to a
+ * browser history; pass a memory history for tests or a server render. An unmatched URL
+ * renders `notFound`, which defaults to a minimal built-in page so a bad URL is never
+ * blank. For a 404 that keeps your layout, add a catch-all file route instead.
+ *
+ * @example
+ * ```ts
+ * html`<${Router} routes=${routes} base="/app" />`;
+ * ```
+ */
 export declare function Router<C = any>(props: RouterProps<C>): any;
 /** Renders this layout's child route, inside this layout's context. */
 export declare function Outlet(): any;
@@ -39,6 +50,14 @@ export declare function Redirect(props: {
     to: string;
     replace?: boolean;
 }): null;
+/**
+ * The router context: the router itself, the current match, and the location.
+ *
+ * Safe to call during a server render, where a detached context yields a no-op stub
+ * rather than throwing, since an SSR pass has nowhere to navigate to. On the client a
+ * missing router is genuine misuse and throws, because the alternative is a component
+ * that silently never navigates.
+ */
 export declare function useRouter(): RouterCtxValue;
 /**
  * Reactive merged params across all matched layers, as an accessor. Deep-equal
@@ -50,7 +69,7 @@ export declare function useParams<T extends Record<string, string> = Record<stri
 export declare function useLevelParams(): Record<string, string>;
 /**
  * Reactive accessor for a single route param. Default `===` equality on the
- * string value, so it only re-triggers when THIS key changes — not when other
+ * string value, so it only re-triggers when this key changes, not when other
  * params at the same level change.
  */
 export declare function useParam(key: string): () => string | undefined;
@@ -97,9 +116,11 @@ export declare function useLocation(): RouterLocation;
 export interface LinkNavigationOptions {
     /** Replace the current history entry instead of pushing a new one. */
     replace?: boolean;
+    /** How this navigation is presented. Defaults to the Router's own setting. */
+    transition?: TransitionMode;
     /**
      * Called with the resolved URL before navigating. Return false to leave the click
-     * alone — for a section of the app that must load as a document (a different
+     * alone, for a section of the app that must load as a document (a different
      * bundle, a server-rendered admin area, a file route).
      */
     shouldNavigate?: (url: URL, anchor: HTMLAnchorElement) => boolean;
@@ -117,17 +138,35 @@ export interface LinkNavigationOptions {
  * <article onClick={onClick} innerHTML={doc.html} />
  * ```
  *
- * The anchors stay real anchors — middle-click, right-click → open in new tab, "copy
+ * The anchors stay real anchors: middle-click, right-click -> open in new tab, "copy
  * link address" and crawlers all keep working, because the element is untouched and only
  * a plain left-click is intercepted.
  *
  * Left alone: modified clicks, anything but the primary button, an already-prevented
  * event, `target`, `download`, `rel="external"`, a non-http scheme (`mailto:`, `tel:`),
- * another origin, and a hash pointing inside the current page — that last one is the
+ * another origin, and a hash pointing inside the current page, that last one is the
  * browser's scroll, and hijacking it breaks in-page anchors.
  */
 export declare function useLinkNavigation(options?: LinkNavigationOptions): (event: MouseEvent) => void;
-export declare function useNavigate(): (to: string, options?: NavigateOptions) => void;
+/**
+ * A function that navigates, for use outside a `Link`.
+ *
+ * Reach for it after an action rather than for a plain link: a form that redirects on
+ * success, a guard that bounces an unauthenticated visitor. Prefer `Link` for anything a
+ * visitor clicks, since an anchor is what middle-click, copy-link and a crawler expect.
+ *
+ * Navigation is a no-op during a server render, for the reason `useRouter` explains.
+ *
+ * @example
+ * ```ts
+ * const navigate = useNavigate();
+ * await save(form);
+ * navigate(`/posts/${id}`, { replace: true });
+ * ```
+ */
+export declare function useNavigate(): (to: string, options?: NavigateOptions & {
+    transition?: TransitionMode;
+}) => void;
 /**
  * The resolved data for the nearest route that declared a `data` loader. Always
  * returns a callable accessor (matching the old router): it suspends under
@@ -147,13 +186,28 @@ export interface LinkProps {
     slot?: string;
     children?: any;
     /**
-     * Everything else is forwarded onto the `<a>` — id, style, title, aria-*,
+     * Everything else is forwarded onto the `<a>`: id, style, title, aria-*,
      * data-*, event handlers. Typed openly because the forwarding is
      * allow-by-default: a prop this interface forgot still reaches the DOM, and
      * refusing it here would only mean the type disagreeing with the runtime.
      */
     [key: string]: unknown;
 }
+/**
+ * An anchor that navigates without a full page load.
+ *
+ * Renders a real `<a href>`, so middle-click, copy-link, and a crawler all behave. A
+ * plain left click is intercepted and routed instead.
+ *
+ * Active state defaults to the current pathname matching `href`, and `activeClass` is
+ * added while it holds. Override `active` when a section link should stay lit for its
+ * children.
+ *
+ * @example
+ * ```ts
+ * html`<${Link} href="/about" activeClass="current">About</${Link}>`;
+ * ```
+ */
 export declare function Link(props: LinkProps): any;
 /** Alias for {@link Link}. */
 export declare const A: typeof Link;
@@ -180,7 +234,7 @@ export interface FormProps {
 export declare function Form(props: FormProps): any;
 /**
  * Download the lazy component chunks for the route(s) matching `pathname` and resolve when
- * they're all loaded. Await this BEFORE hydrating: once each matched lazy file-route is
+ * they're all loaded. Await this before hydrating: once each matched lazy file-route is
  * resolved it renders synchronously on the first pass (no Suspense fallback, no late
  * re-render), so hydration adopts the server DOM in place instead of building a duplicate
  * subtree next to it. No-op for routes with no lazy components. Safe to call when the URL
@@ -192,5 +246,6 @@ export type { RouteDefinition, RouteMatch, MatchedRoute, RouterLocation, Navigat
 export { cache, action, revalidate, createAsync, useSubmission, useAction, } from './data.js';
 export type { RouteDataArgs, RouteLoadFunc, Action, Submission, CacheFn, } from './data.js';
 export { lazy } from '../render/lazy.js';
+export { supportsViewTransitions, prefersReducedMotion, type TransitionMode, } from './transition.js';
 export { runWithOwner } from '@fluixi/reactive/signal';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/lib/router/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/router/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/router/index.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/router/index.js

@@ -1,21 +1,21 @@
 /**
- * @fileoverview Fluixi adapter for the framework-agnostic @fluixi/router core.
  *
  * Renders the resolved match tree TOP-DOWN. Each layer's component is rendered
  * inside the PARENT layer's <Outlet/> scope, so a child route inherits whatever
  * context a parent layout provides. <Outlet/> is reactive but keyed on the child's
  * component reference, so it only re-renders when the child route at that depth
- * actually changes — sibling navigation reuses the layout, deeper navigation
+ * actually changes: sibling navigation reuses the layout, deeper navigation
  * leaves shallower layouts untouched.
  *
  * No parentGate, no deferred content memo: a child is rendered straight from the
  * matched array, never by re-entering a still-building parent, so deeply nested
  * <Outlet/> works at any depth.
  */
-import { createSignal, createMemo, createResource, createEffect, getOwner, onCleanup, untrack, } from '@fluixi/reactive/signal';
+import { createSignal, createMemo, createResource, createEffect, getOwner, onCleanup, untrack, flush, } from '@fluixi/reactive/signal';
+import { prepareComponents, runTransition, } from './transition.js';
 import { insert, createComponent, createNativeElement, setAttribute, } from '@fluixi/dom';
 // Reactive context (not fluixi createProvider, which destructures children
-// eagerly) so a `get children()` getter renders AFTER the context is stamped.
+// eagerly) so a `get children()` getter renders after the context is stamped.
 import { createContext, useContext } from '@fluixi/reactive/signal';
 import { get } from '@fluixi/utils/object';
 import { deepEqual } from '@fluixi/utils/compare';
@@ -59,14 +59,14 @@ function renderLayer(m, depth, base) {
     });
     if (!data)
         return buildPage();
-    // Gate on the data being resolved — like the old router — so the page reads
+    // Gate on the data being resolved, like the old router, so the page reads
     // ready data (rd() returns the value, not a thrown promise) and works without a
     // Suspense boundary. Signal-gated (`ready` only flips when loading actually
     // changes) so navigation re-renders don't re-run this and rebuild the page.
     const res = data;
     const isLoading = () => res.loading;
     // untrack the initial read so the enclosing render memo doesn't subscribe to the
-    // resource state (that would re-run renderLayer and recreate the resource — a loop).
+    // resource state (that would re-run renderLayer and recreate the resource, a loop).
     const [ready, setReady] = createSignal(untrack(() => !isLoading()));
     createEffect(() => setReady(!isLoading()));
     return createMemo(() => (ready() ? buildPage() : null));
@@ -83,19 +83,23 @@ function renderChild(ctx) {
     // signal write (no value check), so a memo that read `matched` would re-run on
     // every navigation and re-render the child. A signal only notifies when its value
     // actually changes, so the render memo below re-runs only when the route at this
-    // depth changes — sibling navigation reuses the layout, deeper navigation leaves
+    // depth changes: sibling navigation reuses the layout, deeper navigation leaves
     // this level untouched. The child is rendered INLINE (no detached createRoot), so
     // it stays connected to the Suspense / context owner chain.
     const [childComp, setChildComp] = createSignal(untrack(() => ctx.matched()[childIdx]?.component));
     createEffect(() => {
         const c = ctx.matched()[childIdx]?.component;
-        setChildComp(() => c);
+        // `matched` is invalidated more than once per navigation, so this effect runs more
+        // than once. Writing only on a real change keeps the redundant runs from touching
+        // the graph at all.
+        if (untrack(childComp) !== c)
+            setChildComp(() => c);
     });
     return createMemo(() => {
         const component = childComp();
         if (!component) {
-            // No route at this depth. At the ROOT (the only ctx carrying `notFound`) that means the
-            // URL matched nothing — render the not-found fallback instead of a blank page. Nested
+            // No route at this depth. At the root (the only ctx carrying `notFound`) that means the
+            // URL matched nothing: render the not-found fallback instead of a blank page. Nested
             // Outlets have no `notFound`, so they stay null (a missing child is just an empty Outlet).
             return ctx.notFound ? ctx.notFound() : null;
         }
@@ -110,8 +114,8 @@ function renderChild(ctx) {
 /**
  * Resolve the Router's `notFound` prop to a renderable view. A component is instantiated; an
  * element/value is returned as-is; when omitted, a minimal built-in 404 keeps the page from
- * rendering blank. Prefer a catch-all file route (`[...slug].tsx` → `*`) when the 404 should sit
- * inside your layout — this prop is the app-level fallback for an otherwise unmatched URL.
+ * rendering blank. Prefer a catch-all file route (`[...slug].tsx` -> `*`) when the 404 should sit
+ * inside your layout, this prop is the app-level fallback for an otherwise unmatched URL.
  */
 function renderNotFound(notFound) {
     if (notFound == null)
@@ -135,6 +139,25 @@ function buildDefaultNotFound() {
     el.appendChild(p);
     return el;
 }
+/**
+ * The presentation for the navigation about to happen, handed from `useNavigate` to the
+ * subscriber in `Router`. Read and cleared within the same synchronous call.
+ */
+let pendingTransitionMode;
+/**
+ * The router. Matches the current URL against `routes` and renders what matches.
+ *
+ * Supplies the router context everything below reaches through `useRouter`,
+ * `useNavigate` and `Link`, so those only work inside it. `history` defaults to a
+ * browser history; pass a memory history for tests or a server render. An unmatched URL
+ * renders `notFound`, which defaults to a minimal built-in page so a bad URL is never
+ * blank. For a 404 that keeps your layout, add a catch-all file route instead.
+ *
+ * @example
+ * ```ts
+ * html`<${Router} routes=${routes} base="/app" />`;
+ * ```
+ */
 export function Router(props) {
     const history = props.history ?? createBrowserHistory();
     const router = createCoreRouter({
@@ -143,12 +166,64 @@ export function Router(props) {
         history,
     });
     const [state, setState] = createSignal(router.state());
-    const unsub = router.subscribe(setState);
+    /**
+     * Which navigation is allowed to commit.
+     *
+     * Preparation is async, so two navigations can be in flight at once: A→B starts
+     * loading B's chunk, the reader clicks through to C before it lands. Each navigation
+     * takes the next number and checks it is still the current one before writing the
+     * match signal, so B resolving late finds itself superseded and returns without
+     * touching anything. Without this, B would commit over C, the URL would say /c and
+     * the page would show B.
+     */
+    let navigationId = 0;
+    /**
+     * How to present the next commit, set by `useNavigate` immediately before it calls
+     * into the core router.
+     *
+     * A module-level hand-off rather than a parameter because the core router's
+     * `navigate` does not carry options through to its listeners, and it notifies
+     * synchronously: the value is written and read within the same call, never left
+     * lying around for an unrelated navigation to pick up.
+     */
+    const takeMode = () => {
+        const mode = pendingTransitionMode ?? (props.transition ?? 'auto');
+        pendingTransitionMode = undefined;
+        return mode;
+    };
+    const unsub = router.subscribe((next) => {
+        const id = ++navigationId;
+        const mode = takeMode();
+        // Load the modules the next route needs before anything is torn down, so a lazy
+        // route renders straight through instead of suspending into a fallback with the
+        // old page already gone.
+        const prepared = prepareComponents((next.match?.matched ?? []).map((m) => m.component).filter(Boolean));
+        const commit = () => {
+            setState(next);
+            // The write only queues; effects are scheduled. Flushing here is what lets the
+            // browser snapshot a settled DOM rather than a half-built one.
+            return flush();
+        };
+        if (!prepared) {
+            // Nothing to wait for: stay on the tick this navigation was already on.
+            void runTransition(mode, commit);
+            return;
+        }
+        void prepared.then(() => {
+            // Superseded while the module loaded. The newer navigation owns the DOM now.
+            if (id !== navigationId)
+                return;
+            return runTransition(mode, commit);
+        });
+    });
     onCleanup(() => {
         unsub();
         router.destroy();
+        // Anything still preparing is now stale, so nothing can commit into a torn-down
+        // router.
+        navigationId++;
     });
-    // Drop pathless layers (no component) — their params still appear in the merged
+    // Drop pathless layers (no component), their params still appear in the merged
     // params exposed by RouterContext.
     const matched = createMemo(() => (state().match?.matched ?? []).filter((m) => m.component));
     const ctx = {
@@ -162,12 +237,12 @@ export function Router(props) {
         matched,
         params: ctx.params,
         location: ctx.location,
-        // Only the root carries this — renderChild shows it when the URL matched nothing.
+        // Only the root carries this: renderChild shows it when the URL matched nothing.
         notFound: () => renderNotFound(props.notFound),
     };
     // Build the root view once, lazily, inside the provider's children getter: the
     // getter must run in the provider scope (so components can useRouter), but the
-    // reactive provider re-invokes it whenever content changes — caching keeps the
+    // reactive provider re-invokes it whenever content changes: caching keeps the
     // root chain from being rebuilt on every navigation.
     let rootView;
     return RouterContext.Provider({
@@ -190,7 +265,7 @@ export function Redirect(props) {
     const ctx = useContext(RouterContext);
     // Nothing to do without a router, and nothing to navigate on the server.
     if (ctx && typeof window !== 'undefined') {
-        // Navigate AFTER the current render commits. Navigating during render (an effect
+        // Navigate after the current render commits. Navigating during render (an effect
         // running mid-render) updated the location but the route never re-matched, so the
         // target never showed. Guard against firing if this Redirect is torn down first.
         let cancelled = false;
@@ -204,9 +279,9 @@ export function Redirect(props) {
 }
 // ─── Hooks ──────────────────────────────────────────────────────────────────
 // Safe stub returned by useRouter on the SERVER when no RouterContext is on the owner
-// chain. That happens during a late/detached re-render — e.g. a slow data resource
-// settling AFTER renderToStringAsync already serialized the response and disposed the
-// root — whose output is discarded. Returning this (instead of throwing) prevents a
+// chain. That happens during a late/detached re-render: e.g. a slow data resource
+// settling after renderToStringAsync already serialized the response and disposed the
+// root: whose output is discarded. Returning this (instead of throwing) prevents a
 // floating rejection that crashes the dev server / shows an error overlay seconds
 // after the page already rendered.
 const _ssrRouterStub = {
@@ -214,12 +289,20 @@ const _ssrRouterStub = {
     location: () => ({ pathname: '', search: '', hash: '', query: {} }),
     params: () => ({}),
 };
+/**
+ * The router context: the router itself, the current match, and the location.
+ *
+ * Safe to call during a server render, where a detached context yields a no-op stub
+ * rather than throwing, since an SSR pass has nowhere to navigate to. On the client a
+ * missing router is genuine misuse and throws, because the alternative is a component
+ * that silently never navigates.
+ */
 export function useRouter() {
     const ctx = useContext(RouterContext);
     if (ctx)
         return ctx;
     // On the server, degrade to a no-op stub (see above). On the client, a missing
-    // router is genuine misuse — throw.
+    // router is genuine misuse: throw.
     if (typeof window === 'undefined')
         return _ssrRouterStub;
     throw new Error('[router] useRouter must be used within <Router>');
@@ -241,7 +324,7 @@ export function useLevelParams() {
 }
 /**
  * Reactive accessor for a single route param. Default `===` equality on the
- * string value, so it only re-triggers when THIS key changes — not when other
+ * string value, so it only re-triggers when this key changes, not when other
  * params at the same level change.
  */
 export function useParam(key) {
@@ -331,13 +414,13 @@ export function useLocation() {
  * <article onClick={onClick} innerHTML={doc.html} />
  * ```
  *
- * The anchors stay real anchors — middle-click, right-click → open in new tab, "copy
+ * The anchors stay real anchors: middle-click, right-click -> open in new tab, "copy
  * link address" and crawlers all keep working, because the element is untouched and only
  * a plain left-click is intercepted.
  *
  * Left alone: modified clicks, anything but the primary button, an already-prevented
  * event, `target`, `download`, `rel="external"`, a non-http scheme (`mailto:`, `tel:`),
- * another origin, and a hash pointing inside the current page — that last one is the
+ * another origin, and a hash pointing inside the current page, that last one is the
  * browser's scroll, and hijacking it breaks in-page anchors.
  */
 export function useLinkNavigation(options = {}) {
@@ -369,15 +452,38 @@ export function useLinkNavigation(options = {}) {
         if (options.shouldNavigate && !options.shouldNavigate(url, anchor))
             return;
         event.preventDefault();
+        pendingTransitionMode = options.transition;
         ctx.router.navigate(url.pathname + url.search + url.hash, { replace: options.replace });
     };
 }
+/**
+ * A function that navigates, for use outside a `Link`.
+ *
+ * Reach for it after an action rather than for a plain link: a form that redirects on
+ * success, a guard that bounces an unauthenticated visitor. Prefer `Link` for anything a
+ * visitor clicks, since an anchor is what middle-click, copy-link and a crawler expect.
+ *
+ * Navigation is a no-op during a server render, for the reason `useRouter` explains.
+ *
+ * @example
+ * ```ts
+ * const navigate = useNavigate();
+ * await save(form);
+ * navigate(`/posts/${id}`, { replace: true });
+ * ```
+ */
 export function useNavigate() {
     // useRouter is SSR-safe (returns a no-op stub on the server when the context is
     // detached), so navigation degrades to a no-op during SSR and only throws on
     // genuine client-side misuse outside <Router>.
     const { router } = useRouter();
-    return (to, options) => router.navigate(to, options);
+    return (to, options) => {
+        // Handed to the Router's subscriber, which runs synchronously inside the call
+        // below and clears it. `transition: 'none'` on one navigation leaves the router's
+        // own setting alone for the next.
+        pendingTransitionMode = options?.transition;
+        router.navigate(to, options);
+    };
 }
 /**
  * The resolved data for the nearest route that declared a `data` loader. Always
@@ -400,18 +506,33 @@ const LINK_OWN_PROPS = new Set([
     'replace',
     'children',
 ]);
+/**
+ * An anchor that navigates without a full page load.
+ *
+ * Renders a real `<a href>`, so middle-click, copy-link, and a crawler all behave. A
+ * plain left click is intercepted and routed instead.
+ *
+ * Active state defaults to the current pathname matching `href`, and `activeClass` is
+ * added while it holds. Override `active` when a section link should stay lit for its
+ * children.
+ *
+ * @example
+ * ```ts
+ * html`<${Link} href="/about" activeClass="current">About</${Link}>`;
+ * ```
+ */
 export function Link(props) {
     const ctx = useContext(RouterContext);
     const navigate = () => ctx?.router.navigate(read(props.href) ?? '', { replace: read(props.replace) });
-    // createNativeElement branches on isServer() → a real ServerNode <a> (serialized as a true
+    // createNativeElement branches on isServer() -> a real ServerNode <a> (serialized as a true
     // element, not an escaped string) on the server, a real DOM <a> on the client.
     const a = createNativeElement('a');
     setAttribute(a, 'href', read(props.href) ?? '');
     if (props.slot)
         setAttribute(a, 'slot', read(props.slot));
-    // Forward any other author attributes (data-*, aria-*, style, id, title, role, …)
+    // Forward any other author attributes (data-*, aria-*, style, id, title, role, ...)
     // onto the <a>, the way <Form> does. Without this a component composed via
-    // `as={Link}` (polymorphic) silently loses its styling hooks — e.g. @fluixi-ui
+    // `as={Link}` (polymorphic) silently loses its styling hooks: e.g. @fluixi-ui
     // parts carry `data-*` slots + inline styles that would otherwise be dropped, so
     // the element renders unstyled. Own-props handled elsewhere are skipped:
     // href/slot above, class/className/active/activeClass in the effect, and
@@ -419,7 +540,7 @@ export function Link(props) {
     // Keys, not entries: `Object.entries` reads every prop, and `children` is a getter
     // that builds fresh nodes per access. Under hydration that discarded first build
     // consumes the server's nodes, so the real read below produced a second copy of
-    // them — a duplicated logo and pager on every prerendered page.
+    // them, a duplicated logo and pager on every prerendered page.
     for (const k of Object.keys(props)) {
         if (LINK_OWN_PROPS.has(k))
             continue;
@@ -444,7 +565,7 @@ export function Link(props) {
             setAttribute(a, 'class', base);
     }
     // Client only: keep href + active class in sync with reactive props / location.
-    // (Skipped on the server — `a` is a ServerNode without these DOM setters; the static
+    // (Skipped on the server: `a` is a ServerNode without these DOM setters; the static
     // href/class were set above.)
     if (typeof a.addEventListener === 'function') {
         createEffect(() => {
@@ -476,18 +597,18 @@ export const A = Link;
  */
 export function Form(props) {
     const action = props.action;
-    const cls = (props.className ?? props.class); // compiler passes class→className
+    const cls = (props.className ?? props.class); // compiler passes class -> className
     const url = action.url ?? '';
     // createNativeElement/setAttribute branch on isServer(), so this builds a real ServerNode
-    // <form> on the server (serialized as a true element, NOT an escaped string) and a real
-    // DOM <form> on the client — hydration reuses the same element.
+    // <form> on the server (serialized as a true element, not an escaped string) and a real
+    // DOM <form> on the client: hydration reuses the same element.
     const form = createNativeElement('form');
     setAttribute(form, 'method', 'post');
     if (url)
         setAttribute(form, 'action', url);
     if (cls)
         setAttribute(form, 'class', cls);
-    // Keys, not entries — same reason as Link: reading `children` here would build its
+    // Keys, not entries, same reason as Link: reading `children` here would build its
     // nodes once and throw them away.
     for (const k of Object.keys(props)) {
         if (k === 'action' || k === 'children' || k === 'class' || k === 'className')
@@ -513,7 +634,7 @@ export function Form(props) {
     }
     // Read children ONCE: the compiler emits `get children()` as a getter that builds fresh
     // nodes on every access, so reading it twice (here + the null check) created a duplicate
-    // set — under hydration that meant two <input>s in the form.
+    // set: under hydration that meant two <input>s in the form.
     const children = props.children;
     if (children != null)
         insert(form, children);
@@ -522,7 +643,7 @@ export function Form(props) {
 // ─── Hydration preload ───────────────────────────────────────────────────────────
 /**
  * Download the lazy component chunks for the route(s) matching `pathname` and resolve when
- * they're all loaded. Await this BEFORE hydrating: once each matched lazy file-route is
+ * they're all loaded. Await this before hydrating: once each matched lazy file-route is
  * resolved it renders synchronously on the first pass (no Suspense fallback, no late
  * re-render), so hydration adopts the server DOM in place instead of building a duplicate
  * subtree next to it. No-op for routes with no lazy components. Safe to call when the URL
@@ -542,9 +663,12 @@ export async function preloadRoutes(routes, pathname) {
 }
 // ─── Re-exports ────────────────────────────────────────────────────────────────
 export { createMemoryHistory, createBrowserHistory, matchRoutes, matchPath, } from '@fluixi/router';
-// Action/cache/lazy layer is orthogonal to routing — re-export so a route file can
+// Action/cache/lazy layer is orthogonal to routing: re-export so a route file can
 // swap its import path wholesale. (Routing hooks above are the router ones.)
 export { cache, action, revalidate, createAsync, useSubmission, useAction, } from './data.js';
 export { lazy } from '../render/lazy.js';
+// Navigation presentation. The router owns the integration; these are exported for
+// apps that need to ask what the environment supports.
+export { supportsViewTransitions, prefersReducedMotion, } from './transition.js';
 // Carried over from the barrel this replaced; route codegen imports it from here.
 export { runWithOwner } from '@fluixi/reactive/signal';