@publish.os/nextjs 0.0.1-alpha.81 → 0.0.1-alpha.91

package/dist/kernel/routes/metadata/llms.js

@@ -3,8 +3,8 @@ import { tags } from "@publish.os/nextjs/cache/tags";
 import { cacheLife, cacheTag } from "next/cache";
 
 // src/lib/runtime/metadata/canonical-url.ts
-function canonicalUrl(manifest, path) {
-  let origin = manifest.site.url?.replace(/\/+$/, "");
+function canonicalUrl(manifest, path, group) {
+  let origin = (group && manifest.groups[group]?.origin) ?? manifest.site.origin;
   if (!origin) return path;
   try {
     return new URL(path, `${origin}/`).toString();
@@ -13,6 +13,122 @@ function canonicalUrl(manifest, path) {
   }
 }
 
+// src/lib/runtime/metadata/discovery-content.ts
+function discoveryOrigin(manifest, group) {
+  return (group ? manifest.groups[group]?.origin : void 0) ?? manifest.site.origin;
+}
+function pathWithin(path, basePath) {
+  return basePath === "/" || path === basePath || path.startsWith(`${basePath}/`);
+}
+function discoveryPages({
+  manifest,
+  group,
+  scope,
+  limit
+}) {
+  let origin = discoveryOrigin(manifest, group), basePath = group ? manifest.groups[group]?.path ?? "/" : "/", pages = manifest.pages.filter((page) => page.status !== "published" || discoveryOrigin(manifest, page.group) !== origin ? !1 : !group || scope === "site" ? !0 : pathWithin(page.path, basePath) ? page.group === group || scope !== "self" && page.group.startsWith(`${group}/`) : !1);
+  return limit ? pages.slice(0, limit) : pages;
+}
+function groupDiscoveryPages({
+  manifest,
+  pages
+}) {
+  let sections = /* @__PURE__ */ new Map();
+  for (let page of pages) {
+    let group = manifest.groups[page.group], key = group ? page.group : "", section = sections.get(key);
+    section || (section = {
+      ...group ? { group: page.group } : {},
+      title: group ? group.key === "__root" ? manifest.site.name : group.title : "Pages",
+      pages: []
+    }, sections.set(key, section)), section.pages.push(page);
+  }
+  return [...sections.values()].sort(
+    (a, b) => (manifest.groups[a.group ?? ""]?.path ?? "/").localeCompare(
+      manifest.groups[b.group ?? ""]?.path ?? "/"
+    ) || a.title.localeCompare(b.title)
+  );
+}
+
+// src/lib/runtime/metadata/llms-serialization.ts
+function inlineText(value) {
+  return value.replace(/[\r\n]+/g, " ").replace(/([\\`*_[\]<>])/g, "\\$1");
+}
+function markdownLink(link) {
+  let url = link.url.replace(
+    /[\s()<>]/g,
+    (value) => value === "(" ? "%28" : value === ")" ? "%29" : encodeURIComponent(value)
+  );
+  return `[${inlineText(link.title)}](${url})`;
+}
+function serializeLlmsIndex(input) {
+  let body = (input.sections ?? [
+    { title: "Pages", pages: input.pages ?? [] }
+  ]).map((section) => {
+    let lines = [
+      ...(section.links ?? []).map((link) => `- ${markdownLink(link)}`),
+      ...section.pages.map((page) => {
+        let description = input.includeDescriptions && page.description ? `: ${inlineText(page.description)}` : "", alternate = page.alternate ? ` (${markdownLink(page.alternate)})` : "";
+        return `- ${markdownLink(page)}${alternate}${description}`;
+      })
+    ];
+    return `## ${inlineText(section.title)}
+
+${lines.join(`
+`)}`;
+  }).join(`
+
+`), linkLines = (input.links ?? []).map(
+    (link) => `- ${markdownLink(link)}`
+  ), linkSection = linkLines.length ? `
+
+## Group LLM indexes
+
+${linkLines.join(`
+`)}` : "", otherGroupLines = (input.otherGroupLinks ?? []).map(
+    (link) => `- ${markdownLink(link)}`
+  ), otherGroupSection = otherGroupLines.length ? `
+
+## Other content groups
+
+${otherGroupLines.join(`
+`)}` : "";
+  return `# ${inlineText(input.title)}
+
+> ${inlineText(input.summary)}
+
+${body}${linkSection}${otherGroupSection}
+`;
+}
+function serializeLlmsFull(input) {
+  let encoder = new TextEncoder(), byteLength = (value) => encoder.encode(value).byteLength, references = [
+    input.indexUrl ? `> LLMS index: ${input.indexUrl}` : void 0,
+    input.sitemapUrl ? `> Sitemap: ${input.sitemapUrl}` : void 0
+  ].filter(Boolean).join(`
+`), header = `# ${input.title} Full Content
+
+${references ? `${references}
+
+` : ""}`, sections = [], totalBytes = byteLength(header), included = 0, truncated = !1;
+  for (let artifact of [...input.artifacts].sort(
+    (a, b) => a.markdownPath.localeCompare(b.markdownPath)
+  )) {
+    let section = `---
+
+${artifact.body.trim()}
+
+`, sectionBytes = byteLength(section);
+    if (totalBytes + sectionBytes > input.maxBytes) {
+      truncated = !0;
+      break;
+    }
+    sections.push(section), totalBytes += sectionBytes, included += 1;
+  }
+  let footer = truncated ? `
+> Truncated at ${included} of ${input.totalCount ?? input.artifacts.length} Markdown pages to stay under ${input.maxBytes} bytes.
+` : "";
+  return `${header}${sections.join("")}${footer}`;
+}
+
 // src/lib/runtime/response/cached-text-response.ts
 var CACHE_CONTROL = "public, max-age=300, s-maxage=3600, stale-while-revalidate=3600, must-revalidate", CDN_CACHE_CONTROL = "public, max-age=3600, stale-while-revalidate=3600, must-revalidate", SHORT_CACHE_CONTROL = "public, max-age=60, s-maxage=600, stale-while-revalidate=300, must-revalidate", SHORT_CDN_CACHE_CONTROL = "public, max-age=300, stale-while-revalidate=3600";
 function cacheControl(policy) {
@@ -34,48 +150,45 @@ function createCachedTextResponse(options) {
 }
 
 // src/route-metadata-llms.ts
-var DEFAULT_LLMS_FULL_MAX_BYTES = 1e6, TEXT_ENCODER = new TextEncoder();
-function byteLength(value) {
-  return TEXT_ENCODER.encode(value).byteLength;
-}
-function pageInScope(page, options) {
-  return options.scope === "site" || !options.group ? !0 : options.scope === "self" ? page.group === options.group : page.group === options.group || page.group.startsWith(`${options.group}/`);
-}
-function llmsSummary(manifest) {
-  return manifest.site.description ? `> ${manifest.site.description}` : `> Agent-readable index for ${manifest.site.name}.`;
-}
-async function llmsTxt(manifest, options = {}) {
+var DEFAULT_LLMS_FULL_MAX_BYTES = 1e6;
+async function llmsTxt(manifest, options = {}, artifactManifest) {
   "use cache";
   cacheLife("page"), cacheTag(
     tags.site(),
     tags.llms(options.group ?? options.scope ?? "root"),
     tags.manifest(manifest.contentHash)
   );
-  let pages = manifest.pages.filter((page) => page.status === "published").filter((page) => pageInScope(page, options)), lines = (options.limit ? pages.slice(0, options.limit) : pages).map((page) => {
-    let description = options.includeDescriptions && page.description ? ` - ${page.description}` : "";
-    return `- [${page.title}](${canonicalUrl(manifest, page.path)})${description}`;
-  }), linkLines = (options.links ?? []).map(
-    (link) => `- [${link.title}](${canonicalUrl(manifest, link.path)})`
-  ), linkSection = linkLines.length ? `
-
-## Group LLM indexes
-
-${linkLines.join(`
-`)}` : "";
-  return `# ${manifest.site.name}
-
-${llmsSummary(manifest)}
-
-## Pages
-
-${lines.join(`
-`)}${linkSection}
-`;
+  let pages = discoveryPages({ manifest, ...options }), group = options.group ? manifest.groups[options.group] : void 0;
+  return serializeLlmsIndex({
+    title: group?.title ?? manifest.site.name,
+    summary: manifest.site.description ? manifest.site.description : `Agent-readable index for ${manifest.site.name}.`,
+    sections: groupDiscoveryPages({ manifest, pages }).map((section) => ({
+      title: section.title,
+      pages: section.pages.map((page) => ({
+        title: page.title,
+        url: canonicalUrl(
+          manifest,
+          artifactManifest?.byHtmlPath[page.path] ?? page.path,
+          page.group
+        ),
+        description: page.description
+      }))
+    })),
+    includeDescriptions: options.includeDescriptions,
+    links: options.links?.map((link) => ({
+      title: link.title,
+      url: canonicalUrl(manifest, link.path, link.group)
+    })),
+    otherGroupLinks: options.otherGroupLinks?.map((link) => ({
+      title: link.title,
+      url: canonicalUrl(manifest, link.path, link.group)
+    }))
+  });
 }
-function createLlmsTxtRoute(manifest, options = {}) {
+function createLlmsTxtRoute(manifest, options = {}, artifactManifest) {
   return async function() {
     return createCachedTextResponse({
-      body: await llmsTxt(manifest, options),
+      body: await llmsTxt(manifest, options, artifactManifest),
       contentType: "text/plain; charset=utf-8"
     });
   };
@@ -89,30 +202,14 @@ function createPrecomputedLlmsTxtRoute(output) {
   };
 }
 async function llmsFullTxt(manifest, artifacts, options = {}) {
-  let maxBytes = options.maxBytes ?? DEFAULT_LLMS_FULL_MAX_BYTES, header = `# ${manifest.site.name} Full Content
-
-> LLMS index: ${canonicalUrl(manifest, "/llms.txt")}
-> Sitemap: ${canonicalUrl(manifest, "/sitemap.md")}
-
-`, sections = [], totalBytes = byteLength(header), included = 0, truncated = !1;
-  for (let artifact of Object.values(artifacts).sort(
-    (a, b) => a.markdownPath.localeCompare(b.markdownPath)
-  )) {
-    let section = `---
-
-${artifact.body.trim()}
-
-`, sectionBytes = byteLength(section);
-    if (totalBytes + sectionBytes > maxBytes) {
-      truncated = !0;
-      break;
-    }
-    sections.push(section), totalBytes += sectionBytes, included += 1;
-  }
-  let footer = truncated ? `
-> Truncated at ${included} of ${Object.keys(artifacts).length} Markdown pages to stay under ${maxBytes} bytes.
-` : "";
-  return `${header}${sections.join("")}${footer}`;
+  return serializeLlmsFull({
+    title: manifest.site.name,
+    indexUrl: options.indexPath === !1 ? void 0 : canonicalUrl(manifest, options.indexPath ?? "/llms.txt"),
+    sitemapUrl: options.sitemapPath === !1 ? void 0 : canonicalUrl(manifest, options.sitemapPath ?? "/sitemap.md"),
+    // Route factories serialize their supplied artifacts; generated output filters by origin.
+    artifacts: Object.values(artifacts),
+    maxBytes: options.maxBytes ?? DEFAULT_LLMS_FULL_MAX_BYTES
+  });
 }
 async function llmsFullTxtResponse(manifest, artifacts, options = {}) {
   return createCachedTextResponse({

package/dist/kernel/routes/metadata/og-image.js

@@ -116,7 +116,7 @@ function getOgImageText(entry) {
 }
 
 // src/route-metadata-og-image.tsx
-import { jsx, jsxs } from "react/jsx-runtime";
+import { jsx, jsxs } from "@publish.os/nextjs/jsx-runtime";
 var ERROR_HEADERS = {
   "cache-control": "public, max-age=60, must-revalidate",
   "cdn-cache-control": "public, max-age=300",

package/dist/kernel/routes/metadata/robots.d.ts

@@ -1,4 +1,4 @@
-import { M as ManifestLike } from '../../../types-CIwwieNw.js';
+import { M as ManifestLike } from '../../../types-J2w_puPF.js';
 
 declare function createRobotsTxtRoute(manifest: ManifestLike): () => Promise<Response>;
 

package/dist/kernel/routes/metadata/robots.js

@@ -3,8 +3,8 @@ import { tags } from "@publish.os/nextjs/cache/tags";
 import { cacheLife, cacheTag } from "next/cache";
 
 // src/lib/runtime/metadata/canonical-url.ts
-function canonicalUrl(manifest, path) {
-  let origin = manifest.site.url?.replace(/\/+$/, "");
+function canonicalUrl(manifest, path, group) {
+  let origin = (group && manifest.groups[group]?.origin) ?? manifest.site.origin;
   if (!origin) return path;
   try {
     return new URL(path, `${origin}/`).toString();

package/dist/kernel/routes/metadata/sitemap.d.ts

@@ -1,7 +1,29 @@
 import { MarkdownRouteArtifactManifest } from '../agent/markdown.js';
-import { M as ManifestLike } from '../../../types-CIwwieNw.js';
+import { M as ManifestLike } from '../../../types-J2w_puPF.js';
+import '../not-found.js';
 
-declare function createSitemapXmlRoute(manifest: ManifestLike): () => Promise<Response>;
-declare function createSitemapMarkdownRoute(manifest: ManifestLike, artifactManifest: MarkdownRouteArtifactManifest): () => Promise<Response>;
+type SitemapReference = {
+    path: string;
+    group?: string;
+};
+type SitemapRouteOptions = {
+    group?: string;
+    path?: string;
+    sitemaps?: SitemapReference[];
+    exclude?: SitemapReference[];
+};
+type SitemapMarkdownRouteOptions = {
+    group?: string;
+    scope?: "site" | "group" | "self";
+    links?: Array<SitemapReference & {
+        title: string;
+    }>;
+    otherGroupLinks?: Array<SitemapReference & {
+        title: string;
+    }>;
+    markdownAlternates?: boolean;
+};
+declare function createSitemapXmlRoute(manifest: ManifestLike, options?: SitemapRouteOptions): () => Promise<Response>;
+declare function createSitemapMarkdownRoute(manifest: ManifestLike, artifactManifest: MarkdownRouteArtifactManifest, options?: SitemapMarkdownRouteOptions): () => Promise<Response>;
 
-export { createSitemapMarkdownRoute, createSitemapXmlRoute };
+export { type SitemapMarkdownRouteOptions, type SitemapRouteOptions, createSitemapMarkdownRoute, createSitemapXmlRoute };

package/dist/kernel/routes/metadata/sitemap.js

@@ -3,8 +3,8 @@ import { tags } from "@publish.os/nextjs/cache/tags";
 import { cacheLife, cacheTag } from "next/cache";
 
 // src/lib/runtime/metadata/canonical-url.ts
-function canonicalUrl(manifest, path) {
-  let origin = manifest.site.url?.replace(/\/+$/, "");
+function canonicalUrl(manifest, path, group) {
+  let origin = (group && manifest.groups[group]?.origin) ?? manifest.site.origin;
   if (!origin) return path;
   try {
     return new URL(path, `${origin}/`).toString();
@@ -13,6 +13,93 @@ function canonicalUrl(manifest, path) {
   }
 }
 
+// src/lib/runtime/metadata/discovery-content.ts
+function discoveryOrigin(manifest, group) {
+  return (group ? manifest.groups[group]?.origin : void 0) ?? manifest.site.origin;
+}
+function pathWithin(path, basePath) {
+  return basePath === "/" || path === basePath || path.startsWith(`${basePath}/`);
+}
+function discoveryPages({
+  manifest,
+  group,
+  scope,
+  limit
+}) {
+  let origin = discoveryOrigin(manifest, group), basePath = group ? manifest.groups[group]?.path ?? "/" : "/", pages = manifest.pages.filter((page) => page.status !== "published" || discoveryOrigin(manifest, page.group) !== origin ? !1 : !group || scope === "site" ? !0 : pathWithin(page.path, basePath) ? page.group === group || scope !== "self" && page.group.startsWith(`${group}/`) : !1);
+  return limit ? pages.slice(0, limit) : pages;
+}
+function groupDiscoveryPages({
+  manifest,
+  pages
+}) {
+  let sections = /* @__PURE__ */ new Map();
+  for (let page of pages) {
+    let group = manifest.groups[page.group], key = group ? page.group : "", section = sections.get(key);
+    section || (section = {
+      ...group ? { group: page.group } : {},
+      title: group ? group.key === "__root" ? manifest.site.name : group.title : "Pages",
+      pages: []
+    }, sections.set(key, section)), section.pages.push(page);
+  }
+  return [...sections.values()].sort(
+    (a, b) => (manifest.groups[a.group ?? ""]?.path ?? "/").localeCompare(
+      manifest.groups[b.group ?? ""]?.path ?? "/"
+    ) || a.title.localeCompare(b.title)
+  );
+}
+
+// src/lib/runtime/metadata/llms-serialization.ts
+function inlineText(value) {
+  return value.replace(/[\r\n]+/g, " ").replace(/([\\`*_[\]<>])/g, "\\$1");
+}
+function markdownLink(link) {
+  let url = link.url.replace(
+    /[\s()<>]/g,
+    (value) => value === "(" ? "%28" : value === ")" ? "%29" : encodeURIComponent(value)
+  );
+  return `[${inlineText(link.title)}](${url})`;
+}
+function serializeLlmsIndex(input) {
+  let body = (input.sections ?? [
+    { title: "Pages", pages: input.pages ?? [] }
+  ]).map((section) => {
+    let lines = [
+      ...(section.links ?? []).map((link) => `- ${markdownLink(link)}`),
+      ...section.pages.map((page) => {
+        let description = input.includeDescriptions && page.description ? `: ${inlineText(page.description)}` : "", alternate = page.alternate ? ` (${markdownLink(page.alternate)})` : "";
+        return `- ${markdownLink(page)}${alternate}${description}`;
+      })
+    ];
+    return `## ${inlineText(section.title)}
+
+${lines.join(`
+`)}`;
+  }).join(`
+
+`), linkLines = (input.links ?? []).map(
+    (link) => `- ${markdownLink(link)}`
+  ), linkSection = linkLines.length ? `
+
+## Group LLM indexes
+
+${linkLines.join(`
+`)}` : "", otherGroupLines = (input.otherGroupLinks ?? []).map(
+    (link) => `- ${markdownLink(link)}`
+  ), otherGroupSection = otherGroupLines.length ? `
+
+## Other content groups
+
+${otherGroupLines.join(`
+`)}` : "";
+  return `# ${inlineText(input.title)}
+
+> ${inlineText(input.summary)}
+
+${body}${linkSection}${otherGroupSection}
+`;
+}
+
 // src/lib/runtime/response/cached-text-response.ts
 var CACHE_CONTROL = "public, max-age=300, s-maxage=3600, stale-while-revalidate=3600, must-revalidate", CDN_CACHE_CONTROL = "public, max-age=3600, stale-while-revalidate=3600, must-revalidate", SHORT_CACHE_CONTROL = "public, max-age=60, s-maxage=600, stale-while-revalidate=300, must-revalidate", SHORT_CDN_CACHE_CONTROL = "public, max-age=300, stale-while-revalidate=3600";
 function cacheControl(policy) {
@@ -34,62 +121,143 @@ function createCachedTextResponse(options) {
 }
 
 // src/route-metadata-sitemap.ts
+var ROOT_CONTENT_GROUP_KEY = "__root";
 function xmlEscape(value) {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/'/g, "&apos;").replace(/"/g, "&quot;");
+}
+function sitemapDirectory(path) {
+  return path.slice(0, path.lastIndexOf("/") + 1) || "/";
 }
-async function sitemapXml(manifest) {
+function rootMountedGroup(manifest, origin) {
+  return Object.values(manifest.groups).find(
+    (group) => group.key !== ROOT_CONTENT_GROUP_KEY && group.path === "/" && discoveryOrigin(manifest, group.key) === origin
+  );
+}
+async function sitemapXml(manifest, options) {
   "use cache";
   cacheLife("page"), cacheTag(tags.site(), tags.sitemap(), tags.manifest(manifest.contentHash));
-  let urls = [
-    "/",
-    ...Object.values(manifest.groups).map((g) => g.path),
-    ...manifest.pages.filter((page) => page.status === "published").map((page) => page.path)
-  ];
+  let targetGroup = options.group ? manifest.groups[options.group] : void 0, directory = sitemapDirectory(
+    options.path ?? `${targetGroup?.path === "/" ? "" : targetGroup?.path ?? ""}/sitemap.xml`
+  ), origin = targetGroup ? discoveryOrigin(manifest, targetGroup.key) : manifest.site.origin;
+  if (options.sitemaps)
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${[
+      ...new Set(
+        options.sitemaps.filter(
+          (sitemap) => discoveryOrigin(manifest, sitemap.group) === origin
+        ).filter(
+          (sitemap) => sitemap.path.startsWith(directory) && sitemap.path !== options.path
+        ).map(
+          (sitemap) => canonicalUrl(manifest, sitemap.path, sitemap.group)
+        )
+      )
+    ].map((url) => `  <sitemap><loc>${xmlEscape(url)}</loc></sitemap>`).join(`
+`)}
+</sitemapindex>
+`;
+  let homeGroup = targetGroup ?? rootMountedGroup(manifest, origin), groups = Object.values(manifest.groups).filter(
+    (group) => discoveryOrigin(manifest, group.key) === origin && (directory === "/" || group.path.startsWith(directory))
+  ), urls = [
+    {
+      path: homeGroup?.path ?? "/",
+      group: homeGroup?.key
+    },
+    ...groups.map((group) => ({ path: group.path, group: group.key })),
+    ...manifest.pages.filter((page) => page.status === "published").filter((page) => discoveryOrigin(manifest, page.group) === origin).map((page) => ({ path: page.path, group: page.group }))
+  ].filter(
+    ({ path }) => (directory === "/" || path.startsWith(directory)) && !(options.exclude ?? []).some(
+      (sitemap) => discoveryOrigin(manifest, sitemap.group) === origin && path.startsWith(sitemapDirectory(sitemap.path))
+    )
+  );
   return `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-${[...new Set(urls)].map(
-    (url) => `  <url><loc>${xmlEscape(canonicalUrl(manifest, url))}</loc></url>`
-  ).join(`
+${[...new Map(
+    urls.map(({ path, group }) => {
+      let url = canonicalUrl(manifest, path, group);
+      return [url, url];
+    })
+  ).values()].map((url) => `  <url><loc>${xmlEscape(url)}</loc></url>`).join(`
 `)}
 </urlset>
 `;
 }
-function createSitemapXmlRoute(manifest) {
+function createSitemapXmlRoute(manifest, options = {}) {
   return async function() {
     return createCachedTextResponse({
-      body: await sitemapXml(manifest),
+      body: await sitemapXml(manifest, options),
       contentType: "application/xml; charset=utf-8"
     });
   };
 }
-async function sitemapMarkdown(manifest, artifactManifest) {
-  let groups = Object.values(manifest.groups).sort((a, b) => a.path.localeCompare(b.path)).map(
-    (group) => `- [${group.title}](${canonicalUrl(manifest, group.path)})`
-  ), pages = manifest.pages.filter((page) => page.status === "published").sort((a, b) => a.path.localeCompare(b.path)).map((page) => {
-    let markdownPath = artifactManifest.byHtmlPath[page.path], markdown = markdownPath ? ` ([Markdown](${canonicalUrl(manifest, markdownPath)}))` : "";
-    return `- [${page.title}](${canonicalUrl(manifest, page.path)})${markdown}`;
+async function sitemapMarkdown(manifest, artifactManifest, options) {
+  let origin = discoveryOrigin(manifest, options.group), targetGroup = options.group ? manifest.groups[options.group] : void 0, rootGroup = targetGroup?.key === ROOT_CONTENT_GROUP_KEY ? void 0 : targetGroup ?? rootMountedGroup(manifest, origin), groups = Object.values(manifest.groups).filter((group) => group.key !== ROOT_CONTENT_GROUP_KEY).filter((group) => discoveryOrigin(manifest, group.key) === origin).filter(
+    (group) => !targetGroup || options.scope === "site" || pathWithin(group.path, targetGroup.path) && (group.key === targetGroup.key || options.scope !== "self" && group.key.startsWith(`${targetGroup.key}/`))
+  ), pages = discoveryPages({ manifest, ...options }).sort(
+    (a, b) => a.path.localeCompare(b.path)
+  ), sections = groupDiscoveryPages({ manifest, pages });
+  for (let group of groups)
+    sections.some((section) => section.group === group.key) || sections.push({ group: group.key, title: group.title, pages: [] });
+  sections.sort(
+    (a, b) => (manifest.groups[a.group ?? ""]?.path ?? "/").localeCompare(
+      manifest.groups[b.group ?? ""]?.path ?? "/"
+    )
+  );
+  let links = options.links ?? [
+    { title: "LLMS index", path: "/llms.txt" },
+    { title: "Full LLMS index", path: "/llms-full.txt" },
+    { title: "XML sitemap", path: "/sitemap.xml" }
+  ];
+  return serializeLlmsIndex({
+    title: `${rootGroup?.title ?? manifest.site.name} Sitemap`,
+    summary: "Browse the published pages and their available Markdown versions.",
+    sections: [
+      ...links.length ? [
+        {
+          title: "Agent indexes",
+          pages: [],
+          links: links.map((link) => ({
+            title: link.title,
+            url: canonicalUrl(manifest, link.path, link.group)
+          }))
+        }
+      ] : [],
+      ...sections.map((section) => {
+        let group = manifest.groups[section.group ?? ""];
+        return {
+          title: section.title,
+          links: group && group.key !== ROOT_CONTENT_GROUP_KEY ? [
+            {
+              title: group.title,
+              url: canonicalUrl(manifest, group.path, group.key)
+            }
+          ] : [],
+          pages: section.pages.map((page) => {
+            let markdownPath = options.markdownAlternates === !1 ? void 0 : artifactManifest.byHtmlPath[page.path];
+            return {
+              title: page.title,
+              url: canonicalUrl(manifest, page.path, page.group),
+              ...markdownPath ? {
+                alternate: {
+                  title: "Markdown",
+                  url: canonicalUrl(manifest, markdownPath, page.group)
+                }
+              } : {}
+            };
+          })
+        };
+      })
+    ],
+    otherGroupLinks: options.otherGroupLinks?.map((link) => ({
+      title: link.title,
+      url: canonicalUrl(manifest, link.path, link.group)
+    }))
   });
-  return [
-    `# ${manifest.site.name} Sitemap`,
-    "## Agent indexes",
-    `- [LLMS index](${canonicalUrl(manifest, "/llms.txt")})`,
-    `- [Full LLMS index](${canonicalUrl(manifest, "/llms-full.txt")})`,
-    `- [XML sitemap](${canonicalUrl(manifest, "/sitemap.xml")})`,
-    "## Sections",
-    groups.length ? groups.join(`
-`) : `- [Home](${canonicalUrl(manifest, "/")})`,
-    "## Pages",
-    pages.length ? pages.join(`
-`) : `- [Home](${canonicalUrl(manifest, "/")})`,
-    ""
-  ].join(`
-
-`);
 }
-function createSitemapMarkdownRoute(manifest, artifactManifest) {
+function createSitemapMarkdownRoute(manifest, artifactManifest, options = {}) {
   return async function() {
     return createCachedTextResponse({
-      body: await sitemapMarkdown(manifest, artifactManifest),
+      body: await sitemapMarkdown(manifest, artifactManifest, options),
       contentType: "text/markdown; charset=utf-8"
     });
   };

package/dist/kernel/routes/not-found.d.ts

@@ -0,0 +1,34 @@
+type NotFoundLink = {
+    title: string;
+    href: string;
+    description?: string;
+    kind?: "sitemap" | "sitemap-md" | "llms" | "llms-full";
+};
+type NotFoundScope = {
+    id: string;
+    path: string;
+    group?: string;
+    origin?: string;
+    describedBy?: string;
+    htmlPath: string;
+    recommendations: readonly NotFoundLink[];
+    indexes: readonly NotFoundLink[];
+    markdown: string;
+};
+declare function resolveNotFoundScope({ scopes, pathname, }: {
+    scopes: readonly NotFoundScope[];
+    pathname: string;
+}): NotFoundScope | undefined;
+declare function serializeNotFoundMarkdown({ recommendations, indexes, }: {
+    recommendations: readonly NotFoundLink[];
+    indexes: readonly NotFoundLink[];
+}): string;
+declare function createNotFoundTextResponse({ scope, pathname, method, contentType, vary, }: {
+    scope?: NotFoundScope;
+    pathname?: string;
+    method: string;
+    contentType?: "text/markdown; charset=utf-8" | "text/plain; charset=utf-8";
+    vary?: boolean;
+}): Response;
+
+export { type NotFoundLink, type NotFoundScope, createNotFoundTextResponse, resolveNotFoundScope, serializeNotFoundMarkdown };