proteum 2.5.17 → 2.5.19

package/agents/project/AGENTS.md

@@ -23,6 +23,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - For every non-trivial coding task, load and follow root-level `DOCUMENTATION.md` before coding.
 - For bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes, load and follow root-level `DOCUMENTATION.md` before coding so the relevant fix note, regression-test docs, ADR, or explicit skip reason is handled in the same change.
 - If the user reports an issue, or you encounter one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
+- If the task adds or changes client data fetching, polling, or retry behavior, read the `Client Request Discipline` section in `client/AGENTS.md` before editing.
 - If the task touches client-side files, especially `client/**` and page files, load and apply root-level `optimizations.md` only after implementation for post-implementation checking and optimization. Skip it at task start and skip it for server-only, test-only, doc-only, and non-client refactor tasks unless the user explicitly asks for optimization work.
 - If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, use root-level `DOCUMENTATION.md` to choose the smallest relevant `./docs/` pack before editing. If a dev server is already running, print the live dev server URL as a clickable Markdown link.
 - If the task needs new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.

package/agents/project/client/AGENTS.md

@@ -31,6 +31,17 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - Toasts and form errors are local feedback only; use `setError(context.app.handleError(error, fallbackMessage))` or rethrow the caught error.
 - `console.*(error)` is not error handling and must not be the last stop for a caught error.
 
