proteum 2.5.18 → 2.5.20

package/agents/project/optimizations.md

@@ -31,6 +31,11 @@ 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 default JSON-LD graph (`Organization`, `WebSite`, generic `WebPage`) adds its `WebPage` only when the page pushed none itself, and never emits empty `sameAs` or `potentialAction` arrays: a second `WebPage` for the same URL with another name reads as two contradictory pages, and an empty array says "none" where the app said nothing.
+- 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.18",
+	"version": "2.5.20",
 	"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,8 @@ 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';
+import { buildDefaultJsonLd } from './jsonld';
 
 // Composants UI
 import App from '@client/app/component';
@@ -175,53 +177,19 @@ 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() {
         this.jsonld.push(
-            {
-                '@type': 'Organization',
-                '@id': this.router.url('/#organization'),
-                name: this.app.identity.author.name,
-                url: this.app.identity.author.url,
-                logo: {
-                    '@type': 'ImageObject',
-                    '@id': this.router.url('/#logo'),
-                    url: this.router.url('/public/brand/1024.png'),
-                    width: '1024px',
-                    height: '1024px',
-                    caption: this.app.identity.name,
-                },
-                sameAs: [],
-            },
-            {
-                '@type': 'WebSite',
-                '@id': this.router.url('/#website'),
-                url: this.router.url('/'),
-                name: this.app.identity.name,
-                description: this.app.identity.description,
-                publisher: { '@id': this.router.url('/#organization') },
-                inLanguage: this.app.identity.locale,
-                potentialAction: [],
-
-                ...(this.app.identity.web.jsonld || {}),
-            },
-            {
-                '@type': 'WebPage',
-                '@id': this.url,
+            ...buildDefaultJsonLd({
+                pageJsonLd: this.jsonld,
                 url: this.url,
-
-                isPartOf: { '@id': this.router.url('/#website') },
-
-                name: this.title,
+                title: this.title,
                 description: this.description,
-                inLanguage: this.app.identity.locale,
-            },
+                identity: this.app.identity,
+                resolveUrl: (path) => this.router.url(path),
+            }),
         );
     }
 }

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

@@ -0,0 +1,94 @@
+/*----------------------------------
+- PAGE JSON-LD DEFAULTS
+----------------------------------*/
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+type TJsonLdNode = { '@type'?: string | string[]; '@id'?: string; [key: string]: unknown };
+
+type TIdentity = {
+    name: string;
+    description: string;
+    locale: string;
+    author: { name: string; url: string };
+    web: { jsonld?: Record<string, unknown> };
+};
+
+export type TDefaultJsonLdInput = {
+    /** The nodes the page pushed itself, before the defaults are added. */
+    pageJsonLd: readonly TJsonLdNode[];
+    url: string;
+    title: string;
+    description: string;
+    identity: TIdentity;
+    resolveUrl: (path: string) => string;
+};
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+const hasType = (node: TJsonLdNode, type: string): boolean =>
+    Array.isArray(node['@type']) ? node['@type'].includes(type) : node['@type'] === type;
+
+/**
+ * The publisher identity every page carries (`#organization`, `#website`) plus a generic
+ * `WebPage` for pages that describe none themselves.
+ *
+ * A page that already pushed a `WebPage` keeps its own: a second node for the same URL
+ * with another name and description reads as two contradictory pages to a consumer.
+ * Empty `sameAs` and `potentialAction` arrays are left out for the same reason: they say
+ * "no profiles" and "no actions" where the app said nothing. `identity.web.jsonld` can
+ * still add either to the `WebSite` node.
+ */
+export const buildDefaultJsonLd = ({
+    pageJsonLd,
+    url,
+    title,
+    description,
+    identity,
+    resolveUrl,
+}: TDefaultJsonLdInput): TJsonLdNode[] => {
+    const nodes: TJsonLdNode[] = [
+        {
+            '@type': 'Organization',
+            '@id': resolveUrl('/#organization'),
+            name: identity.author.name,
+            url: identity.author.url,
+            logo: {
+                '@type': 'ImageObject',
+                '@id': resolveUrl('/#logo'),
+                url: resolveUrl('/public/brand/1024.png'),
+                width: '1024px',
+                height: '1024px',
+                caption: identity.name,
+            },
+        },
+        {
+            '@type': 'WebSite',
+            '@id': resolveUrl('/#website'),
+            url: resolveUrl('/'),
+            name: identity.name,
+            description: identity.description,
+            publisher: { '@id': resolveUrl('/#organization') },
+            inLanguage: identity.locale,
+            ...(identity.web.jsonld || {}),
+        },
+    ];
+
+    if (!pageJsonLd.some((node) => hasType(node, 'WebPage'))) {
+        nodes.push({
+            '@type': 'WebPage',
+            '@id': url,
+            url,
+            isPartOf: { '@id': resolveUrl('/#website') },
+            name: title,
+            description,
+            inLanguage: identity.locale,
+        });
+    }
+
+    return nodes;
+};

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-jsonld.test.cjs

@@ -0,0 +1,45 @@
+const assert = require('node:assert/strict');
+
+require('ts-node/register/transpile-only');
+
+const { buildDefaultJsonLd } = require('../server/services/router/response/page/jsonld');
+
+const input = {
+    url: 'https://example.test/pricing',
+    title: 'Pricing',
+    description: 'What it costs.',
+    identity: {
+        name: 'Example',
+        description: 'An example app.',
+        locale: 'en-US',
+        author: { name: 'Example Ltd', url: 'https://example.test' },
+        web: { jsonld: { potentialAction: [{ '@type': 'SearchAction' }] } },
+    },
+    resolveUrl: (path) => 'https://example.test' + path,
+};
+
+test('default JSON-LD adds a generic WebPage only when the page has none', () => {
+    const withoutPage = buildDefaultJsonLd({ ...input, pageJsonLd: [{ '@type': 'FAQPage' }] });
+    assert.deepEqual(withoutPage.map((node) => node['@type']), ['Organization', 'WebSite', 'WebPage']);
+    assert.equal(withoutPage[2]['@id'], 'https://example.test/pricing');
+    assert.equal(withoutPage[2].name, 'Pricing');
+
+    const withPage = buildDefaultJsonLd({
+        ...input,
+        pageJsonLd: [{ '@type': 'WebPage', '@id': 'https://example.test/pricing#webpage', name: 'Plans' }],
+    });
+    assert.deepEqual(withPage.map((node) => node['@type']), ['Organization', 'WebSite']);
+
+    const withTypedArray = buildDefaultJsonLd({ ...input, pageJsonLd: [{ '@type': ['WebPage', 'FAQPage'] }] });
+    assert.deepEqual(withTypedArray.map((node) => node['@type']), ['Organization', 'WebSite']);
+});
+
+test('default JSON-LD emits no empty sameAs or potentialAction, and keeps identity additions', () => {
+    const nodes = buildDefaultJsonLd({ ...input, pageJsonLd: [] });
+    assert.equal('sameAs' in nodes[0], false);
+    assert.deepEqual(nodes[1].potentialAction, [{ '@type': 'SearchAction' }]);
+
+    const bare = buildDefaultJsonLd({ ...input, identity: { ...input.identity, web: {} }, pageJsonLd: [] });
+    assert.equal('potentialAction' in bare[1], false);
+    assert.equal(bare[1].publisher['@id'], 'https://example.test/#organization');
+});

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' }]);
+});