@lupinum/ginko-content 0.1.0 → 0.1.2

package/dist/module.mjs

@@ -6,6 +6,8 @@ import { defu } from 'defu';
 import { hash } from 'ohash';
 import { resolve, join, relative, isAbsolute } from 'pathe';
 import { withTrailingSlash } from 'ufo';
+import { normalizeContentConfigCollectionNames } from '../dist/types/config';
+export { defineCollection, defineContentConfig, reference } from '../dist/types/config';
 import 'unstorage/drivers/fs';
 import 'unstorage/drivers/http';
 import 'unstorage/drivers/github';
@@ -18,6 +20,7 @@ import { genSafeVariableName, genImport } from 'knitwork';
 import { listen } from 'listhen';
 import { makeIgnored } from '../dist/core/content/ignore';
 import { readFile, readdir } from 'node:fs/promises';
+import { resolveContentSitemapSource, GINKO_SITEMAP_SOURCE_NAME } from '../dist/runtime/utils/sitemap-source';
 import { resolveCollectionI18nConfig } from '../dist/features/localization/config';
 import { globby } from 'globby';
 import { transformContent } from '../dist/parsers/index';
@@ -26,10 +29,11 @@ import { buildContentGraph } from '../dist/core/content/graph';
 import { normalizeCollectionSources, normalizeCollectionExcludes } from '../dist/core/content/sources';
 import { resolveCollectionI18n, prefixPathWithLocale } from '../dist/features/localization/path';
 import { resolveCollection } from '../dist/core/content/collection';
-export { defineCollection, defineContentConfig, reference } from '../dist/types/config';
+import { normalizeRouteMounts, normalizeContentPath } from '../dist/core/content/path';
+import { collectTopLevelReferenceFieldsByTarget } from '../dist/core/references/schema';
 
 const name = "@lupinum/ginko-content";
-const version = "0.1.0";
+const version = "0.1.2";
 
 const logger = consola.withTag("@lupinum/ginko-content");
 const CACHE_VERSION = 3;