+## Client Request Discipline
+
+- A page or layout must not accumulate one mount-time API call per component or store. Before adding a request that fires on page load, extend an existing load-time payload (SSR `data`, the surface's bootstrap endpoint, or an already-fetched store) and hydrate from it; a new load-time call requires an explicit reason why no existing read can carry the data.
+- When an endpoint accepts a set (for example an array of ids), request the whole needed set in one call and coalesce triggers that land in the same tick. Never loop single-item requests over a known set.
+- Any effect or reactive block that can issue a request must key on explicit values (ids, tokens, statuses), must guard with sequence tokens so state identity churn cannot re-fire it, and must treat every terminal status, including `'error'`, as ineligible for automatic re-request.
+- Automatic retries require exponential backoff with jitter, a hard attempt cap, and respect for server pacing (`retryAfterMs`, `Retry-After`). A transport failure or a server failed status ends in a terminal error state with a manual retry affordance, never in an immediate re-request from a render or effect cycle.
+- Treat HTTP 429 as a stop signal for the whole surface, not as a retriable error.
+- Long polls honor the server-provided delay, run as a single chain per logical resource, and are cancelled when superseded or unmounted.
+- Identical concurrent requests must share one in-flight promise, usually a module-level cache with in-flight dedupe.
+- After changing load-time fetching, polling, or retry behavior, measure the surface's executed request count (browser network log or a request-count contract test) and report the before and after numbers with the change.
+
 ## Design
 
 - Follow the existing design language of the touched area.

package/agents/project/optimizations.md

@@ -31,6 +31,10 @@ When tradeoffs exist inside optimization work, optimize in this order:
 ## SEO And Crawlable Output
 
 - Improve SEO output and crawlable, semantic HTML.
+- The SSR document emits every script (entry and page chunks) as `defer` and never preloads a script or a stylesheet: a `defer` script is already fetched when the parser meets it, and the preloads used to race the render-critical CSS at High priority. A `page.scripts` entry with `attrs: { async: true }` keeps `async` instead of `defer`. Third-party tags that should not compete with the first paint belong in an inline loader that runs after `load`, not in a `url` entry.
+- `page.metas` keys are emitted as `name=` unless they belong to an Open Graph vocabulary (`og:`, `article:`, `fb:`, `profile:`, `book:`, `music:`, `video:`), which use `property=`. A key the page already pushed into `page.head` as a `meta` is not emitted a second time, so a page-level `robots` or `og:image` wins over the defaults.
+- The SSR router renders the same tree as the client router, idle page loader included: a page-level element that exists on one side only logs a hydration mismatch on every load and costs the Lighthouse Best Practices score.
+- Production CSS is minified with the `lightningcss` package (`cli/compiler/common/cssMinimizer.ts`), not rspack's bundled minimizer: the bundled copy drops the semicolon between a declaration and a nested at-rule two levels deep, which is the shape Tailwind v4 emits for every variant with an opacity modifier, and the rule is silently lost in production only.
 - For explicit crawl surfaces such as redirects, sitemap or RSS output, and public resources with custom semantics, prefer `server/routes/**` over generated controller actions when the endpoint is not a normal app API.
 
 ## Validation

package/cli/compiler/client/index.ts

@@ -11,6 +11,7 @@ import { rspack, type Configuration, type Module } from '@rspack/core';
 // Core
 import createCommonConfig, { TCompileMode, TCompileOutputTarget, regex } from '../common';
 import { createClientBundleAnalysisPlugins } from '../common/bundleAnalysis';
+import CssMinimizerPlugin from '../common/cssMinimizer';
 import { toRspackAliases } from '../common/rspackAliases';
 import { resolveUiSingletonAliases } from '../common/uiSingletons';
 import identityAssets from './identite';
@@ -348,9 +349,8 @@ export default function createCompiler(
                       removeAvailableModules: true,
                       minimizer: [
                           new rspack.SwcJsMinimizerRspackPlugin({}),
-                          new rspack.LightningCssMinimizerRspackPlugin({
-                              ...(lightningCssTargets ? { minimizerOptions: { targets: lightningCssTargets } } : {}),
-                          }),
+                          // Not `LightningCssMinimizerRspackPlugin`: see cssMinimizer.ts.
+                          new CssMinimizerPlugin(lightningCssTargets ? { targets: lightningCssTargets } : {}),
                       ],
                       nodeEnv: 'production',
                       sideEffects: true,

package/cli/compiler/common/cssMinimizer.ts

@@ -0,0 +1,74 @@
+/*----------------------------------
+- CSS MINIMIZER
+----------------------------------*/
+
+/**
+ * Minifies the emitted stylesheets with the `lightningcss` npm package instead of
+ * rspack's `LightningCssMinimizerRspackPlugin`.
+ *
+ * The rspack plugin runs the LightningCSS copy bundled in its Rust binding, and that
+ * copy prints a declaration followed by a nested at-rule without the semicolon between
+ * them when the nesting is two levels deep (`.a{@media (...){color:#fff;@supports (...){...}}}`
+ * comes out as `color:#fff@supports (...)`), which invalidates the whole rule. Tailwind v4
+ * emits exactly that shape for every variant with an opacity modifier, so a production
+ * build silently lost hover, responsive and dark-mode colours while dev looked right.
+ * Reproduced on @rspack/core 1.7.9 through 2.2.6 whenever the browser targets keep CSS
+ * nesting; `lightningcss` 1.33 prints it correctly, so the minifier reads that package.
+ */
+
+/*----------------------------------
+- DEPENDENCIES
+----------------------------------*/
+
+import browserslist from 'browserslist';
+import { browserslistToTargets, transform } from 'lightningcss';
+import type { Compiler } from '@rspack/core';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+export type TCssMinimizerOptions = {
+    /** Browserslist queries; omitted means LightningCSS defaults (no lowering). */
+    targets?: string | readonly string[];
+};
+
+/*----------------------------------
+- PLUGIN
+----------------------------------*/
+
+const PLUGIN_NAME = 'ProteumCssMinimizer';
+
+export const minifyCss = (filename: string, code: string, options: TCssMinimizerOptions = {}): string => {
+    const targets = options.targets ? browserslistToTargets(browserslist(options.targets)) : undefined;
+    const result = transform({
+        filename,
+        code: Buffer.from(code),
+        minify: true,
+        ...(targets ? { targets } : {}),
+    });
+
+    return result.code.toString();
+};
+
+export default class CssMinimizerPlugin {
+    public constructor(private readonly options: TCssMinimizerOptions = {}) {}
+
+    public apply(compiler: Compiler) {
+        const { Compilation, sources } = compiler.webpack;
+
+        compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
+            compilation.hooks.processAssets.tap(
+                { name: PLUGIN_NAME, stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE },
+                (assets) => {
+                    for (const [name, source] of Object.entries(assets)) {
+                        if (!name.endsWith('.css')) continue;
+
+                        const minified = minifyCss(name, source.source().toString(), this.options);
+                        compilation.updateAsset(name, new sources.RawSource(minified), { minimized: true });
+                    }
+                },
+            );
+        });
+    }
+}

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

