@lupinum/ginko-content 0.1.6 → 0.2.1

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-content",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "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.6";
+const version = "0.2.1";
 
 const CONFIG_FILES = [
   "content.config.ts",
@@ -52,13 +53,13 @@ async function loadContentConfig(nuxt) {
   return loaded?.default || loaded || {};
 }
 
-const createVirtualContentTemplates = (contentContext, nuxt, _contentConfigPath, addTemplateImpl) => {
+const createVirtualContentTemplates = (contentContext, nuxt, contentConfigPath, addTemplateImpl) => {
   const transformersTemplate = addTemplateImpl({
     filename: "content/virtual-transformers.mjs",
     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,7 +74,15 @@ const createVirtualContentTemplates = (contentContext, nuxt, _contentConfigPath,
   const virtualConfigTemplate = addTemplateImpl({
     filename: "content/virtual-config.mjs",
     write: true,
-    getContents: () => "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",
@@ -257,11 +266,17 @@ const generatedContentServerValueNames = [
   "contentCacheHeaders",
   "noopContentCache",
   "vercelContentCache",
+  "headersContentCache",
   "clearContentCacheHint",
   "collectContentCacheHint",
   "getContentCacheHint",
   "withContentCache",
-  "createContentProviderError"
+  "PROVIDER_QUERY_VERSION",
+  "toContentProviderQuery",
+  "toContentProviderNavigationQuery",
+  "createContentProviderError",
+  "normalizeProviderDocument",
+  "shapeProviderDocument"
 ];
 const generatedContentServerTypeSpecs = [
   { local: "ContentCacheAdapter", exported: "ContentCacheAdapter" },
@@ -270,9 +285,13 @@ 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" },
+  { local: "ProviderDocumentInput", exported: "ProviderDocumentInput" },
+  { local: "ShapeProviderDocumentOptions", exported: "ShapeProviderDocumentOptions" },
   { local: "VercelContentCacheOptions", exported: "VercelContentCacheOptions" }
 ];
 const registerRuntimeImports = (resolveRuntimeModule) => {
@@ -390,11 +409,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",
@@ -632,7 +652,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)}`,
@@ -888,7 +908,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;
@@ -921,17 +941,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;
@@ -954,20 +974,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;
     }
   }
@@ -1132,13 +1152,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"],
@@ -1328,6 +1358,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);
@@ -1343,6 +1386,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();
@@ -1350,7 +1399,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}`);
@@ -1553,7 +1602,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],
@@ -1808,12 +1857,9 @@ const registerContentContextFinalization = ({
       return [name, runtimeCollection, collection];
     });
     const runtimeCollections = Object.fromEntries(collectionEntries.map(([name, runtimeCollection]) => [name, runtimeCollection]));
-    const privateRuntimeCollections = Object.fromEntries(collectionEntries.map(([name, runtimeCollection, collection]) => [
+    const privateRuntimeCollections = Object.fromEntries(collectionEntries.map(([name, runtimeCollection]) => [
       name,
-      {
-        ...runtimeCollection,
-        ...nuxt.options.dev && collection.schema ? { schema: collection.schema } : {}
-      }
+      runtimeCollection
     ]));
     const cacheIntegrity = hash({
       locales: resolvedContentContext.locales,
@@ -1883,6 +1929,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;

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>;

package/dist/parsers/reserved.js

@@ -0,0 +1,35 @@
+export const RESERVED_CONTENT_KEYS = [
+  "id",
+  "collection",
+  "locale",
+  "path",
+  "canonicalKey",
+  "type",
+  "file",
+  "resolved",
+  "variants",
+  "localePaths",
+  "unprefixedPath",
+  // Query-time only: `execute.ts`'s `withDirConfig` stamps the directory
+  // `.navigation` config onto variant-resolution (`resolveVariant`) results
+  // as a top-level `dir`, so an authored `dir:` frontmatter key would be
+  // silently clobbered there. It is not stamped at parse time (path-meta
+  // writes the directory name to `file.dir`, not top-level `dir`), so we
+  // reserve it here to strip+warn like the other system keys.
+  "dir"
+];
+export const stripReservedContentKeys = (source, fileId) => {
+  if (!source || typeof source !== "object") {
+    return {};
+  }
+  const reserved = new Set(RESERVED_CONTENT_KEYS);
+  for (const key of RESERVED_CONTENT_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const hint = key === "id" ? " Use `ref` for a stable authored alias." : "";
+      console.warn(
+        `[content] Ignoring reserved frontmatter key "${key}" in "${fileId}"; the system value wins.${hint}`
+      );
+    }
+  }
+  return Object.fromEntries(Object.entries(source).filter(([key]) => !reserved.has(key)));
+};

package/dist/parsers/yaml.js

@@ -1,19 +1,21 @@
 import { load } from "js-yaml";
 import { defineTransformer } from "./utils.js";
+import { stripReservedContentKeys } from "./reserved.js";
 export default defineTransformer({
   name: "Yaml",
   extensions: [".yml", ".yaml"],
-  parse: (_id, content) => {
+  parse: (id, content) => {
     const data = load(String(content));
     let parsed = data;
     if (Array.isArray(data)) {
-      console.warn(`YAML array is not supported in ${_id}, moving the array into the \`body\` key`);
+      console.warn(`YAML array is not supported in ${id}, moving the array into the \`body\` key`);
       parsed = { body: data };
     }
+    parsed = stripReservedContentKeys(parsed, id);
     return {
       ...parsed,
-      _id,
-      _type: "yaml"
+      id,
+      type: "yaml"
     };
   }
 });

package/dist/public/agent

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

package/dist/public/agent.d.ts

@@ -0,0 +1,17 @@
+/**
+ * LLM markdown output public API surface (Nitro / H3 contexts).
+ *
+ * The "agent" feature serves agent-readable content output — `/raw/*.md`,
+ * `/llms.txt`, `/llms-full.txt`, and the component→markdown serializers /
+ * registration primitives. It lives on its own subpath (`@lupinum/ginko-content/agent`)
+ * so it does not share the `./server` query facade. The `agent` code identifiers
+ * match the shipped module option name (`agent: {...}`).
+ *
+ * This is a PURE re-export: the registration API was reshaped once (per-app
+ * registry) in T4.2b — the moved names keep their call signatures.
+ */
+export { agentMarkdownPathForRoute, agentRawPathForRoute, normalizeAgentRoutePath } from '../features/agent/agent-paths.js';
+export { clearAgentMarkdownSerializers, blockquoteMarkdown, createAgentMarkdownRegistry, defineAgentMarkdownComponent, getMarkdownProp, jsonFenceMarkdown, linkMarkdown, queryMarkdownEnabledContent, registerAgentMarkdownComponent, registerAgentMarkdownComponents, registerAgentMarkdownSerializer, registerAgentMarkdownSerializers, renderMarkdownChildren, resolveAgentMarkdownOptions, resolveContentMarkdown, resolveContentMarkdownByRoute, xmlComponentMarkdown } from '../runtime/server/agent-markdown.js';
+export { buildAgentPageIndex, collectAgentMarkdownPrerenderRoutes, getAgentLocales, isSupportedAgentLocale, localeFromAgentPath, renderAgentMarkdownFrontmatter, renderAgentMarkdownPage, renderLlmsFullTxt, renderLlmsTxt, resolveMarkdownForPublicRoute, routePathFromIndexSlug, routePathFromRawSlug } from '../runtime/server/agent-site.js';
+export type { AgentMarkdown, AgentMarkdownComponent, AgentMarkdownComponentMap, AgentMarkdownContext, AgentMarkdownMeta, AgentMarkdownPublicSignals, AgentMarkdownRegistry, AgentMarkdownSerializer, AgentMarkdownSerializerMap, ResolvedAgentMarkdownOptions } from '../runtime/server/agent-markdown.js';
+export type { AgentPage, AgentPageSource } from '../runtime/server/agent-site.js';

package/dist/public/agent.js

@@ -0,0 +1,34 @@
+export { agentMarkdownPathForRoute, agentRawPathForRoute, normalizeAgentRoutePath } from "../features/agent/agent-paths.js";
+export {
+  clearAgentMarkdownSerializers,
+  blockquoteMarkdown,
+  createAgentMarkdownRegistry,
+  defineAgentMarkdownComponent,
+  getMarkdownProp,
+  jsonFenceMarkdown,
+  linkMarkdown,
+  queryMarkdownEnabledContent,
+  registerAgentMarkdownComponent,
+  registerAgentMarkdownComponents,
+  registerAgentMarkdownSerializer,
+  registerAgentMarkdownSerializers,
+  renderMarkdownChildren,
+  resolveAgentMarkdownOptions,
+  resolveContentMarkdown,
+  resolveContentMarkdownByRoute,
+  xmlComponentMarkdown
+} from "../runtime/server/agent-markdown.js";
+export {
+  buildAgentPageIndex,
+  collectAgentMarkdownPrerenderRoutes,
+  getAgentLocales,
+  isSupportedAgentLocale,
+  localeFromAgentPath,
+  renderAgentMarkdownFrontmatter,
+  renderAgentMarkdownPage,
+  renderLlmsFullTxt,
+  renderLlmsTxt,
+  resolveMarkdownForPublicRoute,
+  routePathFromIndexSlug,
+  routePathFromRawSlug
+} from "../runtime/server/agent-site.js";

package/dist/public/client.d.ts

@@ -5,9 +5,8 @@
  * pages use the thin `useContentPage` convenience helper built on top of it.
  */
 export { one, many, paginate, backlinks, resolveOne, variants, tree, neighbors } from '../runtime/app/composables/query-api.js';
-export { getCollectionPath } from '../runtime/query/routes.js';
-export type { CollectionPathOptions } from '../runtime/query/routes.js';
-export { agentMarkdownPathForRoute, agentRawPathForRoute, normalizeAgentRoutePath } from '../runtime/agent-paths.js';
+export { getCollectionPath } from '../features/query/routes.js';
+export type { CollectionPathOptions } from '../features/query/routes.js';
 export { useContentHead } from '../runtime/app/composables/head.js';
 export { useContentPage, useContentOne, useContentMany, useContentPagination, useContentBacklinks, useContentResolveOne, useContentVariants, useContentTree, useContentNavigation, useContentNeighbors } from '../runtime/app/composables/use-content.js';
 export type { UseContentPageOptions } from '../runtime/app/composables/use-content.js';