@@ -240,16 +244,8 @@ const registerContentDevRuntime = (nuxt, options, contentContext) => {
 
 const registerRuntimeImports = (resolveRuntimeModule) => {
   addImports([
-    // Unified query API (ADR-0016) — app wrappers bind the Nuxt content context explicitly.
-    { name: "one", as: "one", from: resolveRuntimeModule("./app/composables/query-api.js") },
-    { name: "many", as: "many", from: resolveRuntimeModule("./app/composables/query-api.js") },
-    { name: "paginate", as: "paginate", from: resolveRuntimeModule("./app/composables/query-api.js") },
-    { name: "backlinks", as: "backlinks", from: resolveRuntimeModule("./app/composables/query-api.js") },
-    { name: "resolveOne", as: "resolveOne", from: resolveRuntimeModule("./app/composables/query-api.js") },
-    { name: "variants", as: "variants", from: resolveRuntimeModule("./app/composables/query-api.js") },
-    { name: "tree", as: "tree", from: resolveRuntimeModule("./app/composables/query-api.js") },
-    { name: "neighbors", as: "neighbors", from: resolveRuntimeModule("./app/composables/query-api.js") },
     { name: "getCollectionPath", as: "getCollectionPath", from: resolveRuntimeModule("./query/routes.js") },
+    { name: "useContentHead", as: "useContentHead", from: resolveRuntimeModule("./app/composables/head.js") },
     // Vue composables — reactive wrappers over the same options shape.
     { name: "useContentPage", as: "useContentPage", from: resolveRuntimeModule("./app/composables/use-content.js") },
     { name: "useContentOne", as: "useContentOne", from: resolveRuntimeModule("./app/composables/use-content.js") },
@@ -259,9 +255,12 @@ const registerRuntimeImports = (resolveRuntimeModule) => {
     { name: "useContentResolveOne", as: "useContentResolveOne", from: resolveRuntimeModule("./app/composables/use-content.js") },
     { name: "useContentVariants", as: "useContentVariants", from: resolveRuntimeModule("./app/composables/use-content.js") },
     { name: "useContentTree", as: "useContentTree", from: resolveRuntimeModule("./app/composables/use-content.js") },
+    { name: "useContentNavigation", as: "useContentNavigation", from: resolveRuntimeModule("./app/composables/use-content.js") },
     { name: "useContentNeighbors", as: "useContentNeighbors", from: resolveRuntimeModule("./app/composables/use-content.js") },
     { name: "useContentLocaleSwitch", as: "useContentLocaleSwitch", from: resolveRuntimeModule("./app/composables/use-content.js") },
-    // Search & site data — kept (out of scope for ADR-0016).
+    { name: "useContentSwitchLocalePath", as: "useContentSwitchLocalePath", from: resolveRuntimeModule("./app/composables/route.js") },
+    // Search & site data — keep the headless useContentSearch export explicit
+    // because Nuxt UI owns the same auto-import name.
     { name: "useContentSearchData", as: "useContentSearchData", from: resolveRuntimeModule("./app/composables/search.js") },
     { name: "useContentSearchResults", as: "useContentSearchResults", from: resolveRuntimeModule("./app/composables/search.js") },
     { name: "querySiteData", as: "querySiteData", from: resolveRuntimeModule("./app/composables/site-data.js") }
@@ -356,25 +355,68 @@ const registerUserContentComponents = async (nuxt, resolve) => {
     }
   }
 };
-const registerGeneratedTypes = (contentConfigPath, resolveRuntimeModuleRoot) => {
+const registerGeneratedTypes = (contentConfigPath, resolveRuntimeModuleRoot, collectionNames = [], i18nCollectionNames = []) => {
+  const collectionNameUnion = collectionNames.length ? collectionNames.map((name) => JSON.stringify(name)).join(" | ") : "never";
+  const i18nCollectionNameUnion = i18nCollectionNames.length ? i18nCollectionNames.map((name) => JSON.stringify(name)).join(" | ") : "never";
+  const collectionMapProperties = collectionNames.map((name) => {
+    const key = JSON.stringify(name);
+    return `    ${key}: StrictParsedContent & __GeneratedCollectionSchema<__ContentCollectionExport<${key}>>`;
+  });
   return addTypeTemplate({
     filename: "types/content.d.ts",
     getContents: () => [
       contentConfigPath ? `import type contentConfig from ${JSON.stringify(contentConfigPath)}` : "type __ContentConfig = { collections?: {} }",
+      contentConfigPath ? `import type * as contentConfigModule from ${JSON.stringify(contentConfigPath)}` : "declare const contentConfigModule: {}",
       "import type { StrictParsedContent } from '@lupinum/ginko-content'",
       "import type { CollectionSchema } from '@lupinum/ginko-content/config'",
       contentConfigPath ? "type __ContentConfig = typeof contentConfig" : "",
       "type __ContentCollections = NonNullable<__ContentConfig['collections']>",
+      `type __RuntimeContentCollectionNames = ${collectionNameUnion}`,
+      "type __NamedContentCollectionNames = {",
+      "  [K in keyof typeof contentConfigModule & string]: typeof contentConfigModule[K] extends { name: K } ? K : never",
+      "}[keyof typeof contentConfigModule & string]",
+      "type __InferredContentCollectionNames = string extends keyof __ContentCollections",
+      "  ? __NamedContentCollectionNames",
+      "  : keyof __ContentCollections & string",
+      "type __ContentCollectionNames = [__RuntimeContentCollectionNames] extends [never]",
+      "  ? __InferredContentCollectionNames",
+      "  : __RuntimeContentCollectionNames",
+      "type __ContentCollectionExport<K extends string> = K extends keyof typeof contentConfigModule",
+      "  ? typeof contentConfigModule[K]",
+      "  : __ContentCollections[K]",
+      "type __GeneratedCollectionSchema<TCollection> = TCollection extends { __schema: infer TSchema }",
+      "  ? TSchema extends { _output: infer TOutput } ? TOutput : {}",
+      "  : CollectionSchema<TCollection>",
       "type __GeneratedContentCollectionMap = {",
-      "  [K in keyof __ContentCollections & string]: StrictParsedContent & CollectionSchema<__ContentCollections[K]>",
+      "  [K in __ContentCollectionNames]: StrictParsedContent & __GeneratedCollectionSchema<__ContentCollectionExport<K>>",
       "}",
-      "type __GeneratedI18nCollectionNames = {",
-      "  [K in keyof __ContentCollections & string]: NonNullable<__ContentCollections[K]['i18n']> extends never ? never : K",
-      "}[keyof __ContentCollections & string]",
+      `type __RuntimeI18nCollectionNames = ${i18nCollectionNameUnion}`,
+      "type __InferredI18nCollectionNames = {",
+      "  [K in __ContentCollectionNames]: __ContentCollectionExport<K> extends { __i18n: true }",
+      "    ? K",
+      "    : __ContentCollectionExport<K> extends { i18n: true } ? K : never",
+      "}[__ContentCollectionNames]",
+      "type __GeneratedI18nCollectionNames = [__RuntimeI18nCollectionNames] extends [never]",
+      "  ? __InferredI18nCollectionNames",
+      "  : __RuntimeI18nCollectionNames",
       "declare module '@lupinum/ginko-content' {",
       "  interface ContentCollectionMap extends __GeneratedContentCollectionMap {}",
       "  interface ContentCollectionI18nMap extends Pick<__GeneratedContentCollectionMap, __GeneratedI18nCollectionNames> {}",
       "}",
+      "declare global {",
+      "  interface GinkoContentCollectionMap {",
+      ...collectionMapProperties,
+      "  }",
+      "  interface GinkoContentCollectionI18nMap extends Pick<__GeneratedContentCollectionMap, __GeneratedI18nCollectionNames> {}",
+      "}",
+      "declare module '@lupinum/ginko-content/dist/types/query' {",
+      "  interface ContentCollectionMap extends __GeneratedContentCollectionMap {}",
+      "  interface ContentCollectionI18nMap extends Pick<__GeneratedContentCollectionMap, __GeneratedI18nCollectionNames> {}",
+      "}",
+      "declare module '@lupinum/ginko-content/dist/types/query.js' {",
+      "  interface ContentCollectionMap extends __GeneratedContentCollectionMap {}",
+      "  interface ContentCollectionI18nMap extends Pick<__GeneratedContentCollectionMap, __GeneratedI18nCollectionNames> {}",
+      "}",
       "declare module '#content/server' {",
       `  const one: typeof import('${resolveRuntimeModuleRoot("./server")}').one`,
       `  const many: typeof import('${resolveRuntimeModuleRoot("./server")}').many`,
@@ -498,6 +540,23 @@ const toLocalPath = (value) => {
     return value;
   }
 };
+const placeholderHosts = /* @__PURE__ */ new Set([
+  "example.com",
+  "example.net",
+  "example.org",
+  "localhost",
+  "127.0.0.1",
+  "0.0.0.0",
+  "::1"
+]);
+const isPlaceholderHost = (host) => placeholderHosts.has(host) || host.endsWith(".example.com") || host.endsWith(".example.net") || host.endsWith(".example.org") || host.endsWith(".localhost");
+const extractPlaceholderSiteUrls = (locValues) => Array.from(new Set(locValues.filter((value) => {
+  try {
+    return isPlaceholderHost(new URL(value).hostname);
+  } catch {
+    return false;
+  }
+})));
 const discoverSitemapsFromDisk = async (outputPublicDir) => {
   const indexPath = join$1(outputPublicDir, SITEMAP_INDEX);
   try {
@@ -553,6 +612,9 @@ const normalizeContentSitemapAssertOptions = (options) => ({
   minUrlsPerSitemap: options?.minUrlsPerSitemap ?? 1,
   requireImages: options?.requireImages ?? false,
   requiredCollections: options?.requiredCollections ?? [],
+  requiredPaths: options?.requiredPaths ?? [],
+  forbiddenPathPrefixes: options?.forbiddenPathPrefixes ?? [],
+  requireProductionSiteUrl: options?.requireProductionSiteUrl ?? false,
   sitemaps: options?.sitemaps ?? {}
 });
 const shouldRunSitemapAssertionOnCompiled = (options, nitro) => {
@@ -594,6 +656,29 @@ async function assertGeneratedSitemaps({
       failures.push(`- ${target.name}: expected image entries but found none`);
     }
   }
+  const sitemapLocValues = discoveredSitemaps.flatMap((target) => extractLocValues(target.xml));
+  const sitemapPaths = Array.from(new Set(sitemapLocValues.map(toLocalPath)));
+  const pathSet = new Set(sitemapPaths);
+  const missingPaths = options.requiredPaths.filter((path) => !pathSet.has(path));
+  if (missingPaths.length) {
+    failures.push(`- Missing required sitemap paths: ${missingPaths.join(", ")}`);
+  }
+  const forbiddenPaths = sitemapPaths.filter(
+    (path) => options.forbiddenPathPrefixes.some((prefix) => path === prefix || path.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`))
+  );
+  if (forbiddenPaths.length) {
+    failures.push(`- Forbidden sitemap paths found: ${forbiddenPaths.join(", ")}`);
+  }
+  if (options.requireProductionSiteUrl) {
+    const placeholderSiteUrls = extractPlaceholderSiteUrls(sitemapLocValues);
+    if (placeholderSiteUrls.length) {
+      failures.push([
+        `- Placeholder sitemap URLs found: ${placeholderSiteUrls.join(", ")}`,
+        "Expected production URLs in generated sitemap loc values.",
+        "Set site.url or runtimeConfig.public.siteUrl to the deployed origin for production release checks."
+      ].join(" "));
+    }
+  }
   const missingCollections = options.requiredCollections.filter((collection) => (collectionRouteCounts[collection] || 0) === 0);
   if (missingCollections.length) {
     failures.push(`- Missing content sitemap routes for collections: ${missingCollections.join(", ")}`);
@@ -643,16 +728,40 @@ function hasNuxtI18nModule(modules = []) {
 function hasNuxtSitemapModule(modules = []) {
   return hasNuxtModule(modules, "@nuxtjs/sitemap");
 }
+function configureNuxtSitemapSource(nuxt, apiBaseURL, sitemapPath = "/sitemap") {
+  if (!hasNuxtSitemapModule(nuxt.options.modules)) {
+    return;
+  }
+  const source = {
+    context: {
+      name: GINKO_SITEMAP_SOURCE_NAME
+    },
+    fetch: resolveContentSitemapSource(apiBaseURL, sitemapPath)
+  };
+  const sitemap = nuxt.options.sitemap ??= {};
+  const sources = Array.isArray(sitemap.sources) ? sitemap.sources : [];
+  sitemap.sources = [
+    ...sources.filter((item) => {
+      if (typeof item === "string") return item !== source.fetch;
+      return item?.fetch !== source.fetch && item?.context?.name !== GINKO_SITEMAP_SOURCE_NAME;
+    }),
+    source
+  ];
+}
 function resolveNuxtSitemapPrerenderRoutes(nuxt) {
   if (!hasNuxtSitemapModule(nuxt.options.modules)) {
     return [];
   }
+  const nuxtSitemap = nuxt.options.sitemap;
+  if (nuxtSitemap?.sitemaps === false) {
+    return ["/sitemap.xml"];
+  }
   const nuxtI18n = nuxt.options.i18n || {};
   if (!hasNuxtI18nModule(nuxt.options.modules) || !Array.isArray(nuxtI18n.locales) || nuxtI18n.locales.length === 0) {
-    return [];
+    return ["/sitemap.xml"];
   }
   const childRoutes = nuxtI18n.locales.map((locale) => typeof locale === "string" ? locale : locale.language || locale.code).filter(Boolean).map((locale) => `/__sitemap__/${locale}.xml`);
-  return Array.from(/* @__PURE__ */ new Set(["/sitemap_index.xml", ...childRoutes]));
+  return Array.from(/* @__PURE__ */ new Set(["/sitemap.xml", "/sitemap_index.xml", ...childRoutes]));
 }
 function resolveModuleI18nOptions(options, nuxt) {
   if (options.i18n === false) {
@@ -711,7 +820,7 @@ function normalizeSearchOptions(options) {
 }
 const defaultMiniSearchOptions = {
   fields: ["title", "content", "headings"],
-  storeFields: ["path", "title", "excerpt", "anchor", "locale"],
+  storeFields: ["path", "title", "excerpt", "anchor", "locale", "collection"],
   boost: {
     title: 4,
     headings: 2,
@@ -1018,9 +1127,7 @@ const collectSitemapCollectionRouteCounts = async (rootDir, contentContext) => {
   return counts;
 };
 const registerContentNitroIntegrationHooks = (nitroConfig, options, contentContext) => {
-  if (contentContext.provider && contentContext.provider !== "filesystem") {
-    return;
-  }
+  const usesFilesystemProvider = !contentContext.provider || contentContext.provider === "filesystem";
   nitroConfig.hooks ||= {};
   if (contentContext.sitemap?.assert?.enabled) {
     appendHook(nitroConfig.hooks, "compiled", async (nitro) => {
@@ -1032,7 +1139,7 @@ const registerContentNitroIntegrationHooks = (nitroConfig, options, contentConte
         await assertGeneratedSitemaps({
           outputPublicDir: nitro.options.output.publicDir,
           options: assertOptions,
-          collectionRouteCounts: await collectSitemapCollectionRouteCounts(options.rootDir, contentContext),
+          collectionRouteCounts: usesFilesystemProvider ? await collectSitemapCollectionRouteCounts(options.rootDir, contentContext) : {},
           logger: nitro.logger
         });
       } catch (error) {
@@ -1044,15 +1151,73 @@ const registerContentNitroIntegrationHooks = (nitroConfig, options, contentConte
     });
   }
   appendHook(nitroConfig.hooks, "prerender:routes", async (routes) => {
-    for (const route of await collectPrerenderRoutes(options.rootDir, contentContext)) {
-      routes.add(route);
+    if (usesFilesystemProvider) {
+      for (const route of await collectPrerenderRoutes(options.rootDir, contentContext)) {
+        routes.add(route);
+      }
     }
-    for (const route of options.sitemapPrerenderRoutes || []) {
+    const sitemapPrerenderRoutes = typeof options.sitemapPrerenderRoutes === "function" ? options.sitemapPrerenderRoutes() : options.sitemapPrerenderRoutes || [];
+    for (const route of sitemapPrerenderRoutes) {
       routes.add(route);
     }
   });
 };
 
+const getContentPageMeta = (page) => {
+  const content = page.meta?.content;
+  return content && typeof content === "object" ? content : void 0;
+};
+const isRouteConfig = (value) => typeof value === "string" || value !== null && typeof value === "object" && Object.values(value).every((entry) => typeof entry === "string");
+const describePage = (page) => page.file || page.path || "<unknown page>";
+const expectedLocalesFor = (collection, locales, defaultLocale) => {
+  const collectionI18n = collection.i18n && typeof collection.i18n === "object" ? collection.i18n : void 0;
+  return collectionI18n?.locales?.length ? collectionI18n.locales : locales.length ? locales : defaultLocale ? [defaultLocale] : [];
+};
+function validateContentPageRouteMetadata(pages, collections, options = {}) {
+  const visit = (page) => {
+    const contentMeta = getContentPageMeta(page);
+    if (contentMeta) {
+      validatePage(page, contentMeta, collections, options);
+    }
+    for (const child of page.children || []) {
+      visit(child);
+    }
+  };
+  for (const page of pages) {
+    visit(page);
+  }
+}
+function validatePage(page, contentMeta, collections, options) {
+  const collectionName = contentMeta.collection;
+  if (typeof collectionName !== "string" || !collectionName) {
+    throw new Error(`@lupinum/ginko-content page "${describePage(page)}" declares content route metadata without a string collection name.`);
+  }
+  const collection = collections[collectionName];
+  if (!collection) {
+    throw new Error(`@lupinum/ginko-content page "${describePage(page)}" declares content collection "${collectionName}", but no matching collection exists in content.config.ts.`);
+  }
+  if (!isRouteConfig(contentMeta.route)) {
+    throw new Error(`@lupinum/ginko-content page "${describePage(page)}" declares content collection "${collectionName}" but no route metadata. Add definePageMeta({ content: { collection: '${collectionName}', route: ... } }).`);
+  }
+  const locales = expectedLocalesFor(collection, options.locales || [], options.defaultLocale);
+  const defaultLocale = collection.i18n && typeof collection.i18n === "object" ? collection.i18n.defaultLocale : options.defaultLocale;
+  const expected = normalizeRouteMounts(collection.route, locales, defaultLocale);
+  const actual = normalizeRouteMounts(contentMeta.route, locales, defaultLocale);
+  if (!expected) {
+    throw new Error(`@lupinum/ginko-content page "${describePage(page)}" declares route metadata for collection "${collectionName}", but that collection has no route config in content.config.ts.`);
+  }
+  for (const locale of Object.keys(expected)) {
+    const expectedRoute = normalizeContentPath(expected[locale]);
+    const actualRoute = actual?.[locale] ? normalizeContentPath(actual[locale]) : void 0;
+    if (!actualRoute) {
+      throw new Error(`@lupinum/ginko-content route metadata mismatch in "${describePage(page)}": collection "${collectionName}" is missing locale "${locale}" route "${expectedRoute}".`);
+    }
+    if (actualRoute !== expectedRoute) {
+      throw new Error(`@lupinum/ginko-content route metadata mismatch in "${describePage(page)}": collection "${collectionName}" locale "${locale}" expected route "${expectedRoute}" but page metadata declares "${actualRoute}".`);
+    }
+  }
+}
+
 const module$1 = defineNuxtModule({
   meta: {
     name,
@@ -1158,6 +1323,7 @@ const module$1 = defineNuxtModule({
     const resolvedI18n = resolveModuleI18nOptions(options, nuxt);
     const resolvedSitemap = normalizeSitemapOptions(options);
     const resolvedSearch = normalizeSearchOptions(options);
+    validateCollectionNames(appContentConfig.collections);
     options.collections = Object.fromEntries(Object.entries(appContentConfig.collections).map(([name2, collection]) => [
       name2,
       {
@@ -1170,10 +1336,11 @@ const module$1 = defineNuxtModule({
       }
     ]));
     options.provider = appContentConfig.provider || options.provider || "filesystem";
-    options.providers = {
+    const providerRegistry = {
       ...options.providers || {},
       ...appContentConfig.providers || {}
     };
+    options.providers = providerRegistry;
     const buildIntegrity = nuxt.options.dev ? void 0 : Date.now();
     const contentContext = {
       ...options,
@@ -1186,6 +1353,15 @@ const module$1 = defineNuxtModule({
       sitemap: resolvedSitemap,
       search: resolvedSearch
     };
+    if (resolvedSitemap !== false) {
+      configureNuxtSitemapSource(nuxt, options.api.baseURL, resolvedSitemap.path);
+    }
+    nuxt.hook("pages:extend", (pages) => {
+      validateContentPageRouteMetadata(pages, options.collections, {
+        locales: resolvedI18n.locales,
+        defaultLocale: resolvedI18n.defaultLocale
+      });
+    });
     if (resolvedSitemap && resolvedSitemap.assert.enabled) {
       nuxt.hook("sitemap:prerender:done", async ({ sitemaps }) => {
         const assertOptions = contentContext.sitemap?.assert;
@@ -1207,7 +1383,12 @@ const module$1 = defineNuxtModule({
     registerRuntimeImports(resolveRuntimeModule);
     registerRuntimeComponents(resolve);
     registerContentComponentsTemplate(addTemplate);
-    registerGeneratedTypes(contentConfigPath, resolveRuntimeModule);
+    registerGeneratedTypes(
+      contentConfigPath,
+      resolveRuntimeModule,
+      Object.keys(appContentConfig.collections),
+      Object.entries(appContentConfig.collections).filter(([, collection]) => Boolean(collection.i18n)).map(([name2]) => name2)
+    );
     await registerUserContentComponents(nuxt, resolve);
     const getSearchRuntime = () => contentContext.search === false ? false : createSearchRuntimeConfig(contentContext.search, options.api.baseURL);
     nuxt.hook("nitro:config", (nitroConfig) => {
@@ -1265,7 +1446,7 @@ const module$1 = defineNuxtModule({
       }
       registerContentNitroIntegrationHooks(nitroConfig, {
         rootDir: nuxt.options.rootDir,
-        sitemapPrerenderRoutes: contentContext.sitemap === false ? [] : resolveNuxtSitemapPrerenderRoutes(nuxt)
+        sitemapPrerenderRoutes: () => contentContext.sitemap === false ? [] : resolveNuxtSitemapPrerenderRoutes(nuxt)
       }, {
         collections: contentContext.collections,
         locales: contentContext.locales,
@@ -1310,6 +1491,8 @@ const module$1 = defineNuxtModule({
       });
     }
     nuxt.hook("modules:done", async () => {
+      await nuxt.callHook("content:providers", contentContext.providers ||= {});
+      assertConfiguredProviderAvailable(contentContext);
       await nuxt.callHook("content:context", contentContext);
       if (contentContext.search !== false) {
         registerContentSearchServerHandlers(options.api.baseURL, contentContext.search, resolveRuntimeModule);
@@ -1317,17 +1500,22 @@ const module$1 = defineNuxtModule({
       contentContext.defaultLocale = contentContext.defaultLocale || contentContext.locales[0];
       contentContext.markdown = processMarkdownOptions(contentContext.markdown);
       await validateBuiltinMarkdownPlugins(contentContext.markdown.plugins, resolvePath);
-      const runtimeCollections = Object.fromEntries(Object.entries(options.collections || {}).map(([name2, collection]) => [
-        name2,
-        {
-          ...collection.source ? { source: collection.source } : {},
-          ...collection.exclude ? { exclude: collection.exclude } : {},
-          strict: collection.strict ?? true,
-          ...collection.route ? { route: collection.route } : {},
-          ...typeof collection.sitemap === "boolean" ? { sitemap: collection.sitemap } : {},
-          ...collection.i18n && collection.i18n !== true ? { i18n: collection.i18n } : {}
-        }
-      ]));
+      const runtimeCollections = Object.fromEntries(Object.entries(options.collections || {}).map(([name2, collection]) => {
+        const references = collectTopLevelReferenceFieldsByTarget(collection.schema);
+        return [
+          name2,
+          {
+            ...collection.source ? { source: collection.source } : {},
+            ...collection.exclude ? { exclude: collection.exclude } : {},
+            ...collection.type ? { type: collection.type } : {},
+            strict: collection.strict ?? true,
+            ...collection.route ? { route: collection.route } : {},
+            ...typeof collection.sitemap === "boolean" ? { sitemap: collection.sitemap } : {},
+            ...collection.i18n && collection.i18n !== true ? { i18n: collection.i18n } : {},
+            ...Object.keys(references).length ? { references } : {}
+          }
+        ];
+      }));
       const cacheIntegrity = hash({
         locales: contentContext.locales,
         defaultLocale: contentContext.defaultLocale,
@@ -1348,6 +1536,18 @@ const module$1 = defineNuxtModule({
     }
   }
 });
+function assertConfiguredProviderAvailable(contentContext) {
+  const provider = contentContext.provider || "filesystem";
+  if (provider === "filesystem") return;
+  if (contentContext.providers?.[provider]) return;
+  if (provider === "cms") {
+    throw new Error('content.config.ts sets provider "cms", but no CMS provider module registered it. Add @lupinum/ginko-cms to nuxt.config.ts modules or remove provider: "cms".');
+  }
+  throw new Error(`content.config.ts sets provider "${provider}", but no provider module registered it. Register a module for "${provider}" or add it to content providers.`);
+}
+function validateCollectionNames(collections) {
+  normalizeContentConfigCollectionNames(collections);
+}
 function validateRemovedMarkdownOptions(options) {
   if (options.highlight !== void 0) {
     throw new Error("`content.highlight` was removed. Enable syntax highlighting with `content.markdown.plugins`, for example `[['highlight', { ...options }]]`.");

package/dist/public/client.d.ts

@@ -7,9 +7,11 @@
 export { one, many, paginate, backlinks, resolveOne, variants, tree, neighbors } from '../runtime/app/composables/query-api.js';
 export { getCollectionPath } from '../runtime/query/routes.js';
 export type { CollectionPathOptions } from '../runtime/query/routes.js';
-export { useContentPage, useContentOne, useContentMany, useContentPagination, useContentBacklinks, useContentResolveOne, useContentVariants, useContentTree, useContentNeighbors, useContentLocaleSwitch } from '../runtime/app/composables/use-content.js';
+export { useContentHead } from '../runtime/app/composables/head.js';
+export { useContentPage, useContentOne, useContentMany, useContentPagination, useContentBacklinks, useContentResolveOne, useContentVariants, useContentTree, useContentNavigation, useContentNeighbors, useContentLocaleSwitch } from '../runtime/app/composables/use-content.js';
 export type { UseContentPageOptions } from '../runtime/app/composables/use-content.js';
-export type { QueryWhere, QueryOperators, ContentSelector, ContentResolvedMeta, BacklinkFields, BacklinkSource, BacklinksOptions, BacklinksResult, LocaleFallback, DocumentFromHandle, OneOptions, ManyOptions, PaginationOptions, PaginationResult, PopulateSpec, PopulatedDocument, ResolveOneOptions, ResolveOneResult, LocalizedDoc, LocalePathEntry, NeighborsOptions, NeighborsResult, ResolutionEnvelope, SortSpec, TreeOptions, VariantsOptions, ContentVariant, ContentNavigationItem, ContentTreeItem, ContentRouteMeta, ContentSearchSection } from '../types/query.js';
+export type { QueryWhere, QueryOperators, ContentSelector, ContentResolvedMeta, BacklinkFields, BacklinkSource, BacklinksOptions, BacklinksResult, LocaleFallback, DocumentFromHandle, OneOptions, ManyOptions, PaginationOptions, PaginationResult, PopulateSpec, PopulatedDocument, ResolveOneOptions, ResolveOneResult, LocalizedDoc, LocalePathEntry, NeighborsOptions, NeighborsResult, ResolutionEnvelope, SortSpec, TreeOptions, VariantsOptions, ContentVariant, ContentNavigationItem, ContentCollectionName, ContentCollectionStringName, ContentCollectionTarget, ContentTreeItem, ContentRouteMeta, ContentSearchSection } from '../types/query.js';
+export type { ContentNavigationNode } from '../runtime/app/composables/use-content.js';
 export { useContentSearch, useContentSearchData, useContentSearchResults } from '../runtime/app/composables/search.js';
 export type { UseContentSearchDataOptions, UseContentSearchDataResult, UseContentSearchOptions, UseContentSearchResult, UseContentSearchResultsOptions, UseContentSearchResultsResult } from '../runtime/app/composables/search.js';
 export { querySiteData } from '../runtime/app/composables/site-data.js';

package/dist/public/client.js

@@ -9,6 +9,7 @@ export {
   neighbors
 } from "../runtime/app/composables/query-api.js";
 export { getCollectionPath } from "../runtime/query/routes.js";
+export { useContentHead } from "../runtime/app/composables/head.js";
 export {
   useContentPage,
   useContentOne,
@@ -18,6 +19,7 @@ export {
   useContentResolveOne,
   useContentVariants,
   useContentTree,
+  useContentNavigation,
   useContentNeighbors,
   useContentLocaleSwitch
 } from "../runtime/app/composables/use-content.js";

package/dist/runtime/app/components/ContentRenderer.vue

@@ -11,6 +11,13 @@ function normalizeBody(value, excerpt) {
   }
   return null;
 }
+function warnUnsupportedValue(value, excerpt) {
+  const path = value?._path ? ` for "${value._path}"` : "";
+  const target = excerpt ? "excerpt" : "body";
+  console.warn(
+    `[ginko-content] <ContentRenderer> could not render ${target}${path}. Pass the full content document with a markdown body, or provide an \`empty\` slot for empty/unsupported content.`
+  );
+}
 export default defineComponent({
   name: "ContentRenderer",
   props: {
@@ -74,11 +81,8 @@ export default defineComponent({
         ...this.$attrs
       });
     }
-    return h(
-      "pre",
-      null,
-      JSON.stringify({ message: "You should use slots with <ContentRenderer>", value, excerpt, tag, prose, unwrap }, null, 2)
-    );
+    warnUnsupportedValue(value, excerpt);
+    return null;
   }
 });
 </script>

package/dist/runtime/app/components/internal/ContentRendererMarkdown.d.vue.ts

@@ -57,8 +57,8 @@ declare const __VLS_export: import("vue").DefineComponent<import("vue").ExtractP
         default: () => {};
     };
 }>> & Readonly<{}>, {
-    data: Record<string, any>;
     excerpt: boolean;
+    data: Record<string, any>;
     components: Record<string, any>;
     prose: boolean;
     tag: string;

package/dist/runtime/app/components/internal/ContentRendererMarkdown.vue.d.ts

@@ -57,8 +57,8 @@ declare const __VLS_export: import("vue").DefineComponent<import("vue").ExtractP
         default: () => {};
     };
 }>> & Readonly<{}>, {
-    data: Record<string, any>;
     excerpt: boolean;
+    data: Record<string, any>;
     components: Record<string, any>;
     prose: boolean;
     tag: string;

package/dist/runtime/app/composables/head.d.ts

@@ -1,11 +1,35 @@
 import type { RouteLocationNormalized, RouteLocationNormalizedLoaded } from 'vue-router';
 import type { Ref } from 'vue';
-import type { ParsedContent } from '../../../types/content';
+type ContentHeadObject = {
+    title?: string;
+    description?: string;
+    image?: string | Record<string, any>;
+    meta?: Array<Record<string, any>>;
+    link?: Array<Record<string, any>>;
+    [key: string]: any;
+};
+type ContentHeadDocument = {
+    title?: string;
+    description?: string;
+    image?: string | Record<string, any>;
+    head?: ContentHeadObject;
+    seo?: ContentHeadObject;
+};
+type ContentHeadRuntimeConfig = {
+    app: {
+        baseURL: string;
+    };
+    public: {
+        siteUrl?: unknown;
+    };
+};
 /**
  * Apply sensible page head defaults from a parsed content document.
  *
- * The composable merges explicit `content.head` values with common fallbacks
+ * The composable merges explicit `content.head` or `content.seo` values with common fallbacks
  * from the document (`title`, `description`, `image`) and adds canonical /
  * Open Graph URL metadata when a public site URL is configured.
  */
-export declare const useContentHead: (_content: ParsedContent | Ref<ParsedContent>, to?: RouteLocationNormalized | RouteLocationNormalizedLoaded) => void;
+export declare const useContentHead: (_content: ContentHeadDocument | null | undefined | Ref<ContentHeadDocument | null | undefined>, to?: RouteLocationNormalized | RouteLocationNormalizedLoaded) => void;
+export declare const resolveContentHead: (data: ContentHeadDocument | null | undefined, to: Pick<RouteLocationNormalized | RouteLocationNormalizedLoaded, "path" | "fullPath">, config: ContentHeadRuntimeConfig) => ContentHeadObject | null;
+export {};