@lupinum/ginko-content 0.1.6 → 0.2.0

package/compatibility.json

@@ -1,7 +1,7 @@
 {
   "name": "Ginko Content release compatibility",
   "releaseStack": {
-    "@lupinum/ginko-content": "0.1.6",
+    "@lupinum/ginko-content": "0.2.0",
     "@lupinum/ginko-cms": "0.1.2",
     "@lupinum/ginko-cms-convex": "0.1.1",
     "@lupinum/ginko-cms-contract": "0.1.1"

package/dist/cli.mjs

@@ -505,7 +505,7 @@ async function inspectRepeatedLocalePrefixes(rootDir, locales) {
           severity: "error",
           file: relativeFile,
           message: `Repeated locale prefix "${repeatedPath}" found in generated output.`,
-          suggestion: "Use locale-neutral raw _path values in content links and let Nuxt I18n add the route prefix once."
+          suggestion: "Bind route-ready item.path values from useContentMany(), navigation, or search results instead of manually prefixing locale paths."
         });
         break;
       }
@@ -573,7 +573,7 @@ async function inspectI18nSearchIndex(rootDir, locales) {
           return false;
         }
         const item = record;
-        return item.locale === locale || item._locale === locale || typeof item.path === "string" && item.path.startsWith(`/${locale}/`);
+        return item.locale === locale || typeof item.path === "string" && item.path.startsWith(`/${locale}/`);
       });
       if (!hasLocaleRecords) {
         findings.push({

package/dist/cms-contract/build.js

@@ -33,6 +33,8 @@ export class CmsContractSchemaUnsupportedError extends Error {
     this.unsupported = unsupported;
     this.name = "CmsContractSchemaUnsupportedError";
   }
+  collectionSlug;
+  unsupported;
 }
 export function buildCmsContract(config, options) {
   const include = options.include ? new Set(options.include) : null;
@@ -59,7 +61,7 @@ function buildCollectionContract(slug, collection, options) {
   const contract = {
     slug,
     label: cms.label ?? deriveLabel(slug),
-    type: cms.type ?? deriveCollectionType(slug, collection),
+    type: resolveCollectionType(slug, cms),
     icon: cms.icon ?? null,
     locales,
     defaultLocale,
@@ -122,9 +124,11 @@ function isSingleRouteSource(collection) {
   const routeSources = sources.filter((source) => typeof source === "string");
   return routeSources.length === 1 && !/[{*?[\]]/.test(routeSources[0] ?? "");
 }
-function deriveCollectionType(slug, collection) {
-  if (collection.cms?.type) return collection.cms.type;
-  if (slug === "docs" || collection.cms?.route?.rootSlug) return "tree";
+function resolveCollectionType(slug, cms) {
+  if (cms.type) return cms.type;
+  console.warn(
+    `[ginko-content] Collection "${slug}" has no explicit \`cms.type\`; defaulting to 'flat'. Declare \`cms: { type: 'flat' | 'tree' }\` in the collection config to silence this warning.`
+  );
   return "flat";
 }
 function deriveLabel(slug) {
@@ -142,15 +146,15 @@ function buildFields(collection, cms, isLocalized) {
     const existing = fields.get(key);
     fields.set(key, mergeField(existing, key, override, isLocalized));
   }
-  return [...fields.values()].sort((a, b) => (a.order ?? 0) - (b.order ?? 0)).map((field2, index) => ({ ...field2, order: index }));
+  return [...fields.values()];
 }
 function implicitPageFields(collection, isLocalized) {
   const fields = [
-    field({ key: "title", type: "text", required: true, localized: isLocalized }),
-    field({ key: "description", type: "textarea", localized: isLocalized })
+    field({ key: "title", type: "text", role: "title", required: true, localized: isLocalized }),
+    field({ key: "description", type: "textarea", role: "description", localized: isLocalized })
   ];
   if (isMarkdownCollection(collection)) {
-    fields.push(field({ key: "bodyMdc", type: "richtext", localized: isLocalized }));
+    fields.push(field({ key: "bodyMdc", type: "richtext", role: "body", localized: isLocalized }));
   }
   return fields;
 }
@@ -240,10 +244,7 @@ function getArrayElement(schema) {
   return def?.element ?? def?.type ?? null;
 }
 function fieldsFromObjectSchema(schema, isLocalized) {
-  return Object.entries(getObjectShape(unwrapSchema(schema))).sort(([left], [right]) => left.localeCompare(right)).map(([key, child], index) => ({
-    ...fieldFromSchema(key, child, isLocalized),
-    order: index
-  }));
+  return Object.entries(getObjectShape(unwrapSchema(schema))).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => fieldFromSchema(key, child, isLocalized));
 }
 function fieldFromMetadata(key, metadata, schema, isLocalized, required) {
   const localized = metadata.localized ?? isLocalized;
@@ -313,14 +314,11 @@ function mergeField(existing, key, override, isLocalized) {
     ...override.description !== void 0 ? { description: override.description } : {},
     ...override.required !== void 0 ? { required: override.required } : {},
     ...override.localized !== void 0 ? { localized: override.localized } : {},
-    ...override.hidden !== void 0 ? { hidden: override.hidden } : {},
     ...override.searchable !== void 0 ? { searchable: override.searchable } : {},
     ...override.sortable !== void 0 ? { sortable: override.sortable } : {},
-    ...override.order !== void 0 ? { order: override.order } : {},
-    ...override.width !== void 0 ? { width: override.width } : {},
     ...override.defaultValue !== void 0 ? { defaultValue: override.defaultValue } : {},
     ...override.validation !== void 0 ? { validation: override.validation } : {},
-    ...override.condition !== void 0 ? { condition: override.condition } : {},
+    ...override.editor !== void 0 ? { editor: override.editor } : {},
     ...override.options !== void 0 ? { options: override.options } : {},
     ...override.relation !== void 0 ? { relation: override.relation } : {},
     ...override.min !== void 0 ? { min: override.min } : {},
@@ -334,22 +332,19 @@ function field(input) {
   return {
     key: input.key,
     type: input.type,
+    role: input.role ?? null,
     label: input.label ?? null,
     description: input.description ?? null,
     required: input.required ?? false,
     localized: input.localized ?? false,
-    hidden: input.hidden ?? false,
     searchable: input.searchable ?? false,
     sortable: input.sortable ?? false,
-    order: input.order ?? 0,
-    width: input.width ?? "full",
     defaultValue: input.defaultValue,
     options: input.options ?? null,
     relation: input.relation ?? null,
     media: input.media ?? null,
     fields: input.fields ?? null,
     validation: input.validation ?? null,
-    condition: input.condition ?? null,
     min: input.min ?? null,
     max: input.max ?? null,
     step: input.step ?? null,

package/dist/cms-contract/types.d.ts

@@ -63,15 +63,13 @@ export interface CmsCollectionRouting {
 export interface CmsFieldContract {
     key: string;
     type: ContentCmsFieldType;
+    role?: 'title' | 'description' | 'body' | null;
     label?: string | Record<string, string> | null;
     description?: string | null;
     required: boolean;
     localized: boolean;
-    hidden: boolean;
     searchable: boolean;
     sortable: boolean;
-    order: number;
-    width: 'full' | 'half';
     defaultValue?: unknown;
     options?: string[] | null;
     relation?: ContentCmsRelationConfig | null;
@@ -81,12 +79,19 @@ export interface CmsFieldContract {
     } | null;
     fields?: CmsFieldContract[] | null;
     validation?: Record<string, unknown> | null;
-    condition?: Record<string, unknown> | null;
     min?: number | null;
     max?: number | null;
     step?: number | null;
     slugFrom?: string | null;
     language?: string | null;
+    /**
+     * Opaque editor-layout passthrough forwarded byte-for-byte from
+     * `ContentCmsFieldConfig.editor`. ginko-content neither types nor interprets
+     * its contents — pure layout policy (width, display order, hidden state,
+     * conditional visibility, ...) lives here and its schema is owned by the
+     * consuming CMS. Absent when the collection config supplied no `editor`.
+     */
+    editor?: Record<string, unknown>;
 }
 /**
  * Reference to a schema validation artifact. The actual artifact (a serialized,
@@ -94,9 +99,9 @@ export interface CmsFieldContract {
  * shipped alongside the contract. The CMS reads the checksum to verify the
  * artifact it holds matches the contract it imported.
  *
- * Keeping the artifact behind a ref (rather than embedding it inline) lets the
- * CMS drop the artifact when it doesn't need publish validation (e.g. for a
- * code-only data collection).
+ * The artifact bytes are embedded so a contract consumer can validate content
+ * without fetching a second artifact, while `artifactId` and `checksum` keep the
+ * embedded payload identifiable and verifiable.
  */
 export interface CmsSchemaArtifactRef {
     /** Stable id used to look up the artifact in the artifact registry. */

package/dist/core/content/document

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

package/dist/core/content/document.d.ts

@@ -0,0 +1,16 @@
+import type { MissingDocument, ParsedContent } from '../../types/content';
+/**
+ * True when a loader result is a {@link MissingDocument} sentinel rather than a
+ * real parsed document. Keyed on the `missing: true` discriminant that every
+ * stub site sets — NOT on `body === null`: a real document may legitimately
+ * have a null body (data-style documents from custom transformers, e.g. the
+ * transformer example's `.names` files) and must not be treated as missing.
+ */
+export declare const isMissingDocument: (document: ParsedContent | MissingDocument) => document is MissingDocument;
+/**
+ * Shared type guard narrowing a loader result to a servable
+ * {@link ParsedContent}. Replaces the per-call-site `body !== null` checks so
+ * every consumer (snapshot writer, content list, single-document lookup) agrees
+ * on what counts as a real document.
+ */
+export declare const isRealDocument: (document: ParsedContent | MissingDocument) => document is ParsedContent;

package/dist/core/content/document.js

@@ -0,0 +1,2 @@
+export const isMissingDocument = (document) => document.missing === true;
+export const isRealDocument = (document) => !isMissingDocument(document);

package/dist/core/content/graph.d.ts

@@ -76,7 +76,7 @@ export declare const resolveLocaleChain: (requestedLocale: string | undefined, d
  * `storage/content.ts:createServerQueryFetch` and
  * `memoizeRuntimeValue(event, 'graph', ...)`.
  *
- * INVARIANT: documents without `_path` are still indexed by id (so refs can
+ * INVARIANT: documents without `path` are still indexed by id (so refs can
  * find them) but are excluded from path/route/canonical lookups. Partials
  * and navigation documents are likewise indexed by id only.
  */
@@ -97,6 +97,7 @@ export declare const buildContentGraph: (documents: ParsedContent[], options?: {
  */
 export declare const resolveGraphVariant: (graph: ContentGraph, canonicalKey: string, requestedLocale?: string, options?: {
     defaultLocale?: string;
+    locales?: string[];
     fallback?: string[];
     exact?: boolean;
     localeFallback?: Record<string, string[]>;
@@ -120,6 +121,7 @@ export declare const resolveGraphVariant: (graph: ContentGraph, canonicalKey: st
  */
 export declare const resolveGraphRouteVariant: (graph: ContentGraph, routePath: string, requestedLocale?: string, options?: {
     defaultLocale?: string;
+    locales?: string[];
     fallback?: string[];
     exact?: boolean;
     localeFallback?: Record<string, string[]>;

package/dist/core/content/graph.js

@@ -1,4 +1,5 @@
 import { normalizeReferenceValue, buildReferenceTargets } from "../references/resolve.js";
+import { sortLocalesCanonically } from "./locale.js";
 const normalizePath = (path) => {
   if (!path || path === "/") {
     return "/";
@@ -27,44 +28,44 @@ export const buildContentGraph = (documents, options = {}) => {
   const byNavigationPath = {};
   const defaultLocale = options.defaultLocale || "";
   for (const document of documents) {
-    const documentId = document._id || `${document._collection || "content"}:${document._path || "document"}`;
+    const documentId = document.id || `${document.collection || "content"}:${document.path || "document"}`;
     byId[documentId] = document;
-    if (!document._path) {
+    if (!document.path) {
       continue;
     }
-    const path = normalizePath(document._path);
+    const path = normalizePath(document.path);
     manifest.paths[path] ||= [];
-    if (document._locale === defaultLocale) {
+    if (document.locale === defaultLocale) {
       manifest.paths[path].unshift(documentId);
     } else {
       manifest.paths[path].push(documentId);
     }
-    if (document._collection) {
-      manifest.collections[document._collection] ||= [];
-      manifest.collections[document._collection].push(documentId);
+    if (document.collection) {
+      manifest.collections[document.collection] ||= [];
+      manifest.collections[document.collection].push(documentId);
     }
-    if (document._navigation) {
-      const locale2 = document._locale || defaultLocale;
+    if (document.navigationFile) {
+      const locale2 = document.locale || defaultLocale;
       byNavigationPath[path] ||= {};
       byNavigationPath[path][locale2] = document;
     }
-    const isVariantDocument = !document._partial && !document._navigation && document._canonicalKey;
+    const isVariantDocument = !document.partial && !document.navigationFile && document.canonicalKey;
     if (!isVariantDocument) {
       continue;
     }
-    const locale = document._locale || defaultLocale;
+    const locale = document.locale || defaultLocale;
     const variant = {
-      canonicalKey: document._canonicalKey,
+      canonicalKey: document.canonicalKey,
       contentId: documentId,
       locale,
       path,
       document
     };
-    manifest.byCanonical[document._canonicalKey] ||= {};
-    manifest.byCanonical[document._canonicalKey][locale] = variant;
-    manifest.byRoute[`${locale}:${path}`] = document._canonicalKey;
-    if (document._type === "markdown" && typeof document.ref === "string" && document.ref.length) {
-      manifest.byRef[document.ref] = document._canonicalKey;
+    manifest.byCanonical[document.canonicalKey] ||= {};
+    manifest.byCanonical[document.canonicalKey][locale] = variant;
+    manifest.byRoute[`${locale}:${path}`] = document.canonicalKey;
+    if (document.type === "markdown" && typeof document.ref === "string" && document.ref.length) {
+      manifest.byRef[document.ref] = document.canonicalKey;
     }
   }
   for (const [canonicalKey, variants] of Object.entries(manifest.byCanonical)) {
@@ -87,7 +88,7 @@ export const buildContentGraph = (documents, options = {}) => {
     byRoute: manifest.byRoute,
     byRef: manifest.byRef,
     byNavigationPath,
-    referenceTargets: buildReferenceTargets(documents.filter((document) => !document._partial && !document._navigation), options.locales || []),
+    referenceTargets: buildReferenceTargets(documents.filter((document) => !document.partial && !document.navigationFile), options.locales || []),
     manifest
   };
 };
@@ -101,7 +102,7 @@ export const resolveGraphVariant = (graph, canonicalKey, requestedLocale, option
   if (!Object.keys(scopedVariants).length) {
     return null;
   }
-  const availableLocales = Object.keys(scopedVariants);
+  const availableLocales = sortLocalesCanonically(Object.keys(scopedVariants), options);
   const localeChain = options.exact ? requestedLocale ? [requestedLocale] : [] : options.fallback?.length ? Array.from(new Set([requestedLocale, ...options.fallback].filter(Boolean))) : resolveLocaleChain(requestedLocale, options.defaultLocale, options.localeFallback || {});
   const resolvedLocale = localeChain.find((locale) => scopedVariants[locale]) || (options.exact ? void 0 : availableLocales[0]);
   if (resolvedLocale === void 0) {
@@ -122,7 +123,7 @@ export const resolveGraphVariant = (graph, canonicalKey, requestedLocale, option
 export const resolveGraphRouteVariant = (graph, routePath, requestedLocale, options = {}) => {
   const normalizedPath = normalizePath(routePath);
   const localeChain = options.exact ? requestedLocale ? [requestedLocale] : [] : options.fallback?.length ? Array.from(new Set([requestedLocale, ...options.fallback].filter(Boolean))) : resolveLocaleChain(requestedLocale, options.defaultLocale, options.localeFallback || {});
-  const localesToSearch = localeChain.length ? localeChain : Array.from(new Set(Object.values(graph.byCanonical).flatMap((variants) => Object.keys(variants))));
+  const localesToSearch = localeChain.length ? localeChain : sortLocalesCanonically(Object.values(graph.byCanonical).flatMap((variants) => Object.keys(variants)), options);
   for (const locale of localesToSearch) {
     const canonicalKey = graph.byRoute[`${locale}:${normalizedPath}`];
     if (!canonicalKey) {

package/dist/core/content/locale.d.ts

@@ -9,7 +9,7 @@
  *  2. **Inline locale variant id** — YAML/JSON sources can carry locale
  *     overrides inline (`i18n: { de: { title: '…' } }`). We split each
  *     such document into one variant per locale at ingest; the
- *     synthetic variants share a `_id` shape of
+ *     synthetic variants share a `id` shape of
  *     `${sourceId}#__locale=${locale}`. `splitInlineLocaleVariantId`
  *     reverses that for lookups.
  *
@@ -33,6 +33,11 @@ export declare const INLINE_LOCALE_ID_SEPARATOR = "#__locale=";
  * buildLocaleFallbackChain('en', 'en')                 // []
  */
 export declare const buildLocaleFallbackChain: (locale: string, defaultLocale?: string, fallback?: Record<string, string[]>) => string[];
+/** Canonical locale order: default locale first, then configured locale order. */
+export declare const sortLocalesCanonically: (locales: string[], config?: {
+    defaultLocale?: string;
+    locales?: string[];
+}) => string[];
 /**
  * Split an inline-variant id back into `{ sourceId, locale }`. Returns the
  * input unchanged (with `locale: undefined`) when no separator is found.

package/dist/core/content/locale.js

@@ -33,6 +33,17 @@ export const buildLocaleFallbackChain = (locale, defaultLocale, fallback) => {
     ...defaultLocale && defaultLocale !== locale ? [defaultLocale] : []
   ]));
 };
+export const sortLocalesCanonically = (locales, config = {}) => {
+  const order = [
+    ...config.defaultLocale ? [config.defaultLocale] : [],
+    ...config.locales || []
+  ];
+  const rank = new Map(order.map((locale, index) => [locale, index]));
+  const inputOrder = new Map(locales.map((locale, index) => [locale, index]));
+  return Array.from(new Set(locales)).sort(
+    (left, right) => (rank.get(left) ?? Number.MAX_SAFE_INTEGER) - (rank.get(right) ?? Number.MAX_SAFE_INTEGER) || (inputOrder.get(left) ?? Number.MAX_SAFE_INTEGER) - (inputOrder.get(right) ?? Number.MAX_SAFE_INTEGER)
+  );
+};
 export const splitInlineLocaleVariantId = (id) => {
   const separatorIndex = id.indexOf(INLINE_LOCALE_ID_SEPARATOR);
   if (separatorIndex === -1) {
@@ -44,7 +55,7 @@ export const splitInlineLocaleVariantId = (id) => {
   };
 };
 export const expandDataLocaleVariants = (document, i18nConfig) => {
-  if (!i18nConfig || document._type !== "yaml" && document._type !== "json") {
+  if (!i18nConfig || document.type !== "yaml" && document.type !== "json") {
     return [document];
   }
   const rawI18n = isPlainObject(document.i18n) ? document.i18n : void 0;
@@ -52,15 +63,15 @@ export const expandDataLocaleVariants = (document, i18nConfig) => {
     return [document];
   }
   const { i18n: _removed, ...baseDocument } = document;
-  const sourceLocale = document._locale || i18nConfig.defaultLocale;
-  const variants = [{ ...baseDocument, _locale: sourceLocale }];
+  const sourceLocale = document.locale || i18nConfig.defaultLocale;
+  const variants = [{ ...baseDocument, locale: sourceLocale }];
   for (const locale of i18nConfig.locales) {
     if (locale === sourceLocale) {
       continue;
     }
     const override = rawI18n[locale];
     if (typeof override !== "undefined" && !isPlainObject(override)) {
-      console.warn(`[content] Inline i18n override for locale "${locale}" in "${document._id}" must be an object. Skipping invalid override.`);
+      console.warn(`[content] Inline i18n override for locale "${locale}" in "${document.id}" must be an object. Skipping invalid override.`);
       continue;
     }
     if (!isPlainObject(override)) {
@@ -69,8 +80,8 @@ export const expandDataLocaleVariants = (document, i18nConfig) => {
     const merged = mergeLocaleOverride(baseDocument, override);
     variants.push({
       ...merged,
-      _id: `${document._id}${INLINE_LOCALE_ID_SEPARATOR}${locale}`,
-      _locale: locale
+      id: `${document.id}${INLINE_LOCALE_ID_SEPARATOR}${locale}`,
+      locale
     });
   }
   return variants;

package/dist/core/content/path.d.ts

@@ -1,9 +1,9 @@
 export declare const describeId: (id: string) => {
-    _source: string;
-    _path: string;
-    _extension: string;
-    _file: string;
-    _basename: string;
+    source: string;
+    path: string;
+    extension: string;
+    file: string;
+    basename: string;
 };
 export declare const isDraftPath: (path: string) => boolean;
 export declare const isPartialPath: (path: string) => boolean;

package/dist/core/content/path.js

@@ -4,18 +4,18 @@ import { slugifyUrlSegment } from "./slug.js";
 const SEMVER_REGEX = /^(\d+)(\.\d+)*(\.x)?$/;
 const NUMERIC_PREFIX_RE = /^(\d+)\.(.+)$/;
 export const describeId = (id) => {
-  const [_source, ...parts] = id.split(":");
-  const [, basename, _extension] = parts[parts.length - 1]?.match(/(.*)\.([^.]+)$/) || [];
+  const [source, ...parts] = id.split(":");
+  const [, basename, extension] = parts[parts.length - 1]?.match(/(.*)\.([^.]+)$/) || [];
   if (basename) {
     parts[parts.length - 1] = basename;
   }
-  const _path = (parts || []).join("/");
+  const path = (parts || []).join("/");
   return {
-    _source,
-    _path,
-    _extension,
-    _file: _extension ? `${_path}.${_extension}` : _path,
-    _basename: basename || ""
+    source,
+    path,
+    extension,
+    file: extension ? `${path}.${extension}` : path,
+    basename: basename || ""
   };
 };
 export const isDraftPath = (path) => /\.draft(\/|\.|$)/.test(path);

package/dist/core/content/snapshot

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

package/dist/core/content/snapshot.d.ts

@@ -0,0 +1,25 @@
+import type { ParsedContent } from '../../types/content';
+export declare const CONTENT_SNAPSHOT_VERSION: 1;
+export interface ContentSnapshot {
+    version: typeof CONTENT_SNAPSHOT_VERSION;
+    /** Must equal the runtime config's cache integrity; mismatch means a stale artifact. */
+    integrity: string;
+    generatedAt: number;
+    /** Fully-qualified, locale-suffixed ids. One per stored variant. */
+    documentIds: string[];
+    /** Source ids represented by the stored documents. Completeness is asserted on these. */
+    documentSourceIds: string[];
+    documents: ParsedContent[];
+}
+export interface BuildContentSnapshotArgs {
+    integrity: string;
+    documents: ParsedContent[];
+    sourceIds: string[];
+    now: number;
+}
+/** Build error carrying every offending path; never fail on just the first one. */
+export declare class ContentSnapshotError extends Error {
+}
+export declare const buildContentSnapshot: (args: BuildContentSnapshotArgs) => ContentSnapshot;
+export declare const isContentSnapshot: (value: unknown) => value is ContentSnapshot;
+export declare const assertSnapshotComplete: (snapshot: ContentSnapshot, sourceIds: string[]) => void;

package/dist/core/content/snapshot.js

@@ -0,0 +1,99 @@
+import { splitInlineLocaleVariantId } from "./locale.js";
+export const CONTENT_SNAPSHOT_VERSION = 1;
+export class ContentSnapshotError extends Error {
+}
+const documentIdOf = (document) => document.id;
+const documentSourceIdOf = (document) => splitInlineLocaleVariantId(documentIdOf(document)).sourceId;
+const isPlainObject = (value) => {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+const describeSymbolKey = (symbol) => `[${String(symbol)}] (symbol-keyed property)`;
+const collectNonJsonValues = (value, path, ancestors, offenders) => {
+  if (value === null || value === void 0 || typeof value === "string" || typeof value === "boolean") {
+    return;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) offenders.push(path);
+    return;
+  }
+  if (typeof value !== "object") {
+    offenders.push(path);
+    return;
+  }
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) offenders.push(path);
+    return;
+  }
+  if (ancestors.has(value)) {
+    offenders.push(path);
+    return;
+  }
+  ancestors.add(value);
+  try {
+    for (const symbol of Object.getOwnPropertySymbols(value)) {
+      if (Object.prototype.propertyIsEnumerable.call(value, symbol)) {
+        offenders.push(`${path}${describeSymbolKey(symbol)}`);
+      }
+    }
+    if (Array.isArray(value)) {
+      for (let index = 0; index < value.length; index += 1) {
+        if (!(index in value)) {
+          offenders.push(`${path}[${index}]`);
+          continue;
+        }
+        collectNonJsonValues(value[index], `${path}[${index}]`, ancestors, offenders);
+      }
+      return;
+    }
+    if (!isPlainObject(value)) {
+      offenders.push(path);
+      return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+      collectNonJsonValues(child, `${path}.${key}`, ancestors, offenders);
+    }
+  } finally {
+    ancestors.delete(value);
+  }
+};
+export const buildContentSnapshot = (args) => {
+  const lossy = [];
+  const documents = [];
+  for (const document of args.documents) {
+    const offenders = [];
+    collectNonJsonValues(document, "$", /* @__PURE__ */ new WeakSet(), offenders);
+    if (offenders.length) {
+      lossy.push(...offenders.map((path) => `${documentIdOf(document)}:${path}`));
+      continue;
+    }
+    documents.push(JSON.parse(JSON.stringify(document)));
+  }
+  if (lossy.length > 0) {
+    throw new ContentSnapshotError(
+      `[content] snapshot: ${lossy.length} non-JSON value(s) found (invalid Date, Map, circular reference, symbol key, ...): ${lossy.slice(0, 10).join(", ")}`
+    );
+  }
+  return {
+    version: CONTENT_SNAPSHOT_VERSION,
+    integrity: args.integrity,
+    generatedAt: args.now,
+    documentIds: documents.map(documentIdOf),
+    documentSourceIds: [...new Set(documents.map(documentSourceIdOf))].sort(),
+    documents
+  };
+};
+export const isContentSnapshot = (value) => {
+  if (typeof value !== "object" || value === null) return false;
+  const snapshot = value;
+  return snapshot.version === CONTENT_SNAPSHOT_VERSION && typeof snapshot.integrity === "string" && typeof snapshot.generatedAt === "number" && Array.isArray(snapshot.documentIds) && Array.isArray(snapshot.documentSourceIds) && Array.isArray(snapshot.documents);
+};
+export const assertSnapshotComplete = (snapshot, sourceIds) => {
+  const have = new Set(snapshot.documentSourceIds);
+  const missing = [...new Set(sourceIds)].filter((id) => !have.has(id));
+  if (missing.length > 0) {
+    throw new ContentSnapshotError(
+      `[content] snapshot incomplete: ${missing.length} source document(s) missing (first ${Math.min(missing.length, 20)}): ${missing.slice(0, 20).join(", ")}. This build would silently 404 these pages in production.`
+    );
+  }
+};

package/dist/core/provider-errors.d.ts

@@ -1,4 +1,4 @@
-export type ContentProviderErrorCode = 'unknown_provider' | 'unknown_collection' | 'unsupported_provider_operation' | 'unsupported_query_operator' | 'unsupported_query_shape' | 'data_collection_route_access' | 'data_collection_search_access' | 'data_collection_sitemap_access' | 'missing_locale_route' | 'provider_config_missing' | 'provider_module_missing' | 'provider_module_invalid' | 'provider_result_invalid' | 'unsupported_provider_search_index' | 'unsupported_provider_search' | 'unsupported_provider_site_data' | 'unsupported_provider_prerender';
+export type ContentProviderErrorCode = 'unknown_provider' | 'unknown_collection' | 'unsupported_provider_operation' | 'unsupported_query_operator' | 'unsupported_query_shape' | 'provider_query_not_json_pure' | 'data_collection_route_access' | 'data_collection_search_access' | 'data_collection_sitemap_access' | 'missing_locale_route' | 'provider_config_missing' | 'provider_module_missing' | 'provider_module_invalid' | 'provider_result_invalid' | 'unsupported_provider_search_index' | 'unsupported_provider_search' | 'unsupported_provider_site_data' | 'unsupported_provider_prerender';
 export declare const statusForProviderError: Record<ContentProviderErrorCode, number>;
 export interface ContentProviderError extends Error {
     statusCode: number;

package/dist/core/provider-errors.js

@@ -4,6 +4,7 @@ export const statusForProviderError = {
   unsupported_provider_operation: 400,
   unsupported_query_operator: 400,
   unsupported_query_shape: 400,
+  provider_query_not_json_pure: 500,
   data_collection_route_access: 400,
   data_collection_search_access: 400,
   data_collection_sitemap_access: 400,

package/dist/core/query/builder.js

@@ -152,11 +152,11 @@ export function createQuery(fetcher, opts = {}) {
       const snapshot = { params: () => ({ ...this.params(), count: true }) };
       return fetcher(snapshot).then(resolveQueryResult);
     },
-    locale: (_locale, options) => {
-      const filteredWhere = queryParams.where ? ensureArray(queryParams.where).filter((item) => typeof item._locale === "undefined") : void 0;
+    locale: (locale, options) => {
+      const filteredWhere = queryParams.where ? ensureArray(queryParams.where).filter((item) => typeof item.locale === "undefined") : void 0;
       return next({
         resolveLocale: {
-          locale: _locale,
+          locale,
           fallback: Array.isArray(options?.fallback) ? options?.fallback : Boolean(options?.fallback),
           exact: !options?.fallback
         },