proteum 2.5.25 → 2.7.0

package/README.md

@@ -275,13 +275,17 @@ my-app/
 
 | Topic | Guide |
 | --- | --- |
+| Client navigation (blocking, deferred, prefetch) | [docs/client-navigation.md](docs/client-navigation.md) |
+| Client assets (hashed names, cache headers, stale builds) | [docs/client-assets.md](docs/client-assets.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) |
+| HTTP security headers & CSP | [docs/http-security-headers.md](docs/http-security-headers.md) |
 | Agent routing & token efficiency | [docs/agent-routing.md](docs/agent-routing.md) |
 | Dev commands | [docs/dev-commands.md](docs/dev-commands.md) |
 | Dev sessions | [docs/dev-sessions.md](docs/dev-sessions.md) |
 | Migrating to 2.5 | [docs/migration-2.5.md](docs/migration-2.5.md) |
+| Release history | [docs/HISTORY.md](docs/HISTORY.md) |
 
 ## 🧭 Philosophy
 

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/cli/compiler/client/index.ts

@@ -15,6 +15,7 @@ import CssMinimizerPlugin from '../common/cssMinimizer';
 import { toRspackAliases } from '../common/rspackAliases';
 import { resolveUiSingletonAliases } from '../common/uiSingletons';
 import identityAssets from './identite';
+import { getClientOutputNames } from './outputNames';
 import cli from '../..';
 import { logVerbose } from '../../runtime/verbose';
 
@@ -126,6 +127,8 @@ export default function createCompiler(
     const transpileModuleDirectories = app.transpileModuleDirectories;
     const lightningCssTargets = resolveLightningCssTargets(app);
     const hmrClientEntry = path.join(frameworkSourceRoot, 'client', 'dev', 'hmr.ts');
+    // Content-hashed in production, entries included: see outputNames.ts.
+    const outputNames = getClientOutputNames(dev);
 
     const commonConfig = createCommonConfig(app, 'client', mode, outputTarget);
 
@@ -172,7 +175,7 @@ export default function createCompiler(
         output: {
             pathinfo: dev,
             path: outputPath + '/public',
-            filename: '[name].js', // Output client.js
+            filename: outputNames.entry,
             assetModuleFilename: '[hash][ext]',
             environment: {
                 arrowFunction: true,
@@ -185,9 +188,9 @@ export default function createCompiler(
                 optionalChaining: true,
                 templateLiteral: true,
             },
-            cssFilename: '[name].css',
-            cssChunkFilename: '[name].css',
-            chunkFilename: dev ? '[name].js' : '[id].[contenthash:8].js',
+            cssFilename: outputNames.css,
+            cssChunkFilename: outputNames.css,
+            chunkFilename: outputNames.chunk,
         },
 
         resolve: {
@@ -290,7 +293,9 @@ export default function createCompiler(
                   ]),
 
             // Extract CSS in dev too so SSR emits the same stylesheet links as production.
-            new rspack.CssExtractRspackPlugin({}),
+            // The extract plugin names its files itself (its default is `[name].css`); `output.cssFilename`
+            // only applies to native CSS, so the hashed name is passed here.
+            new rspack.CssExtractRspackPlugin({ filename: outputNames.css, chunkFilename: outputNames.css }),
 
             ...createClientBundleAnalysisPlugins(app, outputTarget),
         ],

package/cli/compiler/client/outputNames.ts

@@ -0,0 +1,28 @@
+/*----------------------------------
+- CLIENT OUTPUT NAMES
+----------------------------------*/
+
+export type TClientOutputNames = {
+    // Entry files: `runtime`, `framework`, `vendors`, `client`
+    entry: string;
+    // Async JS chunks
+    chunk: string;
+    // Entry and page CSS
+    css: string;
+};
+
+/*
+ * Production files carry a content hash, entries included. An unhashed `runtime.js` that a
+ * browser or CDN keeps after a deploy still maps chunk ids to files that no longer exist
+ * (21 Oct 2026: a 4 h CDN browser TTL served the old runtime, its chunks 404ed). The same holds
+ * for CSS: a page chunk keeps its name across builds, so new HTML could pair with a stylesheet
+ * from the previous build. The HTML reads every name from `client-manifest.json`, so nothing
+ * names these files, and the router's public cache classifies `name.<hash>.ext` as versioned.
+ *
+ * Dev keeps stable names: HMR and the dev middleware rely on them, and dev serves `no-store`.
+ * `[name]` stays before the hash so the network panel and bundle analysis stay readable.
+ */
+export const getClientOutputNames = (dev: boolean): TClientOutputNames =>
+    dev
+        ? { entry: '[name].js', chunk: '[name].js', css: '[name].css' }
+        : { entry: '[name].[contenthash:8].js', chunk: '[id].[contenthash:8].js', css: '[name].[contenthash:8].css' };

package/cli/compiler/common/files/autres.ts

@@ -23,6 +23,8 @@ module.exports = (app: App, dev: boolean, client: boolean) => [
         test: /\.(woff(2)?|ttf|eot)(\?v=\d+\.\d+\.\d+)?$/,
         //loader: 'file-loader',
         type: 'asset/resource',
-        generator: { filename: 'fonts/[name].[ext]' },
+        // Hashed so the router serves fonts immutable. `[ext]` carries its own dot: the former
+        // `[name].[ext]` emitted `figtree-latin..woff2`, unhashed and revalidated on every load.
+        generator: { filename: 'fonts/[name].[contenthash:8][ext]' },
     },
 ];

package/cli/scaffold/templates.ts

@@ -218,6 +218,10 @@ export const routerBaseConfig = {
         upload: {
             maxSize: '10mb',
         },
+        // Content-Security-Policy for router answers (HTML only under /api): see Proteum's docs/http-security-headers.md.
+        csp: {
+            scripts: [],
+        },
     },
     context: () => ({}),
 } satisfies RouterBaseConfig;

