@lupinum/ginko-content 0.1.6 → 0.2.0

package/dist/core/query/execute.js

@@ -1,16 +1,26 @@
+import { isPlanRegex } from "./plan.js";
+import { sortLocalesCanonically } from "../content/locale.js";
 import { resolveGraphCanonicalKey, resolveGraphRouteVariant, resolveGraphVariant, resolveLocaleChain, selectGraphDocuments } from "../content/graph.js";
 import { ensureArray, get, omit, sortList, withKeys, withoutKeys } from "./operators.js";
 import { normalizeRouteMounts, routeToContentPathCandidates } from "../content/path.js";
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-const includesEntry = (haystack, entry) => typeof haystack === "string" ? haystack.includes(String(entry)) : haystack.includes(entry);
+const reviveRegex = (value) => isPlanRegex(value) ? new RegExp(value.source, value.flags) : value;
+const comparableValue = (value) => value instanceof Date ? value.toISOString() : value;
+const includesEntry = (haystack, entry) => typeof haystack === "string" ? isPlanRegex(entry) ? reviveRegex(entry).test(haystack) : haystack.includes(String(entry)) : haystack.some((value) => compareOperators.eq(value, entry));
 const compareOperators = {
-  eq: (item, value) => value instanceof RegExp ? value.test(String(item)) : item === value,
-  ne: (item, value) => value instanceof RegExp ? !value.test(String(item)) : item !== value,
-  gt: (item, value) => item > value,
-  gte: (item, value) => item >= value,
-  lt: (item, value) => item < value,
-  lte: (item, value) => item <= value,
-  in: (item, value) => ensureArray(value).some((entry) => Array.isArray(item) ? item.includes(entry) : compareOperators.eq(item, entry)),
+  eq: (item, value) => {
+    const operand = reviveRegex(value);
+    return operand instanceof RegExp ? operand.test(String(item)) : comparableValue(item) === comparableValue(operand);
+  },
+  ne: (item, value) => {
+    const operand = reviveRegex(value);
+    return operand instanceof RegExp ? !operand.test(String(item)) : comparableValue(item) !== comparableValue(operand);
+  },
+  gt: (item, value) => comparableValue(item) > comparableValue(value),
+  gte: (item, value) => comparableValue(item) >= comparableValue(value),
+  lt: (item, value) => comparableValue(item) < comparableValue(value),
+  lte: (item, value) => comparableValue(item) <= comparableValue(value),
+  in: (item, value) => ensureArray(value).some((entry) => Array.isArray(item) ? item.some((itemEntry) => compareOperators.eq(itemEntry, entry)) : compareOperators.eq(item, entry)),
   contains: (item, value) => {
     const haystack = Array.isArray(item) ? item : String(item);
     return ensureArray(value).every((entry) => includesEntry(haystack, entry));
@@ -29,11 +39,17 @@ const compareOperators = {
   type: (item, value) => typeof item === String(value),
   prefix: (item, value) => String(item || "").startsWith(String(value)),
   regex: (item, value) => {
-    if (value instanceof RegExp) {
-      return value.test(String(item || ""));
+    const operand = reviveRegex(value);
+    if (operand instanceof RegExp) {
+      return operand.test(String(item || ""));
+    }
+    if (typeof operand === "object" && operand !== null) {
+      throw new TypeError(
+        "$regex operand must be a plain string or a tagged { __ginkoContentQueryValue: 'RegExp', source, flags } wire value produced by the current PROVIDER_QUERY_VERSION lowering; received an untagged object (likely an old-wire { source, flags } regex predating PROVIDER_QUERY_VERSION)"
+      );
     }
-    const matched = String(value).match(/\/(.*)\/([dgimsuy]*)$/);
-    const regex = matched?.[1] ? new RegExp(matched[1], matched[2] || "") : new RegExp(String(value));
+    const matched = String(operand).match(/\/(.*)\/([dgimsuy]*)$/);
+    const regex = matched?.[1] ? new RegExp(matched[1], matched[2] || "") : new RegExp(String(operand));
     return regex.test(String(item || ""));
   }
 };
@@ -49,6 +65,8 @@ export const evaluateQueryPlanFilter = (item, filter) => {
       return filter.clauses.some((clause) => evaluateQueryPlanFilter(item, clause));
     case "not":
       return !evaluateQueryPlanFilter(item, filter.clause);
+    default:
+      throw new TypeError(`Unknown query filter node: ${filter.type}`);
   }
 };
 const collectFieldComparisons = (filter, field) => {
@@ -62,6 +80,9 @@ const collectFieldComparisons = (filter, field) => {
       if (filter.operator === "eq" && typeof filter.value === "string") {
         return [filter.value];
       }
+      if (filter.operator === "regex" && isPlanRegex(filter.value)) {
+        return [new RegExp(filter.value.source, filter.value.flags)];
+      }
       if (filter.operator === "regex" && filter.value instanceof RegExp) {
         return [filter.value];
       }
@@ -77,6 +98,8 @@ const collectFieldComparisons = (filter, field) => {
     case "or":
     case "not":
       return [];
+    default:
+      throw new TypeError(`Unknown query filter node: ${filter.type}`);
   }
 };
 const applyQueryPlanSort = (matched, plan) => {
@@ -142,21 +165,21 @@ const withDirConfig = (content, dirConfig) => {
   }
   return {
     ...content,
-    _dir: {
+    dir: {
       ...dirConfig,
       ...dirConfig.body
     }
   };
 };
 export const executeQueryPlanOnDocuments = (documents, plan) => {
-  const matched = documents.filter((item) => !plan.collection || item?._collection === plan.collection).filter((item) => evaluateQueryPlanFilter(item, plan.filter)).map((item) => ({ ...item }));
+  const matched = documents.filter((item) => !plan.collection || item?.collection === plan.collection).filter((item) => evaluateQueryPlanFilter(item, plan.filter)).map((item) => ({ ...item }));
   applyQueryPlanSort(matched, plan);
   return finalizeQueryPlanResponse(matched, plan);
 };
 const executeStandardPlan = (graph, plan) => {
   const candidates = selectGraphDocuments(graph, {
     collection: plan.collection,
-    paths: collectFieldComparisons(plan.filter, "_path")
+    paths: collectFieldComparisons(plan.filter, "path")
   });
   const matched = candidates.filter((item) => evaluateQueryPlanFilter(item, plan.filter)).map((item) => ({ ...item }));
   applyQueryPlanSort(matched, plan);
@@ -164,9 +187,13 @@ const executeStandardPlan = (graph, plan) => {
 };
 const executeLocalePlan = (graph, plan, options) => {
   const requestedLocale = plan.resolveLocale?.locale;
+  const collectionConfig = plan.collection ? options.collections?.[plan.collection] : void 0;
+  const collectionI18n = collectionConfig?.i18n && typeof collectionConfig.i18n === "object" ? collectionConfig.i18n : void 0;
+  const defaultLocale = collectionI18n?.defaultLocale || options.defaultLocale;
+  const locales = collectionI18n?.locales?.length ? collectionI18n.locales : [];
   const candidates = selectGraphDocuments(graph, {
     collection: plan.collection,
-    paths: collectFieldComparisons(plan.filter, "_path")
+    paths: collectFieldComparisons(plan.filter, "path")
   });
   const localeChain = resolveLocaleChain(
     requestedLocale,
@@ -177,18 +204,21 @@ const executeLocalePlan = (graph, plan, options) => {
   const merged = [];
   const indexByCanonical = /* @__PURE__ */ new Map();
   for (const item of candidates.filter((item2) => evaluateQueryPlanFilter(item2, plan.filter))) {
-    if (plan.resolveLocale?.exact && item._locale !== requestedLocale) {
+    if (plan.resolveLocale?.exact && item.locale !== requestedLocale) {
       continue;
     }
-    const key = item._canonicalKey || item.id || item._id || item._path;
-    const rank = localeRank.get(item._locale || "") ?? Number.MAX_SAFE_INTEGER;
-    const availableLocales = item._canonicalKey ? Object.keys(graph.byCanonical[item._canonicalKey] || {}) : [item._locale].filter(Boolean);
+    const key = item.canonicalKey || item.id || item.id || item.path;
+    const rank = localeRank.get(item.locale || "") ?? Number.MAX_SAFE_INTEGER;
+    const availableLocales = item.canonicalKey ? sortLocalesCanonically(Object.keys(graph.byCanonical[item.canonicalKey] || {}), { defaultLocale, locales }) : [item.locale].filter(Boolean);
     const enriched = {
       ...item,
-      _requestedLocale: requestedLocale,
-      _resolvedLocale: item._locale,
-      _fallback: item._locale !== requestedLocale,
-      _availableLocales: availableLocales
+      resolved: {
+        ...item.resolved || {},
+        requestedLocale,
+        locale: item.locale,
+        fallback: item.locale !== requestedLocale,
+        availableLocales
+      }
     };
     if (typeof key !== "string") {
       continue;
@@ -221,6 +251,7 @@ const executeVariantPlan = (graph, plan, options) => {
     if (!canonicalKey) return null;
     return resolveGraphVariant(graph, canonicalKey, plan.resolveVariant.locale, {
       defaultLocale,
+      locales: collectionI18n?.locales,
       fallback: plan.resolveVariant.fallback,
       exact: plan.resolveVariant.exact,
       localeFallback,
@@ -228,7 +259,7 @@ const executeVariantPlan = (graph, plan, options) => {
     });
   })() : plan.resolveVariant.route ? (() => {
     const localeChain = plan.resolveVariant.exact ? plan.resolveVariant.locale ? [plan.resolveVariant.locale] : [] : plan.resolveVariant.fallback?.length ? Array.from(new Set([plan.resolveVariant.locale, ...plan.resolveVariant.fallback].filter(Boolean))) : resolveLocaleChain(plan.resolveVariant.locale, defaultLocale, localeFallback || {});
-    const candidateLocales = localeChain.length ? localeChain : Array.from(new Set(Object.values(graph.byCanonical).flatMap((variants) => Object.keys(variants))));
+    const candidateLocales = localeChain.length ? localeChain : sortLocalesCanonically(Object.values(graph.byCanonical).flatMap((variants) => Object.keys(variants)), { defaultLocale, locales: collectionI18n?.locales });
     if (!candidateLocales.length) {
       candidateLocales.push("");
     }
@@ -246,6 +277,7 @@ const executeVariantPlan = (graph, plan, options) => {
       }
       const resolved = resolveGraphVariant(graph, canonicalKey, plan.resolveVariant.locale, {
         defaultLocale,
+        locales: collectionI18n?.locales,
         fallback: plan.resolveVariant.fallback,
         exact: plan.resolveVariant.exact,
         localeFallback,
@@ -260,6 +292,7 @@ const executeVariantPlan = (graph, plan, options) => {
     plan.resolveVariant.locale,
     {
       defaultLocale,
+      locales: collectionI18n?.locales,
       fallback: plan.resolveVariant.fallback,
       exact: plan.resolveVariant.exact,
       localeFallback,
@@ -270,23 +303,26 @@ const executeVariantPlan = (graph, plan, options) => {
     return { result: void 0 };
   }
   const content = graph.byId[variant.contentId];
-  if (plan.collection && content?._collection !== plan.collection) {
+  if (plan.collection && content?.collection !== plan.collection) {
     return { result: void 0 };
   }
-  const dirConfig = findDirConfig(graph, content?._path, variant.resolvedLocale);
+  const dirConfig = findDirConfig(graph, content?.path, variant.resolvedLocale);
   const variantPaths = Object.fromEntries(
     Object.entries(graph.byCanonical[variant.canonicalKey] || {}).map(([locale, entry]) => [locale, entry.path])
   );
   const enriched = {
     ...withDirConfig(content, dirConfig),
-    ...plan.resolveVariant.path ? { _requestedPath: plan.resolveVariant.path } : {},
-    ...plan.resolveVariant.route ? { _requestedRoute: plan.resolveVariant.route } : {},
-    ...plan.resolveVariant.ref ? { _requestedRef: plan.resolveVariant.ref } : {},
-    _requestedLocale: variant.requestedLocale,
-    _resolvedLocale: variant.resolvedLocale,
-    _fallback: variant.fallback,
-    _availableLocales: variant.availableLocales,
-    _variantPaths: variantPaths
+    resolved: {
+      ...content?.resolved || {},
+      ...plan.resolveVariant.path ? { requestedPath: plan.resolveVariant.path } : {},
+      ...plan.resolveVariant.route ? { requestedRoute: plan.resolveVariant.route } : {},
+      ...plan.resolveVariant.ref ? { requestedRef: plan.resolveVariant.ref } : {},
+      requestedLocale: variant.requestedLocale,
+      locale: variant.resolvedLocale,
+      fallback: variant.fallback,
+      availableLocales: variant.availableLocales,
+      variantPaths
+    }
   };
   const matched = evaluateQueryPlanFilter(enriched, plan.filter) ? [enriched] : [];
   return finalizeQueryPlanResponse(matched, plan);
@@ -302,8 +338,11 @@ export const executeQueryPlan = (graph, plan, options = {}) => {
 };
 export const resolveQueryPlanVariant = (graph, plan, options = {}) => {
   if (plan.resolveVariant) {
+    const collectionConfig = plan.collection ? options.collections?.[plan.collection] : void 0;
+    const collectionI18n = collectionConfig?.i18n && typeof collectionConfig.i18n === "object" ? collectionConfig.i18n : void 0;
     return resolveGraphRouteVariant(graph, plan.resolveVariant.path || plan.resolveVariant.route || "", plan.resolveVariant.locale, {
-      defaultLocale: options.defaultLocale,
+      defaultLocale: collectionI18n?.defaultLocale || options.defaultLocale,
+      locales: collectionI18n?.locales,
       fallback: plan.resolveVariant.fallback,
       exact: plan.resolveVariant.exact,
       localeFallback: options.localeFallback

package/dist/core/query/filter.js

@@ -50,7 +50,7 @@ export const compileWhere = (where) => {
       }
       continue;
     }
-    const targetKey = key === "path" ? "_path" : key;
+    const targetKey = key === "path" ? "path" : key;
     const operand = compileFieldOperand(value);
     if (operand !== void 0) {
       ;
@@ -110,7 +110,7 @@ export const compileQueryParams = (input) => {
       ...params.resolveLocale?.exact ? { exact: true } : {}
     };
   } else if (path) {
-    const pathClause = { _path: path };
+    const pathClause = { path };
     const existing = Array.isArray(params.where) ? params.where : params.where ? [params.where] : [];
     params.where = [...existing, pathClause];
   }

package/dist/core/query/lower.js

@@ -1,7 +1,75 @@
 import { assertSupportedQueryOperators, SUPPORTED_QUERY_OPERATORS } from "./operators.js";
+const serializeQueryValue = (value) => {
+  if (value instanceof RegExp) {
+    assertSupportedRegexFlags(value.flags);
+    return { __ginkoContentQueryValue: "RegExp", source: value.source, flags: value.flags };
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (Array.isArray(value)) {
+    return value.map(serializeQueryValue);
+  }
+  if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, serializeQueryValue(child)]));
+  }
+  return value;
+};
+const SUPPORTED_REGEX_FLAGS = /^[imsu]*$/;
+const assertSupportedRegexFlags = (flags) => {
+  if (!SUPPORTED_REGEX_FLAGS.test(flags)) {
+    throw new TypeError(`Unsupported RegExp flags "${flags}". Content queries support only i, m, s, and u.`);
+  }
+  try {
+    new RegExp("", flags);
+  } catch {
+    throw new TypeError(`Invalid RegExp flags "${flags}".`);
+  }
+};
+const STRING_REGEX_WITH_FLAGS = /\/(.*)\/([dgimsuy]+)$/;
+const assertSupportedRegexStringFlags = (value) => {
+  const matched = value.match(STRING_REGEX_WITH_FLAGS);
+  if (matched) {
+    assertSupportedRegexFlags(matched[2]);
+  }
+};
 const ensureQueryWhereArray = (where) => {
   return Array.isArray(where) ? [...where] : where ? [where] : [];
 };
+const REMOVED_ENVELOPE_FIELDS = {
+  _id: "id",
+  _path: "path",
+  _locale: "locale",
+  _collection: "collection",
+  _canonicalKey: "canonicalKey",
+  _type: "type",
+  _extension: "file.extension",
+  _navigation: "navigationFile",
+  _partial: "partial",
+  _draft: "draft"
+};
+const collectWhereFields = (condition, out) => {
+  for (const [key, value] of Object.entries(condition)) {
+    if ((key === "$and" || key === "$or") && value) {
+      for (const clause of ensureQueryWhereArray(value)) collectWhereFields(clause, out);
+    } else if (key === "$not" && value && typeof value === "object" && !Array.isArray(value)) {
+      collectWhereFields(value, out);
+    } else if (!key.startsWith("$")) {
+      out.add(key);
+    }
+  }
+};
+const warnOnRemovedEnvelopeFields = (params) => {
+  if (!import.meta.dev) return;
+  const fields = /* @__PURE__ */ new Set();
+  for (const condition of ensureQueryWhereArray(params.where)) collectWhereFields(condition, fields);
+  for (const option of params.sort || []) for (const key of Object.keys(option)) if (!key.startsWith("$")) fields.add(key);
+  for (const field of [...params.only || [], ...params.without || []]) fields.add(field);
+  for (const field of fields) {
+    const replacement = REMOVED_ENVELOPE_FIELDS[field.split(".")[0]];
+    if (replacement) console.warn(`[ginko-content] Query references removed envelope field "${field.split(".")[0]}" \u2014 use "${replacement}" instead; the old field no longer exists, so this clause has no effect.`);
+  }
+};
 const COMPARISON_OPERATORS = new Set(SUPPORTED_QUERY_OPERATORS);
 const collapse = (type, clauses) => {
   const filtered = clauses.filter((clause) => clause.type !== "true");
@@ -14,7 +82,7 @@ const collapse = (type, clauses) => {
   return { type, clauses: filtered };
 };
 const lowerFieldCondition = (field, value) => {
-  if (value && typeof value === "object" && !Array.isArray(value) && !(value instanceof RegExp)) {
+  if (value && typeof value === "object" && !Array.isArray(value) && !(value instanceof RegExp) && !(value instanceof Date)) {
     const objectValue = value;
     if ("$options" in objectValue && !("$regex" in objectValue)) {
       throw new TypeError("Query operator $options requires $regex.");
@@ -32,13 +100,16 @@ const lowerFieldCondition = (field, value) => {
           });
           continue;
         }
+        if (key === "$regex" && typeof nestedValue === "string" && typeof objectValue.$options !== "string") {
+          assertSupportedRegexStringFlags(nestedValue);
+        }
         clauses.push({
           type: "compare",
           field,
           // `key` is gated by the `COMPARISON_OPERATORS` set above; after
           // stripping the leading `$` it maps 1:1 to a `CompareOperator`.
           operator: key.slice(1),
-          value: key === "$regex" && typeof objectValue.$options === "string" && !(nestedValue instanceof RegExp) ? new RegExp(String(nestedValue), objectValue.$options) : nestedValue
+          value: key === "$regex" && typeof objectValue.$options === "string" && !(nestedValue instanceof RegExp) ? serializeQueryValue(regexValue(String(nestedValue), objectValue.$options)) : serializeQueryValue(nestedValue)
         });
         continue;
       }
@@ -50,9 +121,13 @@ const lowerFieldCondition = (field, value) => {
     type: "compare",
     field,
     operator: "eq",
-    value
+    value: serializeQueryValue(value)
   };
 };
+const regexValue = (source, flags) => {
+  assertSupportedRegexFlags(flags);
+  return { __ginkoContentQueryValue: "RegExp", source, flags };
+};
 const lowerWhereCondition = (condition) => {
   const clauses = [];
   for (const [key, value] of Object.entries(condition)) {
@@ -93,6 +168,7 @@ const lowerSort = (sort = []) => {
 };
 export const lowerQueryPlan = (params) => {
   assertSupportedQueryOperators(params.where);
+  warnOnRemovedEnvelopeFields(params);
   const resolveVariant = params.resolveVariant;
   return {
     collection: params.collection,

package/dist/core/query/params.js

@@ -49,13 +49,13 @@ export const normalizeContentQueryParams = (params, options = {}) => {
   };
   if (options.path) {
     if (normalized.first && where.length === 0) {
-      where.push({ _path: withoutTrailingSlash(options.path) });
+      where.push({ path: withoutTrailingSlash(options.path) });
     } else {
-      where.push({ _path: new RegExp(`^${escapeContentPath(options.path)}`) });
+      where.push({ path: new RegExp(`^${escapeContentPath(options.path)}`) });
     }
   }
   if (!normalized.sort?.length) {
-    normalized.sort = [{ _stem: 1, $numeric: true }];
+    normalized.sort = [{ "file.stem": 1, $numeric: true }];
   }
   if (normalized.resolveLocale?.locale && normalized.resolveLocale.fallback === true) {
     normalized.resolveLocale = {
@@ -68,15 +68,15 @@ export const normalizeContentQueryParams = (params, options = {}) => {
     };
   }
   if (options.includeDraftFilter) {
-    if (!findQueryWhere(where, (item) => typeof item._draft !== "undefined")) {
-      where.push({ _draft: { $ne: true } });
+    if (!findQueryWhere(where, (item) => typeof item.draft !== "undefined")) {
+      where.push({ draft: { $ne: true } });
     }
   }
   if (options.collectionI18n?.locales.length && !normalized.resolveLocale && !normalized.resolveVariant) {
-    const queryLocale = findQueryWhere(where, (item) => typeof item._locale !== "undefined")?._locale;
+    const queryLocale = findQueryWhere(where, (item) => typeof item.locale !== "undefined")?.locale;
     const defaultLocale = options.activeLocale || options.collectionI18n.defaultLocale;
     if (!queryLocale && defaultLocale) {
-      where.push({ _locale: defaultLocale });
+      where.push({ locale: defaultLocale });
     }
   }
   return normalized;

package/dist/core/query/plan.d.ts

@@ -15,6 +15,24 @@
  */
 /** Discriminator for a `{ type: 'compare' }` filter node. */
 export type CompareOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'contains' | 'containsAny' | 'icontains' | 'exists' | 'type' | 'regex' | 'prefix';
+/**
+ * JSON-pure representation of a regular expression on a compare node's value.
+ *
+ * The plan is the provider wire contract (CS-5) and must survive
+ * `JSON.parse(JSON.stringify(plan))` unchanged — a live `RegExp` instance
+ * serializes to `{}` and corrupts the wire. Lowering therefore stores regex
+ * operands as a tagged object; the executor reconstructs the `RegExp`
+ * immediately before matching (see `reviveRegex` in `./execute.ts`). The tag
+ * keeps user data shaped like `{ source, flags }` from being mistaken for a
+ * regex.
+ */
+export interface PlanRegex {
+    __ginkoContentQueryValue: 'RegExp';
+    source: string;
+    flags: string;
+}
+/** True when `value` is a JSON-pure regex operand. */
+export declare const isPlanRegex: (value: unknown) => value is PlanRegex;
 /**
  * Normalized where-clause AST. `{ type: 'true' }` is the identity node used
  * when the user did not pass any predicate; this keeps downstream code free

package/dist/core/query/plan.js

@@ -0,0 +1,7 @@
+export const isPlanRegex = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const record = value;
+  return record.__ginkoContentQueryValue === "RegExp" && typeof record.source === "string" && typeof record.flags === "string" && Object.keys(record).length === 3;
+};

package/dist/core/references/resolve.js

@@ -146,27 +146,24 @@ export const resolveMarkdownRenderRefs = (node, resolvedRefs, links, resolveRout
 export const buildReferenceTargets = (contents, locales = []) => {
   const targets = /* @__PURE__ */ new Map();
   for (const document of contents) {
-    if (!document || document._partial || document._navigation) {
+    if (!document || document.partial || document.navigationFile) {
       continue;
     }
-    const fileParts = (document._file || "").replace(/^\/+/, "").split("/").filter(Boolean);
-    const canonicalId = typeof document._canonicalKey === "string" && document._canonicalKey.length ? document._canonicalKey : fileParts.slice(fileParts[0] && locales.includes(fileParts[0]) ? 1 : 0).join("/").replace(/\.[^.]+$/, "");
+    const fileParts = (document.file?.path || "").replace(/^\/+/, "").split("/").filter(Boolean);
+    const canonicalId = typeof document.canonicalKey === "string" && document.canonicalKey.length ? document.canonicalKey : fileParts.slice(fileParts[0] && locales.includes(fileParts[0]) ? 1 : 0).join("/").replace(/\.[^.]+$/, "");
     if (!canonicalId) {
       continue;
     }
     targets.set(canonicalId, canonicalId);
-    if (typeof document.id === "string" && document.id.length) {
-      targets.set(document.id, canonicalId);
-    }
     if (typeof document.ref === "string" && document.ref.length) {
       targets.set(document.ref, canonicalId);
     }
-    const normalizedPath = normalizeReferenceValue(String(document._path || ""));
+    const normalizedPath = normalizeReferenceValue(String(document.path || ""));
     if (normalizedPath) {
       targets.set(normalizedPath, canonicalId);
     }
-    if (document._locale && normalizedPath) {
-      targets.set(`${document._locale}/${normalizedPath}`, canonicalId);
+    if (document.locale && normalizedPath) {
+      targets.set(`${document.locale}/${normalizedPath}`, canonicalId);
     }
   }
   return targets;

package/dist/features/agent/agent-markdown

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

package/dist/features/agent/agent-markdown.d.ts

@@ -0,0 +1,116 @@
+import type { MarkdownNode, ParsedContent } from '../../types/content';
+import type { AgentMetadataField, ContentCollectionConfig } from '../../types/config';
+export interface AgentMarkdownPublicSignals {
+    search?: 'yes' | 'no';
+    aiInput?: 'yes' | 'no';
+    aiTrain?: 'yes' | 'no';
+}
+export interface ResolvedAgentMarkdownOptions {
+    includeInIndex: boolean;
+    includeInFull: boolean;
+    metadata: AgentMetadataField[];
+}
+export interface AgentMarkdown {
+    path: string;
+    markdownPath: string;
+    rawPath: string;
+    locale?: string;
+    collection: string;
+    title: string;
+    description: string;
+    markdown: string;
+    sourceFile?: string;
+    canonicalUrl: string;
+    lastModified?: string;
+    publicSignals?: AgentMarkdownPublicSignals;
+    metadataFields: string[];
+    includeInIndex: boolean;
+    includeInFull: boolean;
+}
+export type AgentMarkdownMeta = Omit<AgentMarkdown, 'markdown'>;
+/**
+ * The single context the agent-markdown walker is a pure function of.
+ *
+ * It carries (a) the per-app serializer {@link AgentMarkdownRegistry} and
+ * (b) the config-derived data the walker reads (markdown tag aliases, the
+ * configured locales, and the default locale used for link prefixing), in
+ * addition to the document coordinates and the per-node render helpers passed
+ * to serializers. The walker holds no module-global state: everything it reads
+ * arrives on this context, built by the runtime handlers from the resolved
+ * content config.
+ */
+export interface AgentMarkdownContext {
+    collection: string;
+    page: ParsedContent;
+    path: string;
+    locale?: string;
+    /** Per-app serializer registry the walker resolves component tags against. */
+    registry: AgentMarkdownRegistry;
+    /** Component tag alias map (the resolved config's `markdown.tags`). */
+    tagAliases: Record<string, string>;
+    /** Default locale used when prefixing localized links. */
+    defaultLocale: string;
+    /** Configured locales used when prefixing localized links. */
+    locales: string[];
+    prop: (name: string) => string;
+    props: (node?: MarkdownNode) => Record<string, unknown>;
+    cleanProps: (node?: MarkdownNode) => Record<string, unknown>;
+    children: (node?: MarkdownNode) => string;
+    renderChildren: (node: MarkdownNode) => string;
+    renderNode: (node: MarkdownNode) => string;
+    blockquote: (value: string) => string;
+    jsonFence: (value: unknown) => string;
+    link: (label: string, href: string) => string;
+    omitted: (name: string, reason?: string) => string;
+    xmlComponent: (name: string, props?: Record<string, unknown>, children?: string) => string;
+}
+/**
+ * The environment slice the runtime handlers supply to the walker entrypoint;
+ * the walker derives the per-node render helpers from it. Equivalent to an
+ * {@link AgentMarkdownContext} without the closure-bound render helpers.
+ */
+export type AgentMarkdownRenderContext = Pick<AgentMarkdownContext, 'collection' | 'page' | 'path' | 'locale' | 'registry' | 'tagAliases' | 'defaultLocale' | 'locales'>;
+export type AgentMarkdownSerializer = (node: MarkdownNode, ctx: AgentMarkdownContext) => string | null | undefined;
+export type AgentMarkdownSerializerMap = Record<string, AgentMarkdownSerializer>;
+export interface AgentMarkdownSerializerRegistrationOptions {
+    override?: boolean;
+}
+export interface AgentMarkdownComponent {
+    render: AgentMarkdownSerializer;
+}
+export type AgentMarkdownComponentMap = Record<string, AgentMarkdownComponent>;
+/**
+ * A per-app serializer registry. Each call to {@link createAgentMarkdownRegistry}
+ * returns an isolated registry with its own backing store — there is no
+ * module-global serializer map, so re-running module setup (dev HMR) yields a
+ * fresh registry instead of accumulating or colliding with prior registrations.
+ */
+export interface AgentMarkdownRegistry {
+    register: (name: string, serializer: AgentMarkdownSerializer, options?: AgentMarkdownSerializerRegistrationOptions) => void;
+    registerMany: (entries: AgentMarkdownSerializerMap, options?: AgentMarkdownSerializerRegistrationOptions) => void;
+    registerComponent: (name: string, component: AgentMarkdownComponent, options?: AgentMarkdownSerializerRegistrationOptions) => void;
+    registerComponents: (entries: AgentMarkdownComponentMap, options?: AgentMarkdownSerializerRegistrationOptions) => void;
+    clear: () => void;
+    get: (name: string) => AgentMarkdownSerializer | undefined;
+}
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const getMarkdownProp: (node: MarkdownNode, name: string) => string;
+export declare const renderMarkdownChildren: (node: MarkdownNode, ctx: AgentMarkdownContext) => string;
+export declare const blockquoteMarkdown: (value: string) => string;
+export declare const escapeMarkdownLinkLabel: (value: string) => string;
+export declare const linkMarkdown: (label: string, href: string) => string;
+export declare const imageMarkdown: (alt: string, src: string) => string;
+export declare const jsonFenceMarkdown: (value: unknown) => string;
+export declare const cleanPropsObject: (props: unknown) => Record<string, unknown>;
+export declare const xmlComponentMarkdown: (name: string, props?: Record<string, unknown>, children?: string) => string;
+export declare const defineAgentMarkdownComponent: (component: AgentMarkdownComponent) => AgentMarkdownComponent;
+/**
+ * Create an isolated per-app serializer registry. The backing store is local to
+ * the returned registry — two registries never share serializers — which is what
+ * makes agent markdown serialization safe under dev HMR and across concurrent
+ * apps. Registration/precedence semantics match the historical global registry:
+ * re-registering the same serializer under a name is a no-op, a different one
+ * throws unless `{ override: true }`.
+ */
+export declare const createAgentMarkdownRegistry: () => AgentMarkdownRegistry;
+export declare const resolveAgentMarkdownOptions: (collection: ContentCollectionConfig | undefined) => ResolvedAgentMarkdownOptions | null;