@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

package/scripts/generate-cem.test.mjs

@@ -0,0 +1,122 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  buildManifest,
+  collectLitProperties,
+  collectLiteralUnions,
+  expandType,
+} from "./generate-cem.mjs";
+
+test("collectLiteralUnions keeps string-literal aliases only", () => {
+  const unions = collectLiteralUnions([
+    `export type Size = "sm" | "md";\nexport type Route = string | URL;`,
+    `export type Shape =\n  | "default"\n  | "circle";`,
+  ]);
+  assert.equal(unions.get("Size"), `"sm" | "md"`);
+  assert.equal(unions.get("Shape"), `"default" | "circle"`);
+  assert.equal(unions.has("Route"), false);
+});
+
+test("collectLiteralUnions drops names defined twice with different values", () => {
+  const unions = collectLiteralUnions([`export type Mode = "a" | "b";`, `export type Mode = "c" | "d";`]);
+  assert.equal(unions.has("Mode"), false);
+});
+
+test("expandType replaces aliases and normalizes whitespace", () => {
+  const unions = new Map([["Size", `"sm" | "md"`]]);
+  assert.equal(expandType("Size | undefined", unions), `"sm" | "md" | undefined`);
+  assert.equal(expandType(`| "a"\n    | "b"`, unions), `"a" | "b"`);
+  assert.equal(expandType("Route | string", unions), "Route | string");
+});
+
+test("collectLitProperties finds fields and accessors, with comments in between", () => {
+  const names = collectLitProperties(`
+    @property({ type: String }) label = "";
+    @property({
+      type: Function,
+      attribute: false,
+    }) /** doc */
+    get items() { return this._items; }
+    @state() open = false;
+  `);
+  assert.deepEqual([...names].sort(), ["items", "label"]);
+});
+
+const raw = {
+  schemaVersion: "1.0.0",
+  modules: [
+    {
+      path: "src/core/mixins/FormElement.ts",
+      declarations: [
+        {
+          kind: "mixin",
+          name: "Form",
+          attributes: [{ name: "name", type: { text: "string" }, fieldName: "name" }],
+          members: [{ kind: "field", name: "name", attribute: "name" }],
+        },
+      ],
+    },
+    {
+      path: "src/core/components/ui/button/button.ts",
+      declarations: [
+        {
+          kind: "class",
+          name: "Button",
+          customElement: true,
+          mixins: [{ name: "FormElement", package: "@supersoniks/concorde/core/mixins/FormElement" }],
+          attributes: [{ name: "size", type: { text: "Size" }, fieldName: "size" }],
+          members: [
+            { kind: "field", name: "size", attribute: "size", type: { text: "Size" } },
+            { kind: "field", name: "items", type: { text: "ListItems" } },
+            { kind: "field", name: "pointerDownTime", type: { text: "number" } },
+            { kind: "field", name: "_internal" },
+            { kind: "method", name: "render" },
+            { kind: "method", name: "handleClick" },
+            { kind: "method", name: "show", description: "Opens it." },
+          ],
+        },
+      ],
+      exports: [{ kind: "custom-element-definition", declaration: { name: "Button" } }],
+    },
+    {
+      path: "src/core/components/functional/example/example.ts",
+      declarations: [{ kind: "class", name: "Example", customElement: true }],
+      exports: [{ kind: "custom-element-definition", declaration: { name: "Example" } }],
+    },
+  ],
+};
+
+function build() {
+  return buildManifest(raw, {
+    unions: new Map([["Size", `"sm" | "md"`]]),
+    resolveTagName: (p) => (p.includes("button") ? "sonic-button" : "sonic-example"),
+    litProperties: (p) => (p.includes("button") ? new Set(["size", "items"]) : new Set()),
+    exclude: (p) => p.includes("/functional/example/"),
+  });
+}
+
+test("buildManifest keeps elements with their tag name and definition export", () => {
+  const manifest = build();
+  assert.equal(manifest.modules.length, 1);
+  const [mod] = manifest.modules;
+  const [el] = mod.declarations;
+  assert.equal(el.tagName, "sonic-button");
+  assert.deepEqual(
+    mod.exports.find((e) => e.kind === "custom-element-definition"),
+    { kind: "custom-element-definition", name: "sonic-button", declaration: { name: "Button", module: mod.path } },
+  );
+  assert.equal(el.attributes.find((a) => a.name === "size").type.text, `"sm" | "md"`);
+});
+
+test("buildManifest keeps the public API only and merges mixins", () => {
+  const [el] = build().modules[0].declarations;
+  assert.deepEqual(
+    el.members.map((m) => m.name),
+    ["size", "items", "show", "name"],
+  );
+  const inherited = el.attributes.find((a) => a.name === "name");
+  assert.deepEqual(inherited.inheritedFrom, {
+    name: "FormElement",
+    module: "src/core/mixins/FormElement.ts",
+  });
+});

