@lupinum/ginko-content 0.1.5 → 0.2.0

package/dist/runtime/server/agent-markdown.js

@@ -1,324 +1,49 @@
-import { kebabCase, pascalCase } from "scule";
-import { agentMarkdownPathForRoute, agentRawPathForRoute, normalizeAgentRoutePath } from "../agent-paths.js";
-import { getCollectionPath } from "../query/routes.js";
+import {
+  createAgentMarkdownRegistry,
+  resolveAgentMarkdownOptions
+} from "../../features/agent/agent-markdown";
+import { renderAgentMarkdownBody } from "../../features/agent/walker";
+import { agentMarkdownPathForRoute, agentRawPathForRoute, normalizeAgentRoutePath } from "../../features/agent/agent-paths";
+import { getCollectionPath } from "../../features/query/routes";
 import { getContentProvider } from "./providers/index.js";
+import { createProviderQuery } from "./provider-query.js";
 import { contentConfig } from "./storage-access.js";
-const serializers = /* @__PURE__ */ new Map();
-const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+export * from "../../features/agent/agent-markdown";
+export { renderAgentMarkdownBody } from "../../features/agent/walker";
+const appRegistry = createAgentMarkdownRegistry();
+export const getAgentMarkdownRegistry = () => appRegistry;
+export const registerAgentMarkdownSerializer = (name, serializer, options) => appRegistry.register(name, serializer, options);
+export const registerAgentMarkdownSerializers = (entries, options) => appRegistry.registerMany(entries, options);
+export const registerAgentMarkdownComponent = (name, component, options) => appRegistry.registerComponent(name, component, options);
+export const registerAgentMarkdownComponents = (entries, options) => appRegistry.registerComponents(entries, options);
+export const clearAgentMarkdownSerializers = () => appRegistry.clear();
 const defaultLocale = () => contentConfig().defaultLocale || contentConfig().locales?.[0] || contentConfig().agent?.site?.defaultLocale || "en";
 const configuredLocales = () => {
   const locales = contentConfig().agent?.site?.locales?.length ? contentConfig().agent?.site?.locales : contentConfig().locales;
   return locales?.length ? locales : [defaultLocale()];
 };
