@hgdc/agents 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @hgdc/agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rendre un site lisible par les agents IA : chaque page existe en Markdown, servie quand la requête accepte `text/markdown` ([acceptmarkdown.com](https://acceptmarkdown.com)), avec `Vary: Accept`. Une page introuvable reste en 404, en Markdown pour un agent. Le HTML servi aux navigateurs ne change pas.
+
+Sans dépendance. Le convertisseur vise le HTML qu'un produit rend lui-même (Astro, React SSR) : il lit le `<main>` (sinon le `<body>`) et laisse de côté ce qui est caché aux lecteurs d'écran (`aria-hidden`, `visually-hidden`, `hidden`), les scripts, les styles, les SVG et les formulaires.
+
+## App rendue côté serveur (TanStack Start)
+
+TanStack Start répond 406 à une requête sans `text/html` ni `*/*`. Le point d'entrée serveur enrobe donc son handler, avant le routeur :
+
+```ts
+// src/server.ts
+import handler, { createServerEntry } from "@tanstack/react-start/server-entry"
+import { linksFooter, withMarkdown } from "@hgdc/agents"
+
+const fetch = withMarkdown(handler.fetch, {
+  footer: linksFooter([{ label: "Résumé pour les agents", href: "https://app.hgdc.ch/mail/llms.txt" }]),
+})
+
+export default createServerEntry({ fetch })
+```
+
+Seuls les GET et HEAD qui préfèrent le Markdown sont convertis (`prefersMarkdown` : `text/markdown` accepté avec une qualité au moins égale à `text/html` ; un joker ne compte pas). Une redirection, un fichier ou du JSON passent tels quels.
+
+## Site prérendu (Astro, sortie Build Output API)
+
+À la fin du build, `@hgdc/agents/build` écrit `<page>.md` à côté de chaque page et donne les routes qui les servent, sur HGDC Host comme sur Vercel :
+
+```js
+import { markdownRoutes, writeMarkdownPages } from "@hgdc/agents/build"
+
+// astro:build:done ({ dir }), après l'adaptateur Vercel qui a écrit .vercel/output/config.json
+const pages = await writeMarkdownPages(dir, { site: "https://hgdc.ch", footer })
+const { before, miss } = markdownRoutes(pages, { site: "https://hgdc.ch" })
+config.routes.unshift(...before) // avant { handle: "filesystem" }
+config.routes.splice(-1, 0, ...miss) // juste avant la page 404 de l'adaptateur
+```
+
+`base` (`/agence`) sert un site publié sous un chemin : son accueil s'écrit `<base>/index.md` et sa 404 Markdown reste sous le préfixe.
+
+## Référence
+
+| Export                                        | Rôle                                                 |
+| --------------------------------------------- | ---------------------------------------------------- |
+| `htmlToMarkdown(html, url)`                   | Markdown du contenu d'une page, liens rendus absolus |
+| `prefersMarkdown(accept)`                     | La requête préfère-t-elle le Markdown ?              |
+| `withMarkdown(fetch, { footer })`             | Handler `fetch` qui sert le Markdown aux agents      |
+| `linksFooter(links)`                          | Pied de page : liens séparés par « · »               |
+| `varyOnAccept(headers)`                       | Ajoute `Accept` à `Vary`                             |
+| `writeMarkdownPages(dir, options)` (`/build`) | Écrit les `.md` d'un build prérendu                  |
+| `markdownRoutes(pages, options)` (`/build`)   | Routes Build Output API v3 qui les servent           |

package/dist/build.d.ts

@@ -0,0 +1,41 @@
+/** Route Build Output API v3, sous-ensemble utilisé ici. */
+export type Route = {
+    src: string;
+    dest?: string;
+    status?: number;
+    headers?: Record<string, string>;
+    has?: {
+        type: "header";
+        key: string;
+        value: string;
+    }[];
+    continue?: boolean;
+};
+export type MarkdownPage = {
+    /** Chemin public de la page : `/`, `/contact`, `/agence/blog/article`. */
+    path: string;
+    /** Fichier Markdown écrit, relatif au dossier du build : `index.md`, `contact.md`. */
+    file: string;
+};
+export type MarkdownBuildOptions = {
+    /** Origine publique, sans barre finale : `https://hgdc.ch`. */
+    site: string;
+    /** Préfixe du site s'il est servi sous un chemin (`/agence`) ; sa page d'accueil s'écrit `<base>/index.md`. */
+    base?: string;
+    /** Pied de chaque page Markdown, après une ligne `---`. */
+    footer?: string;
+};
+/**
+ * Écrit `<page>.md` pour chaque page prérendue de `dir` (dossier rendu par Astro, `dist/` : l'adaptateur
+ * Vercel le copie ensuite vers `.vercel/output/static`), et `404.md` à côté de chaque `404.html`.
+ */
+export declare function writeMarkdownPages(dir: URL, options: MarkdownBuildOptions): Promise<MarkdownPage[]>;
+/**
+ * Routes à placer avant `{ handle: "filesystem" }` (`before`) et juste avant la page 404 de l'adaptateur
+ * (`miss`) : Markdown servi sur `Accept: text/markdown` avec `Vary: Accept` et l'adresse canonique en `Link`,
+ * `Vary: Accept` sur le HTML des mêmes pages, `404.md` (statut 404) pour une adresse inconnue.
+ */
+export declare function markdownRoutes(pages: MarkdownPage[], options: Pick<MarkdownBuildOptions, "site" | "base">): {
+    before: Route[];
+    miss: Route[];
+};

package/dist/build.js

@@ -0,0 +1,113 @@
+// Sites prérendus (Astro + sortie Build Output API v3, servie par HGDC Host ou Vercel) : écrit la
+// version Markdown de chaque page au build et produit les routes qui la servent sur
+// `Accept: text/markdown`. Rien ne s'exécute à la requête : tout est fichier statique et route.
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { htmlToMarkdown } from "./markdown.js";
+const NOT_FOUND = "404.html";
+// Valeur de condition commune à Host (edge/src/router.ts) et Vercel : correspondance sur toute la valeur.
+const ACCEPTS_MARKDOWN = { type: "header", key: "accept", value: ".*text/markdown.*" };
+const MARKDOWN_TYPE = "text/markdown; charset=utf-8";
+// Host refuse une expression de plus de 4096 caractères : les listes de pages se découpent en dessous.
+const MAX_PATTERN = 3000;
+const escapeRegex = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Chemin public d'un fichier HTML du build, `null` si ce n'est pas une page. */
+function pagePath(file) {
+    if (file === "index.html")
+        return "/";
+    const m = /^(.+)\/index\.html$/.exec(file);
+    return m ? `/${m[1]}` : null;
+}
+/** Fichier Markdown d'une page : `index.md` pour la racine (ou le préfixe), `<chemin>.md` sinon. */
+function markdownFile(path, base) {
+    if (path === "/")
+        return "index.md";
+    if (path === base)
+        return `${base.slice(1)}/index.md`;
+    return `${path.slice(1)}.md`;
+}
+/**
+ * Écrit `<page>.md` pour chaque page prérendue de `dir` (dossier rendu par Astro, `dist/` : l'adaptateur
+ * Vercel le copie ensuite vers `.vercel/output/static`), et `404.md` à côté de chaque `404.html`.
+ */
+export async function writeMarkdownPages(dir, options) {
+    const base = options.base ?? "";
+    const footer = options.footer ? `\n---\n\n${options.footer}\n` : "";
+    const pages = [];
+    const files = (await readdir(dir, { recursive: true })).map((f) => f.replaceAll("\\", "/")).sort();
+    for (const file of files) {
+        const notFound = file === NOT_FOUND || file.endsWith(`/${NOT_FOUND}`);
+        const path = notFound ? null : pagePath(file);
+        if (!notFound && path === null)
+            continue;
+        const html = await readFile(new URL(file, dir), "utf-8");
+        const url = `${options.site}${path ?? `${base}/`}`;
+        const target = notFound ? file.replace(/\.html$/, ".md") : markdownFile(path, base);
+        await writeFile(new URL(target, dir), htmlToMarkdown(html, url) + footer);
+        if (path !== null)
+            pages.push({ path, file: target });
+    }
+    return pages;
+}
+/** Alternances `a|b|c` de moins de `MAX_PATTERN` caractères. */
+function chunks(items) {
+    const out = [];
+    let current = [];
+    for (const item of items) {
+        if (current.length && [...current, item].join("|").length > MAX_PATTERN) {
+            out.push(current.join("|"));
+            current = [];
+        }
+        current.push(item);
+    }
+    if (current.length)
+        out.push(current.join("|"));
+    return out;
+}
+/**
+ * Routes à placer avant `{ handle: "filesystem" }` (`before`) et juste avant la page 404 de l'adaptateur
+ * (`miss`) : Markdown servi sur `Accept: text/markdown` avec `Vary: Accept` et l'adresse canonique en `Link`,
+ * `Vary: Accept` sur le HTML des mêmes pages, `404.md` (statut 404) pour une adresse inconnue.
+ */
+export function markdownRoutes(pages, options) {
+    const base = options.base ?? "";
+    const canonical = (path) => `<${options.site}${path}>; rel="canonical"`;
+    const before = [];
+    // Pages dont le fichier ne suit pas `<chemin>.md` (racine, préfixe) : une route chacune.
+    const special = pages.filter((p) => p.file !== `${p.path.slice(1)}.md`);
+    const regular = pages.filter((p) => p.file === `${p.path.slice(1)}.md`);
+    for (const group of chunks(pages.map((p) => escapeRegex(p.path))))
+        before.push({ src: `^(?:${group})$`, headers: { Vary: "Accept" }, continue: true });
+    for (const page of special) {
+        const src = `^${escapeRegex(page.path)}$`;
+        const link = canonical(page.path === "/" ? "/" : page.path);
+        before.push({
+            src,
+            has: [ACCEPTS_MARKDOWN],
+            dest: `/${page.file}`,
+            headers: { "Content-Type": MARKDOWN_TYPE, Vary: "Accept", Link: link },
+        });
+        before.push({ src: `^/${escapeRegex(page.file)}$`, headers: { Link: link }, continue: true });
+    }
+    for (const group of chunks(regular.map((p) => escapeRegex(p.path.slice(1))))) {
+        const link = `<${options.site}/$1>; rel="canonical"`;
+        before.push({
+            src: `^/(${group})$`,
+            has: [ACCEPTS_MARKDOWN],
+            dest: "/$1.md",
+            headers: { "Content-Type": MARKDOWN_TYPE, Vary: "Accept", Link: link },
+        });
+        // Lue directement (/contact.md), la version Markdown renvoie à la page HTML de référence.
+        before.push({ src: `^/(${group})\\.md$`, headers: { Link: link }, continue: true });
+    }
+    const scope = base ? `^${escapeRegex(base)}(?:/.*)?$` : "^/.*$";
+    const miss = [
+        {
+            src: scope,
+            has: [ACCEPTS_MARKDOWN],
+            dest: `${base}/404.md`,
+            status: 404,
+            headers: { "Content-Type": MARKDOWN_TYPE, Vary: "Accept" },
+        },
+    ];
+    return { before, miss };
+}

package/dist/fetch.d.ts

@@ -0,0 +1,19 @@
+export type MarkdownOptions = {
+    /** Markdown ajouté en pied de chaque page, après une ligne `---` : liens vers llms.txt, sitemap, contact. */
+    footer?: string;
+};
+/** Pied de page standard : une ligne de liens, `[libellé](adresse)` séparés par « · ». */
+export declare function linksFooter(links: {
+    label: string;
+    href: string;
+}[]): string;
+/**
+ * Enrobe un handler `fetch` : une requête GET ou HEAD qui préfère `text/markdown` reçoit la page HTML
+ * convertie, au même statut (404 compris), avec `Content-Type: text/markdown` et `Vary: Accept`. Les autres
+ * requêtes passent telles quelles ; leurs pages HTML reçoivent `Vary: Accept`. Une redirection, un fichier
+ * ou du JSON ne sont jamais convertis.
+ *
+ * TanStack Start refuse en 406 une requête sans `text/html` ni `*\/*` : le handler reçoit donc la requête
+ * avec `Accept: text/html`.
+ */
+export declare function withMarkdown<Rest extends unknown[]>(handler: (request: Request, ...rest: Rest) => Response | Promise<Response>, options?: MarkdownOptions): (request: Request, ...rest: Rest) => Promise<Response>;

package/dist/fetch.js

@@ -0,0 +1,50 @@
+// Version Markdown des pages d'une app rendue côté serveur (TanStack Start, ou tout handler `fetch`).
+import { htmlToMarkdown } from "./markdown.js";
+import { prefersMarkdown, varyOnAccept } from "./negotiate.js";
+/** Pied de page standard : une ligne de liens, `[libellé](adresse)` séparés par « · ». */
+export function linksFooter(links) {
+    return links.map((l) => `[${l.label}](${l.href})`).join(" · ");
+}
+const isHtml = (response) => /^text\/html\b/i.test(response.headers.get("content-type") ?? "");
+// En-têtes qui décrivent le corps HTML et deviennent faux pour le Markdown.
+const BODY_HEADERS = ["content-type", "content-length", "content-encoding", "etag", "last-modified", "content-md5"];
+/**
+ * Enrobe un handler `fetch` : une requête GET ou HEAD qui préfère `text/markdown` reçoit la page HTML
+ * convertie, au même statut (404 compris), avec `Content-Type: text/markdown` et `Vary: Accept`. Les autres
+ * requêtes passent telles quelles ; leurs pages HTML reçoivent `Vary: Accept`. Une redirection, un fichier
+ * ou du JSON ne sont jamais convertis.
+ *
+ * TanStack Start refuse en 406 une requête sans `text/html` ni `*\/*` : le handler reçoit donc la requête
+ * avec `Accept: text/html`.
+ */
+export function withMarkdown(handler, options = {}) {
+    return async (request, ...rest) => {
+        const read = request.method === "GET" || request.method === "HEAD";
+        if (!read || !prefersMarkdown(request.headers.get("accept"))) {
+            const response = await handler(request, ...rest);
+            if (read && isHtml(response))
+                return withHeaders(response, response.body, varyOnAccept);
+            return response;
+        }
+        const headers = new Headers(request.headers);
+        headers.set("accept", "text/html");
+        // Requête reconstruite depuis l'URL : le Request de Nitro (srvx) n'est pas celui d'undici, et
+        // `new Request(request, …)` le refuse. HEAD est rendu en GET, sinon le corps à convertir serait vide.
+        const response = await handler(new Request(request.url, { method: "GET", headers, signal: request.signal }), ...rest);
+        if (!isHtml(response) || response.status < 200 || (response.status >= 300 && response.status < 400))
+            return withHeaders(response, request.method === "HEAD" ? null : response.body, varyOnAccept);
+        const html = await response.text();
+        const markdown = htmlToMarkdown(html, request.url) + (options.footer ? `\n---\n\n${options.footer}\n` : "");
+        return withHeaders(response, request.method === "HEAD" ? null : markdown, (out) => {
+            for (const name of BODY_HEADERS)
+                out.delete(name);
+            out.set("content-type", "text/markdown; charset=utf-8");
+            varyOnAccept(out);
+        });
+    };
+}
+function withHeaders(response, body, edit) {
+    const headers = new Headers(response.headers);
+    edit(headers);
+    return new Response(body, { status: response.status, statusText: response.statusText, headers });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { htmlToMarkdown, pageTitle } from "./markdown.js";
+export { prefersMarkdown, varyOnAccept } from "./negotiate.js";
+export { linksFooter, withMarkdown, type MarkdownOptions } from "./fetch.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { htmlToMarkdown, pageTitle } from "./markdown.js";
+export { prefersMarkdown, varyOnAccept } from "./negotiate.js";
+export { linksFooter, withMarkdown } from "./fetch.js";

package/dist/markdown.d.ts

@@ -0,0 +1,7 @@
+/** Titre de la page (`<title>`), pour une page dont le contenu n'a pas de titre de niveau 1. */
+export declare function pageTitle(html: string): string | null;
+/**
+ * Markdown du contenu d'une page HTML.
+ * @param base adresse de la page, pour rendre les liens absolus
+ */
+export declare function htmlToMarkdown(html: string, base: string | URL): string;

package/dist/markdown.js

@@ -0,0 +1,268 @@
+// HTML → Markdown pour les agents. Prévu pour le HTML qu'un produit rend lui-même (Astro, React SSR),
+// bien formé et sans contenu tiers : pas de dépendance, seulement les éléments qu'un site de la
+// famille emploie. Ce qui est caché aux lecteurs d'écran (aria-hidden, visually-hidden, hidden)
+// l'est aussi aux agents.
+const VOID = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "source",
+    "track",
+    "wbr",
+]);
+const DROPPED = new Set([
+    "script",
+    "style",
+    "svg",
+    "template",
+    "noscript",
+    "button",
+    "form",
+    "input",
+    "select",
+    "textarea",
+    "dialog",
+]);
+const INLINE = new Set([
+    "a",
+    "abbr",
+    "b",
+    "br",
+    "cite",
+    "code",
+    "em",
+    "i",
+    "img",
+    "kbd",
+    "label",
+    "mark",
+    "q",
+    "s",
+    "small",
+    "span",
+    "strong",
+    "sub",
+    "sup",
+    "time",
+    "u",
+]);
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+const decode = (text) => text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, name) => {
+    if (name[0] !== "#")
+        return ENTITIES[name.toLowerCase()] ?? whole;
+    const code = name[1] === "x" || name[1] === "X" ? Number.parseInt(name.slice(2), 16) : Number.parseInt(name.slice(1), 10);
+    return Number.isFinite(code) && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+});
+function parseAttrs(source) {
+    const attrs = {};
+    for (const m of source.matchAll(/([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g))
+        attrs[m[1].toLowerCase()] = decode(m[2] ?? m[3] ?? m[4] ?? "");
+    return attrs;
+}
+/** Arbre minimal d'un fragment HTML. */
+function parse(html) {
+    const root = { tag: "#root", attrs: {}, children: [] };
+    const stack = [root];
+    const top = () => stack[stack.length - 1];
+    const cleaned = html.replace(/<!--[\s\S]*?-->/g, "").replace(/<(script|style|svg|template)\b[\s\S]*?<\/\1>/gi, "");
+    let last = 0;
+    for (const m of cleaned.matchAll(/<(\/?)([a-zA-Z][a-zA-Z0-9-]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/g)) {
+        const text = cleaned.slice(last, m.index);
+        if (text)
+            top().children.push(decode(text));
+        last = m.index + m[0].length;
+        const tag = m[2].toLowerCase();
+        if (m[1]) {
+            // Fermeture : remonte jusqu'à l'élément ouvert correspondant (tolère un oubli).
+            const at = stack.findLastIndex((el) => el.tag === tag);
+            if (at > 0)
+                stack.length = at;
+            continue;
+        }
+        const el = { tag, attrs: parseAttrs(m[3]), children: [] };
+        top().children.push(el);
+        if (!VOID.has(tag) && !m[3].trimEnd().endsWith("/"))
+            stack.push(el);
+    }
+    const tail = cleaned.slice(last);
+    if (tail)
+        top().children.push(decode(tail));
+    return root;
+}
+const hasClass = (el, pattern) => pattern.test(el.attrs.class ?? "");
+const hidden = (el) => DROPPED.has(el.tag) ||
+    el.attrs["aria-hidden"] === "true" ||
+    "hidden" in el.attrs ||
+    // `hidden` seul est la classe Tailwind `display: none` : l'autre moitié d'une image claire/sombre
+    // (`hidden dark:block`). `dark:hidden` ou `sm:hidden` ne comptent pas.
+    hasClass(el, /(?:^|\s)(?:visually-hidden|sr-only|skip-link|hidden)(?:\s|$)/);
+const hasBlock = (node) => typeof node !== "string" && !hidden(node) && (!INLINE.has(node.tag) || node.children.some(hasBlock));
+// Espaces ordinaires seulement : U+00A0 et U+202F (espace fine) sont des choix typographiques.
+const collapse = (text) => text.replace(/[ \t\n\r\f]+/g, " ");
+const escape = (text) => text.replace(/([\\*_`[\]])/g, "\\$1");
+function inline(nodes, link) {
+    let out = "";
+    let afterElement = false;
+    for (const node of nodes) {
+        if (typeof node === "string") {
+            out += escape(collapse(node));
+            afterElement = false;
+            continue;
+        }
+        if (hidden(node))
+            continue;
+        // Deux éléments collés (boutons, badges côte à côte) : séparés par une espace, comme à l'écran.
+        if (afterElement && node.tag !== "br" && out && !/\s$/.test(out))
+            out += " ";
+        afterElement = true;
+        const inner = () => inline(node.children, link);
+        switch (node.tag) {
+            case "br":
+                // Saut de ligne forcé de CommonMark : barre oblique inverse en fin de ligne.
+                out += "\\\n";
+                break;
+            case "strong":
+            case "b": {
+                const text = inner().trim();
+                if (text)
+                    out += `**${text}**`;
+                break;
+            }
+            case "em":
+            case "i": {
+                const text = inner().trim();
+                if (text)
+                    out += `_${text}_`;
+                break;
+            }
+            case "code":
+                out += `\`${inner().replace(/\\([\\*_`[\]])/g, "$1")}\``;
+                break;
+            case "img":
+                // L'image en double pour le thème sombre (only-dark) ne se lit qu'une fois.
+                if (node.attrs.alt && !hasClass(node, /(?:^|\s)only-dark(?:\s|$)/))
+                    out += escape(node.attrs.alt);
+                break;
+            case "a": {
+                const text = inner().trim();
+                const href = node.attrs.href ? link(node.attrs.href) : null;
+                out += href && text ? `[${text}](${href})` : text;
+                break;
+            }
+            default:
+                out += inner();
+        }
+    }
+    return out;
+}
+/** Bloc de texte propre : espaces fusionnés, bords retirés, sauts de ligne forcés gardés. */
+const tidy = (text) => text
+    .split("\n")
+    .map((line) => line.replace(/ {2,}/g, " ").trim())
+    .join("\n")
+    .trim()
+    .replace(/\\$/, "");
+function blocks(el, link) {
+    const out = [];
+    let run = [];
+    const flush = () => {
+        const text = tidy(inline(run, link));
+        if (text)
+            out.push(text);
+        run = [];
+    };
+    for (const node of el.children) {
+        if (!hasBlock(node)) {
+            run.push(node);
+            continue;
+        }
+        flush();
+        out.push(...block(node, link));
+    }
+    flush();
+    return out;
+}
+function block(el, link) {
+    const text = () => tidy(inline(el.children, link)).replace(/\n/g, " ");
+    const heading = /^h([1-6])$/.exec(el.tag);
+    if (heading) {
+        const t = text();
+        return t ? [`${"#".repeat(Number(heading[1]))} ${t}`] : [];
+    }
+    switch (el.tag) {
+        case "hr":
+            return ["---"];
+        case "ul":
+        case "ol": {
+            const items = el.children.filter((c) => typeof c !== "string" && c.tag === "li" && !hidden(c));
+            const lines = items.map((li, i) => {
+                const marker = el.tag === "ol" ? `${i + 1}. ` : "- ";
+                const body = blocks(li, link).join("\n\n");
+                return marker + body.replace(/\n(?!\n)/g, `\n${" ".repeat(marker.length)}`);
+            });
+            return lines.length ? [lines.join("\n")] : [];
+        }
+        case "blockquote":
+            return blocks(el, link).map((b) => b.replace(/^/gm, "> "));
+        case "dt":
+        case "summary": {
+            const t = text();
+            return t ? [`**${t}**`] : [];
+        }
+        case "a": {
+            // Lien qui enveloppe des blocs (carte) : le contenu, puis le lien seul.
+            const href = el.attrs.href ? link(el.attrs.href) : null;
+            const inner = blocks(el, link);
+            return href ? [...inner, `[${inner[0]?.replace(/^#+ /, "") ?? href}](${href})`] : inner;
+        }
+        default:
+            return blocks(el, link);
+    }
+}
+/** Contenu de la page : le premier `<main>`, sinon le `<body>`, sinon tout le fragment. */
+function pageContent(html) {
+    const main = /<main\b[^>]*>([\s\S]*?)<\/main>/i.exec(html);
+    if (main)
+        return main[1];
+    const body = /<body\b[^>]*>([\s\S]*?)<\/body>/i.exec(html);
+    return body ? body[1] : html;
+}
+/** Titre de la page (`<title>`), pour une page dont le contenu n'a pas de titre de niveau 1. */
+export function pageTitle(html) {
+    const title = /<title\b[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+    return title ? collapse(decode(title[1])).trim() || null : null;
+}
+/**
+ * Markdown du contenu d'une page HTML.
+ * @param base adresse de la page, pour rendre les liens absolus
+ */
+export function htmlToMarkdown(html, base) {
+    const page = new URL(base);
+    const link = (href) => {
+        if (href.startsWith("#"))
+            return null;
+        if (/^(?:mailto|tel):/i.test(href))
+            return href;
+        try {
+            const url = new URL(href, page);
+            return /^https?:$/.test(url.protocol) ? url.href : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const out = blocks(parse(pageContent(html)), link);
+    if (!out.some((b) => b.startsWith("# "))) {
+        const title = pageTitle(html);
+        if (title)
+            out.unshift(`# ${escape(title)}`);
+    }
+    return `${out.join("\n\n")}\n`;
+}

package/dist/negotiate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Vrai si la requête préfère le Markdown au HTML : `text/markdown` accepté (q > 0), avec une qualité au
+ * moins égale à celle de `text/html` demandé explicitement. Les jokers (`*\/*`, `text/*`) ne comptent pas :
+ * un navigateur ne reçoit jamais de Markdown.
+ */
+export declare function prefersMarkdown(accept: string | null | undefined): boolean;
+/** Ajoute `Accept` à l'en-tête `Vary` d'une réponse, sans doublon. */
+export declare function varyOnAccept(headers: Headers): void;

package/dist/negotiate.js

@@ -0,0 +1,32 @@
+// Négociation de contenu : un agent qui demande text/markdown le reçoit (acceptmarkdown.com).
+function parseAccept(accept) {
+    return accept
+        .split(",")
+        .map((part) => {
+        const [type = "", ...params] = part.trim().toLowerCase().split(";");
+        const q = params.map((p) => /^\s*q\s*=\s*([\d.]+)\s*$/.exec(p)?.[1]).find((v) => v !== undefined);
+        return { type: type.trim(), q: q === undefined ? 1 : Math.min(1, Number(q) || 0) };
+    })
+        .filter((range) => range.type);
+}
+/**
+ * Vrai si la requête préfère le Markdown au HTML : `text/markdown` accepté (q > 0), avec une qualité au
+ * moins égale à celle de `text/html` demandé explicitement. Les jokers (`*\/*`, `text/*`) ne comptent pas :
+ * un navigateur ne reçoit jamais de Markdown.
+ */
+export function prefersMarkdown(accept) {
+    if (!accept)
+        return false;
+    const ranges = parseAccept(accept);
+    const quality = (type) => Math.max(0, ...ranges.filter((r) => r.type === type).map((r) => r.q));
+    const markdown = quality("text/markdown");
+    return markdown > 0 && markdown >= quality("text/html");
+}
+/** Ajoute `Accept` à l'en-tête `Vary` d'une réponse, sans doublon. */
+export function varyOnAccept(headers) {
+    const vary = headers.get("vary");
+    if (!vary)
+        headers.set("vary", "Accept");
+    else if (!vary.split(",").some((v) => ["accept", "*"].includes(v.trim().toLowerCase())))
+        headers.set("vary", `${vary}, Accept`);
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@hgdc/agents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Sites lisibles par les agents IA : version Markdown des pages (Accept: text/markdown), 404 en Markdown, routes Build Output API pour les sites prérendus.",
+  "license": "UNLICENSED",
+  "homepage": "https://github.com/hugogebel-boop/hgdc-kit/tree/main/packages/agents#readme",
+  "bugs": "https://github.com/hugogebel-boop/hgdc-kit/security/advisories/new",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hugogebel-boop/hgdc-kit.git",
+    "directory": "packages/agents"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "default": "./dist/build.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}