@lupinum/ginko-content 0.1.5 → 0.2.0

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-content",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "configKey": "content",
   "compatibility": {
     "nuxt": ">=4.0.0"

package/dist/module.mjs

@@ -22,15 +22,16 @@ import { transformContent } from '../dist/parsers/index';
 import { resolveCollectionI18n, prefixPathWithLocale } from '../dist/features/localization/path';
 import { resolveContentSitemapSource, GINKO_SITEMAP_SOURCE_NAME } from '../dist/runtime/utils/sitemap-source';
 import { normalizeRouteMounts, normalizeContentPath } from '../dist/core/content/path';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
+import { isContentSnapshot } from '../dist/core/content/snapshot';
 import { withTrailingSlash } from 'ufo';
 import { normalizeContentConfigCollectionNames } from '../dist/types/config';
 export { agentMetadataFields, defineAgentAppPage, defineAgentMarkdownPolicy, defineAgentMetadataFields, defineAgentSection, defineCollection, defineContentConfig, reference } from '../dist/types/config';
 import { collectTopLevelReferenceFieldsByTarget } from '../dist/core/references/schema';
 
 const name = "@lupinum/ginko-content";
-const version = "0.1.5";
+const version = "0.2.0";
 
 const CONFIG_FILES = [
   "content.config.ts",
@@ -58,7 +59,7 @@ const createVirtualContentTemplates = (contentContext, nuxt, contentConfigPath,
     write: true,
     getContents: () => {
       const transformers = contentContext.transformers.map((transformer) => {
-        const name = genSafeVariableName(relative(nuxt.options.rootDir, transformer)).replace(/_(45|46|47)/g, "_") + "_" + hash(transformer);
+        const name = genSafeVariableName(relative(nuxt.options.rootDir, transformer)).replace(/_(45|46|47)/g, "_") + "_" + hash(transformer).replace(/[^a-z0-9_$]/gi, "_");
         return { name, import: genImport(transformer, name) };
       });
       return [
@@ -73,10 +74,15 @@ const createVirtualContentTemplates = (contentContext, nuxt, contentConfigPath,
   const virtualConfigTemplate = addTemplateImpl({
     filename: "content/virtual-config.mjs",
     write: true,
-    getContents: () => contentConfigPath ? [
-      `import config from ${JSON.stringify(contentConfigPath)}`,
-      "export default config || {}"
-    ].join("\n") : "export default {}"
+    getContents: () => {
+      if (!contentConfigPath) {
+        return "export default {}";
+      }
+      return [
+        `import config from ${JSON.stringify(contentConfigPath)}`,
+        "export default config"
+      ].join("\n");
+    }
   }).dst;
   const virtualProvidersTemplate = addTemplateImpl({
     filename: "content/virtual-providers.mjs",
@@ -260,10 +266,14 @@ const generatedContentServerValueNames = [
   "contentCacheHeaders",
   "noopContentCache",
   "vercelContentCache",
+  "headersContentCache",
   "clearContentCacheHint",
   "collectContentCacheHint",
   "getContentCacheHint",
   "withContentCache",
+  "PROVIDER_QUERY_VERSION",
+  "toContentProviderQuery",
+  "toContentProviderNavigationQuery",
   "createContentProviderError"
 ];
 const generatedContentServerTypeSpecs = [
@@ -273,6 +283,8 @@ const generatedContentServerTypeSpecs = [
   { local: "ContentCacheInvalidateInput", exported: "ContentCacheInvalidateInput" },
   { local: "ContentProvider", exported: "ContentProvider" },
   { local: "ContentProviderCapabilities", exported: "ContentProviderCapabilities" },
+  { local: "ContentProviderQuery", exported: "ContentProviderQuery" },
+  { local: "ContentProviderNavigationOptions", exported: "ContentProviderNavigationOptions" },
   { local: "ContentProviderResult<T>", exported: "ContentProviderResult<T>" },
   { local: "MaybeContentProviderResult<T>", exported: "MaybeContentProviderResult<T>" },
   { local: "ContentProviderErrorCode", exported: "ContentProviderErrorCode" },
@@ -393,11 +405,12 @@ const registerGeneratedTypes = (contentConfigPath, resolveRuntimeModuleRoot, col
     const key = JSON.stringify(name);
     return `    ${key}: StrictParsedContent & __GeneratedCollectionSchema<__ContentCollectionExport<${key}>>`;
   });
+  const serverModuleLiteral = JSON.stringify(resolveRuntimeModuleRoot("./server"));
   const contentServerValueDeclarations = generatedContentServerValueNames.map(
-    (name) => `  const ${name}: typeof import('${resolveRuntimeModuleRoot("./server")}').${name}`
+    (name) => `  const ${name}: typeof import(${serverModuleLiteral}).${name}`
   );
   const contentServerTypeDeclarations = generatedContentServerTypeSpecs.map(
-    (spec) => `  type ${spec.local} = import('${resolveRuntimeModuleRoot("./server")}').${spec.exported}`
+    (spec) => `  type ${spec.local} = import(${serverModuleLiteral}).${spec.exported}`
   );
   return addTypeTemplate({
     filename: "types/content.d.ts",
@@ -635,7 +648,7 @@ const registerContentComponentsTemplate = (addTemplateImpl) => {
           const pathLiteral = JSON.stringify(path);
           const exportLiteral = JSON.stringify(exp);
           const nameLiteral = JSON.stringify(pascalName);
-          return `  ${pascalName}: () => import(${pathLiteral}).then(mod => pickExport(mod, ${exportLiteral}, ${nameLiteral}, ${pathLiteral})),`;
+          return `  ${nameLiteral}: () => import(${pathLiteral}).then(mod => pickExport(mod, ${exportLiteral}, ${nameLiteral}, ${pathLiteral})),`;
         }),
         "}",
         `export const globalComponents = ${JSON.stringify(globalComponents)}`,
@@ -891,7 +904,7 @@ const parseDerivedCollectionFiles = async (rootDir, collections, collectionNames
         collectionResolver: (filePath) => resolveCollection(filePath, collections, contentContext.locales || [])
       }
     });
-    const collection = typeof parsed._collection === "string" ? collections[parsed._collection] : void 0;
+    const collection = typeof parsed.collection === "string" ? collections[parsed.collection] : void 0;
     documents.push(...expandDataLocaleVariants(parsed, collection?.i18n === true ? void 0 : collection?.i18n));
   }
   return documents;
@@ -924,17 +937,17 @@ const collectDerivedPrerenderRoutes = async (rootDir, contentContext) => {
     const seenCanonicalKeys = /* @__PURE__ */ new Set();
     for (const contentId of graph.byCollection[collection] || []) {
       const document = graph.byId[contentId];
-      if (!document || !document._canonicalKey || document._partial || document._navigation) {
+      if (!document || !document.canonicalKey || document.partial || document.navigationFile) {
         continue;
       }
-      if (document._draft && !includeDrafts) {
+      if (document.draft && !includeDrafts) {
         continue;
       }
-      if (seenCanonicalKeys.has(document._canonicalKey)) {
+      if (seenCanonicalKeys.has(document.canonicalKey)) {
         continue;
       }
-      seenCanonicalKeys.add(document._canonicalKey);
-      const variants = graph.byCanonical[document._canonicalKey] || {};
+      seenCanonicalKeys.add(document.canonicalKey);
+      const variants = graph.byCanonical[document.canonicalKey] || {};
       for (const [locale, variant] of Object.entries(variants)) {
         if (!variant.path) {
           continue;
@@ -957,20 +970,20 @@ const collectSitemapCollectionRouteCounts = async (rootDir, contentContext) => {
     const seenCanonicalKeys = /* @__PURE__ */ new Set();
     for (const contentId of graph.byCollection[collection] || []) {
       const document = graph.byId[contentId];
-      if (!document || !document._canonicalKey || document._partial || document._navigation) {
+      if (!document || !document.canonicalKey || document.partial || document.navigationFile) {
         continue;
       }
-      if (document._draft && !includeDrafts) {
+      if (document.draft && !includeDrafts) {
         continue;
       }
-      if (seenCanonicalKeys.has(document._canonicalKey)) {
+      if (seenCanonicalKeys.has(document.canonicalKey)) {
         continue;
       }
-      const variants = Object.values(graph.byCanonical[document._canonicalKey] || {});
+      const variants = Object.values(graph.byCanonical[document.canonicalKey] || {});
       if (!variants.some((variant) => variant.path)) {
         continue;
       }
-      seenCanonicalKeys.add(document._canonicalKey);
+      seenCanonicalKeys.add(document.canonicalKey);
       counts[collection] += 1;
     }
   }
@@ -1135,13 +1148,23 @@ function normalizeSearchOptions(options) {
   return {
     engine: options.search?.engine || "minisearch",
     ignoredTags: options.search?.ignoredTags || ["script", "style", "pre"],
-    filterQuery: options.search?.filterQuery || { _draft: false, _partial: false },
+    filterQuery: options.search?.filterQuery || { draft: false, partial: false },
     collections: options.search?.collections,
     extraFields: options.search?.extraFields || [],
     apiBaseURL: options.search?.apiBaseURL,
     minisearch: normalizeMiniSearchOptions(options.search?.minisearch)
   };
 }
+async function assertPagefindAvailable(search, importPagefind = () => import('pagefind')) {
+  if (search === false || search.engine !== "pagefind") {
+    return;
+  }
+  try {
+    await importPagefind();
+  } catch {
+    throw new Error('Content search engine "pagefind" is enabled but the optional "pagefind" package is not installed. Install it: pnpm add -D pagefind');
+  }
+}
 const defaultMiniSearchOptions = {
   fields: ["title", "content", "headings"],
   storeFields: ["path", "title", "excerpt", "anchor", "locale", "collection"],
@@ -1331,6 +1354,19 @@ const collectRawMarkdownRoutesFromGeneratedFrontmatter = (markdown) => {
 };
 const publicOutputPath = (publicDir, route) => join(publicDir, normalizeStaticRoutePath(route).replace(/^\//, ""));
 
+const assertPrerenderedContentSnapshot = (buildDir) => {
+  const snapshotPath = resolve$1(buildDir, "content-cache/snapshot.json");
+  let raw;
+  try {
+    raw = readFileSync(snapshotPath, "utf8");
+  } catch {
+    throw new Error("[content] production snapshot missing from prerendered content cache. Ensure the content cache route is prerendered.");
+  }
+  const snapshot = JSON.parse(raw);
+  if (!isContentSnapshot(snapshot)) {
+    throw new Error("[content] production snapshot is invalid in prerendered content cache.");
+  }
+};
 const hookNuxtBoundary$2 = (nuxt, name, callback) => {
   const hook = nuxt.hook;
   hook(name, callback);
@@ -1346,6 +1382,12 @@ const registerStaticOutputGeneration = ({
 }) => {
   if (nuxt.options.dev) return;
   hookNuxtBoundary$2(nuxt, "nitro:build:before", (nitro) => {
+    const usesFilesystemProvider = !contentContext.provider || contentContext.provider === "filesystem";
+    if (usesFilesystemProvider) {
+      nitro.hooks.hook("prerender:done", () => {
+        assertPrerenderedContentSnapshot(nuxt.options.buildDir);
+      });
+    }
     nitro.hooks.hook("prerender:init", (prerenderer) => {
       prerenderer.hooks.hook("compiled", async () => {
         const searchRuntime = getSearchRuntime();
@@ -1353,7 +1395,7 @@ const registerStaticOutputGeneration = ({
         const serverFilename = typeof prerenderer.options.rollupConfig?.output?.entryFileNames === "string" ? prerenderer.options.rollupConfig.output.entryFileNames : "index.mjs";
         const serverEntrypoint = resolve$1(prerenderer.options.output.serverDir, serverFilename);
         const { localFetch } = await import(pathToFileURL(serverEntrypoint).href);
-        if (searchRuntime !== false && searchRuntime.engine !== "cms" && (!contentContext.provider || contentContext.provider === "filesystem")) {
+        if (searchRuntime !== false && searchRuntime.engine !== "cms" && usesFilesystemProvider) {
           const response = await localFetch(searchRuntime.indexURL);
           if (!response.ok) {
             throw new Error(`Failed to generate search index: [${response.status}] ${response.statusText}`);
@@ -1499,15 +1541,6 @@ const registerContentNitroConfig = ({
           nitroConfig.prerender.routes.push(`/${locale}/llms.txt`, `/${locale}/llms-full.txt`);
         }
       }
-      for (const page of appContentConfig.agent.pages || []) {
-        const routes = typeof page.route === "string" ? [page.route] : Object.values(page.route);
-        for (const route of routes) {
-          const normalized = route === "/" ? "/" : `/${route.replace(/^\/+|\/+$/g, "")}`;
-          nitroConfig.prerender.routes.push(
-            normalized === "/" ? "/raw/index.md" : `/raw${normalized}.md`
-          );
-        }
-      }
     }
   });
 };
@@ -1565,7 +1598,7 @@ const contentModuleDefaults = {
   search: {
     engine: "minisearch",
     ignoredTags: ["script", "style", "pre"],
-    filterQuery: { _draft: false, _partial: false },
+    filterQuery: { draft: false, partial: false },
     extraFields: [],
     minisearch: {
       fields: [...defaultMiniSearchOptions.fields],
@@ -1664,7 +1697,55 @@ const sanitizePrivateMarkdownPlugins = (plugins) => plugins.map((plugin) => ({
   name: plugin.name,
   options: sanitizePrivateMarkdownPluginValue(plugin.options || {})
 }));
-const applyContentRuntimeConfig = (nuxt, options, contentContext, runtimeCollections, buildIntegrity, cacheIntegrity) => {
+const localizedValue = (value, locale, fallback = "") => {
+  if (typeof value === "string") return value;
+  if (!value) return fallback;
+  return value[locale] || Object.values(value)[0] || fallback;
+};
+const resolveAgentAppPageValue = async (value, ctx) => {
+  if (typeof value === "function") {
+    return await value(ctx);
+  }
+  return localizedValue(value, ctx.locale);
+};
+const sanitizeAgentConfig = async (agent, contentContext, siteUrl) => {
+  if (!agent) {
+    return void 0;
+  }
+  const defaultLocale = agent.site?.defaultLocale || contentContext.defaultLocale || contentContext.locales?.[0] || "en";
+  const locales = agent.site?.locales?.length ? agent.site.locales : contentContext.locales?.length ? contentContext.locales : [defaultLocale];
+  const agentSiteUrl = siteUrl || agent.site?.url || "http://localhost:3000";
+  const pages = await Promise.all((agent.pages || []).map(async (page) => {
+    const title = {};
+    const description = {};
+    const markdown = {};
+    for (const locale of locales) {
+      const ctx = { locale, defaultLocale, siteUrl: agentSiteUrl };
+      title[locale] = await resolveAgentAppPageValue(page.title, ctx);
+      description[locale] = await resolveAgentAppPageValue(page.description, ctx);
+      markdown[locale] = await page.render(ctx);
+    }
+    return {
+      id: page.id,
+      route: page.route,
+      section: page.section,
+      title,
+      description,
+      updated: page.updated,
+      includeInIndex: page.includeInIndex,
+      includeInFull: page.includeInFull,
+      metadata: page.metadata,
+      markdown
+    };
+  }));
+  return {
+    ...agent.site ? { site: agent.site } : {},
+    ...agent.markdown ? { markdown: agent.markdown } : {},
+    ...agent.sections ? { sections: agent.sections } : {},
+    ...pages.length ? { pages } : {}
+  };
+};
+const applyContentRuntimeConfig = async (nuxt, options, contentContext, appContentConfig, runtimeCollections, privateRuntimeCollections, buildIntegrity, cacheIntegrity) => {
   const revalidate = options.revalidate === false ? void 0 : options.revalidate;
   const searchRuntime = contentContext.search === false ? false : {
     apiBaseURL: contentContext.search.apiBaseURL || `${options.api.baseURL.replace(/\/$/, "")}/search`,
@@ -1708,8 +1789,10 @@ const applyContentRuntimeConfig = (nuxt, options, contentContext, runtimeCollect
     navigation: contentContext.navigation,
     contentHead: options.contentHead ?? true
   });
+  const runtimeAgent = await sanitizeAgentConfig(appContentConfig.agent, contentContext, siteUrl);
   const privateContentRuntime = {
     ...contentContext,
+    ...runtimeAgent ? { agent: runtimeAgent } : {},
     markdown: {
       ...contentContext.markdown,
       plugins: sanitizePrivateMarkdownPlugins(contentContext.markdown.plugins)
@@ -1724,13 +1807,14 @@ const applyContentRuntimeConfig = (nuxt, options, contentContext, runtimeCollect
       allowUnsigned: revalidate.allowUnsigned === true
     } : false,
     ...privateContentRuntime,
-    collections: runtimeCollections
+    collections: privateRuntimeCollections
   });
 };
 
 const registerContentContextFinalization = ({
   nuxt,
   options,
+  appContentConfig,
   contentContext,
   buildIntegrity,
   resolvePath,
@@ -1751,22 +1835,28 @@ const registerContentContextFinalization = ({
     };
     onResolved(resolvedContentContext);
     await validateBuiltinMarkdownPlugins(resolvedContentContext.markdown.plugins, resolvePath);
-    const runtimeCollections = Object.fromEntries(Object.entries(options.collections || {}).map(([name, collection]) => {
+    const collectionEntries = Object.entries(options.collections || {}).map(([name, collection]) => {
       const references = collectTopLevelReferenceFieldsByTarget(collection.schema);
-      return [
-        name,
-        {
-          ...collection.source ? { source: collection.source } : {},
-          ...collection.exclude ? { exclude: collection.exclude } : {},
-          ...collection.type ? { type: collection.type } : {},
-          strict: collection.strict ?? true,
-          ...collection.route ? { route: collection.route } : {},
-          ...typeof collection.sitemap === "boolean" ? { sitemap: collection.sitemap } : {},
-          ...collection.i18n && collection.i18n !== true ? { i18n: collection.i18n } : {},
-          ...Object.keys(references).length ? { references } : {}
-        }
-      ];
-    }));
+      const runtimeCollection = {
+        ...collection.source ? { source: collection.source } : {},
+        ...collection.exclude ? { exclude: collection.exclude } : {},
+        ...collection.type ? { type: collection.type } : {},
+        strict: collection.strict ?? true,
+        ...collection.route ? { route: collection.route } : {},
+        ...typeof collection.translatedSlugs === "boolean" ? { translatedSlugs: collection.translatedSlugs } : {},
+        ...typeof collection.sitemap === "boolean" ? { sitemap: collection.sitemap } : {},
+        ...collection.i18n && collection.i18n !== true ? { i18n: collection.i18n } : {},
+        ...collection.cms ? { cms: collection.cms } : {},
+        ...collection.agent ? { agent: collection.agent } : {},
+        ...Object.keys(references).length ? { references } : {}
+      };
+      return [name, runtimeCollection, collection];
+    });
+    const runtimeCollections = Object.fromEntries(collectionEntries.map(([name, runtimeCollection]) => [name, runtimeCollection]));
+    const privateRuntimeCollections = Object.fromEntries(collectionEntries.map(([name, runtimeCollection]) => [
+      name,
+      runtimeCollection
+    ]));
     const cacheIntegrity = hash({
       locales: resolvedContentContext.locales,
       defaultLocale: resolvedContentContext.defaultLocale,
@@ -1779,7 +1869,7 @@ const registerContentContextFinalization = ({
       yaml: resolvedContentContext.yaml,
       csv: resolvedContentContext.csv
     });
-    applyContentRuntimeConfig(nuxt, options, resolvedContentContext, runtimeCollections, buildIntegrity, cacheIntegrity);
+    await applyContentRuntimeConfig(nuxt, options, resolvedContentContext, appContentConfig, runtimeCollections, privateRuntimeCollections, buildIntegrity, cacheIntegrity);
   });
 };
 
@@ -1835,6 +1925,7 @@ const module$1 = defineNuxtModule({
     const resolvedI18n = resolveModuleI18nOptions(options, nuxt);
     const resolvedSitemap = normalizeSitemapOptions(options);
     const resolvedSearch = normalizeSearchOptions(options);
+    await assertPagefindAvailable(resolvedSearch);
     validateCollectionNames(appContentConfig.collections);
     if (!hasAgentSurface(appContentConfig)) {
       options.agent = false;
@@ -1939,6 +2030,7 @@ const module$1 = defineNuxtModule({
     registerContentContextFinalization({
       nuxt,
       options,
+      appContentConfig,
       contentContext,
       buildIntegrity,
       resolvePath,

package/dist/parsers/csv.js

@@ -22,7 +22,7 @@ function toJsonArray(tree) {
 export default defineTransformer({
   name: "csv",
   extensions: [".csv"],
-  parse: async (_id, content, options = {}) => {
+  parse: async (id, content, options = {}) => {
     const csvOptions = typeof options === "object" && options !== null ? options : {};
     const tree = fromCSV(String(content ?? ""), {
       delimiter: ",",
@@ -31,8 +31,8 @@ export default defineTransformer({
     });
     const result = csvOptions.json === false ? toJsonArray(tree) : toJsonObject(tree);
     return {
-      _id,
-      _type: "csv",
+      id,
+      type: "csv",
       body: result
     };
   }

package/dist/parsers/index.js

@@ -27,15 +27,15 @@ function getTransformers(ext, additionalTransformers = []) {
 }
 export async function transformContent(id, content, options = {}) {
   const { transformers = [] } = options;
-  const file = { _id: id, body: content };
+  const file = { id, body: content };
   const ext = extname(id);
   const parser = getParser(ext, transformers);
   if (!parser) {
     console.warn(`${ext} files are not supported, "${id}" storing body as null`);
-    return { _id: file._id, body: null };
+    return { id: file.id, body: null, missing: true };
   }
   const parserOptions = options[camelCase(parser.name)] || {};
-  const parsed = await parser.parse(file._id, file.body, parserOptions);
+  const parsed = await parser.parse(file.id, file.body, parserOptions);
   const matchedTransformers = getTransformers(ext, transformers);
   const result = await matchedTransformers.reduce(async (prev, cur) => {
     const next = await prev || parsed;

package/dist/parsers/json.js

@@ -1,29 +1,31 @@
 import { destr } from "destr";
 import { defineTransformer } from "./utils.js";
+import { stripReservedContentKeys } from "./reserved.js";
 export default defineTransformer({
   name: "Json",
   extensions: [".json", ".json5"],
-  parse: async (_id, content) => {
+  parse: async (id, content) => {
     let parsed;
     if (typeof content === "string") {
-      if (_id.endsWith("json5")) {
+      if (id.endsWith("json5")) {
         parsed = (await import("json5").then((m) => m.default || m)).parse(content);
-      } else if (_id.endsWith("json")) {
+      } else if (id.endsWith("json")) {
         parsed = destr(content);
       }
     } else {
       parsed = content;
     }
     if (Array.isArray(parsed)) {
-      console.warn(`JSON array is not supported in ${_id}, moving the array into the \`body\` key`);
+      console.warn(`JSON array is not supported in ${id}, moving the array into the \`body\` key`);
       parsed = {
         body: parsed
       };
     }
+    parsed = stripReservedContentKeys(parsed, id);
     return {
       ...parsed,
-      _id,
-      _type: "json"
+      id,
+      type: "json"
     };
   }
 });

package/dist/parsers/markdown-plugins.js

@@ -82,10 +82,10 @@ const resolveMarkdownPluginOptions = async (plugin) => {
 };
 const builtinMarkdownPlugins = {
   breaks: {
-    load: () => loadModule("comark/plugins/breaks")
+    load: () => loadBuiltinModule(() => import("comark/plugins/breaks"))
   },
   emoji: {
-    load: () => loadModule("comark/plugins/emoji")
+    load: () => loadBuiltinModule(() => import("comark/plugins/emoji"))
   },
   footnotes: {
     load: async () => footnotesPlugin
@@ -94,7 +94,7 @@ const builtinMarkdownPlugins = {
     load: async () => highlightPlugin
   },
   "json-render": {
-    load: () => loadModule("comark/plugins/json-render")
+    load: () => loadBuiltinModule(() => import("comark/plugins/json-render"))
   },
   math: {
     load: () => loadModule("comark/plugins/math")
@@ -103,10 +103,10 @@ const builtinMarkdownPlugins = {
     load: () => loadModule("comark/plugins/mermaid")
   },
   punctuation: {
-    load: () => loadModule("comark/plugins/punctuation")
+    load: () => loadBuiltinModule(() => import("comark/plugins/punctuation"))
   },
   security: {
-    load: () => loadModule("comark/plugins/security")
+    load: () => loadBuiltinModule(() => import("comark/plugins/security"))
   },
   summary: {
     load: async () => summaryPlugin
@@ -135,6 +135,10 @@ async function loadModule(specifier) {
   );
   return resolveModule(imported);
 }
+async function loadBuiltinModule(loader) {
+  const imported = await loader();
+  return resolveModule(imported);
+}
 function resolveModule(imported) {
   return imported.default || imported;
 }

package/dist/parsers/markdown.js

@@ -3,16 +3,18 @@ import { isRelative } from "ufo";
 import { defineTransformer } from "./utils.js";
 import { generatePath } from "./path-meta.js";
 import { resolveMarkdownPlugins } from "./markdown-plugins.js";
+import { stripReservedContentKeys } from "./reserved.js";
 import { mapMarkdownNodes, toMarkdownRoot } from "../core/markdown/tree";
 export default defineTransformer({
   name: "markdown",
   extensions: [".md"],
-  parse: async (_id, content, options = {}) => {
+  parse: async (id, content, options = {}) => {
     const config = { ...typeof options === "object" && options !== null ? options : {} };
     const plugins = await resolveMarkdownPlugins(config.plugins || []);
     const tree = await parse(content, {
       plugins
     });
+    const frontmatter = stripReservedContentKeys(tree.frontmatter, id);
     const body = normalizeMarkdownBody({
       ...toMarkdownRoot(tree.nodes),
       toc: tree.meta?.toc
@@ -21,13 +23,12 @@ export default defineTransformer({
       ...toMarkdownRoot(tree.meta.summary)
     }) : void 0;
     return {
-      ...tree.frontmatter,
-      _empty: body.children.length === 0,
-      description: typeof tree.frontmatter.description === "string" ? tree.frontmatter.description : "",
+      ...frontmatter,
+      description: typeof frontmatter.description === "string" ? frontmatter.description : "",
       excerpt,
       body,
-      _type: "markdown",
-      _id
+      type: "markdown",
+      id
     };
   }
 });

package/dist/parsers/path-meta.js

@@ -5,32 +5,34 @@ export default defineTransformer({
   extensions: [".*"],
   transform(content, options = {}) {
     const { locales = [], defaultLocale = "en", respectPathCase = false, translatedSlugs = false } = options;
-    const { _source, _file, _path, _extension, _basename } = describeId(content._id);
-    const parts = _path.split("/");
-    const _locale = locales.includes(parts[0]) ? parts.shift() : defaultLocale;
-    const isNavigation = _basename === ".navigation";
+    const { source, file, path, extension, basename } = describeId(content.id);
+    const parts = path.split("/");
+    const locale = locales.includes(parts[0]) ? parts.shift() : defaultLocale;
+    const isNavigation = basename === ".navigation";
     const rawPath = isNavigation ? parts.slice(0, -1).join("/") : parts.join("/");
     const filePath = generatePath(rawPath, { respectPathCase });
-    const _canonicalKey = generateCanonicalKey(isNavigation ? parts.slice(0, -1) : parts, { translatedSlugs, respectPathCase });
-    const _collection = options.collectionResolver?.(_file);
+    const canonicalKey = generateCanonicalKey(isNavigation ? parts.slice(0, -1) : parts, { translatedSlugs, respectPathCase });
+    const collection = options.collectionResolver?.(file);
     return {
       ...content,
       // Fallback title synthesis lives here (not in the markdown parser) so it
       // applies uniformly to every parser output. Moving it into the markdown
       // parser would duplicate the logic in the yaml / json / csv parsers.
-      title: content.title || (isNavigation ? void 0 : generateTitle(refineUrlPart(_basename))),
-      _path: filePath,
-      _dir: filePath.split("/").slice(-2)[0],
-      _draft: content.draft || isDraftPath(_path),
-      _partial: isNavigation || isPartialPath(_path),
-      _locale,
-      _canonicalKey,
-      _collection,
-      _navigation: isNavigation,
-      _source,
-      _file,
-      _stem: _path,
-      _extension
+      title: content.title || (isNavigation ? void 0 : generateTitle(refineUrlPart(basename))),
+      path: filePath,
+      draft: content.draft || isDraftPath(path),
+      partial: isNavigation || isPartialPath(path),
+      locale,
+      canonicalKey,
+      collection,
+      navigationFile: isNavigation,
+      file: {
+        source,
+        path: file,
+        stem: path,
+        dir: filePath.split("/").slice(-2)[0],
+        extension
+      }
     };
   }
 });

package/dist/parsers/reserved

@@ -0,0 +1 @@
+export * from './reserved.js'

package/dist/parsers/reserved.d.ts

@@ -0,0 +1,15 @@
+/**
+ * System-computed identity keys on the content envelope. User frontmatter may
+ * not define these: the system value always wins and a dev/build warning is
+ * emitted so authors notice the shadowed key.
+ *
+ * The former user-facing "explicit id" alias has been retired — authors who
+ * want a stable, rename-proof alias for internal links should use `ref`.
+ */
+export declare const RESERVED_CONTENT_KEYS: readonly ["id", "collection", "locale", "path", "canonicalKey", "type", "file", "resolved", "variants", "localePaths", "unprefixedPath", "dir"];
+/**
+ * Strip reserved system keys from raw user frontmatter/data. Identity keys are
+ * stamped later by path-meta; derived localization keys would otherwise be
+ * trusted as system state.
+ */
+export declare const stripReservedContentKeys: <T extends Record<string, unknown>>(source: Record<string, unknown> | null | undefined, fileId: string) => Partial<T>;