package/client/app/staleBuild.ts

@@ -0,0 +1,80 @@
+/*----------------------------------
+- STALE BUILD RECOVERY
+----------------------------------*/
+
+/*
+ * A page running an older build asks for chunk files that a deploy removed. The only cure is a
+ * fresh document: the new HTML names the new, content-hashed entry files, so a reload loads the
+ * new build. One reload per build id, kept in sessionStorage, so a chunk that is missing in the
+ * new build too (a deploy race, a CDN that kept a 404) ends on the error instead of a loop.
+ *
+ * - Every build id that reloaded is kept, not only the last one: during a rollout two builds can
+ *   answer at once, and a single slot let the tab bounce between them for as long as it lasted.
+ * - A route chunk that loads clears the list, so a reload spent on a network blip does not take
+ *   the recovery away from the real deploy that comes later in the same tab.
+ * - Offline, a chunk fails because there is no network, not because the build is gone: no reload,
+ *   which would only swap the page for the browser's offline screen.
+ */
+
+export const STALE_BUILD_RELOAD_KEY = 'proteum:stale-build-reload';
+
+// A rollout overlaps two builds at most; the cap only bounds what a long-lived tab can store
+const MAX_RELOADED_BUILDS = 5;
+
+type TReloadStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+
+export type TStaleBuildReloadOptions = {
+    storage?: () => TReloadStorage;
+    reload?: () => void;
+    isOnline?: () => boolean;
+};
+
+const defaultStorage = () => window.sessionStorage;
+
+const readReloadedBuilds = (store: TReloadStorage) => (store.getItem(STALE_BUILD_RELOAD_KEY) || '').split(',').filter(Boolean);
+
+// The shapes rspack's runtime rejects with: `ChunkLoadError` for a JS chunk, the code for a CSS chunk.
+export const isChunkLoadError = (error: Error) =>
+    error.name === 'ChunkLoadError' || ('code' in error && error.code === 'CSS_CHUNK_LOAD_FAILED');
+
+/**
+ * Reloads the page once for `buildId` and returns true, or returns false when this build already
+ * reloaded in this tab, when the browser is offline, or when sessionStorage is unavailable (no
+ * guard means no reload).
+ */
+export const reloadOnceForStaleBuild = (
+    buildId: string,
+    {
+        storage = defaultStorage,
+        reload = () => window.location.reload(),
+        isOnline = () => window.navigator.onLine !== false,
+    }: TStaleBuildReloadOptions = {},
+): boolean => {
+    if (!isOnline()) return false;
+
+    try {
+        const store = storage();
+        const reloaded = readReloadedBuilds(store);
+        if (reloaded.includes(buildId)) return false;
+
+        store.setItem(STALE_BUILD_RELOAD_KEY, [...reloaded, buildId].slice(-MAX_RELOADED_BUILDS).join(','));
+    } catch (error) {
+        // Storage blocked (private mode, sandboxed frame, quota): without the guard a reload could loop
+        console.warn('Stale build recovery skipped: sessionStorage is unavailable.', error);
+        return false;
+    }
+
+    reload();
+    return true;
+};
+
+/** A route chunk loaded: the running build is whole, so a later missing chunk gets its reload again. */
+export const clearStaleBuildReloads = (storage: () => TReloadStorage = defaultStorage) => {
+    try {
+        const store = storage();
+        if (store.getItem(STALE_BUILD_RELOAD_KEY) !== null) store.removeItem(STALE_BUILD_RELOAD_KEY);
+    } catch (error) {
+        // Nothing to clear when storage is blocked: the reload was never granted either
+        console.warn('Stale build recovery could not reset its guard.', error);
+    }
+};

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
     ----------------------------------*/