@lupinum/ginko-content 0.3.0-rc.3 → 0.3.0

package/README.md

@@ -10,11 +10,14 @@ Use it when you want content files to stay simple, but your Nuxt app still
 needs explicit APIs for route resolution, typed frontmatter, localized content,
 and server-side reads.
 
+This README describes the stable `0.3` line.
+
 ## Requirements
 
-- Node.js 22 or later
+- Node.js 22.18–22.x, 24.11–24.x, or 26+
 - Nuxt 4.4.7 through Nuxt 4.x
-- Vue 3.5 or later
+- Vue 3.5.35 through Vue 3.x
+- ESM; CommonJS `require()` is not supported
 
 ## Install
 
@@ -75,7 +78,7 @@ Render the current route through the collection:
 ```vue
 <!-- pages/[...slug].vue -->
 <script setup lang="ts">
-import { pages } from '~/content.config'
+import { pages } from '~~/content.config'
 
 const { page } = await useContentPage(pages)
 </script>
@@ -94,9 +97,10 @@ const { page } = await useContentPage(pages)
 - locale-aware content routing
 - route-aware page loading with `useContentPage(pages)`
 - semantic previous/next route-page data through `useContentPage(pages, { surround })`
-- server reads through `one`, `many`, `paginate`, `resolveOne`, `tree`, and
-  `neighbors`
-- Vue composables for the same read model
+- server reads through `one`, `many`, `paginate`, `resolveOne`, `navigation`,
+  and `surround`
+- route and search composables, plus pure client query functions for other
+  reads
 - search helpers for MiniSearch, Pagefind, and provider-owned search
 - sitemap integration for public content routes
 - a server-side provider contract for advanced custom sources
@@ -116,7 +120,8 @@ Do not duplicate docs, blog, pricing, privacy, or translated locale paths in
 `@nuxtjs/sitemap >= 8.0.15 < 9` when translated static app slugs such as `/preise`
 and `/en/pricing` need cross-locale sitemap alternates.
 
-See the public guide: [Sitemap and prerender](../../docs/content/docs/4.guides/4.routing-and-seo/3.sitemap-and-prerender.md).
+See the public guide:
+[Sitemap and prerender](https://github.com/lupinum-dev/ginko-content/blob/main/docs/content/docs/4.guides/4.routing-and-seo/3.sitemap-and-prerender.md).
 
 ## Integration Dependencies
 
@@ -134,10 +139,13 @@ See the public guide: [Sitemap and prerender](../../docs/content/docs/4.guides/4
 The default provider reads files from your Nuxt project. The package does not
 include a CMS UI, Studio, admin panel, or content editing workflow.
 
-## Docs
+## Project links
 
-- Documentation: [ginko-content.nuxt.dev](https://ginko-content.nuxt.dev)
+- Documentation source: [Getting started](https://github.com/lupinum-dev/ginko-content/blob/main/docs/content/docs/3.get-started/1.installation.md)
 - Repository: [github.com/lupinum-dev/ginko-content](https://github.com/lupinum-dev/ginko-content)
+- Issues: [GitHub issues](https://github.com/lupinum-dev/ginko-content/issues)
+- Contributing: [CONTRIBUTING.md](https://github.com/lupinum-dev/ginko-content/blob/main/CONTRIBUTING.md)
+- Security: [SECURITY.md](https://github.com/lupinum-dev/ginko-content/blob/main/SECURITY.md)
 
 ## Credits
 

package/dist/cli.mjs

@@ -316,62 +316,63 @@ function extractLocaleCodesFromConfig(text) {
 
 async function detectI18n(rootDir) {
   const nuxtConfigPath = join(rootDir, "nuxt.config.ts");
-  const contentConfigPath = join(rootDir, "content.config.ts");
   const nuxtConfig = await readTextIfPresent(nuxtConfigPath);
-  const contentConfig = await readTextIfPresent(contentConfigPath);
   const packageJson = await readPackageJson(rootDir);
-  const locales = /* @__PURE__ */ new Set([
-    ...extractLocaleCodesFromConfig(nuxtConfig),
-    ...extractLocaleCodesFromConfig(contentConfig)
-  ]);
-  const contentDir = join(rootDir, "content");
-  if (existsSync(contentDir)) {
-    const entries = await readdir(contentDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory() && localeCodePattern.test(entry.name)) {
-        locales.add(entry.name);
-      }
-    }
-  }
+  const contentI18nBlocks = findObjectPropertyBlocks(nuxtConfig, "content").flatMap((block) => findObjectPropertyBlocks(block, "i18n"));
+  const nuxtI18nBlocks = findObjectPropertyBlocks(nuxtConfig, "i18n");
+  for (const contentI18nBlock of contentI18nBlocks) {
+    const index = nuxtI18nBlocks.indexOf(contentI18nBlock);
+    if (index !== -1) {
+      nuxtI18nBlocks.splice(index, 1);
+    }
+  }
+  const nuxtI18nConfig = nuxtI18nBlocks.join("\n");
+  const contentI18nConfig = contentI18nBlocks.join("\n");
+  const hasNuxtI18nModule = /['"]@nuxtjs\/i18n['"]/.test(nuxtConfig);
+  const authorityConfig = hasNuxtI18nModule ? nuxtI18nConfig : contentI18nConfig;
   return {
-    locales: [...locales].sort(),
-    hasNuxtI18nModule: /['"]@nuxtjs\/i18n['"]/.test(nuxtConfig),
-    hasContentI18nConfig: /\bcontent\s*:\s*\{[\s\S]*?\bi18n\s*:/.test(nuxtConfig),
-    hasNuxtI18nDependency: hasDependency(packageJson, "@nuxtjs/i18n")
+    locales: extractLocaleCodesFromConfig(authorityConfig).sort(),
+    hasNuxtI18nModule,
+    hasNuxtI18nDependency: hasDependency(packageJson, "@nuxtjs/i18n"),
+    nuxtI18nDeclaresLocales: /\blocales\s*:/.test(nuxtI18nConfig),
+    nuxtI18nDeclaresDefaultLocale: /\bdefaultLocale\s*:/.test(nuxtI18nConfig),
+    contentI18nDeclaresLocales: /\blocales\s*:/.test(contentI18nConfig),
+    contentI18nDeclaresDefaultLocale: /\bdefaultLocale\s*:/.test(contentI18nConfig)
   };
 }
-async function inspectI18nConfig(rootDir, detected) {
+function inspectI18nConfig(detected) {
   const findings = [];
-  if (!detected.locales.length) {
-    findings.push({
-      severity: "error",
-      file: "nuxt.config.ts",
-      message: "No i18n locales detected.",
-      suggestion: "Configure @nuxtjs/i18n locales and content.i18n.locales, or create content/<locale>/ folders."
-    });
-  }
-  if (!detected.hasNuxtI18nDependency) {
-    findings.push({
-      severity: "error",
-      file: "package.json",
-      message: "Direct @nuxtjs/i18n dependency is missing for an i18n app.",
-      suggestion: "Install @nuxtjs/i18n directly so Nuxt owns route localization explicitly."
-    });
-  }
-  if (!detected.hasNuxtI18nModule) {
-    findings.push({
-      severity: "error",
-      file: "nuxt.config.ts",
-      message: "@nuxtjs/i18n module is not registered.",
-      suggestion: "Add @nuxtjs/i18n to modules before relying on localized content routes."
-    });
-  }
-  if (!detected.hasContentI18nConfig) {
+  if (detected.hasNuxtI18nModule) {
+    if (!detected.hasNuxtI18nDependency) {
+      findings.push({
+        severity: "error",
+        file: "package.json",
+        message: "Direct @nuxtjs/i18n dependency is missing for an i18n app.",
+        suggestion: "Install @nuxtjs/i18n directly so Nuxt owns route localization explicitly."
+      });
+    }
+    if (!detected.nuxtI18nDeclaresLocales || !detected.nuxtI18nDeclaresDefaultLocale) {
+      findings.push({
+        severity: "error",
+        file: "nuxt.config.ts",
+        message: "Nuxt I18n locale authority is incomplete.",
+        suggestion: "Declare locales and defaultLocale under top-level i18n in nuxt.config.ts."
+      });
+    }
+    if (detected.contentI18nDeclaresLocales || detected.contentI18nDeclaresDefaultLocale) {
+      findings.push({
+        severity: "error",
+        file: "nuxt.config.ts",
+        message: "Duplicate locale authority found in content.i18n.",
+        suggestion: "Remove locales and defaultLocale from content.i18n; Nuxt I18n is authoritative when registered. Keep only fallback and translatedSlugs there."
+      });
+    }
+  } else if (!detected.contentI18nDeclaresLocales || !detected.contentI18nDeclaresDefaultLocale) {
     findings.push({
       severity: "error",
       file: "nuxt.config.ts",
-      message: "content.i18n runtime config is missing.",
-      suggestion: "Add content.i18n with defaultLocale and locales so collections resolve localized documents."
+      message: "Content-owned locale authority is incomplete.",
+      suggestion: "Without @nuxtjs/i18n, declare locales and defaultLocale under content.i18n in nuxt.config.ts."
     });
   }
   return findings;
@@ -599,7 +600,7 @@ async function inspectI18nSearchIndex(rootDir, locales) {
 async function inspectI18n(rootDir) {
   const detected = await detectI18n(rootDir);
   return [
-    ...await inspectI18nConfig(rootDir, detected),
+    ...inspectI18nConfig(detected),
     ...await inspectI18nCollections(rootDir),
     ...await inspectI18nContentFolders(rootDir, detected.locales),
     ...await inspectI18nDuplicateContentGroups(rootDir, detected.locales),
@@ -746,15 +747,11 @@ async function inspectPublicApiUsage(rootDir) {
     {
       // `content.preview` is a real Ginko option (ContentPreviewOptions), unlike
       // `content.database`/`content.build`, so it is not flagged as a v3
-      // leftover. This rule only reminds authors of its actual scope: the
-      // filesystem provider always shows drafts/partials in development, and a
-      // configured token additionally unlocks visibility for files already
-      // present in a deployed filesystem checkout. It does not fetch
-      // not-yet-published content — that kind of production preview workflow
-      // is owned by a CMS provider, not the filesystem provider.
+      // leftover. It protects preview-storage overlay reads; it is not a
+      // production filesystem-preview switch or a partial-visibility switch.
       pattern: /\bcontent\.preview\b/,
       message: "content.preview configuration found.",
-      suggestion: "content.preview only gates draft/partial visibility for the filesystem provider; it always applies in development. In production it unlocks drafts already present in the deployed content directory \u2014 it is not a substitute for a provider-owned preview workflow that fetches unpublished content.",
+      suggestion: "content.preview protects filesystem preview-storage overlays. Ordinary drafts are visible in development, partials remain structural non-routes, and authenticated filesystem preview is unsupported in production; use provider-owned preview there.",
       severity: "info"
     },
     {

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

@@ -1,12 +1,12 @@
 /**
  * @lupinum/ginko-content/cms-contract
  *
- * Pure, runtime-safe surface that ginko-cms consumes. This subpath contains
+ * Pure, runtime-safe surface for CMS/provider consumers. This subpath contains
  * NO Node, Nuxt, h3, nitropack, filesystem, or @nuxt/kit dependencies. Every
- * module re-exported from here MUST be importable from a V8 isolate (Convex
- * component, Cloudflare Workers, browser).
+ * module re-exported from here MUST be importable from a V8 isolate, worker,
+ * or browser.
  *
- * The CMS uses this surface to:
+ * Consumers use this surface to:
  *  - normalize a host's `content.config.ts` into the one portable
  *    `ResolvedContentContractV1` artifact (`buildResolvedContentContract`),
  *  - produce RFC 8785 canonical JSON and incremental SHA-256 hashes without
@@ -18,12 +18,12 @@
  *  - parse MDC into the same AST the filesystem provider uses (`parseMdcBody`).
  *
  * If a future change introduces a Node/Nuxt dependency anywhere in this
- * tree, the CMS Convex build will break loudly. That's intentional.
+ * tree, isolate builds will break loudly. That's intentional.
  */
 export { RESOLVED_CONTENT_CONTRACT_VERSION, buildResolvedContentContract, type BuildResolvedContentContractInput, type BuildResolvedContentContractOptions, } from './build.js';
 export type { PortableComponentPolicyV1, PortableMediaType, ResolvedContentCollectionV1, ResolvedContentContractV1, ResolvedContentFieldTypeV1, ResolvedContentFieldV1, ResolvedContentValidationV1, ContentCmsCollectionConfig, ContentCmsFieldConfig, ContentCmsFieldType, ContentCmsRelationConfig, ContentCollectionConfig, ContentCollectionI18nConfig, } from './types.js';
-export { describeId, generatePath, generateCanonicalKey, generateTitle, isDraftPath, isPartialPath, longestMountForPath, mountContentPath, normalizeContentPath, normalizeRouteMounts, prefixPathWithLocale, refineUrlPart, routeRemainder, routeToContentPathCandidates, slugifyUrlSegment, stripLocalePrefix, } from './path.js';
-export { CONTENT_FIELD_METADATA_KEY, CONTENT_REFERENCE_PREFIX, collectTopLevelReferenceFields, getContentFieldMetadata, getObjectShape, getReferenceDescriptor, getSchemaDef, getSchemaTypeName, unwrapSchema, type ContentFieldMetadata, type ContentFieldSchema, } from './schema.js';
+export { describeId, generatePath, generateCanonicalKey, generateTitle, isDraftPath, isPartialPath, mountContentPath, normalizeContentPath, normalizeRouteMounts, prefixPathWithLocale, refineUrlPart, routeRemainder, routeToContentPathCandidates, slugifyUrlSegment, stripLocalePrefix, } from './path.js';
+export { CONTENT_FIELD_METADATA_KEY, CONTENT_REFERENCE_METADATA_KEY, collectTopLevelReferenceFields, getContentFieldMetadata, getObjectShape, getReferenceDescriptor, getSchemaDef, getSchemaTypeName, unwrapSchema, type ContentFieldMetadata, type ContentFieldSchema, } from './schema.js';
 export { parseMdcBody, type ParseMdcBodyOptions, type ParseMdcBodyResult, } from './mdc.js';
 export { assertPublicMarkdownAst, isSafePublicMarkdownUrl, PublicMarkdownValidationError, validatePublicMarkdownAst, type PublicMarkdownIssue, type PublicMarkdownIssueCode, type PublicMarkdownValidationResult, } from './render-policy.js';
 export { verifyPublicImageBytes, type VerifiedPublicImage, } from './asset-bytes.js';

package/dist/cms-contract/index.js

@@ -9,7 +9,6 @@ export {
   generateTitle,
   isDraftPath,
   isPartialPath,
-  longestMountForPath,
   mountContentPath,
   normalizeContentPath,
   normalizeRouteMounts,
@@ -22,7 +21,7 @@ export {
 } from "./path.js";
 export {
   CONTENT_FIELD_METADATA_KEY,
-  CONTENT_REFERENCE_PREFIX,
+  CONTENT_REFERENCE_METADATA_KEY,
   collectTopLevelReferenceFields,
   getContentFieldMetadata,
   getObjectShape,

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

@@ -1,13 +1,7 @@
 /**
- * parseMdcBody - single canonical MDC parser entry point for the CMS.
- *
- * The CMS used to fake a parsed MDC body at read-time by wrapping the raw
- * markdown string in a paragraph element and regexing headings. That broke
- * MDC components, links, tables, and any non-trivial markdown.
- *
- * Per Gate 0: parse once at publish time using ginko-content's real parser,
- * store the AST on `publicEntries`, and have the public provider return the
- * stored AST verbatim. The CMS imports this function from the pure subpath.
+ * Single canonical MDC parser entry point for external CMS integrations.
+ * Parse at publish time, persist the resulting AST, and return that AST from
+ * the public provider instead of maintaining a second markdown parser.
  */
 import type { MarkdownRoot, Toc } from '../types/content.js';
 export interface ParseMdcBodyOptions {

package/dist/cms-contract/mdc.js

@@ -1,9 +1,11 @@
-import { parse } from "comark";
+import { normalizeComarkNodes } from "../core/markdown/normalize-comark.js";
+import { parseComark } from "../core/markdown/parse-comark.js";
 import { mapMarkdownNodes, toMarkdownRoot } from "../core/markdown/tree.js";
 export async function parseMdcBody(raw, options = {}) {
-  const tree = await parse(raw ?? "");
-  const toc = deriveToc(tree.nodes, options);
-  const body = toMarkdownRoot(tree.nodes, toc);
+  const tree = await parseComark(raw ?? "");
+  const nodes = normalizeComarkNodes(tree.nodes);
+  const toc = deriveToc(nodes, options);
+  const body = toMarkdownRoot(nodes, toc);
   const searchText = renderPlainText(body);
   return { body, toc, searchText };
 }

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

@@ -1,12 +1,10 @@
 /**
  * Pure path helpers re-exported from `ginko-content`'s canonical path engine.
  *
- * The CMS uses these instead of duplicating its own path-generation logic.
- * Per Gate 0 of the refactor: ginko-content owns path semantics; ginko-cms
- * imports them. No more parallel implementations of `generatePath` /
- * `generateCanonicalKey` / `slugifyUrlSegment`.
+ * External CMS integrations use these instead of duplicating path-generation
+ * logic. Ginko Content remains the sole owner of public path semantics.
  *
  * All re-exports MUST be runtime-pure (no Node, no Nuxt, no h3). They are.
  */
-export { describeId, generatePath, generateCanonicalKey, generateTitle, isDraftPath, isPartialPath, normalizeContentPath, normalizeRouteMounts, longestMountForPath, routeRemainder, mountContentPath, prefixPathWithLocale, stripLocalePrefix, refineUrlPart, routeToContentPathCandidates, } from '../core/content/path.js';
+export { describeId, generatePath, generateCanonicalKey, generateTitle, isDraftPath, isPartialPath, normalizeContentPath, normalizeRouteMounts, routeRemainder, mountContentPath, prefixPathWithLocale, stripLocalePrefix, refineUrlPart, routeToContentPathCandidates, } from '../core/content/path.js';
 export { slugifyUrlSegment } from '../core/content/slug.js';

package/dist/cms-contract/path.js

@@ -7,7 +7,6 @@ export {
   isPartialPath,
   normalizeContentPath,
   normalizeRouteMounts,
-  longestMountForPath,
   routeRemainder,
   mountContentPath,
   prefixPathWithLocale,

package/dist/cms-contract/render-policy.js

@@ -226,6 +226,10 @@ export function validatePublicMarkdownAst(value, policy = { components: {} }) {
         continue;
       }
       if (name === "style" && tag === "span" && isSafeShikiStyle(propValue)) continue;
+      if (tag === "blockquote" && name === "data-alert") {
+        if (typeof propValue !== "string" || !["note", "tip", "important", "warning", "caution"].includes(propValue)) report("invalid_prop_value", propPath, "Blockquote alert metadata is invalid.");
+        continue;
+      }
       if (!name || /^on/i.test(name) || /^v-|^@|^:|^#/.test(name) || FORBIDDEN_PROPS.has(lower)) {
         report("unsafe_prop", propPath, `Property "${name}" is not render-safe.`);
         continue;

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

@@ -15,4 +15,4 @@ export { getSchemaDef, getSchemaTypeName, unwrapSchema, getObjectShape, getRefer
  */
 export { CONTENT_FIELD_METADATA_KEY, type ContentFieldMetadata, type ContentFieldSchema, } from '../types/fields.js';
 export { getContentFieldMetadata } from '../types/fields.js';
-export { CONTENT_REFERENCE_PREFIX } from '../types/reference.js';
+export { CONTENT_REFERENCE_METADATA_KEY, } from '../types/reference.js';

package/dist/cms-contract/schema.js

@@ -10,4 +10,6 @@ export {
   CONTENT_FIELD_METADATA_KEY
 } from "../types/fields.js";
 export { getContentFieldMetadata } from "../types/fields.js";
-export { CONTENT_REFERENCE_PREFIX } from "../types/reference.js";
+export {
+  CONTENT_REFERENCE_METADATA_KEY
+} from "../types/reference.js";

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

@@ -14,7 +14,7 @@
  *    Canonical keys are only unique within a collection.
  *  - **`byCanonical`**: a derived convenience index containing only keys
  *    that occur in one collection. Ambiguous unscoped lookups fail closed.
- *  - **`byRoute`**: route path (user-visible URL) → content id. Used by the
+ *  - **`byRoute`**: locale plus route path → canonical key. Used by the
  *    page resolver when the request arrives as a localized URL.
  *  - **`byRef`**: normalized ref string → canonical key. This is how
  *    markdown links such as `[Ada]($authors.ada)` find their target without a scan.
@@ -28,8 +28,8 @@
  */
 import type { ParsedContent } from '../../types/content';
 import type { ContentLocaleEntry } from '../../types/query';
-import type { ContentManifest, ManifestVariant, ResolvedVariant } from '../../types/runtime';
-export interface ContentGraphVariant extends ManifestVariant {
+import type { ContentVariantIdentity, ResolvedVariant } from '../../types/runtime';
+export interface ContentGraphVariant extends ContentVariantIdentity {
     document: ParsedContent;
 }
 export interface ContentGraph {
@@ -44,7 +44,9 @@ export interface ContentGraph {
     byCollectionCanonical: Record<string, Record<string, Record<string, ContentGraphVariant>>>;
     /** Unambiguous canonical keys only. Derived from `byCollectionCanonical`. */
     byCanonical: Record<string, Record<string, ContentGraphVariant>>;
-    /** route path → content id. Used by page resolution. */
+    /** Exact collection → ref → canonical key alias index. */
+    byCollectionRef: Record<string, Record<string, string>>;
+    /** `"<locale>:<route path>"` → canonical key. Used by page resolution. */
     byRoute: Record<string, string>;
     /** normalized ref string → canonical key. */
     byRef: Record<string, string>;
@@ -54,25 +56,7 @@ export interface ContentGraph {
     referenceTargets: Map<string, string>;
     /** Exact collection-scoped user-writable reference targets. */
     referenceTargetsByCollection: Record<string, Map<string, string>>;
-    manifest: ContentManifest;
 }
-/**
- * Build the locale resolution chain for a request.
- *
- * Order, from highest to lowest priority:
- *   1. The explicitly requested locale (if any).
- *   2. Author-configured fallbacks for that locale.
- *   3. The site-wide default locale.
- *
- * Duplicates are removed while preserving first-occurrence order, so the
- * caller can walk the chain and stop at the first hit without worrying
- * about re-visiting the default.
- *
- * @example
- * resolveLocaleChain('fr', 'en', { fr: ['de'] })  // ['fr', 'de', 'en']
- * resolveLocaleChain(undefined, 'en')            // ['en']
- */
-export declare const resolveLocaleChain: (requestedLocale: string | undefined, defaultLocale?: string, fallback?: Record<string, string[]>) => string[];
 /**
  * Build a `ContentGraph` from a flat list of parsed documents.
  *
@@ -88,6 +72,7 @@ export declare const resolveLocaleChain: (requestedLocale: string | undefined, d
 export declare const buildContentGraph: (documents: ParsedContent[], options?: {
     locales?: string[];
     defaultLocale?: string;
+    referencePathAliases?: (document: ParsedContent) => readonly string[];
 }) => ContentGraph;
 /** Resolve the exact collection-scoped variant set, or an unambiguous one. */
 export declare const getGraphCanonicalVariants: (graph: ContentGraph, canonicalKey: string, collection?: string) => Record<string, ContentGraphVariant> | undefined;

package/dist/core/content/graph.js

@@ -1,34 +1,21 @@
 import { isNavigationFile } from "./structural.js";
 import { normalizeReferenceValue, buildReferenceTargets } from "../references/resolve.js";
-import { sortLocalesCanonically } from "./locale.js";
+import { resolveLocaleChain, sortLocalesCanonically } from "./locale.js";
 const normalizePath = (path) => {
   if (!path || path === "/") {
     return "/";
   }
   return path.startsWith("/") ? path.endsWith("/") ? path.slice(0, -1) || "/" : path : `/${path.replace(/\/+$/, "")}`;
 };
-const emptyManifest = () => ({
-  byCollectionCanonical: {},
-  byCanonical: {},
-  byCollectionRef: {},
-  byRef: {},
-  byRoute: {},
-  paths: {},
-  collections: {}
-});
-export const resolveLocaleChain = (requestedLocale, defaultLocale, fallback = {}) => {
-  const chain = [
-    ...requestedLocale ? [requestedLocale] : [],
-    ...requestedLocale && fallback[requestedLocale] || [],
-    ...defaultLocale ? [defaultLocale] : []
-  ].filter(Boolean);
-  return Array.from(new Set(chain));
-};
 export const buildContentGraph = (documents, options = {}) => {
-  const manifest = emptyManifest();
   const byId = {};
+  const byCollection = {};
+  const byPath = {};
   const byCollectionCanonical = {};
   const byCanonical = {};
+  const byCollectionRef = {};
+  const byRef = {};
+  const byRoute = {};
   const byNavigationPath = {};
   const defaultLocale = options.defaultLocale || "";
   for (const document of documents) {
@@ -38,15 +25,15 @@ export const buildContentGraph = (documents, options = {}) => {
       continue;
     }
     const path = normalizePath(document.path);
-    manifest.paths[path] ||= [];
+    byPath[path] ||= [];
     if (document.locale === defaultLocale) {
-      manifest.paths[path].unshift(documentId);
+      byPath[path].unshift(documentId);
     } else {
-      manifest.paths[path].push(documentId);
+      byPath[path].push(documentId);
     }
     if (document.collection) {
-      manifest.collections[document.collection] ||= [];
-      manifest.collections[document.collection].push(documentId);
+      byCollection[document.collection] ||= [];
+      byCollection[document.collection].push(documentId);
     }
     if (isNavigationFile(document)) {
       const locale2 = document.locale || defaultLocale;
@@ -66,45 +53,43 @@ export const buildContentGraph = (documents, options = {}) => {
       path,
       document
     };
-    manifest.byCollectionCanonical[collection] ||= {};
-    manifest.byCollectionCanonical[collection][document.canonicalKey] ||= {};
-    manifest.byCollectionCanonical[collection][document.canonicalKey][locale] = variant;
-    manifest.byRoute[`${locale}:${path}`] = document.canonicalKey;
+    byCollectionCanonical[collection] ||= {};
+    byCollectionCanonical[collection][document.canonicalKey] ||= {};
+    byCollectionCanonical[collection][document.canonicalKey][locale] = variant;
+    byRoute[`${locale}:${path}`] = document.canonicalKey;
     if (document.type === "markdown" && typeof document.ref === "string" && document.ref.length) {
-      manifest.byCollectionRef[collection] ||= {};
-      manifest.byCollectionRef[collection][document.ref] = document.canonicalKey;
+      byCollectionRef[collection] ||= {};
+      byCollectionRef[collection][document.ref] = document.canonicalKey;
     }
   }
   const collectionsByCanonical = /* @__PURE__ */ new Map();
-  for (const [collection, canonicalEntries] of Object.entries(manifest.byCollectionCanonical)) {
-    byCollectionCanonical[collection] = {};
-    for (const [canonicalKey, variants] of Object.entries(canonicalEntries)) {
-      const graphVariants = Object.fromEntries(
-        Object.entries(variants).map(([locale, variant]) => [locale, { ...variant, document: byId[variant.contentId] }])
-      );
-      byCollectionCanonical[collection][canonicalKey] = graphVariants;
+  for (const [collection, canonicalEntries] of Object.entries(byCollectionCanonical)) {
+    for (const canonicalKey of Object.keys(canonicalEntries)) {
       collectionsByCanonical.set(canonicalKey, [...collectionsByCanonical.get(canonicalKey) || [], collection]);
     }
   }
   for (const [canonicalKey, collections] of collectionsByCanonical) {
     if (collections.length !== 1) continue;
     const collection = collections[0];
-    manifest.byCanonical[canonicalKey] = manifest.byCollectionCanonical[collection][canonicalKey];
     byCanonical[canonicalKey] = byCollectionCanonical[collection][canonicalKey];
   }
   const collectionsByRef = /* @__PURE__ */ new Map();
-  for (const [collection, refs] of Object.entries(manifest.byCollectionRef)) {
+  for (const [collection, refs] of Object.entries(byCollectionRef)) {
     for (const ref of Object.keys(refs)) {
       collectionsByRef.set(ref, [...collectionsByRef.get(ref) || [], collection]);
     }
   }
   for (const [ref, collections] of collectionsByRef) {
-    if (collections.length === 1) manifest.byRef[ref] = manifest.byCollectionRef[collections[0]][ref];
+    if (collections.length === 1) byRef[ref] = byCollectionRef[collections[0]][ref];
   }
   const referenceTargetsByCollection = Object.fromEntries(
-    Object.keys(manifest.byCollectionCanonical).map((collection) => [
+    Object.keys(byCollectionCanonical).map((collection) => [
       collection,
-      buildReferenceTargets(documents.filter((document) => (document.collection || "content") === collection && !document.partial && !isNavigationFile(document)), options.locales || [])
+      buildReferenceTargets(
+        documents.filter((document) => (document.collection || "content") === collection && !document.partial && !isNavigationFile(document)),
+        options.locales || [],
+        options.referencePathAliases
+      )
     ])
   );
   const referenceTargetCollections = /* @__PURE__ */ new Map();
@@ -120,16 +105,16 @@ export const buildContentGraph = (documents, options = {}) => {
   return {
     documents,
     byId,
-    byCollection: manifest.collections,
-    byPath: manifest.paths,
+    byCollection,
+    byPath,
     byCollectionCanonical,
     byCanonical,
-    byRoute: manifest.byRoute,
-    byRef: manifest.byRef,
+    byCollectionRef,
+    byRoute,
+    byRef,
     byNavigationPath,
     referenceTargets,
-    referenceTargetsByCollection,
-    manifest
+    referenceTargetsByCollection
   };
 };
 export const getGraphCanonicalVariants = (graph, canonicalKey, collection) => {
@@ -145,8 +130,9 @@ export const resolveGraphVariant = (graph, canonicalKey, requestedLocale, option
     return null;
   }
   const availableLocales = sortLocalesCanonically(Object.keys(variants), 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) => variants[locale]) || (options.exact ? void 0 : availableLocales[0]);
+  const hasExplicitFallback = options.fallback !== void 0;
+  const localeChain = options.exact ? requestedLocale ? [requestedLocale] : [] : hasExplicitFallback ? Array.from(new Set([requestedLocale, ...options.fallback || []].filter(Boolean))) : resolveLocaleChain(requestedLocale, options.defaultLocale, options.localeFallback || {});
+  const resolvedLocale = localeChain.find((locale) => variants[locale]) || (options.exact || hasExplicitFallback ? void 0 : availableLocales[0]);
   if (resolvedLocale === void 0) {
     return null;
   }
@@ -164,7 +150,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 localeChain = options.exact ? requestedLocale ? [requestedLocale] : [] : options.fallback !== void 0 ? Array.from(new Set([requestedLocale, ...options.fallback || []].filter(Boolean))) : resolveLocaleChain(requestedLocale, options.defaultLocale, options.localeFallback || {});
   const localesToSearch = localeChain.length ? localeChain : sortLocalesCanonically(getGraphVariantLocales(graph, options.collection), options);
   for (const locale of localesToSearch) {
     const canonicalKey = graph.byRoute[`${locale}:${normalizedPath}`];
@@ -187,7 +173,7 @@ export const resolveGraphCanonicalKey = (graph, identity, collection) => {
   if (hasCollectionVariant(normalizedIdentity)) {
     return normalizedIdentity;
   }
-  const refCanonicalKey = collection ? graph.manifest.byCollectionRef[collection]?.[normalizedIdentity] : graph.byRef[normalizedIdentity];
+  const refCanonicalKey = collection ? graph.byCollectionRef[collection]?.[normalizedIdentity] : graph.byRef[normalizedIdentity];
   if (refCanonicalKey && hasCollectionVariant(refCanonicalKey)) {
     return refCanonicalKey;
   }

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

@@ -23,10 +23,14 @@ import type { ContentCollectionI18nConfig } from '../../types/config';
 /** Separator between source id and locale in inline-variant ids. */
 export declare const INLINE_LOCALE_ID_SEPARATOR = "#__locale=";
 /**
- * Produce the fallback chain for a specific locale (excluding the locale
- * itself). The caller prepends the requested locale if it wants a
- * walkable chain — this helper is what to look at *after* the requested
- * locale missed.
+ * Build the locale resolution chain for a request. The requested locale,
+ * configured fallbacks, and default locale are ordered by priority and
+ * deduplicated without reordering.
+ */
+export declare const resolveLocaleChain: (requestedLocale: string | undefined, defaultLocale?: string, fallback?: Readonly<Record<string, readonly string[]>>) => string[];
+/**
+ * Produce the fallback portion of the canonical locale chain, excluding the
+ * requested locale itself.
  *
  * @example
  * buildLocaleFallbackChain('fr', 'en', { fr: ['de'] })  // ['de', 'en']
@@ -64,3 +68,5 @@ export declare const splitInlineLocaleVariantId: (id: string) => {
  * override should not fail ingest for the whole document.
  */
 export declare const expandDataLocaleVariants: (document: ParsedContent, i18nConfig?: ContentCollectionI18nConfig) => ParsedContent[];
+/** Physical locale identity used when content has no configured locale authority. */
+export declare const DEFAULT_CONTENT_LOCALE = "en";