proteum 2.5.19 → 2.5.20

package/agents/project/optimizations.md

@@ -33,6 +33,7 @@ When tradeoffs exist inside optimization work, optimize in this order:
 - 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.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.19",
+	"version": "2.5.20",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

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

@@ -12,6 +12,7 @@ import type { Layout, TRoute, TErrorRoute, TClientOrServerContext } from '@commo
 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';
@@ -181,44 +182,14 @@ export default class ServerPage<TRouter extends TServerRouter = TServerRouter> e
 
     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/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');
+});