@supersoniks/concorde 5.1.2 → 5.1.3

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/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;
+}

package/scripts/site-pages.test.mjs

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "path";
+import test from "node:test";
+import { STATIC_PAGES, homepageJsonLd } from "./site-pages.mjs";
+import {
+  generateHomepageMarkdown,
+  generateHtaccess,
+  generateSitemap,
+  writeAgentSiteArtifacts,
+} from "./generate-crawl-docs.mjs";
+
+function stripTags(html) {
+  return html
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+test("homepage JSON-LD has SoftwareApplication and complete Organization", () => {
+  const ld = homepageJsonLd();
+  assert.equal(ld["@context"], "https://schema.org");
+  const byType = Object.fromEntries(ld["@graph"].map((n) => [n["@type"], n]));
+  const app = byType.SoftwareApplication;
+  assert.ok(app.name && app.description && app.url && app.offers);
+  assert.equal(app.publisher["@id"], byType.Organization["@id"]);
+  const org = byType.Organization;
+  assert.equal(org.url, "https://supersoniks.com/");
+  assert.equal(org.address["@type"], "PostalAddress");
+  assert.equal(org.address.addressLocality, "Tours");
+  assert.equal(org.contactPoint["@type"], "ContactPoint");
+  assert.ok(org.contactPoint.contactType && org.contactPoint.telephone);
+  assert.ok(org.sameAs.every((u) => u.startsWith("https://")));
+});
+
+test("source index.html embeds the generated JSON-LD and Open Graph tags", () => {
+  const html = fs.readFileSync(path.resolve("index.html"), "utf8");
+  const block = html.match(
+    /<script type="application\/ld\+json">([\s\S]*?)<\/script>/,
+  );
+  assert.ok(block, "JSON-LD script missing");
+  assert.deepEqual(JSON.parse(block[1]), homepageJsonLd());
+  for (const prop of ["og:type", "og:title", "og:description", "og:url", "og:image"]) {
+    assert.match(html, new RegExp(`<meta property="${prop}" content="[^"]+"`), prop);
+  }
+  assert.match(
+    html,
+    /<meta property="og:image" content="https:\/\/concorde\.supersoniks\.org\/img\/og-concorde\.jpg"/,
+  );
+  assert.ok(fs.existsSync(path.resolve("public/img/og-concorde.jpg")));
+  assert.match(html, /<meta name="twitter:card" content="summary_large_image"/);
+  assert.match(html, /href="\/about"/);
+  assert.match(html, /href="\/privacy"/);
+});
+
+test("site page Markdown is read from site-pages/", () => {
+  assert.deepEqual(
+    STATIC_PAGES.map((p) => p.slug),
+    ["about", "privacy"],
+  );
+  for (const { slug, markdown } of STATIC_PAGES) {
+    assert.equal(
+      markdown,
+      fs.readFileSync(path.resolve(`site-pages/${slug}.md`), "utf8"),
+    );
+    assert.match(markdown, /^# /);
+  }
+});
+
+test("site pages are SPA shells with their own metadata and inline content", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "concorde-pages-"));
+  try {
+    writeAgentSiteArtifacts(dir);
+    for (const { slug } of STATIC_PAGES) {
+      const md = fs.readFileSync(path.join(dir, `${slug}.md`), "utf8");
+      const html = fs.readFileSync(path.join(dir, `${slug}.html`), "utf8");
+      assert.ok(md.length >= 500, `${slug}.md too short (${md.length})`);
+      const section = html.match(
+        /<section id="docs-agent-content"[^>]*>([\s\S]*?)<\/section>/,
+      );
+      assert.ok(section, `${slug}.html page section missing`);
+      assert.ok(stripTags(section[1]).length >= 500, `${slug}.html too short`);
+      assert.match(section[1], /<h1/);
+      assert.doesNotMatch(section[1], /<h1>Concorde by Supersoniks<\/h1>/);
+      assert.match(html, /<sonic-router>/, "SPA shell expected");
+      const url = `https://concorde\\.supersoniks\\.org/${slug}`;
+      assert.match(html, new RegExp(`<link rel="canonical" href="${url}" />`));
+      assert.match(html, new RegExp(`<meta property="og:url" content="${url}"`));
+      assert.match(html, new RegExp(`href="/${slug}\\.md"`));
+      assert.equal((html.match(/<title>/g) || []).length, 1);
+      const ld = JSON.parse(
+        html.match(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/)[1],
+      );
+      assert.equal(ld.url, `https://concorde.supersoniks.org/${slug}`);
+      assert.equal(ld.publisher.address.addressLocality, "Tours");
+    }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("sitemap and homepage Markdown link the site pages", () => {
+  const xml = generateSitemap([], []);
+  const md = generateHomepageMarkdown();
+  for (const slug of ["about", "privacy"]) {
+    assert.match(xml, new RegExp(`<loc>https://concorde\\.supersoniks\\.org/${slug}</loc>`));
+    assert.match(md, new RegExp(`https://concorde\\.supersoniks\\.org/${slug}\\)`));
+  }
+});
+
+test("htaccess serves site pages as HTML or Markdown", () => {
+  const conf = generateHtaccess();
+  assert.match(conf, /\^\(about\|privacy\)\$ \/\$1\.md \[END\]/);
+  assert.match(conf, /\^\(about\|privacy\)\$ \/\$1\.html \[END\]/);
+});

package/site-pages/about.md

@@ -0,0 +1,22 @@
+# About Concorde
+
+Concorde is an open-source web components framework built on [Lit](https://lit.dev). It is designed, written and maintained by [Supersoniks](https://supersoniks.com/), a company based in Tours, France, which uses it in production.
+
+## Why it exists
+
+Supersoniks works on many stacks: PHP back offices, static pages, React and Vue front ends. Rewriting the same buttons, forms and data lists for each stack was slow and led to inconsistent interfaces. Concorde solves this with standard custom elements (`sonic-*`) that work the same way in any host page, plus a small data layer (DataProvider, decorators) that connects components to each other and to REST APIs without a framework.
+
+## What it includes
+
+- UI components: buttons, inputs, selects, checkboxes, modals, toasts, cards, menus, tooltips and more.
+- Data components: lists, queues, fetch, submit, router, states and server-driven UI from JSON.
+- Lit decorators such as `@get`, `@post`, `@subscribe` and `@bind`.
+- Theming through CSS custom properties, with light and dark modes.
+
+## Licence and distribution
+
+Concorde is published on npm as [`@supersoniks/concorde`](https://www.npmjs.com/package/@supersoniks/concorde) under the MIT licence. This site (https://concorde.supersoniks.org) is its official documentation.
+
+## Publisher
+
+Supersoniks, 22 rue du Docteur Bretonneau, 37000 Tours, France · +33 2 47 68 93 25 · [contact Supersoniks](https://supersoniks.com/un-projet). See also the [privacy notice](/privacy).