proteum 2.5.25 → 2.6.0

package/README.md

@@ -275,6 +275,7 @@ my-app/
 
 | Topic | Guide |
 | --- | --- |
+| Client navigation (blocking, deferred, prefetch) | [docs/client-navigation.md](docs/client-navigation.md) |
 | Diagnostics & explainability | [docs/diagnostics.md](docs/diagnostics.md) |
 | Model Context Protocol (MCP) | [docs/mcp.md](docs/mcp.md) |
 | Request tracing & perf | [docs/request-tracing.md](docs/request-tracing.md) |

package/agents/project/AGENTS.md

@@ -252,6 +252,8 @@ export default defineController({
 - Controller fetchers and promises returned from `data` resolve before render.
 - `render` consumes resolved page data and uses generated controller methods from render args or `@/client/context`.
 - Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page data state.
+- Client navigation is blocking by default: data first, then the swap. A page swaps in before its data only when the router config sets `navigation: { mode: 'deferred' }`, the page sets `options.navigation: 'deferred'`, and it has a `data` loader. Its render then receives every data key as possibly `undefined` plus a `navigation` prop (`status` `ready`, `pending` or `error`, `stale`, `reloading`, `error`, `since`, `retry()`), must render the pending and error states, and cannot return a data key named `navigation`. Contract: `node_modules/proteum/docs/client-navigation.md`.
+- Run page-view analytics and anything that needs the page data on screen on the `page.ready` router hook, not `page.changed`. It fires once per navigation, when the data is first on screen (on a deferred page that includes a `retry()` recovering a failed first data step), never for later retries or reloads. Read the URL from the request it passes, not `window.location`. The router resets `document.body` classes before both hooks: an app re-adds its own in both.
 - Error pages use `defineErrorRoute({ code, options, render })` in `client/pages/_messages/**`.
 - Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path, options object, and data payload.
 

package/agents/project/client/pages/AGENTS.md

@@ -36,9 +36,30 @@ export default definePageRoute({
 - Route behavior belongs in the explicit `options` object, not in page data.
 - `data` returns one flat object, or the route definition sets `data: null` when no page data is needed.
 - Returning route-option keys such as `auth`, `layout`, `static`, `redirectLogged`, or their `_`-prefixed variants from `data` is a contract error.
-- Controller fetchers and promises returned from `data` resolve before render.
+- Controller fetchers and promises returned from `data` resolve before render, except on a deferred page (below). Only controller fetchers reach the server; other promises resolve in the browser and plain values skip the round trip. Both go through JSON, as SSR data does. A loader without any controller fetcher sends no request on a client navigation.
 - If a page needs route data, return it from `data` and read it in `render`.
 
+## Blocking And Deferred Navigation
+
+- Blocking is the default: a client navigation fetches the page data, then swaps the page in. Render reads resolved data only.
+- `options: { navigation: 'deferred' }` swaps the page in before its data, but only when the router config sets `navigation: { mode: 'deferred' }` and the page has a `data` loader. Otherwise the page stays blocking and its `navigation` prop is always `ready`.
+- A deferred render receives every data key as `T | undefined` and a `navigation` prop: `status` (`ready`, `pending`, `error`), `pending`, `stale` (previous data still on screen), `reloading` (that data is this page's own: `api.reload`, or `retry()` after ready), `error`, `since`, `retry()`. Render the skeleton while data is missing, the previous data while `stale`, and an error with `navigation.retry()` on `error`. A render that reads the URL beside its data keeps stale data only while `reloading`.
+- A deferred page cannot return a data key named `navigation`. Blocking pages may.
+- Keep pages blocking when they redirect or throw on their data, and for public full-load pages.
+- `api.reload(...)` on a deferred page re-runs only its data step through `navigation.retry()` and merges the result into the page state, keeping `api.set` values.
+- `page.ready` fires once per navigation, when its data is first on screen, including after a `retry()` that recovers a failed first data step; never for later retries or reloads.
+- Full contract: `node_modules/proteum/docs/client-navigation.md`.
+
+```tsx
+export default definePageRoute({
+    path: '/radars',
+    options: { auth: true, navigation: 'deferred' },
+    data: ({ Radars }) => ({ radars: Radars.list() }),
+    render: ({ radars, navigation }) =>
+        radars === undefined ? <RadarsSkeleton navigation={navigation} /> : <RadarsPage radars={radars} />,
+});
+```
+
 ## Page Rules
 
 - Prefer generated page args or the app client context. Do not import `.proteum` implementation files directly.

package/client/services/router/components/Link.tsx

@@ -5,6 +5,11 @@
 // Npm
 import React from 'react';
 import type { ComponentChild } from 'preact';
+
+// Core
+import { ReactClientContext } from '@/client/context';
+
+// Specific
 import { history } from '../request/history';
 
 export const shouldOpenNewTab = (url: string, target?: string) =>
@@ -21,16 +26,35 @@ export const Link = ({
     className,
     onClick,
     target,
+    prefetch,
     ...props
 }: {
     to: string;
     children?: ComponentChild;
     class?: string;
     className?: string;
+    // Loads the route chunk of `to` on hover or focus
+    prefetch?: boolean;
 } & React.AnchorHTMLAttributes<HTMLAnchorElement>) => {
+    const context = React.useContext(ReactClientContext);
     const openNewTab = shouldOpenNewTab(to, typeof target === 'string' ? target : undefined);
     const resolvedTarget = openNewTab ? '_blank' : target;
 
+    const { onMouseEnter, onFocus } = props;
+    const prefetchHandlers =
+        prefetch && !openNewTab
+            ? {
+                  onMouseEnter: (e: React.MouseEvent<HTMLAnchorElement>) => {
+                      void context?.Router.prefetch(to);
+                      onMouseEnter?.(e);
+                  },
+                  onFocus: (e: React.FocusEvent<HTMLAnchorElement>) => {
+                      void context?.Router.prefetch(to);
+                      onFocus?.(e);
+                  },
+              }
+            : {};
+
     const handleClick: React.MouseEventHandler<HTMLAnchorElement> | undefined = openNewTab
         ? onClick
         : (e) => {
@@ -42,6 +66,7 @@ export const Link = ({
     return (
         <a
             {...props}
+            {...prefetchHandlers}
             href={to}
             target={resolvedTarget}
             onClick={handleClick}

package/client/services/router/components/Page.tsx

@@ -6,6 +6,7 @@ import React from 'react';
 
 // Core
 import useContext from '@/client/context';
+import type { TFrontRenderer } from '@common/router/response/page';
 
 // Specific
 import type Page from '../response/page';
@@ -25,6 +26,12 @@ export default ({ page }: { page: Page }) => {
     page.setAllData = setApiData;
     const fullData = { ...context.data, ...apiData };
 
+    // Bind navigation the same way: the page instance holds the state, the setter re-renders
+    //  A same-chunk navigation keeps this component, so the new page takes over both setters
+    const [, setNavigation] = React.useState(page.navigation);
+    page.setNavigation = setNavigation;
+    const { navigation } = page;
+
     // Temporary fix: context.page may not be updated at this stage
     //  Seems to be the case when we change page, but still same page component with different data
     // TODO: ensure these updated are made every tume we change page / context
@@ -33,15 +40,24 @@ export default ({ page }: { page: Page }) => {
     context.context = context;
 
     // Page component has not changed, but data were updated (ex: url parameters change)
+    //  A deferred page gets its data from the navigation sequencer instead: it keeps the previous data
+    //  on screen while stale, and merges a reload into what api.set wrote
     React.useEffect(() => {
-        setApiData(page.data);
+        if (!page.isDeferred()) setApiData(page.data);
     }, [page.data]);
 
-    const rendererProps = { ...context, ...fullData } as Parameters<NonNullable<typeof page.renderer>>[0];
+    // Only a page declaring navigation: 'deferred' receives the prop: blocking pages may use the key for data
+    const rendererProps = {
+        ...context,
+        ...fullData,
+        ...(page.route.options.navigation === 'deferred' ? { navigation } : {}),
+    } as Parameters<TFrontRenderer>[0];
+    // A deferred renderer reads the same props, plus `navigation`
+    const Renderer = page.renderer as TFrontRenderer | undefined;
 
     /*----------------------------------
     - RENDER
     ----------------------------------*/
     //  Make request parameters and api data accessible from the page component
-    return page.renderer ? <page.renderer {...rendererProps} /> : <>Renderer missing</>;
+    return Renderer ? <Renderer {...rendererProps} /> : <>Renderer missing</>;
 };

package/client/services/router/components/router.tsx

@@ -15,6 +15,7 @@ import ClientRequest from '../request';
 import { history, location, Update } from '../request/history';
 //import initTooltips from '@client/components/Donnees/Tooltip';
 import type Page from '../response/page';
+import { createNavigationSequencer, type TNavigationSequencer } from '../navigation';
 
 /*----------------------------------
 - TYPES
@@ -35,8 +36,108 @@ const withProfiler = <T,>(callback: (runtime: (typeof import('@client/dev/profil
     return callback(profilerModule.profilerRuntime);
 };
 
-const scrollToElement = (selector: string) =>
-    document.querySelector(selector)?.scrollIntoView({ behavior: 'smooth', block: 'start', inline: 'nearest' });
+// The hash arrives percent-encoded (`#caf%C3%A9`): the id is matched decoded, like the browser's own fragment scroll
+const readHashId = (hash: string) => {
+    const id = hash.startsWith('#') ? hash.slice(1) : hash;
+    try {
+        return decodeURIComponent(id);
+    } catch (error) {
+        // A malformed escape cannot name a decoded id: look it up as written
+        if (error instanceof URIError) return id;
+        throw error;
+    }
+};
+
+// Exported for the router tests. A hash names an element id, so look the id up: as a selector, `#prices` minus
+//  its `#` matches a <prices> tag, and an id such as `2026-prices` throws.
+export const scrollToHash = (hash: string) => {
+    const id = readHashId(hash);
+    if (id) document.getElementById(id)?.scrollIntoView({ behavior: 'smooth', block: 'start', inline: 'nearest' });
+};
+
+/*----------------------------------
+- NAVIGATION
+----------------------------------*/
+
+type TRouterView = {
+    setCurrentPage: React.Dispatch<React.SetStateAction<Page | undefined>>;
+    setReadyCount: React.Dispatch<React.SetStateAction<number>>;
+};
+
+type TRouterNavigation = { sequencer: TNavigationSequencer<ClientRequest, Page>; view: TRouterView };
+
+const navigations = new WeakMap<ClientRouter, TRouterNavigation>();
+
+// Exported for the router tests
+export const createRouterNavigation = (
+    clientRouter: ClientRouter,
+    context: ReturnType<typeof useContext>,
+    view: TRouterView,
+    initialPage: Page | undefined,
+): TRouterNavigation => {
+    const navigation: TRouterNavigation = { view, sequencer: undefined! };
+
+    navigation.sequencer = createNavigationSequencer<ClientRequest, Page>(
+        {
+            resolve: (request, isCurrent) => clientRouter.resolve(request, isCurrent),
+            defers: (page) => page.isDeferred(),
+            prepare: (page) => {
+                page.prepareFetchers();
+            },
+            // Fetch API data to hydrate the page
+            fetch: (page, prepared) => page.preRender(undefined, prepared ? page.fetchers : undefined),
+            commit: (newpage) => {
+                // The context names the page on screen: set at the swap, never at resolution, so a navigation
+                //  that never commits (superseded, failed) leaves api.set and api.reload on the page still shown
+                context.page = newpage as typeof context.page;
+
+                // Add page container
+                navigation.view.setCurrentPage((page) => {
+                    // WARN: Don't cancel navigation if same page as before, as we already instanciated the new page
+                    //  and bound the context with it. Otherwise it would cause reference issues
+                    //  (ex: page.setAllData makes ref to the new context)
+
+                    // If if the layout changed
+                    const curLayout = page?.layout;
+                    const newLayout = newpage?.layout;
+                    if (newLayout && curLayout && newLayout.path !== curLayout.path) {
+                        // TEMPORARY FIX: reload everything when we change layout
+                        //  Because layout can have a different CSS theme
+                        //  But when we call setLayout, the style of the previous layout are still oaded and applied
+                        //  Find a way to unload the  previous layout / page resources before to load the new one
+                        console.log(LogPrefix, `Changing layout. Before:`, curLayout, 'New layout:', newLayout);
+                        const app = context.app as { setLayout?: (layout: NonNullable<typeof newLayout>) => void };
+                        app.setLayout?.(newLayout);
+                    }
+
+                    return newpage;
+                });
+            },
+            // Data and navigation state change in one batch, so no render sees ready without the data
+            render: (page, data) => {
+                if (data === 'replace') page.setAllData(() => page.data);
+                else if (data === 'merge') page.setAllData((current) => ({ ...current, ...page.data }));
+                page.setNavigation(page.navigation);
+            },
+            ready: () => navigation.view.setReadyCount((count: number) => count + 1),
+            setLoading: (loading) => clientRouter.setLoading(loading),
+            fail: (step, error, sessionId) => {
+                const message = step === 'route' ? 'Unable to load the page:' : 'Unable to fetch data:';
+                console.error(LogPrefix, message, error);
+                // A chunk that fails to load means a new version: the app error handler tells the user
+                if (step === 'route') clientRouter.app.handleError(error);
+                if (step === 'retry') return;
+                withProfiler((runtime) =>
+                    runtime.failNavigation(error instanceof Error ? error.message : String(error), sessionId),
+                );
+            },
+            startRender: (sessionId) => withProfiler((runtime) => runtime.startRenderStep(sessionId)),
+        },
+        initialPage,
+    );
+
+    return navigation;
+};
 
 /*----------------------------------
 - COMPONENT
@@ -48,6 +149,18 @@ export default ({ service: clientRouter, loaderComponent }: TProps) => {
 
     const context = useContext();
     const [currentPage, setCurrentPage] = React.useState<undefined | Page>(context.page as Page | undefined);
+    // Bumped when a deferred page settles ready for the first time, so page.ready runs after that render
+    const [readyCount, setReadyCount] = React.useState(0);
+    const readyPage = React.useRef<Page>();
+
+    // The sequencer outlives this component, which remounts when the layout changes: ports reach the mounted one
+    const view: TRouterView = { setCurrentPage, setReadyCount };
+    let navigation = clientRouter && navigations.get(clientRouter);
+    if (navigation) navigation.view = view;
+    else if (clientRouter) {
+        navigation = createRouterNavigation(clientRouter, context, view, currentPage);
+        navigations.set(clientRouter, navigation);
+    }
 
     // Bind context object to client router
     if (clientRouter !== undefined) {
@@ -72,7 +185,7 @@ export default ({ service: clientRouter, loaderComponent }: TProps) => {
             request.hash !== currentRequest.hash &&
             request.hash !== undefined
         ) {
-            scrollToElement(request.hash);
+            scrollToHash(request.hash);
             return;
         }
 
@@ -85,62 +198,51 @@ export default ({ service: clientRouter, loaderComponent }: TProps) => {
         );
         clientRouter.runHook('page.change', request);
         window.scrollTo({ top: 0, behavior: 'smooth' });
-        clientRouter.setLoading(true);
-        const newpage = (context.page = await clientRouter.resolve(request));
 
-        // Unable to load (no connection, server error, ....)
-        if (newpage === null) return;
-
-        return await changePage(newpage, data, request, sessionId);
+        // Loader, route, then data and swap in the order of the page navigation mode
+        return await navigation?.sequencer.navigate(request, data, sessionId);
     };
 
-    async function changePage(newpage: Page, data?: {}, request?: ClientRequest, sessionId?: string) {
-        // Fetch API data to hydrate the page
-        try {
-            await newpage.preRender();
-        } catch (error) {
-            console.error(LogPrefix, 'Unable to fetch data:', error);
-            withProfiler((runtime) =>
-                runtime.failNavigation(error instanceof Error ? error.message : String(error), sessionId),
-            );
-            clientRouter?.setLoading(false);
-            return;
-        }
-
-        // Add additional data
-        if (data) newpage.data = { ...newpage.data, ...data };
-        withProfiler((runtime) => runtime.startRenderStep(sessionId));
-
-        // Add page container
-        setCurrentPage((page) => {
-            // WARN: Don't cancel navigation if same page as before, as we already instanciated the new page and bound the context with it
-            //  Otherwise it would cause reference issues (ex: page.setAllData makes ref to the new context)
-
-            // If if the layout changed
-            const curLayout = currentPage?.layout;
-            const newLayout = newpage?.layout;
-            if (newLayout && curLayout && newLayout.path !== curLayout.path) {
-                // TEMPORARY FIX: reload everything when we change layout
-                //  Because layout can have a different CSS theme
-                //  But when we call setLayout, the style of the previous layout are still oaded and applied
-                //  Find a way to unload the  previous layout / page resources before to load the new one
-                console.log(LogPrefix, `Changing layout. Before:`, curLayout, 'New layout:', newLayout);
-                /*window.location.replace( request ? request.url : window.location.href );
-                return page; // Don't spread since it's an instance*/
-
-                (context.app as { setLayout?: (layout: NonNullable<typeof newLayout>) => void }).setLayout?.(newLayout);
-            }
-
-            return newpage;
-        });
+    function changePage(newpage: Page, data?: {}) {
+        return navigation?.sequencer.show(newpage, data);
     }
 
     /*----------------------------------
     - HOOKS
     ----------------------------------*/
 
-    const restoreScroll = (currentPage?: Page) =>
-        currentPage?.scrollToId && scrollToElement(currentPage.scrollToId.substring(1));
+    const restoreScroll = (currentPage?: Page) => currentPage?.scrollToId && scrollToHash(currentPage.scrollToId);
+
+    const finishNavigation = (currentPage?: Page) => {
+        const routeLabel =
+            currentPage && 'path' in currentPage.route && currentPage.route.path
+                ? currentPage.route.path
+                : currentPage && 'code' in currentPage.route
+                  ? String(currentPage.route.code)
+                  : undefined;
+        withProfiler((runtime) =>
+            runtime.finishNavigation({
+                chunkId: currentPage?.chunkId,
+                routeLabel,
+                title: currentPage?.title,
+            }),
+        );
+    };
+
+    // page.ready: once per page, after the render that shows its data
+    const markReady = (page: Page | undefined, afterData: boolean) => {
+        if (!clientRouter || !page || readyPage.current === page || page.navigation.status !== 'ready') return;
+        readyPage.current = page;
+
+        if (afterData) {
+            // Title, body classes and hash target come from the render with data
+            page.updateClient();
+            restoreScroll(page);
+            finishNavigation(page);
+        }
+
+        clientRouter.runHook('page.ready', (page.context.request || context.request) as ClientRequest);
+    };
 
     // First render
     React.useEffect(() => {
@@ -155,12 +257,17 @@ export default ({ service: clientRouter, loaderComponent }: TProps) => {
         });
     }, []);
 
+    // A deferred page keeps the loader until its data settles. Read here, at render, for the effect below: data
+    //  landing between this render and that effect (one frame) would read as ready there, fire page.ready before
+    //  the data render, and leave the refresh after it (title, hash scroll, profiler) unrun.
+    const pending = currentPage !== undefined && currentPage.navigation.status !== 'ready';
+
     // On every page change
     React.useEffect(() => {
         if (!clientRouter) return;
 
         // Page loaded
-        clientRouter.setLoading(false);
+        if (!pending) clientRouter.setLoading(false);
 
         // Reset scroll
         window.scrollTo(0, 0);
@@ -168,24 +275,18 @@ export default ({ service: clientRouter, loaderComponent }: TProps) => {
         currentPage?.updateClient();
         // Scroll to the selected content via url hash
         restoreScroll(currentPage);
-        const routeLabel =
-            currentPage && 'path' in currentPage.route && currentPage.route.path
-                ? currentPage.route.path
-                : currentPage && 'code' in currentPage.route
-                  ? String(currentPage.route.code)
-                  : undefined;
-        withProfiler((runtime) =>
-            runtime.finishNavigation({
-                chunkId: currentPage?.chunkId,
-                routeLabel,
-                title: currentPage?.title,
-            }),
-        );
+        if (!pending) finishNavigation(currentPage);
 
         // Hooks
         clientRouter.runHook('page.changed', (currentPage?.context.request || context.request) as ClientRequest);
+        if (!pending) markReady(currentPage, false);
     }, [currentPage]);
 
+    // A deferred page settled ready
+    React.useEffect(() => {
+        if (readyCount > 0) markReady(currentPage, true);
+    }, [readyCount]);
+
     /*----------------------------------
     - RENDER
     ----------------------------------*/