-const prefixLocalizedHref = (path, locale) => {
-  const normalized = normalizeAgentRoutePath(path);
-  if (!locale || locale === defaultLocale()) return normalized;
-  if (configuredLocales().some((candidate) => normalized === `/${candidate}` || normalized.startsWith(`/${candidate}/`))) return normalized;
-  return normalized === "/" ? `/${locale}` : `/${locale}${normalized}`;
-};
-const isExternalHref = (href) => /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("//");
-const routeMarkdownPathForHref = (href, locale, currentPath = "/") => {
-  const hash = href.match(/#.*$/)?.[0] || "";
-  const withoutHash = href.replace(/#.*$/, "");
-  if (!withoutHash) return href;
-  if (isExternalHref(withoutHash)) return href;
-  if (withoutHash.endsWith(".md")) return href;
-  const target = withoutHash.startsWith("/") ? prefixLocalizedHref(withoutHash, locale) : new URL(withoutHash, `https://agent.local${normalizeAgentRoutePath(currentPath)}`).pathname;
-  return `${agentRawPathForRoute(target)}${hash}`;
-};
-export const getMarkdownProp = (node, name) => {
-  const props = isRecord(node.props) ? node.props : {};
-  const value = props[name];
-  return typeof value === "string" ? value : "";
-};
-export const renderMarkdownChildren = (node, ctx) => ctx.renderChildren(node);
-export const blockquoteMarkdown = (value) => value.trim().split("\n").map((line) => line ? `> ${line}` : ">").join("\n");
-const escapeMarkdownLinkLabel = (value) => value.replace(/\\/g, "\\\\").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
-const escapeMarkdownLinkHref = (value) => value.replace(/\)/g, "%29").replace(/\s/g, "%20");
-const isSafeMarkdownHref = (href) => {
-  if (!href) return false;
-  if (href.startsWith("//")) return false;
-  if (href.startsWith("/") || href.startsWith("#") || href.startsWith("./") || href.startsWith("../")) return true;
-  return /^(https?:|mailto:|tel:)/i.test(href);
-};
-export const linkMarkdown = (label, href) => {
-  const resolvedLabel = label || href;
-  if (!href || !isSafeMarkdownHref(href)) return escapeMarkdownLinkLabel(resolvedLabel);
-  return `[${escapeMarkdownLinkLabel(resolvedLabel)}](${escapeMarkdownLinkHref(href)})`;
-};
-export const imageMarkdown = (alt, src) => {
-  if (!src || !isSafeMarkdownHref(src)) return escapeMarkdownLinkLabel(alt || src);
-  return `![${escapeMarkdownLinkLabel(alt)}](${escapeMarkdownLinkHref(src)})`;
-};
-export const jsonFenceMarkdown = (value) => `\`\`\`json
-${JSON.stringify(value, null, 2)}
-\`\`\``;
-const xmlNamePattern = /^[a-z][\w.:-]*$/i;
-const safeXmlName = (name) => xmlNamePattern.test(name) ? name : "component";
-const escapeXmlAttribute = (value) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-const isScalarXmlAttributeValue = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
-const shouldDropAgentProp = (name) => {
-  const normalized = name.trim();
-  const sensitive = normalized.toLowerCase();
-  return !normalized || normalized === "class" || normalized === "style" || normalized === "key" || normalized === "ref" || normalized.startsWith("v-") || normalized.startsWith("@") || normalized.startsWith("on") || normalized.startsWith("data-") || normalized.startsWith("aria-") || /token|secret|password|passwd|credential|authorization|apikey|api-key|clientsecret|client-secret|privatekey|private-key|accesskey|access-key/i.test(sensitive);
-};
-const normalizeAgentPropName = (name) => {
-  const normalized = name.trim();
-  if (normalized.startsWith(":")) return normalized.slice(1);
-  if (normalized.startsWith("v-bind:")) return normalized.slice("v-bind:".length);
-  return normalized;
-};
-const cleanAgentPropValue = (value) => {
-  if (value === void 0 || value === null || value === "") return void 0;
-  if (Array.isArray(value)) {
-    const clean = value.map((entry) => cleanAgentPropValue(entry)).filter((entry) => entry !== void 0);
-    return clean.length ? clean : void 0;
-  }
-  if (isRecord(value)) {
-    const clean = cleanPropsObject(value);
-    return Object.keys(clean).length ? clean : void 0;
-  }
-  return value;
-};
-const cleanPropsObject = (props) => {
-  if (!isRecord(props)) return {};
-  const clean = {};
-  for (const [name, value] of Object.entries(props)) {
-    const normalizedName = normalizeAgentPropName(name);
-    const cleanedValue = cleanAgentPropValue(value);
-    if (shouldDropAgentProp(normalizedName) || cleanedValue === void 0) continue;
-    if (!(normalizedName in clean) || normalizedName === name.trim()) {
-      clean[normalizedName] = cleanedValue;
-    }
-  }
-  return clean;
-};
-export const xmlComponentMarkdown = (name, props = {}, children = "") => {
-  const tagName = safeXmlName(name);
-  const cleanProps = cleanPropsObject(props);
-  const attrs = [];
-  const complexProps = {};
-  for (const [key, value] of Object.entries(cleanProps)) {
-    if (!xmlNamePattern.test(key)) {
-      complexProps[key] = value;
-      continue;
-    }
-    if (isScalarXmlAttributeValue(value)) {
-      attrs.push(`${key}="${escapeXmlAttribute(String(value))}"`);
-      continue;
-    }
-    complexProps[key] = value;
-  }
-  const attrText = attrs.length ? ` ${attrs.join(" ")}` : "";
-  const bodyParts = [
-    Object.keys(complexProps).length ? jsonFenceMarkdown(complexProps) : "",
-    children.trim()
-  ].filter(Boolean);
-  if (!bodyParts.length) return `<${tagName}${attrText} />`;
-  return `<${tagName}${attrText}>
-${bodyParts.join("\n\n")}
-</${tagName}>`;
-};
-export const registerAgentMarkdownSerializer = (name, serializer, options = {}) => {
-  const existing = serializers.get(name);
-  if (existing === serializer && !options.override) return;
-  if (existing && !options.override) {
-    throw new Error(
-      `Agent Markdown serializer "${name}" is already registered. Use { override: true } only when replacing an existing serializer intentionally.`
-    );
-  }
-  serializers.set(name, serializer);
-};
-export const registerAgentMarkdownSerializers = (entries, options = {}) => {
-  for (const [name, serializer] of Object.entries(entries)) {
-    registerAgentMarkdownSerializer(name, serializer, options);
-  }
-};
-export const defineAgentMarkdownComponent = (component) => component;
-export const registerAgentMarkdownComponent = (name, component, options = {}) => {
-  registerAgentMarkdownSerializer(name, component.render, options);
-};
-export const registerAgentMarkdownComponents = (entries, options = {}) => {
-  for (const [name, component] of Object.entries(entries)) {
-    registerAgentMarkdownComponent(name, component, options);
-  }
-};
-export const clearAgentMarkdownSerializers = () => {
-  serializers.clear();
-};
-export const resolveAgentMarkdownOptions = (collection) => {
-  if (!collection || collection.type === "data") return null;
-  const value = collection.agent?.markdown;
-  if (value === true) {
-    return {
-      includeInIndex: true,
-      includeInFull: true,
-      metadata: []
-    };
-  }
-  if (!value || !isRecord(value)) return null;
-  return {
-    includeInIndex: value.includeInIndex !== false,
-    includeInFull: value.includeInFull !== false,
-    metadata: Array.isArray(value.metadata) ? value.metadata.filter((field) => typeof field === "string" && field.length > 0) : []
-  };
-};
+const buildRenderContext = (collection, page, path, locale) => ({
+  collection,
+  page,
+  path,
+  locale,
+  registry: appRegistry,
+  tagAliases: contentConfig().markdown?.tags || {},
+  defaultLocale: defaultLocale(),
+  locales: configuredLocales()
+});
 const collectionConfig = (collection) => contentConfig().collections?.[collection];
 const markdownEnabledCollectionEntries = (collections) => Object.entries(contentConfig().collections || {}).filter(([name, config]) => (!collections?.length || collections.includes(name)) && resolveAgentMarkdownOptions(config));
 const isPublicPage = (page, config) => Boolean(
-  page && config && config.type !== "data" && config.sitemap !== false && !page._draft && !page._partial && !page._navigation && page.navigation !== false && page.robots !== "noindex" && page.sitemap !== false
+  page && config && config.type !== "data" && config.sitemap !== false && !page.draft && !page.partial && !page.navigationFile && page.navigation !== false && page.robots !== "noindex" && page.sitemap !== false
 );
 const escapeMarkdownText = (value) => value.replace(/\*/g, "\\*").replace(/_/g, "\\_").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
-const textValue = (node) => {
-  if (node.type === "text") return node.value || "";
-  return (node.children || []).map((child) => textValue(child)).join("");
-};
-const renderChildren = (node, ctx) => (node.children || []).map((child) => renderNode(child, ctx)).join("").trim();
-const block = (value) => value.trim() ? `${value.trim()}
-
-` : "";
-const renderList = (node, ctx, ordered = false) => block((node.children || []).map((child, index) => {
-  const body = renderChildren(child, ctx).replace(/\n+/g, "\n  ").trim();
-  return `${ordered ? `${index + 1}.` : "-"} ${body}`;
-}).join("\n"));
-const renderTable = (node, ctx) => {
-  const rows = (node.children || []).flatMap(
-    (section) => section.tag === "thead" || section.tag === "tbody" ? section.children || [] : [section]
-  ).filter((row) => row.tag === "tr");
-  if (!rows.length) return "";
-  const cells = rows.map(
-    (row) => (row.children || []).filter((cell) => cell.tag === "th" || cell.tag === "td").map((cell) => renderChildren(cell, ctx).replace(/\|/g, "\\|").trim())
-  );
-  const width = Math.max(...cells.map((row) => row.length));
-  const normalized = cells.map((row) => [...row, ...Array.from({ length: width - row.length }, () => "")]);
-  const [head = [], ...bodyRows] = normalized;
-  return block([
-    `| ${head.join(" | ")} |`,
-    `| ${head.map(() => "---").join(" | ")} |`,
-    ...bodyRows.map((row) => `| ${row.join(" | ")} |`)
-  ].join("\n"));
-};
-const renderUnknownComponentOmission = (name, reason) => `> Component omitted: \`${name}\`.
-> ${reason || "This page contains an interactive or site-specific block that has no agent markdown serializer yet."}`;
-const renderUnknownComponent = (node, ctx) => {
-  const tag = node.tag || "component";
-  const props = cleanPropsObject(node.props);
-  const children = renderChildren(node, ctx);
-  if (children || Object.keys(props).length) {
-    return block(xmlComponentMarkdown(tag, props, children));
-  }
-  return block(renderUnknownComponentOmission(tag));
-};
-const serializerForTag = (tag) => {
-  const markdownTags = contentConfig().markdown?.tags || {};
-  const candidates = new Set([
-    tag,
-    pascalCase(tag),
-    kebabCase(tag),
-    markdownTags[tag],
-    markdownTags[pascalCase(tag)],
-    markdownTags[kebabCase(tag)]
-  ].filter((value) => Boolean(value)));
-  for (const candidate of candidates) {
-    const serializer = serializers.get(candidate);
-    if (serializer) return serializer;
-  }
-};
-const renderNode = (node, ctx) => {
-  if (node.type === "text") return node.value || "";
-  const tag = node.tag || "";
-  const serializer = tag ? serializerForTag(tag) : void 0;
-  if (serializer) {
-    const nodeCtx = {
-      ...ctx,
-      prop: (name) => getMarkdownProp(node, name),
-      props: (target) => isRecord((target || node).props) ? (target || node).props : {},
-      cleanProps: (target) => cleanPropsObject((target || node).props),
-      children: (target) => renderChildren(target || node, nodeCtx)
-    };
-    const rendered = serializer(node, nodeCtx);
-    if (typeof rendered === "string") return block(rendered);
-  }
-  if (!tag) return renderChildren(node, ctx);
-  if (/^h[1-6]$/.test(tag)) {
-    const depth = Number(tag.slice(1));
-    return block(`${"#".repeat(Math.max(1, Math.min(6, depth)))} ${renderChildren(node, ctx)}`);
-  }
-  switch (tag) {
-    case "p":
-      return block(renderChildren(node, ctx));
-    case "blockquote":
-      return block(renderChildren(node, ctx).split("\n").map((line) => `> ${line}`).join("\n"));
-    case "strong":
-    case "b":
-      return `**${renderChildren(node, ctx)}**`;
-    case "em":
-    case "i":
-      return `_${renderChildren(node, ctx)}_`;
-    case "span":
-      return renderChildren(node, ctx);
-    case "code":
-      return `\`${node.value || textValue(node)}\``;
-    case "pre":
-      return block(`\`\`\`
-${textValue(node)}
-\`\`\``);
-    case "a": {
-      const href = typeof node.props?.href === "string" ? node.props.href : "";
-      const text = renderChildren(node, ctx) || href;
-      return href ? linkMarkdown(text, routeMarkdownPathForHref(href, ctx.locale, ctx.path)) : text;
-    }
-    case "ul":
-      return renderList(node, ctx);
-    case "ol":
-      return renderList(node, ctx, true);
-    case "li":
-      return renderChildren(node, ctx);
-    case "hr":
-      return "---\n\n";
-    case "br":
-      return "\n";
-    case "img": {
-      const src = typeof node.props?.src === "string" ? node.props.src : "";
-      const alt = typeof node.props?.alt === "string" ? node.props.alt : "";
-      return src ? imageMarkdown(alt, src) : escapeMarkdownLinkLabel(alt);
-    }
-    case "table":
-      return renderTable(node, ctx);
-    case "thead":
-    case "tbody":
-    case "tr":
-    case "th":
-    case "td":
-      return renderChildren(node, ctx);
-    default:
-      return renderUnknownComponent(node, ctx);
-  }
-};
-const renderMarkdownRoot = (body, context) => {
-  if (!body?.children?.length) return "";
-  const ctx = {
-    ...context,
-    prop: () => "",
-    props: (node) => node ? isRecord(node.props) ? node.props : {} : {},
-    cleanProps: (node) => cleanPropsObject(node?.props),
-    children: (node) => node ? renderChildren(node, ctx) : "",
-    renderChildren: (node) => renderChildren(node, ctx),
-    renderNode: (node) => renderNode(node, ctx),
-    blockquote: (value) => blockquoteMarkdown(value),
-    jsonFence: (value) => jsonFenceMarkdown(value),
-    link: (label, href) => linkMarkdown(label, href),
-    omitted: (name, reason) => renderUnknownComponentOmission(name, reason),
-    xmlComponent: (name, props, children) => xmlComponentMarkdown(name, props, children)
-  };
-  return body.children.map((node) => renderNode(node, ctx)).join("").trim();
-};
 const hasH1 = (markdown) => /^#\s+/m.test(markdown);
 const normalizeDescription = (page) => typeof page.description === "string" && page.description.trim() ? page.description.trim() : "";
 const renderAgentMarkdown = (page, collection, path, locale, _options) => {
   const title = typeof page.title === "string" && page.title.trim() ? page.title.trim() : path.split("/").filter(Boolean).pop() || "Index";
   const description = normalizeDescription(page);
-  const rendered = renderMarkdownRoot(page.body, { collection, page, path, locale });
+  const rendered = renderAgentMarkdownBody(page.body, buildRenderContext(collection, page, path, locale));
   const parts = [];
   if (!hasH1(rendered)) parts.push(`# ${escapeMarkdownText(title)}`);
   if (description && !rendered.includes(description)) parts.push(`> ${description}`);
@@ -326,8 +51,8 @@ const renderAgentMarkdown = (page, collection, path, locale, _options) => {
   return parts.join("\n\n").trim() + "\n";
 };
 const toAgentMarkdown = (collection, page, options) => {
-  const path = normalizeAgentRoutePath(page.path || page._requestedRoute || page._path);
-  const locale = page.locale || page._resolvedLocale || page._locale;
+  const path = normalizeAgentRoutePath(page.path || page.resolved?.requestedRoute);
+  const locale = page.locale || page.resolved?.locale || page.locale;
   const title = typeof page.title === "string" && page.title.trim() ? page.title.trim() : path.split("/").filter(Boolean).pop() || "Index";
   const description = normalizeDescription(page);
   return {
@@ -339,7 +64,7 @@ const toAgentMarkdown = (collection, page, options) => {
     title,
     description,
     markdown: renderAgentMarkdown(page, collection, path, locale, options),
-    ...page._file ? { sourceFile: page._file } : {},
+    ...page.file?.path ? { sourceFile: page.file?.path } : {},
     canonicalUrl: path,
     ...typeof page.updated === "string" ? { lastModified: page.updated } : {},
     metadataFields: options.metadata,
@@ -377,11 +102,11 @@ const publicPathForLocale = (collection, config, rowPath, locale, defaultLocale2
   });
 };
 const publicPathForQueryRow = (collection, config, row, locale) => {
-  const requested = row.path || row._requestedRoute;
+  const requested = row.path || row.resolved?.requestedRoute;
   if (requested) return normalizeAgentRoutePath(requested);
   const defaultLocale2 = collectionDefaultLocale(config);
-  const rowPath = normalizeAgentRoutePath(row._path || "/");
-  const resolvedLocale = row._resolvedLocale || row._locale;
+  const rowPath = normalizeAgentRoutePath(row.path || "/");
+  const resolvedLocale = row.resolved?.locale || row.locale;
   if (locale && resolvedLocale && locale !== resolvedLocale) {
     const sourceLocalePath = publicPathForLocale(collection, config, rowPath, resolvedLocale, defaultLocale2);
     return prefixRequestedLocale(sourceLocalePath, locale, defaultLocale2);
@@ -416,15 +141,15 @@ export async function queryMarkdownEnabledContent(event, options = {}) {
   for (const [collection, config] of markdownEnabledCollectionEntries(options.collections)) {
     const agentOptions = resolveAgentMarkdownOptions(config);
     if (!agentOptions) continue;
-    const rows = normalizeQueryResult(await provider.query(event, {
+    const rows = normalizeQueryResult(await provider.query(event, createProviderQuery({
       collection,
-      only: ["path", "locale", "localePaths", "_path", "_locale", "_resolvedLocale", "_requestedRoute", "_file", "_draft", "_partial", "_navigation", "title", "description", "updated", "navigation", "robots", "sitemap"],
+      only: ["path", "locale", "localePaths", "resolved", "file", "draft", "partial", "navigationFile", "title", "description", "updated", "navigation", "robots", "sitemap"],
       ...options.limit ? { limit: options.limit } : {},
       ...options.locale ? { resolveLocale: { locale: options.locale, fallback: true } } : {}
-    }));
+    })));
     for (const row of rows) {
       if (!isPublicPage(row, config)) continue;
-      const locale = options.locale || row._resolvedLocale || row._locale;
+      const locale = options.locale || row.resolved?.locale || row.locale;
       const path = publicPathForQueryRow(collection, config, row, locale);
       const title = typeof row.title === "string" && row.title.trim() ? row.title.trim() : path.split("/").filter(Boolean).pop() || "Index";
       const description = normalizeDescription(row);
@@ -436,7 +161,7 @@ export async function queryMarkdownEnabledContent(event, options = {}) {
         collection,
         title,
         description,
-        ...row._file ? { sourceFile: row._file } : {},
+        ...row.file?.path ? { sourceFile: row.file?.path } : {},
         canonicalUrl: path,
         ...typeof row.updated === "string" ? { lastModified: row.updated } : {},
         metadataFields: agentOptions.metadata,

package/dist/runtime/server/agent-site.js

@@ -1,6 +1,6 @@
 import { getRequestURL } from "h3";
 import { linkMarkdown, queryMarkdownEnabledContent, resolveContentMarkdownByRoute } from "./agent-markdown.js";
-import { agentMarkdownPathForRoute, agentRawPathForRoute, agentRoutePathFromIndexSlug, agentRoutePathFromRawSlug, normalizeAgentRoutePath } from "../agent-paths.js";
+import { agentMarkdownPathForRoute, agentRawPathForRoute, agentRoutePathFromIndexSlug, agentRoutePathFromRawSlug, normalizeAgentRoutePath } from "../../features/agent/agent-paths";
 import { contentConfig } from "./storage-access.js";
 const localizedValue = (value, locale, fallback = "") => {
   if (typeof value === "string") return value;
@@ -49,6 +49,12 @@ const resolveLocalizedMaybeFunction = async (value, ctx) => {
   if (typeof value === "function") return await value(ctx);
   return localizedValue(value, ctx.locale);
 };
+const resolveAppPageMarkdown = async (page, ctx) => {
+  if (typeof page.render === "function") {
+    return await page.render(ctx);
+  }
+  return localizedValue(page.markdown, ctx.locale);
+};
 const resolveAppPageRoute = (page, locale) => normalizeAgentRoutePath(localizedValue(page.route, locale, "/"));
 const createAppPageContext = (locale, siteUrl) => ({
   locale,
@@ -96,6 +102,7 @@ const createAppOwnedAgentPages = async (locale, siteUrl) => {
     const path = resolveAppPageRoute(page, locale);
     const rawPath = agentRawPathForRoute(path);
     const section = resolveSection(page.section, locale);
+    const markdown = await resolveAppPageMarkdown(page, ctx);
     result.push({
       title: await resolveLocalizedMaybeFunction(page.title, ctx),
       description: await resolveLocalizedMaybeFunction(page.description, ctx),
@@ -113,7 +120,7 @@ const createAppOwnedAgentPages = async (locale, siteUrl) => {
       metadataFields: page.metadata,
       includeInIndex: page.includeInIndex !== false,
       includeInFull: page.includeInFull !== false,
-      markdown: await page.render(ctx)
+      markdown
     });
   }
   return result;

package/dist/runtime/server/api/agent-raw.js

@@ -1,7 +1,7 @@
 import { createError, defineEventHandler } from "h3";
 import { localeFromAgentPath, resolveMarkdownForPublicRoute, routePathFromRawSlug } from "../agent-site.js";
 import { setAgentMarkdownHeaders } from "../agent-http.js";
-import { isUnsafeAgentRoutePath } from "../../agent-paths.js";
+import { isUnsafeAgentRoutePath } from "../../../features/agent/agent-paths";
 export default defineEventHandler(async (event) => {
   const routePath = routePathFromRawSlug(event.context.params?.slug);
   if (isUnsafeAgentRoutePath(routePath)) {

package/dist/runtime/server/api/cache.d.ts

@@ -1,8 +1,8 @@
 import type { NavItem } from '../../../types/content';
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
-    contents: unknown[];
     navigation: NavItem[];
     generatedAt: number;
+    documentCount: number;
     generateTime: number;
 }>>;
 export default _default;

package/dist/runtime/server/api/cache.js

@@ -1,26 +1,65 @@
 import { defineEventHandler } from "h3";
+import { isRealDocument } from "../../../core/content/document";
+import { assertSnapshotComplete, buildContentSnapshot } from "../../../core/content/snapshot";
+import { chunksFromArray, loadContentVariants } from "../../../storage/contents";
 import { getContentProvider } from "../providers/index.js";
+import { createProviderNavigationQuery } from "../provider-query.js";
 import { createContentProviderError } from "../../../public/provider-errors";
-import { cacheStorage } from "../storage-access.js";
+import { cacheStorage, contentConfig, getSourceContentIds } from "../storage-access.js";
+const hasRoutePath = (document) => typeof document.path === "string" && document.path.length > 0;
+const describeExcludedSource = (variants) => {
+  if (variants.every((variant) => !isRealDocument(variant))) {
+    return "unreadable (source missing or failed to parse)";
+  }
+  return "no route path (parsed, but every variant lacks a path)";
+};
 export default defineEventHandler(async (event) => {
   const now = Date.now();
-  const contents = [];
+  const config = contentConfig();
+  const sourceIds = await getSourceContentIds(event);
+  const documents = [];
+  const excluded = /* @__PURE__ */ new Map();
+  for (const chunk of chunksFromArray(sourceIds, 10)) {
+    const results = await Promise.all(chunk.map(async (id) => [id, await loadContentVariants(event, id)]));
+    for (const [id, variants] of results) {
+      const routable = variants.filter(isRealDocument).filter(hasRoutePath);
+      if (routable.length === 0) {
+        excluded.set(id, describeExcludedSource(variants));
+      }
+      documents.push(...routable);
+    }
+  }
+  if (excluded.size > 0) {
+    const details = [...excluded.entries()].slice(0, 20).map(([id, reason]) => `${id}: ${reason}`).join("; ");
+    throw new Error(
+      `[content] snapshot build failed: ${excluded.size} source document(s) produced no servable content and would silently 404 in production. First ${Math.min(excluded.size, 20)} \u2014 ${details}`
+    );
+  }
+  const snapshot = buildContentSnapshot({
+    integrity: config.cacheIntegrity,
+    documents,
+    sourceIds,
+    now
+  });
+  assertSnapshotComplete(snapshot, sourceIds);
+  await cacheStorage(event).setItem("snapshot.json", snapshot);
   const provider = await getContentProvider(event);
   if (!provider.navigationQuery) {
     throw createContentProviderError("unsupported_provider_operation", `${provider.name} does not support navigation queries`, {
       provider: provider.name
     });
   }
-  const navigation = await provider.navigationQuery(event, {});
+  const { query: navQuery, options: navOptions } = createProviderNavigationQuery({});
+  const navigation = await provider.navigationQuery(event, navQuery, navOptions);
   await cacheStorage(event).setItem("_nav.json", navigation);
   const meta = {
     generatedAt: now,
+    documentCount: snapshot.documentIds.length,
     generateTime: Date.now() - now
   };
   await cacheStorage(event).setItem("_meta.json", meta);
   return {
     ...meta,
-    contents,
     navigation
   };
 });

package/dist/runtime/server/api/locales.js

@@ -15,10 +15,10 @@ export default defineEventHandler(async (event) => {
     collection,
     exact: false
   });
-  const locales = resolved ? resolved.variants.filter((doc) => doc._canonicalKey === resolved.canonicalKey && typeof doc._locale === "string").sort((left, right) => String(left._locale).localeCompare(String(right._locale))).map((doc) => ({
+  const locales = resolved ? resolved.variants.filter((doc) => doc.canonicalKey === resolved.canonicalKey && typeof doc.locale === "string").sort((left, right) => String(left.locale).localeCompare(String(right.locale))).map((doc) => ({
     canonicalKey: resolved.canonicalKey,
-    locale: String(doc._locale),
-    ...typeof doc._path === "string" ? { path: doc._path } : {}
+    locale: String(doc.locale),
+    ...typeof doc.path === "string" ? { path: doc.path } : {}
   })) : [];
   if (!locales.length) {
     throw createError({

package/dist/runtime/server/api/navigation.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types").NavItem[]>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types/content").NavItem[]>>;
 export default _default;

package/dist/runtime/server/api/navigation.js

@@ -1,6 +1,7 @@
 import { defineEventHandler, getQuery } from "h3";
 import { getContentQuery } from "../../utils/query.js";
 import { getContentProvider } from "../providers/index.js";
+import { createProviderNavigationQuery } from "../provider-query.js";
 import { createContentProviderError } from "../../../public/provider-errors";
 export default defineEventHandler(async (event) => {
   const query = getContentQuery(event);
@@ -17,5 +18,6 @@ export default defineEventHandler(async (event) => {
       provider: provider.name
     });
   }
-  return await provider.navigationQuery(event, query);
+  const { query: providerQuery, options } = createProviderNavigationQuery(query);
+  return await provider.navigationQuery(event, providerQuery, options);
 });

package/dist/runtime/server/api/query.js

@@ -1,9 +1,9 @@
 import { defineEventHandler } from "h3";
 import { getContentQuery } from "../../utils/query.js";
 import { getContentProvider } from "../providers/index.js";
-import { normalizeProviderQueryResponse } from "../provider-query.js";
+import { createProviderQuery, normalizeProviderQueryResponse } from "../provider-query.js";
 export default defineEventHandler(async (event) => {
   const query = getContentQuery(event);
   const provider = await getContentProvider(event);
-  return normalizeProviderQueryResponse(query, await provider.query(event, query), provider.name);
+  return normalizeProviderQueryResponse(query, await provider.query(event, createProviderQuery(query)), provider.name);
 });

package/dist/runtime/server/api/search-index.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types").ContentSearchIndexRecord[]>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types/search").ContentSearchIndexRecord[]>>;
 export default _default;

package/dist/runtime/server/api/sitemap.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types").ContentSitemapEntry[]>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types/query").ContentSitemapEntry[]>>;
 export default _default;

package/dist/runtime/server/cache-adapters.d.ts

@@ -1,5 +1,23 @@
 import type { ContentCacheAdapter, ContentCacheHint } from '../../public/provider';
+/**
+ * Choosing a cache adapter:
+ * - `noopContentCache` — the default. Both `apply` and `invalidate` are intentionally
+ *   inert: the runtime still computes and stores a cache hint per request, but nothing
+ *   is written to the response and no upstream cache is purged. Use when caching is
+ *   handled entirely outside this module (a CDN/edge config you own) or disabled.
+ * - `vercelContentCache` — `apply` is intentionally inert (Vercel ISR revalidation is a
+ *   pull, not a per-response header this module sets); only `invalidate` does work,
+ *   firing prerender-revalidate HEAD requests. Use on Vercel ISR deployments.
+ * - `headersContentCache` — the active-`apply` adapter: writes `Cache-Control`/`ETag`/
+ *   `Last-Modified` onto every content response from the hint. Use when this module
+ *   should own response cache headers directly (self-hosted / generic CDN).
+ */
 export declare const noopContentCache: () => ContentCacheAdapter;
+/**
+ * Emits the per-request cache hint as HTTP response headers via {@link contentCacheHeaders}.
+ * `invalidate` is a no-op: header-based caching has no upstream store to purge.
+ */
+export declare const headersContentCache: () => ContentCacheAdapter;
 export interface VercelContentCacheOptions {
     origin: string;
     bypassToken: string;

package/dist/runtime/server/cache-adapters.js

@@ -1,3 +1,4 @@
+import { setHeader } from "h3";
 export const noopContentCache = () => ({
   name: "noop",
   apply: () => {
@@ -5,6 +6,17 @@ export const noopContentCache = () => ({
   invalidate: async () => {
   }
 });
+export const headersContentCache = () => ({
+  name: "headers",
+  apply: (event, hint) => {
+    const headers = contentCacheHeaders(hint);
+    headers.forEach((value, key) => {
+      setHeader(event, key, value);
+    });
+  },
+  invalidate: async () => {
+  }
+});
 export const vercelContentCache = (options) => {
   const origin = options.origin.replace(/\/$/, "");
   const fetchImpl = options.fetch || globalThis.fetch;