@@ -0,0 +1,41 @@
+/*----------------------------------
+- PAGE LOADING INDICATOR
+----------------------------------*/
+
+// Npm
+import React from 'react';
+
+// Specific
+import type ClientRouter from '..';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+export type TPageLoadingProps = {
+    clientRouter?: ClientRouter;
+    loaderComponent?: React.ComponentType<{ isLoading: boolean }>;
+};
+
+/*----------------------------------
+- COMPONENT
+----------------------------------*/
+
+/**
+ * Rendered by both the client router and its SSR variant. The server used to omit it,
+ * so every hydration started with "Expected a DOM node of type div" in the console:
+ * the loader must exist in the server HTML, idle, for the two trees to match.
+ */
+export default function PageLoading({ clientRouter, loaderComponent: LoaderComponent }: TPageLoadingProps) {
+    const [isLoading, setLoading] = React.useState(false);
+
+    if (clientRouter) clientRouter.setLoading = setLoading;
+
+    return LoaderComponent ? (
+        <LoaderComponent isLoading={isLoading} />
+    ) : (
+        <div id="loading" class={isLoading ? 'display' : ''}>
+            <i class="spin" />
+        </div>
+    );
+}

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

@@ -11,6 +11,7 @@ import useContext from '@/client/context';
 // Specific
 import type ClientRouter from '..';
 import PageComponent from './Page';
+import PageLoading from './PageLoading';
 
 /*----------------------------------
 - TYPES
@@ -21,16 +22,21 @@ export type TProps = { service?: ClientRouter; loaderComponent?: React.Component
 /*----------------------------------
 - COMPONENT
 ----------------------------------*/
