@supersoniks/concorde 5.1.1 → 5.1.3

package/scripts/generate-crawl-docs.test.mjs

@@ -0,0 +1,124 @@
+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 {
+  generateHomepageMarkdown,
+  generateHtaccess,
+  generateNotFoundHtml,
+  generateNotFoundMarkdown,
+  pagePath,
+  writeAgentSiteArtifacts,
+} from "./generate-crawl-docs.mjs";
+
+function stripTags(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+test("pagePath builds pretty public pathnames", () => {
+  assert.equal(
+    pagePath("docs/getting-started/start.md"),
+    "/docs/getting-started/start",
+  );
+  assert.equal(
+    pagePath("core/components/ui/button/button.md"),
+    "/core/components/ui/button",
+  );
+  assert.equal(
+    pagePath("core/components/functional/sdui/sdui-extension-points.md"),
+    "/core/components/functional/sdui/sdui-extension-points",
+  );
+});
+
+test("homepage Markdown meets Accept negotiation body requirements", () => {
+  const md = generateHomepageMarkdown();
+  assert.match(md, /^# Concorde by Supersoniks/m);
+  assert.match(md, /@supersoniks\/concorde/);
+  assert.match(md, /llms\.txt/);
+  assert.match(md, /Accept: text\/markdown/);
+  assert.match(md, /docs\/getting-started\/start/);
+  assert.doesNotMatch(md, /\/crawl\//);
+  assert.doesNotMatch(md, /\/docs\/_getting-started\//);
+  assert.ok(md.length >= 500, `expected ≥500 chars, got ${md.length}`);
+});
+
+test("404 Markdown explains the error and links agent entry points", () => {
+  const md = generateNotFoundMarkdown();
+  assert.ok(md.length >= 20);
+  assert.match(md, /not found/i);
+  assert.match(md, /llms\.txt|sitemap\.xml|docs\/index/);
+  assert.doesNotMatch(md, /\/crawl\//);
+  assert.match(md, /https:\/\/concorde\.supersoniks\.org/);
+});
+
+test("404 HTML keeps a human-readable fallback", () => {
+  const html = generateNotFoundHtml();
+  assert.match(html, /<h1>Page not found<\/h1>/);
+  assert.match(html, /llms\.txt/);
+  assert.doesNotMatch(html, /\/crawl\//);
+});
+
+test("htaccess maps components and negotiates Markdown/HTML", () => {
+  const conf = generateHtaccess();
+  assert.match(conf, /RewriteEngine On/);
+  assert.match(conf, /text\/markdown/);
+  assert.match(conf, /index\.md/);
+  assert.match(conf, /ErrorDocument 404 \/404\.md/);
+  assert.match(conf, /\$1\/\$2\/\$2\.md/);
+  assert.match(conf, /Googlebot/);
+  assert.match(conf, /index\.html \[END\]/);
+  assert.match(conf, /DirectorySlash Off/);
+  assert.doesNotMatch(conf, /docs\/_/);
+  assert.doesNotMatch(conf, /THE_REQUEST/);
+  assert.doesNotMatch(conf, /\^crawl\//);
+});
+
+test("writeAgentSiteArtifacts emits negotiation files", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "concorde-agent-"));
+  try {
+    writeAgentSiteArtifacts(dir);
+    for (const name of ["index.md", "404.md", "404.html", ".htaccess"]) {
+      const filePath = path.join(dir, name);
+      assert.ok(fs.existsSync(filePath), `missing ${name}`);
+      assert.ok(fs.statSync(filePath).size > 20, `${name} too small`);
+    }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("source index.html ships ≥500 chars of meaningful agent content with H1", () => {
+  const indexPath = path.resolve("index.html");
+  const html = fs.readFileSync(indexPath, "utf8");
+  assert.match(html, /id="docs-agent-content"/);
+  assert.match(html, /<h1>Concorde by Supersoniks<\/h1>/);
+  assert.match(html, /href="\/docs\/getting-started\/start"/);
+  assert.doesNotMatch(html, /\/docs\/_getting-started\//);
+  assert.doesNotMatch(html, /\/crawl\//);
+
+  const section = html.match(
+    /<section id="docs-agent-content"[^>]*>([\s\S]*?)<\/section>/,
+  );
+  assert.ok(section, "docs-agent-content section missing");
+  const text = stripTags(section[1]);
+  assert.ok(
+    text.length >= 500,
+    `agent section text expected ≥500 chars, got ${text.length}`,
+  );
+});
+
+test("public robots.txt allows pathnames and drops /crawl/", () => {
+  const robots = fs.readFileSync(path.resolve("public/robots.txt"), "utf8");
+  assert.match(robots, /Allow: \//);
+  assert.match(robots, /Allow: \/docs\//);
+  assert.match(robots, /Allow: \/core\//);
+  assert.match(robots, /Allow: \/llms\.txt/);
+  assert.doesNotMatch(robots, /Allow: \/crawl\//);
+  assert.doesNotMatch(robots, /Googlebot[\s\S]*Disallow: \//);
+});

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,57 +1,62 @@
 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");
-/**
- * lister les fichiers d'un répertoire de manière récursive
- */
+
 function listFiles(dir) {
   let files = [];
   let list = fs.readdirSync(dir);
   list.forEach((file) => {
-    const path = dir + "/" + file;
-    let stat = fs.statSync(path);
+    const filePath = dir + "/" + file;
+    let stat = fs.statSync(filePath);
     if (stat && stat.isDirectory()) {
-      files = files.concat(listFiles(path));
+      files = files.concat(listFiles(filePath));
     } else {
-      files.push(path);
+      files.push(filePath);
     }
   });
   return files;
 }
 
+function ensureCopy(absSrc, absDest) {
+  fs.mkdirSync(path.dirname(absDest), { recursive: true });
+  fs.copyFileSync(absSrc, absDest);
+}
+
 /**
- * copier toues les fichiers .md présents dans le répertpoire src et ses sous dossiers de manière récurcive vers dossier docs en respectant l'arborescence qu'il y avait dans le dossier src
- * il faut creer le chemin si il n'existe pas avant de copier le fichier
+ * Publish markdown at the public pathname (`/docs/…/page.md`, `/core/…/page.md`)
+ * and keep a `/src/…` copy for non-md assets (and legacy MD until 301).
  */
 function copyDocs() {
-  let files = listFiles(src);
+  const files = listFiles(src);
   for (const file of files) {
-    if (file.indexOf(".md") != -1 || file.indexOf(".json") != -1) {
-      let idx = file.indexOf("src/");
-      let dest = file.substring(idx);
-      let split = dest.split("/");
-      let dir = path.resolve(docs);
-      for (let i = 0; i < split.length - 1; i++) {
-        dir += "/" + split[i];
-        if (!fs.existsSync(dir)) {
-          fs.mkdirSync(dir);
-        }
-      }
-      dir += "/" + split[split.length - 1];
-      fs.copyFileSync(file, dir);
+    const isMd = /\.mdx?$/i.test(file);
+    const isJson = file.endsWith(".json");
+    if (!isMd && !isJson) continue;
+
+    const idx = file.indexOf("src/");
+    if (idx === -1) continue;
+    const underSrc = file.substring(idx); // src/docs/…/x.md
+    const withoutSrc = underSrc.replace(/^src\//, ""); // docs/…/x.md
+
+    // Always keep under docs/src/… (json + legacy md paths)
+    ensureCopy(file, path.join(docs, underSrc));
+
+    // Public MD URLs: /docs/… and /core/… (+ .md)
+    if (isMd && /^(docs|core)\//.test(withoutSrc)) {
+      ensureCopy(file, path.join(docs, withoutSrc));
     }
   }
 }
+
 copyDocs();
+// Custom Elements Manifest, served at /custom-elements.json
+fs.copyFileSync(generateCem(), path.join(docs, "custom-elements.json"));
 generateCrawlDocs();
 
-/**
- * Par rapport au projet, regarder si ../concorde_doc existe et si oui, remplacer le contenu de /concorde_doc par celui de contenu dans docs/ en dehors des fichiers spécifiques à git .git .gitignore .gitattributes)
- */
-
 function copyToConcordeDoc() {
   let concordeDoc = path.resolve("../concorde_doc");
 
@@ -60,15 +65,17 @@ function copyToConcordeDoc() {
   }
 
   try {
-    /* first remove all files/foilders in concorde_doc  except .git folder and .gitignore file */
     let files = listFiles(concordeDoc);
     for (const file of files) {
       if (file.indexOf(".git") == -1) {
         fs.unlinkSync(file);
       }
     }
+    const legacyCrawl = path.join(concordeDoc, "crawl");
+    if (fs.existsSync(legacyCrawl)) {
+      fs.rmSync(legacyCrawl, { recursive: true, force: true });
+    }
 
-    /*then copy the new files*/
     files = listFiles(docs);
     for (const file of files) {
       let idx = file.indexOf("docs/") + 5;
@@ -95,29 +102,9 @@ function copyToConcordeDoc() {
     console.warn(
       "copyToConcordeDoc: skipped (",
       err.code || err.message,
-      ") — docs/ and docs/crawl/ were still generated.",
+      ") — docs/ pathnames (HTML + MD + hubs) were still generated.",
     );
   }
 }
 
 copyToConcordeDoc();
-
-/**
- * dans ../concorde_doc, faire un git  add, commit et push
- */
-/* 
-function gitConcordeDoc() {
-  let concordeDoc = path.resolve("../concorde_doc");
-  if (fs.existsSync(concordeDoc)) {
-    exec("cd " + concordeDoc + " && git add . && git commit -m 'update doc' && git push", (error, stdout, stderr) => {
-      if (error) {
-        console.error(`exec error: ${error}`);
-        return;
-      }
-      console.log(`stdout: ${stdout}`);
-      console.error(`stderr: ${stderr}`);
-    });
-  }
-}
-
-gitConcordeDoc(); */

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).