package/scripts/generate-crawl-docs.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from "url";
 import { marked } from "marked";
 import { gfmHeadingId } from "marked-gfm-heading-id";
 import { toPublicPath } from "./docs-public-url.mjs";
+import { STATIC_PAGES, renderSitePage } from "./site-pages.mjs";
 
 const SITE_ORIGIN = "https://concorde.supersoniks.org";
 const SRC_DIR = path.resolve("src");
@@ -297,7 +298,7 @@ function writeFileEnsuringDir(filePath, content) {
   fs.writeFileSync(filePath, content);
 }
 
-function generateLlmsTxt(pages, hubs = []) {
+export function generateLlmsTxt(pages, hubs = []) {
   const lines = [
     "# Concorde by Supersoniks",
     "",
@@ -314,8 +315,10 @@ function generateLlmsTxt(pages, hubs = []) {
     `- [Sitemap](${SITE_ORIGIN}/sitemap.xml)`,
     `- [npm package @supersoniks/concorde](https://www.npmjs.com/package/@supersoniks/concorde)`,
     `- [Getting started](${SITE_ORIGIN}/docs/getting-started/start)`,
-    `- [AI agents (skills)](${SITE_ORIGIN}/docs/getting-started/ai-agents)`,
+    `- [AI agents (skill)](${SITE_ORIGIN}/docs/getting-started/ai-agents)`,
     `- [Components index](${SITE_ORIGIN}/docs/getting-started/components)`,
+    `- [custom-elements.json](${SITE_ORIGIN}/custom-elements.json) — Custom Elements Manifest: attributes, properties, events and slots of every \`sonic-*\` element`,
+    `- [About](${SITE_ORIGIN}/about) · [Privacy](${SITE_ORIGIN}/privacy)`,
     "",
     "Doc pages use the same pathnames as the interactive site (`/docs/…`, `/core/…`).",
     "Markdown: same URL with `.md` (e.g. `/docs/getting-started/start.md`), or `Accept: text/markdown` on the pathname.",
@@ -495,13 +498,16 @@ function generateTopicHubs(pages) {
   return hubs;
 }
 
-function generateSitemap(pages, hubs = []) {
+export function generateSitemap(pages, hubs = []) {
   const homeUrl = `  <url>\n    <loc>${SITE_ORIGIN}/</loc>\n  </url>`;
   const homeMdUrl = `  <url>\n    <loc>${SITE_ORIGIN}/index.md</loc>\n  </url>`;
   const indexUrl = `  <url>\n    <loc>${SITE_ORIGIN}/docs/index.html</loc>\n  </url>`;
   const hubUrls = hubs
     .map((h) => `  <url>\n    <loc>${SITE_ORIGIN}/${h.hubPath}</loc>\n  </url>`)
     .join("\n");
+  const staticUrls = STATIC_PAGES.map(
+    (p) => `  <url>\n    <loc>${SITE_ORIGIN}/${p.slug}</loc>\n  </url>`,
+  ).join("\n");
   const urls = pages
     .map((p) => `  <url>\n    <loc>${SITE_ORIGIN}${p.pagePath}</loc>\n  </url>`)
     .join("\n");
@@ -511,6 +517,7 @@ function generateSitemap(pages, hubs = []) {
 ${homeUrl}
 ${homeMdUrl}
 ${indexUrl}
+${staticUrls}
 ${hubUrls}
 ${urls}
 </urlset>
@@ -533,14 +540,14 @@ Install the npm package [\`@supersoniks/concorde\`](https://www.npmjs.com/packag
 - Docs index: ${SITE_ORIGIN}/docs/index.html
 - Sitemap: ${SITE_ORIGIN}/sitemap.xml
 - Getting started: ${SITE_ORIGIN}/docs/getting-started/start
-- AI agents (skills): ${SITE_ORIGIN}/docs/getting-started/ai-agents
+- AI agents (skill): ${SITE_ORIGIN}/docs/getting-started/ai-agents
 - Components: ${SITE_ORIGIN}/docs/getting-started/components
 
 Doc pages share pathnames with the interactive site (\`/docs/…\`, \`/core/…\`). Markdown is at the same path with a \`.md\` suffix (e.g. \`/docs/getting-started/start.md\`), or via \`Accept: text/markdown\` on the pathname (\`Content-Type: text/markdown\`, \`Vary: Accept\`).
 
 ## What Concorde includes
 
-Custom elements (\`sonic-*\`) for buttons, forms, lists, queues, SDUI trees and more. Decorators such as \`@get\`, \`@post\`, \`@subscribe\` and \`@bind\` wire components to a shared DataProvider without framework lock-in. Concorde is MIT-licensed and maintained by Supersoniks.
+Custom elements (\`sonic-*\`) for buttons, forms, lists, queues, SDUI trees and more. Decorators such as \`@get\`, \`@post\`, \`@subscribe\` and \`@bind\` wire components to a shared DataProvider without framework lock-in. Concorde is MIT-licensed and maintained by Supersoniks ([about](${SITE_ORIGIN}/about), [privacy](${SITE_ORIGIN}/privacy)).
 `;
 }
 
@@ -581,11 +588,28 @@ export function generateHtaccess() {
   return fs.readFileSync(htaccessPath, "utf8");
 }
 
+/** SPA shell for site pages: the built docs/index.html, else the source one. */
+function readSpaShell(docsOut) {
+  const built = path.join(docsOut, "index.html");
+  return fs.readFileSync(
+    fs.existsSync(built) ? built : path.resolve("index.html"),
+    "utf8",
+  );
+}
+
 export function writeAgentSiteArtifacts(docsOut = DOCS_OUT) {
   fs.writeFileSync(path.join(docsOut, "index.md"), generateHomepageMarkdown());
   fs.writeFileSync(path.join(docsOut, "404.md"), generateNotFoundMarkdown());
   fs.writeFileSync(path.join(docsOut, "404.html"), generateNotFoundHtml());
   fs.writeFileSync(path.join(docsOut, ".htaccess"), generateHtaccess());
+  const shell = readSpaShell(docsOut);
+  for (const page of STATIC_PAGES) {
+    fs.writeFileSync(path.join(docsOut, `${page.slug}.md`), page.markdown);
+    fs.writeFileSync(
+      path.join(docsOut, `${page.slug}.html`),
+      renderSitePage(page, marked.parse(page.markdown), shell),
+    );
+  }
 }
 
 function removeLegacyCrawlDir() {

package/scripts/generate-sdui-catalog.mjs

@@ -14,7 +14,7 @@ import { fileURLToPath } from "url";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, "..");
 const CEM_DIR = path.join(ROOT, ".tmp-cem");
-const CEM_PATH = path.join(CEM_DIR, "custom-elements.json");
+export const CEM_PATH = path.join(CEM_DIR, "custom-elements.json");
 const OUT_CATALOG = path.join(
   ROOT,
   "src/core/components/functional/sdui/component-catalog.json"
@@ -24,7 +24,7 @@ const OUT_GAPS = path.join(
   "src/core/components/functional/sdui/component-catalog.gaps.json"
 );
 
-function extractTagNameFromSource(filePath) {
+export function extractTagNameFromSource(filePath) {
   if (!fs.existsSync(filePath)) return undefined;
   const src = fs.readFileSync(filePath, "utf8");
   const literal = src.match(/@customElement\(\s*["'`]([^"'`]+)["'`]\s*\)/);
@@ -176,8 +176,12 @@ export function cemToCatalog(cem, { resolveTagName } = {}) {
   };
 }
 
-function runCem() {
+export function runCem(
+  configPath = path.join(ROOT, "custom-elements-manifest.config.mjs"),
+) {
   fs.mkdirSync(CEM_DIR, { recursive: true });
+  const pkgPath = path.join(ROOT, "package.json");
+  const pkgBefore = fs.readFileSync(pkgPath, "utf8");
   const cemBin = path.join(
     ROOT,
     "node_modules/@custom-elements-manifest/analyzer/cem.js"
@@ -188,16 +192,13 @@ function runCem() {
       cemBin,
       "analyze",
       "--config",
-      path.join(ROOT, "custom-elements-manifest.config.mjs"),
+      configPath,
     ],
     { cwd: ROOT, stdio: ["ignore", "pipe", "pipe"] }
   );
-  // Ne pas laisser cem écrire customElements dans package.json
-  const pkgPath = path.join(ROOT, "package.json");
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-  if (pkg.customElements) {
-    delete pkg.customElements;
-    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  // cem may rewrite package.json (customElements): keep it as it was
+  if (fs.readFileSync(pkgPath, "utf8") !== pkgBefore) {
+    fs.writeFileSync(pkgPath, pkgBefore);
   }
 }
 

package/scripts/github-export.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Prépare une arborescence « lib publique » pour GitHub :
+ * - sans site doc (src/docs, index.html, …)
+ * - sans sonic-captcha (altcha.supersoniks.org)
+ * - sans scripts / jobs GitLab internes
+ *
+ * Usage :
+ *   node scripts/github-export.mjs [répertoire_cible]
+ *
+ * Par défaut : ../concorde-github-export
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+const IGNORE_FILE = path.join(ROOT, ".github-export-ignore");
+const DEFAULT_OUT = path.resolve(ROOT, "../concorde-github-export");
+
+const EXPORT_FILTER_KEY =
+  /(?:^|\/)(?:docs|mock-api|undefined)(?:\/|$)|captcha|\.demo\.|\.stories\.|TestUtils|\/prism\/|\/search\/|\/tailwind\/|\/header\/|\/navigation\/|\/layout\.ts$|\/code\.ts$|^code$|^docs$|^layout$/;
+
+function readIgnorePatterns() {
+  if (!fs.existsSync(IGNORE_FILE)) return [];
+  return fs
+    .readFileSync(IGNORE_FILE, "utf8")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith("#"));
+}
+
+function globToRegExp(pattern) {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "{{GLOBSTAR}}")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\{\{GLOBSTAR\}\}/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+
+function shouldExclude(relativePath, patterns) {
+  const normalized = relativePath.replace(/\\/g, "/");
+  for (const pattern of patterns) {
+    const re = globToRegExp(pattern);
+    if (re.test(normalized)) return true;
+    if (normalized.startsWith(pattern.endsWith("/") ? pattern : `${pattern}/`))
+      return true;
+    if (normalized === pattern) return true;
+  }
+  return false;
+}
+
+function listAllFiles(dir, base = dir) {
+  const out = [];
+  for (const name of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (name.name === ".git" || name.name === "node_modules") continue;
+    const full = path.join(dir, name.name);
+    const rel = path.relative(base, full).replace(/\\/g, "/");
+    if (name.isDirectory()) {
+      if (shouldExclude(rel, ignorePatterns)) continue;
+      out.push(...listAllFiles(full, base));
+    } else {
+      if (!shouldExclude(rel, ignorePatterns)) out.push(rel);
+    }
+  }
+  return out;
+}
+
+function copyFile(rel, destRoot) {
+  const src = path.join(ROOT, rel);
+  const dest = path.join(destRoot, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function patchUiTs(destRoot) {
+  const uiPath = path.join(
+    destRoot,
+    "src/core/components/ui/ui.ts",
+  );
+  if (!fs.existsSync(uiPath)) return;
+  const content = fs.readFileSync(uiPath, "utf8");
+  const patched = content.replace(
+    /import "\.\/captcha\/captcha";\n?/,
+    "",
+  );
+  fs.writeFileSync(uiPath, patched);
+}
+
+function exportHaystack(value) {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") {
+    return `${value.types ?? ""}${value.default ?? ""}`;
+  }
+  return String(value);
+}
+
+function filterPackageJson(destRoot) {
+  const pkgPath = path.join(destRoot, "package.json");
+  if (!fs.existsSync(pkgPath)) return;
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  if (pkg.exports && typeof pkg.exports === "object") {
+    const next = {};
+    for (const [key, value] of Object.entries(pkg.exports)) {
+      const hay = `${key}:${exportHaystack(value)}`;
+      if (EXPORT_FILTER_KEY.test(hay)) continue;
+      if (exportHaystack(value).includes("/captcha/")) continue;
+      if (exportHaystack(value).includes("/docs/")) continue;
+      if (exportHaystack(value).includes(".demo.")) continue;
+      if (exportHaystack(value).includes(".stories.")) continue;
+      next[key] = value;
+    }
+    pkg.exports = next;
+  }
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+
+function patchReadme(destRoot) {
+  const readmePath = path.join(destRoot, "README.md");
+  if (!fs.existsSync(readmePath)) return;
+  let text = fs.readFileSync(readmePath, "utf8");
+  text = text.replace(
+    /Le dépôt GitHub est un \*\*miroir\*\* synchronisé depuis GitLab \(voir \[OPEN_SOURCE_CHECKPOINT\.md\]\(OPEN_SOURCE_CHECKPOINT\.md\)\)\./,
+    "Le dépôt GitHub est un **export filtré** depuis GitLab (librairie uniquement, sans site doc ni composant captcha — voir [OPEN_SOURCE_CHECKPOINT.md](OPEN_SOURCE_CHECKPOINT.md)).",
+  );
+  fs.writeFileSync(readmePath, text);
+}
+
+const ignorePatterns = readIgnorePatterns();
+const outDir = path.resolve(process.argv[2] || DEFAULT_OUT);
+
+if (fs.existsSync(outDir)) {
+  fs.rmSync(outDir, { recursive: true, force: true });
+}
+fs.mkdirSync(outDir, { recursive: true });
+
+const files = listAllFiles(ROOT);
+for (const rel of files) {
+  copyFile(rel, outDir);
+}
+
+patchUiTs(outDir);
+filterPackageJson(outDir);
+patchReadme(outDir);
+
+console.log(`✅ Export GitHub : ${files.length} fichiers → ${outDir}`);
+console.log("   Exclusions : .github-export-ignore");
+console.log("   Patches    : ui.ts (sans captcha), package.json exports");

package/scripts/post-build-docs.js

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { generateCrawlDocs } from "./generate-crawl-docs.mjs";
+import { generateCem } from "./generate-cem.mjs";
 
 const src = path.resolve("src");
 const docs = path.resolve("docs");
@@ -52,6 +53,8 @@ function copyDocs() {
 }
 
 copyDocs();
+// Custom Elements Manifest, served at /custom-elements.json
+fs.copyFileSync(generateCem(), path.join(docs, "custom-elements.json"));
 generateCrawlDocs();
 
 function copyToConcordeDoc() {

package/scripts/pre-publish.mjs

@@ -4,8 +4,9 @@ import fs from "fs";
 const requiredFiles = [
   'concorde-core.bundle.js',
   'concorde-core.es.js',
-  'ai/AGENTS.md',
+  'ai/skills/concorde/SKILL.md',
   'scripts/ai-init.mjs',
+  'custom-elements.json',
 ];
 
 let allFilesExist = true;

package/scripts/site-pages.mjs

@@ -0,0 +1,212 @@
+/**
+ * Homepage JSON-LD and the root site pages (/about, /privacy).
+ *
+ * Page content lives in site-pages/*.md: the SPA renders it at /about, and
+ * the build publishes `slug.md` + `slug.html` (SPA shell with the page
+ * inlined for crawlers and link previews).
+ */
+import fs from "fs";
+import { fileURLToPath } from "url";
+
+export const SITE_ORIGIN = "https://concorde.supersoniks.org";
+export const NPM_URL = "https://www.npmjs.com/package/@supersoniks/concorde";
+
+/** Publisher details, from https://supersoniks.com/mentions-legales */
+export const ORGANIZATION = {
+  name: "Supersoniks",
+  legalName: "SUPERSONIKS",
+  url: "https://supersoniks.com/",
+  contactUrl: "https://supersoniks.com/un-projet",
+  telephone: "+33 2 47 68 93 25",
+  streetAddress: "22 rue du Docteur Bretonneau",
+  postalCode: "37000",
+  addressLocality: "Tours",
+  addressCountry: "FR",
+  sameAs: [
+    "https://www.linkedin.com/company/supersoniks/",
+    "https://www.facebook.com/supersoniks",
+    "https://www.instagram.com/agencesupersoniks/",
+  ],
+};
+
+function escapeHtml(text) {
+  return String(text)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/* -------------------------------------------------------------------------- */
+/* JSON-LD                                                                    */
+/* -------------------------------------------------------------------------- */
+
+export function organizationJsonLd() {
+  return {
+    "@type": "Organization",
+    "@id": `${ORGANIZATION.url}#organization`,
+    name: ORGANIZATION.name,
+    legalName: ORGANIZATION.legalName,
+    url: ORGANIZATION.url,
+    telephone: ORGANIZATION.telephone,
+    address: {
+      "@type": "PostalAddress",
+      streetAddress: ORGANIZATION.streetAddress,
+      postalCode: ORGANIZATION.postalCode,
+      addressLocality: ORGANIZATION.addressLocality,
+      addressCountry: ORGANIZATION.addressCountry,
+    },
+    contactPoint: {
+      "@type": "ContactPoint",
+      contactType: "customer service",
+      telephone: ORGANIZATION.telephone,
+      url: ORGANIZATION.contactUrl,
+      availableLanguage: ["fr", "en"],
+    },
+    sameAs: ORGANIZATION.sameAs,
+  };
+}
+
+/** Homepage graph: WebSite + SoftwareApplication + Organization. */
+export function homepageJsonLd() {
+  const org = { "@id": `${ORGANIZATION.url}#organization` };
+  return {
+    "@context": "https://schema.org",
+    "@graph": [
+      {
+        "@type": "WebSite",
+        "@id": `${SITE_ORIGIN}/#website`,
+        name: "Concorde",
+        alternateName: "Concorde by Supersoniks",
+        url: `${SITE_ORIGIN}/`,
+        inLanguage: "en",
+        publisher: org,
+      },
+      {
+        "@type": "SoftwareApplication",
+        "@id": `${SITE_ORIGIN}/#software`,
+        name: "Concorde",
+        alternateName: "@supersoniks/concorde",
+        description:
+          "Concorde is an open-source web components framework built on Lit: UI components, data binding, forms, routing helpers and theming that work in React, Vue, PHP or plain HTML.",
+        url: `${SITE_ORIGIN}/`,
+        applicationCategory: "DeveloperApplication",
+        applicationSubCategory: "Web components framework",
+        operatingSystem: "Any (web browser)",
+        programmingLanguage: "TypeScript",
+        license: "https://opensource.org/licenses/MIT",
+        downloadUrl: NPM_URL,
+        softwareHelp: `${SITE_ORIGIN}/docs/getting-started/start`,
+        image: `${SITE_ORIGIN}/img/og-concorde.jpg`,
+        offers: { "@type": "Offer", price: "0", priceCurrency: "EUR" },
+        author: org,
+        publisher: org,
+        sameAs: [NPM_URL],
+      },
+      organizationJsonLd(),
+    ],
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Site pages: /about, /privacy                                               */
+/* -------------------------------------------------------------------------- */
+
+const SITE_PAGES_DIR = fileURLToPath(new URL("../site-pages/", import.meta.url));
+
+export const STATIC_PAGES = [
+  {
+    slug: "about",
+    title: "About Concorde — web components framework by Supersoniks",
+    description:
+      "Concorde is an open-source Lit web components framework designed and maintained by Supersoniks, Tours, France.",
+  },
+  {
+    slug: "privacy",
+    title: "Privacy notice — Concorde by Supersoniks",
+    description:
+      "Privacy notice of the Concorde documentation site: no cookies, no analytics, third-party hosts and your GDPR rights.",
+  },
+].map((page) => ({
+  ...page,
+  markdown: fs.readFileSync(`${SITE_PAGES_DIR}${page.slug}.md`, "utf8"),
+}));
+
+function pageJsonLd(page) {
+  return {
+    "@context": "https://schema.org",
+    "@type": page.slug === "about" ? "AboutPage" : "WebPage",
+    name: page.title,
+    description: page.description,
+    url: `${SITE_ORIGIN}/${page.slug}`,
+    isPartOf: { "@type": "WebSite", name: "Concorde", url: `${SITE_ORIGIN}/` },
+    publisher: organizationJsonLd(),
+  };
+}
+
+function replaceOnce(html, re, replacement, what) {
+  if (!re.test(html)) throw new Error(`site page shell: ${what} not found`);
+  return html.replace(re, () => replacement);
+}
+
+/**
+ * `slug.html`: the SPA shell (built docs/index.html) with the page's
+ * metadata and its rendered content in the no-JS section. Browsers boot the
+ * SPA, which renders the same Markdown; crawlers read the inline copy.
+ */
+export function renderSitePage(page, bodyHtml, shellHtml) {
+  const url = `${SITE_ORIGIN}/${page.slug}`;
+  const title = escapeHtml(page.title);
+  const description = escapeHtml(page.description);
+  let html = shellHtml;
+  html = replaceOnce(html, /<title>[\s\S]*?<\/title>/, `<title>${title}</title>`, "title");
+  html = replaceOnce(
+    html,
+    /<meta\s+name="description"\s+content="[^"]*"\s*\/?>/,
+    `<meta name="description" content="${description}" />`,
+    "description",
+  );
+  html = replaceOnce(
+    html,
+    /<link rel="canonical" href="[^"]*"\s*\/?>/,
+    `<link rel="canonical" href="${url}" />`,
+    "canonical",
+  );
+  html = replaceOnce(
+    html,
+    /<link rel="alternate" type="text\/markdown" href="[^"]*"/,
+    `<link rel="alternate" type="text/markdown" href="/${page.slug}.md"`,
+    "markdown alternate",
+  );
+  html = replaceOnce(
+    html,
+    /<meta property="og:title" content="[^"]*"/,
+    `<meta property="og:title" content="${title}"`,
+    "og:title",
+  );
+  html = replaceOnce(
+    html,
+    /<meta property="og:description" content="[^"]*"/,
+    `<meta property="og:description" content="${description}"`,
+    "og:description",
+  );
+  html = replaceOnce(
+    html,
+    /<meta property="og:url" content="[^"]*"/,
+    `<meta property="og:url" content="${url}"`,
+    "og:url",
+  );
+  html = replaceOnce(
+    html,
+    /<script type="application\/ld\+json">[\s\S]*?<\/script>/,
+    `<script type="application/ld+json">${JSON.stringify(pageJsonLd(page))}</script>`,
+    "JSON-LD",
+  );
+  html = replaceOnce(
+    html,
+    /<section id="docs-agent-content"([^>]*)>[\s\S]*?<\/section>/,
+    `<section id="docs-agent-content" aria-hidden="true">\n${bodyHtml}\n    </section>`,
+    "page section",
+  );
+  return html;
+}