-export default function RouterComponent({ service: _clientRouter, loaderComponent: _loaderComponent }: TProps) {
+export default function RouterComponent({ service: _clientRouter, loaderComponent }: TProps) {
     const context = useContext();
     const currentPage = context.page;
 
-    if (!currentPage) return null;
-
+    // Same tree as the client router: the page, then the idle loader.
     return (
-        <PageComponent
-            page={currentPage as Parameters<typeof PageComponent>[0]['page']}
-            key={currentPage.chunkId === undefined ? undefined : 'page_' + currentPage.chunkId}
-        />
+        <>
+            {currentPage && (
+                <PageComponent
+                    page={currentPage as Parameters<typeof PageComponent>[0]['page']}
+                    key={currentPage.chunkId === undefined ? undefined : 'page_' + currentPage.chunkId}
+                />
+            )}
+
+            <PageLoading loaderComponent={loaderComponent} />
+        </>
     );
 }

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

@@ -10,6 +10,7 @@ import useContext from '@/client/context';
 // Specific
 import type ClientRouter from '..';
 import PageComponent from './Page';
+import PageLoading from './PageLoading';
 import ClientRequest from '../request';
 import { history, location, Update } from '../request/history';
 //import initTooltips from '@client/components/Donnees/Tooltip';
@@ -34,26 +35,6 @@ const withProfiler = <T,>(callback: (runtime: (typeof import('@client/dev/profil
     return callback(profilerModule.profilerRuntime);
 };
 
-const PageLoading = ({
-    clientRouter,
-    loaderComponent: LoaderComponent,
-}: {
-    clientRouter?: ClientRouter;
-    loaderComponent?: React.ComponentType<{ isLoading: boolean }>;
-}) => {
-    const [isLoading, setLoading] = React.useState(false);
-
-    if (clientRouter) clientRouter.setLoading = setLoading;
-
-    return LoaderComponent ? (
-        <LoaderComponent isLoading={isLoading} />
-    ) : (
-        <div id="loading" class={isLoading ? 'display' : ''}>
-            <i class="spin" />
-        </div>
-    );
-};
-
 const scrollToElement = (selector: string) =>
     document.querySelector(selector)?.scrollIntoView({ behavior: 'smooth', block: 'start', inline: 'nearest' });
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.17",
+	"version": "2.5.19",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -38,6 +38,7 @@
 		"autoprefixer": "^10.4.21",
 		"aws-sdk": "^2.1415.0",
 		"bowser": "^2.11.0",
+		"browserslist": "^4.29.0",
 		"cli-highlight": "^2.1.11",
 		"clipanion": "^4.0.0-rc.4",
 		"compression": "^1.7.4",
@@ -67,6 +68,7 @@
 		"iso-639-1": "^2.1.9",
 		"jsonwebtoken": "^8.5.1",
 		"less-loader": "^10.0.1",
+		"lightningcss": "^1.33.0",
 		"locale": "^0.1.0",
 		"markdown-it": "^13.0.1",
 		"md5": "^2.3.0",

package/server/services/router/http/index.ts

@@ -513,6 +513,16 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
 
         routes.use('/robots.txt', express.static(path.resolve(__dirname, 'public/robots.txt')));
 
+        // Browsers probe the site root for `/favicon.ico` regardless of the icon links
+        // the document declares, so without this mount every probe walked the whole
+        // router to reach a 404 (12 ms of routing versus 2 ms of static file). Served
+        // from the app's own build output; when an app ships no icon there, static
+        // falls through and the 404 behaves exactly as before.
+        routes.use(
+            '/favicon.ico',
+            express.static(path.join(Container.path.root, APP_OUTPUT_DIR, 'public/app/favicon.ico')),
+        );
+
         routes.get('/ping', (req, res) => res.send('pong'));
 
         /*----------------------------------

package/server/services/router/response/page/document.tsx

@@ -66,13 +66,11 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
                     <head>
                         {/* Format */}
                         <meta charSet="utf-8" />
-                        <meta content="IE=edge" httpEquiv="X-UA-Compatible" />
                         <meta name="viewport" content="width=device-width, initial-scale=1" />
 
                         {/* Mobile */}
                         <meta name="application-name" content={this.app.identity.web.title} />
                         <meta name="apple-mobile-web-app-title" content={this.app.identity.web.title} />
-                        <meta name="apple-mobile-web-app-title" content={this.app.identity.web.title} />
                         <meta content={this.app.identity.author.name} name="author" />
                         <meta name="theme-color" content={this.app.identity.maincolor} />
                         <meta name="msapplication-TileColor" content={this.app.identity.maincolor} />
@@ -134,10 +132,7 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
 
                 {page.style.map((style) =>
                     'url' in style ? (
-                        <>
-                            <link rel="preload" href={style.url} as="style" />
-                            <link rel="stylesheet" type="text/css" href={style.url} />
-                        </>
+                        <link key={style.id} rel="stylesheet" type="text/css" href={style.url} />
                     ) : (
                         <>
                             <style id={style.id} dangerouslySetInnerHTML={{ __html: style.inline }} />
@@ -156,12 +151,9 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
                 {styles.map((style) => {
                     const href = this.clientAssetUrl(style);
 
-                    return (
-                        <React.Fragment key={style}>
-                            <link rel="preload" href={href} as="style" />
-                            <link rel="stylesheet" type="text/css" href={href} />
-                        </React.Fragment>
-                    );
+                    // A stylesheet link in `<head>` is fetched at Highest priority on its own;
+                    // the preload that used to precede it was a duplicate request line.
+                    return <link key={style} rel="stylesheet" type="text/css" href={href} />;
                 })}
             </>
         );
@@ -175,12 +167,10 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
                 {scripts.map((script) => {
                     const src = this.clientAssetUrl(script);
 
-                    return (
-                        <React.Fragment key={script}>
-                            <link rel="preload" href={src} as="script" />
-                            <script defer type="text/javascript" src={src} />
-                        </React.Fragment>
-                    );
+                    // No `<link rel="preload">` beside the tag: a `defer` script is already fetched
+                    // as soon as the parser meets it, at Low priority. The preload re-requested it
+                    // at High priority, so every script raced the render-critical stylesheets.
+                    return <script key={script} defer type="text/javascript" src={src} />;
                 })}
             </>
         );
@@ -226,12 +216,19 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
 
                 {this.clientScripts()}
 
+                {/* Page chunks are `defer` like the entry, unless the page asked for `async`
+                    (an analytics tag, for example). Without it they were parser-blocking in
+                    `<head>`, and `addChunks` runs after `renderToString`, so no page could set
+                    the attribute itself. Same rule as above: no preload beside the tag. */}
                 {page.scripts.map((script) =>
                     'url' in script ? (
-                        <>
-                            <link rel="preload" href={script.url} as="script" />
-                            <script type="text/javascript" src={script.url} {...(script.attrs || {})} />
-                        </>
+                        <script
+                            key={script.id}
+                            type="text/javascript"
+                            src={script.url}
+                            defer={!(script.attrs && script.attrs.async)}
+                            {...(script.attrs || {})}
+                        />
                     ) : (
                         <>
                             <script

package/server/services/router/response/page/index.tsx

@@ -11,6 +11,7 @@ import { type TServerRouter, TRouterContext } from '@server/services/router';
 import type { Layout, TRoute, TErrorRoute, TClientOrServerContext } from '@common/router';
 import PageResponse, { TFrontRenderer, TPageRenderContext } from '@common/router/response/page';
 import { getClientBuildManifest } from './clientManifest';
+import { buildMetaTags } from './metas';
 
 // Composants UI
 import App from '@client/app/component';
@@ -175,11 +176,7 @@ export default class ServerPage<TRouter extends TServerRouter = TServerRouter> e
             ...this.metas,
         };
 
-        for (const key in metas) {
-            const value = metas[key];
-            if (value === '') continue;
-            this.head.push({ $: 'meta', property: key, content: value });
-        }
+        this.head.push(...buildMetaTags(metas, this.head));
     }
 
     private buildJsonLd() {

package/server/services/router/response/page/metas.ts

@@ -0,0 +1,45 @@
+/*----------------------------------
+- PAGE METAS
+----------------------------------*/
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+type TMetaValue = string | Date | undefined | null;
+export type TMetaTag = { $: string } & { [key: string]: TMetaValue };
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+/**
+ * Open Graph and its extensions are RDFa vocabularies read from `property`. Everything
+ * else (`robots`, `description`, `twitter:*`, `theme-color`...) is only honoured as
+ * `name`: emitted as `property="robots"`, the default robots meta was inert on every page.
+ */
+export const isOpenGraphMetaKey = (key: string): boolean => /^(og|article|fb|profile|book|music|video):/.test(key);
+
+/**
+ * Turns the page's meta dictionary into head tags, skipping the keys the page already
+ * pushed into `head` itself (a `noindex` on a faceted view, a per-page social image):
+ * a second tag with the same key would leave crawlers to pick between the two.
+ */
+export const buildMetaTags = (metas: { [key: string]: TMetaValue }, head: readonly TMetaTag[]): TMetaTag[] => {
+    const pushedMetaKeys = new Set(
+        head
+            .filter((tag) => tag.$ === 'meta')
+            .map((tag) => tag.name || tag.property)
+            .filter((key): key is string => typeof key === 'string'),
+    );
+    const tags: TMetaTag[] = [];
+
+    for (const key in metas) {
+        const value = metas[key];
+        if (value === '' || value === undefined || value === null || pushedMetaKeys.has(key)) continue;
+
+        tags.push({ $: 'meta', [isOpenGraphMetaKey(key) ? 'property' : 'name']: key, content: value });
+    }
+
+    return tags;
+};

package/tests/css-minimizer.test.cjs

@@ -0,0 +1,31 @@
+const assert = require('node:assert/strict');
+
+require('ts-node/register/transpile-only');
+
+const { minifyCss } = require('../cli/compiler/common/cssMinimizer');
+
+// The shape Tailwind v4 emits for a variant with an opacity modifier (`lg:text-white/70`):
+// a declaration followed by a nested `@supports` fallback, two levels deep.
+const NESTED_FALLBACK =
+    '.a { @media (width >= 64rem) { color: #ffffffb3; @supports (color: color-mix(in lab, red, red)) { color: color-mix(in oklab, var(--c) 70%, transparent); } } }';
+
+test('css minimizer keeps the semicolon between a declaration and a nested at-rule', () => {
+    // Browsers that support nesting, so nothing is flattened: the case the rspack-bundled
+    // LightningCSS printed as `color:#ffffffb3@supports`, which drops the whole rule.
+    const minified = minifyCss('x.css', NESTED_FALLBACK, { targets: ['last 2 chrome versions'] });
+
+    assert.doesNotMatch(minified, /[^;{}\s]@supports/);
+    assert.match(minified, /color:#ffffffb3;@supports/);
+});
+
+test('css minimizer lowers nesting for browsers that need it and honours a string query', () => {
+    const minified = minifyCss('x.css', NESTED_FALLBACK, { targets: 'chrome 100' });
+
+    assert.doesNotMatch(minified, /[^;{}\s]@supports/);
+    // Chrome 100 has no CSS nesting: the media query is hoisted around the rule.
+    assert.match(minified, /^@media \(min-width:64rem\)\{\.a\{/);
+});
+
+test('css minimizer minifies without targets', () => {
+    assert.equal(minifyCss('x.css', '.a {\n  color: #ffffff;\n}\n'), '.a{color:#fff}');
+});

package/tests/page-metas.test.cjs

@@ -0,0 +1,30 @@
+const assert = require('node:assert/strict');
+
+require('ts-node/register/transpile-only');
+
+const { buildMetaTags, isOpenGraphMetaKey } = require('../server/services/router/response/page/metas');
+
+test('page metas use property only for Open Graph vocabularies', () => {
+    assert.equal(isOpenGraphMetaKey('og:title'), true);
+    assert.equal(isOpenGraphMetaKey('article:published_time'), true);
+    assert.equal(isOpenGraphMetaKey('robots'), false);
+    assert.equal(isOpenGraphMetaKey('twitter:card'), false);
+
+    const tags = buildMetaTags({ robots: 'index', 'og:type': 'website', 'twitter:card': 'summary' }, []);
+
+    assert.deepEqual(tags, [
+        { $: 'meta', name: 'robots', content: 'index' },
+        { $: 'meta', property: 'og:type', content: 'website' },
+        { $: 'meta', name: 'twitter:card', content: 'summary' },
+    ]);
+});
+
+test('page metas skip keys the page already pushed and empty values', () => {
+    const head = [
+        { $: 'meta', name: 'robots', content: 'noindex,follow' },
+        { $: 'link', rel: 'canonical', href: '/x' },
+    ];
+    const tags = buildMetaTags({ robots: 'index', 'og:description': '', 'og:title': 'T' }, head);
+
+    assert.deepEqual(tags, [{ $: 'meta', property: 'og:title', content: 'T' }]);
+});