@lupinum/ginko-content 0.1.1 → 0.1.2

package/dist/runtime/query/unified.js

@@ -1,8 +1,8 @@
 import { compileQueryParams } from "../../core/query/filter";
 import { decorateLocalePathsWithFallbacks, localizePageResult } from "../../features/localization/results";
-import { normalizeRouteMounts } from "../../features/localization/path";
+import { normalizeContentPath, normalizeRouteMounts } from "../../features/localization/path";
 import { normalizeReferenceValue } from "../../core/references/resolve";
-import { collectTopLevelReferenceFields } from "../../core/references/schema";
+import { collectTopLevelReferenceFields, collectTopLevelReferenceFieldsByTarget } from "../../core/references/schema";
 import { MAX_PUBLIC_QUERY_LIMIT, MAX_PUBLIC_QUERY_SKIP } from "./public-limits.js";
 const NAVIGATION_INTERNAL_FIELDS = [
   "_id",
@@ -95,6 +95,23 @@ const decorate = (doc, collection, runtime, requestedLocale) => {
   result.localePaths = decorateLocalePathsWithFallbacks(result.localePaths, locales, fallbackLocale, defaultLocale, routeMounts);
   return result;
 };
+const collectionRouteRoots = (collection, runtime) => {
+  const collectionConfig = runtime?.collections?.[collection];
+  const collectionI18n = collectionConfig?.i18n;
+  const collectionLocales = collectionI18n && typeof collectionI18n === "object" ? collectionI18n.locales : void 0;
+  const collectionDefault = collectionI18n && typeof collectionI18n === "object" ? collectionI18n.defaultLocale : void 0;
+  const locales = collectionLocales?.length ? collectionLocales : runtime?.locales?.length ? runtime.locales : [];
+  const defaultLocale = collectionDefault || runtime?.defaultLocale;
+  const routeMounts = normalizeRouteMounts(collectionConfig?.route, locales, defaultLocale);
+  return new Set(Object.values(routeMounts || {}).map((value) => normalizeContentPath(value)));
+};
+const isCollectionRouteRoot = (path, collection, runtime) => collectionRouteRoots(collection, runtime).has(normalizeContentPath(path));
+const isAncestorRoutePath = (path, childPath) => {
+  const normalized = normalizeContentPath(path);
+  const child = normalizeContentPath(childPath);
+  return normalized === "/" ? child !== "/" : child.startsWith(`${normalized}/`);
+};
+const isNavigationRootPath = (path, flat) => Boolean(flat[0]?.path && isAncestorRoutePath(path, flat[0].path));
 const collectionDefaultLocale = (collection, runtime) => {
   const collectionI18n = runtime?.collections?.[collection]?.i18n;
   const collectionDefault = collectionI18n && typeof collectionI18n === "object" ? collectionI18n.defaultLocale : void 0;
@@ -133,7 +150,7 @@ const explainResolution = (collection, requestedBy, normalizedBy, requestedLocal
 const ensureCollectionName = (handle) => {
   if (typeof handle === "string") return handle;
   if (!handle || typeof handle !== "object" || typeof handle.name !== "string") {
-    throw new TypeError("query API: expected a collection handle from defineCollection(name, config) or a string collection name");
+    throw new TypeError("query API: expected a string collection name or a collection handle from defineContentConfig({ collections }). Use useContentPage('docs') or config.collections.docs.");
   }
   return handle.name;
 };
@@ -150,6 +167,55 @@ const populateReferenceValue = async (context, target, value, locale, fallback)
     ...fallback !== void 0 ? { fallback } : {}
   });
 };
+const wildcardReferenceTarget = "*";
+const collectReferenceFieldsByTarget = (source, sourceCollection, runtime) => {
+  if (typeof source !== "string") {
+    return collectTopLevelReferenceFieldsByTarget(source.schema);
+  }
+  return runtime?.collections?.[sourceCollection]?.references || {};
+};
+const invertReferenceFields = (references) => {
+  const fields = /* @__PURE__ */ new Map();
+  for (const [target, targetFields] of Object.entries(references)) {
+    for (const field of targetFields) {
+      const targets = fields.get(field) || [];
+      targets.push(target);
+      fields.set(field, targets);
+    }
+  }
+  return fields;
+};
+const createPopulateTargetMismatchError = (sourceCollection, field, expectedTargets, actualTarget) => new Error([
+  `Cannot populate "${sourceCollection}.${field}" from "${actualTarget}".`,
+  `Reference metadata declares "${sourceCollection}.${field}" points to ${expectedTargets.map((target) => `"${target}"`).join(" or ")}.`,
+  `Change populate.${field} to the declared target collection, or update ${sourceCollection}.schema relation metadata.`
+].join(" "));
+const validatePopulateSpec = (source, sourceCollection, runtime, populate) => {
+  if (!populate || !isRecord(populate)) {
+    return;
+  }
+  const references = collectReferenceFieldsByTarget(source, sourceCollection, runtime);
+  const fieldTargets = invertReferenceFields(references);
+  if (!fieldTargets.size) {
+    return;
+  }
+  for (const [field, target] of Object.entries(populate)) {
+    const declaredTargets = fieldTargets.get(field);
+    if (!declaredTargets?.length) {
+      continue;
+    }
+    const actualTarget = ensureCollectionName(target);
+    if (declaredTargets.includes(actualTarget) || declaredTargets.includes(wildcardReferenceTarget)) {
+      continue;
+    }
+    throw createPopulateTargetMismatchError(
+      sourceCollection,
+      field,
+      declaredTargets.filter((target2) => target2 !== wildcardReferenceTarget),
+      actualTarget
+    );
+  }
+};
 const populateDocument = async (context, doc, populate, locale, fallback) => {
   if (!populate || !isRecord(populate)) {
     return doc;
@@ -179,6 +245,7 @@ const selectWithPopulate = (select, populate) => {
 export async function resolveOne(context, handle, options) {
   const collection = ensureCollectionName(handle);
   const runtime = context.runtime;
+  validatePopulateSpec(handle, collection, runtime, options.populate);
   const by = options.by;
   const fallback = resolveFallback(options.fallback, collection, runtime);
   const params = compileQueryParams({
@@ -216,6 +283,7 @@ export async function one(context, handle, options) {
 export async function many(context, handle, options = {}) {
   const collection = ensureCollectionName(handle);
   const runtime = context.runtime;
+  validatePopulateSpec(handle, collection, runtime, options.populate);
   const fallback = resolveFallback(options.fallback, collection, runtime);
   const params = compileQueryParams({
     collection,
@@ -247,6 +315,7 @@ const normalizePositiveInteger = (value, fallback) => {
 export async function paginate(context, handle, options) {
   const collection = ensureCollectionName(handle);
   const runtime = context.runtime;
+  validatePopulateSpec(handle, collection, runtime, options.populate);
   const requestedPage = normalizePositiveInteger(options.page, 1);
   const limit = Math.min(normalizePositiveInteger(options.limit, 10), MAX_PUBLIC_QUERY_LIMIT);
   const skip = Math.min((requestedPage - 1) * limit, MAX_PUBLIC_QUERY_SKIP);
@@ -323,9 +392,13 @@ const resolveExplicitBacklinkFields = (fields, sourceName) => {
   const sourceFields = fields?.[sourceName];
   return Array.isArray(sourceFields) ? sourceFields.filter((field) => typeof field === "string" && field.length > 0) : [];
 };
-const inferBacklinkFields = (source, targetCollection) => {
+const inferBacklinkFields = (source, targetCollection, runtime) => {
   if (typeof source === "string") {
-    return [];
+    const references = runtime?.collections?.[source]?.references;
+    return [
+      ...references?.[targetCollection] || [],
+      ...references?.["*"] || []
+    ];
   }
   return collectTopLevelReferenceFields(source.schema, targetCollection);
 };
@@ -346,6 +419,9 @@ const backlinkWhere = (fields, candidates) => {
   }));
   return clauses.length ? { $or: clauses } : void 0;
 };
+const createMissingBacklinkFieldsError = (sourceCollection, targetCollection) => new Error(
+  `Cannot infer backlink fields from "${sourceCollection}" to "${targetCollection}". Declare fields.relation('${targetCollection}') / fields.relations('${targetCollection}') in ${sourceCollection}.schema, or pass fields explicitly.`
+);
 export async function backlinks(context, targetHandle, options) {
   const targetCollection = ensureCollectionName(targetHandle);
   const target = await one(context, targetHandle, {
@@ -366,9 +442,12 @@ export async function backlinks(context, targetHandle, options) {
     const fields = [
       .../* @__PURE__ */ new Set([
         ...resolveExplicitBacklinkFields(options.fields, sourceName),
-        ...inferBacklinkFields(source, targetCollection)
+        ...inferBacklinkFields(source, targetCollection, context.runtime)
       ])
     ];
+    if (!fields.length) {
+      throw createMissingBacklinkFieldsError(sourceName, targetCollection);
+    }
     const where = backlinkWhere(fields, candidates);
     if (!where) {
       return [];
@@ -441,6 +520,8 @@ export async function tree(context, handle, options = {}) {
   return list;
 }
 export async function neighbors(context, handle, options) {
+  const collection = ensureCollectionName(handle);
+  const runtime = context.runtime;
   const seed = await one(context, handle, {
     by: options.by,
     locale: options.locale,
@@ -465,6 +546,12 @@ export async function neighbors(context, handle, options) {
   walk(fullTree);
   const targetPath = seed.path;
   const idx = flat.findIndex((entry) => entry.path === targetPath);
+  if (idx === -1 && (isCollectionRouteRoot(targetPath, collection, runtime) || isNavigationRootPath(targetPath, flat))) {
+    return {
+      prev: null,
+      next: flat[0]?.item ?? null
+    };
+  }
   if (idx === -1) return { prev: null, next: null };
   return {
     prev: flat[idx - 1]?.item ?? null,

package/dist/runtime/server/api/search.d.ts

@@ -1,2 +1,3 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("..").MaybeContentProviderResult<import("../../../types").ContentSearchResult[]>>>;
+import type { ContentSearchResult } from '../../../types/search';
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<ContentSearchResult[]>>;
 export default _default;

package/dist/runtime/server/api/search.js

@@ -3,6 +3,10 @@ import { useRuntimeConfig } from "nitropack/runtime";
 import { buildSearchIndex, searchRecords } from "../search.js";
 import { getContentProvider } from "../providers/index.js";
 import { createContentProviderError } from "../../../public/provider-errors";
+const normalizeSearchResults = (results = []) => results.map((result) => ({
+  ...result,
+  collection: typeof result.collection === "string" ? result.collection : ""
+}));
 export default defineEventHandler(async (event) => {
   const runtimeConfig = useRuntimeConfig(event);
   const searchConfig = runtimeConfig.content.search;
@@ -22,11 +26,11 @@ export default defineEventHandler(async (event) => {
         provider: provider.name
       });
     }
-    return await provider.search(event, {
+    return normalizeSearchResults(await provider.search(event, {
       term,
       locale,
       collections: searchConfig.collections
-    });
+    }));
   }
   const records = await buildSearchIndex(event, {
     collections: searchConfig.collections,

package/dist/runtime/server/pagefind.js

@@ -14,6 +14,7 @@ export async function writePagefindIndex(records, outputPath) {
       meta: {
         title: record.title,
         excerpt: record.excerpt,
+        collection: record.collection,
         locale: record.locale || "",
         anchor: record.anchor || "",
         path: record.path

package/dist/runtime/server/search.d.ts

@@ -4,6 +4,17 @@ import type { ContentQueryBuilderWhere } from '../../types/query';
 import type { ContentSearchIndexRecord } from '../../types/search';
 export { searchRecords } from '../shared/search';
 type SearchablePage = Pick<ParsedContent, '_path' | '_locale' | 'title' | 'description' | 'body'> & Record<string, unknown>;
+type RuntimeSearchConfig = {
+    search?: {
+        collections?: string[];
+    } | false;
+    collections?: Record<string, {
+        type?: 'page' | 'data';
+        route?: unknown;
+        sitemap?: boolean;
+    } | unknown>;
+};
+export declare const resolveSearchCollections: (runtimeContent: RuntimeSearchConfig, collectionsOverride?: string[]) => string[];
 export declare const clearSearchRecordsCache: () => void;
 export declare function serverSearchContent(event: H3Event, filterQuery?: ContentQueryBuilderWhere, locale?: string, collectionsOverride?: string[], opts?: {
     allLocales?: boolean;

package/dist/runtime/server/search.js

@@ -5,6 +5,21 @@ import { serverQueryCollection } from "./provider-query.js";
 import { createContentProviderError } from "../../public/provider-errors";
 export { searchRecords } from "../shared/search.js";
 const unique = (values) => Array.from(new Set(values.filter(Boolean)));
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const hasRouteMount = (route) => route !== void 0 && route !== null && route !== "";
+const isRouteBackedSearchCollection = (config) => {
+  if (!isRecord(config) || config.sitemap === false || config.type === "data") {
+    return false;
+  }
+  return config.type === "page" || hasRouteMount(config.route) || config.sitemap === true;
+};
+export const resolveSearchCollections = (runtimeContent, collectionsOverride) => {
+  const configuredCollections = collectionsOverride || (runtimeContent.search && runtimeContent.search !== false ? runtimeContent.search.collections : void 0);
+  if (configuredCollections?.length) {
+    return unique(configuredCollections);
+  }
+  return Object.entries(runtimeContent.collections || {}).filter(([, config]) => isRouteBackedSearchCollection(config)).map(([collection]) => collection);
+};
 const searchRecordsCache = /* @__PURE__ */ new Map();
 const MAX_SEARCH_RECORDS_CACHE_ENTRIES = 12;
 export const clearSearchRecordsCache = () => {
@@ -32,9 +47,7 @@ const mergeSearchFilter = (filterQuery, locale) => {
 };
 export async function serverSearchContent(event, filterQuery, locale, collectionsOverride, opts = {}) {
   const runtimeConfig = useRuntimeConfig(event);
-  const configuredCollections = collectionsOverride || runtimeConfig.content.search?.collections;
-  const contentCollections = Object.keys(runtimeConfig.content.collections || {});
-  const collections = (configuredCollections?.length ? configuredCollections : contentCollections).filter(Boolean);
+  const collections = resolveSearchCollections(runtimeConfig.content, collectionsOverride);
   const results = await Promise.all(collections.map(async (collection) => {
     const loadPages = async (queryLocale) => {
       const query = serverQueryCollection(event, collection).select("_path", "_locale", "title", "description", "body");
@@ -64,6 +77,7 @@ const toSearchRecord = (section) => {
   return {
     ...extraFields,
     id: section.id,
+    collection: section.collection || "",
     path,
     title: section.title,
     excerpt: section.content.slice(0, 240),
@@ -76,12 +90,15 @@ const toSearchRecord = (section) => {
 const buildProviderSearchSections = async (event, collections, provider, opts) => {
   const runtimeConfig = useRuntimeConfig(event);
   const sections = await Promise.all(collections.map(async (collection) => {
-    const loadCollectionLocale = async (locale) => await provider.searchSections(event, collection, {
+    const loadCollectionLocale = async (locale) => (await provider.searchSections(event, collection, {
       ignoredTags: opts.ignoredTags || [],
       extraFields: unique(["_locale", ...opts.extraFields || []]),
       filterQuery: opts.filterQuery,
       locale
-    });
+    })).map((section) => ({
+      ...section,
+      collection
+    }));
     if (opts.locale) {
       return await loadCollectionLocale(opts.locale);
     }
@@ -100,7 +117,7 @@ export async function buildSearchIndex(event, opts = {}) {
   const cacheKey = JSON.stringify({
     provider: provider.name,
     integrity: runtimeConfig.content.cacheIntegrity || runtimeConfig.public.content?.integrity,
-    collections: opts.collections || runtimeConfig.content.search?.collections,
+    collections: resolveSearchCollections(runtimeConfig.content, opts.collections),
     ignoredTags: opts.ignoredTags || [],
     extraFields: opts.extraFields || runtimeConfig.content.search?.extraFields || [],
     filterQuery: opts.filterQuery,
@@ -111,7 +128,7 @@ export async function buildSearchIndex(event, opts = {}) {
   if (cached) {
     return cached;
   }
-  const collections = (opts.collections || runtimeConfig.content.search?.collections || Object.keys(runtimeConfig.content.collections || {})).filter(Boolean);
+  const collections = resolveSearchCollections(runtimeConfig.content, opts.collections);
   if (!provider.capabilities.searchSections) {
     throw createContentProviderError("unsupported_provider_search_index", `${provider.name} does not support search index generation`, {
       provider: provider.name

package/dist/runtime/shared/search.js

@@ -1,7 +1,7 @@
 import MiniSearch from "minisearch";
 const DEFAULT_SEARCH_OPTIONS = {
   fields: ["title", "content", "headings"],
-  storeFields: ["path", "title", "excerpt", "anchor", "locale"],
+  storeFields: ["path", "title", "excerpt", "anchor", "locale", "collection"],
   boost: {
     title: 4,
     headings: 2,
@@ -10,7 +10,7 @@ const DEFAULT_SEARCH_OPTIONS = {
   fuzzy: 0.2,
   prefix: true
 };
-const REQUIRED_STORE_FIELDS = ["path", "title", "excerpt"];
+const REQUIRED_STORE_FIELDS = ["path", "title", "excerpt", "collection"];
 const MAX_SEARCH_INDEX_CACHE_ENTRIES = 12;
 const searchIndexCache = /* @__PURE__ */ new Map();
 const resolveSearchOptions = (options = {}) => {
@@ -79,6 +79,7 @@ export const searchRecords = (records, term, locale, searchOptions) => {
     return {
       ...storedFields,
       path: typeof result.path === "string" ? result.path : "",
+      collection: typeof result.collection === "string" ? result.collection : "",
       title: typeof result.title === "string" ? result.title : "",
       excerpt: typeof result.excerpt === "string" ? result.excerpt : "",
       score: result.score,

package/dist/testing/provider-fixture.js

@@ -342,6 +342,7 @@ export const createFixtureContentProvider = (fixture, name = fixture.providerNam
       const term = request.term.toLocaleLowerCase();
       return fixture.documents.filter((doc) => !request.collections?.length || request.collections.includes(doc._collection || "")).filter((doc) => !request.locale || doc._locale === request.locale).filter((doc) => String(doc.title || "").toLocaleLowerCase().includes(term)).map((doc) => ({
         score: 1,
+        collection: doc._collection || "",
         title: doc.title || "",
         excerpt: String(doc.description || ""),
         path: localizePath(fixture, doc._collection || "", doc._path || "/", doc._locale),

package/dist/types/config.d.ts

@@ -20,6 +20,7 @@ export type ContentCollectionSource = string | string[];
  * express roots such as `{ en: '/docs', de: '/dokumentation' }`.
  */
 export type ContentCollectionRouteConfig = string | Record<string, string>;
+export type ContentCollectionKind = 'page' | 'data';
 export type ContentCmsFieldType = 'text' | 'textarea' | 'richtext' | 'slug' | 'email' | 'url' | 'number' | 'range' | 'select' | 'multiselect' | 'radio' | 'checkbox' | 'toggle' | 'date' | 'datetime' | 'time' | 'json' | 'object' | 'array' | 'blocks' | 'relation' | 'relations' | 'image' | 'images' | 'file' | 'icon' | 'code' | 'color' | 'divider' | 'section';
 export interface ContentCmsRelationConfig {
     collectionId: string;
@@ -79,6 +80,11 @@ export interface ContentCollectionSourceObject {
  * Declarative collection definition used by `content.config.ts`.
  */
 export interface ContentCollectionConfig<TSchema extends ZodType | undefined = ZodType | undefined> {
+    /**
+     * Collection kind declared in `defineCollection`. Page collections are public
+     * content routes by default; data collections are app-owned records.
+     */
+    type?: ContentCollectionKind;
     /**
      * Source glob or source descriptor understood by the filesystem ingestion
      * layer. CMS-backed projects do not need a runtime source; filesystem
@@ -131,13 +137,13 @@ export interface ContentCollectionConfig<TSchema extends ZodType | undefined = Z
      */
     cms?: ContentCmsCollectionConfig;
 }
-export type ContentCollectionKind = 'page' | 'data';
 export type ContentProviderName = 'filesystem' | (string & {});
 export type DefineCollectionOptions<TSchema extends ZodType | undefined = ZodType | undefined> = Omit<ContentCollectionConfig<TSchema>, 'source' | 'exclude'>;
 export interface DefineCollectionObject<TSchema extends ZodType | undefined = ZodType | undefined> extends DefineCollectionOptions<TSchema> {
     /**
      * Nuxt Content v3-compatible collection kind. Ginko does not keep separate
-     * page/data collection runtimes; `data` collections default to `sitemap: false`.
+     * page/data query builders, but the kind remains canonical metadata at runtime.
+     * `data` collections default to `sitemap: false`.
      */
     type: ContentCollectionKind;
     /**
@@ -213,6 +219,16 @@ export interface ContentCollectionHandle<Name extends string = string, TSchema e
 type IsI18nConfig<TConfig> = TConfig extends {
     i18n: true | ContentCollectionI18nConfig;
 } ? TConfig['i18n'] extends false ? false : true : false;
+type CollectionNameFromConfigKey<Key extends string, TCollection> = TCollection extends ContentCollectionHandle<infer Name, ZodType | undefined, boolean> ? [Name] extends [never] ? Key : Name : Key;
+type NamedContentCollection<Key extends string, TCollection> = TCollection extends ContentCollectionHandle<infer Name, infer TSchema, infer TI18n> ? Omit<TCollection, 'name' | '__schema' | '__i18n'> & ContentCollectionHandle<[
+    Name
+] extends [never] ? Key : Name, TSchema, TI18n> : TCollection extends ContentCollectionConfig<infer TSchema> ? Omit<TCollection, 'name' | '__schema' | '__i18n'> & ContentCollectionHandle<CollectionNameFromConfigKey<Key, TCollection>, TSchema, IsI18nConfig<TCollection>> : TCollection;
+type NamedContentCollections<TCollections extends Record<string, ContentCollectionConfig>> = {
+    [Key in keyof TCollections]: Key extends string ? NamedContentCollection<Key, TCollections[Key]> : TCollections[Key];
+};
+type NamedContentConfig<TCollections extends Record<string, ContentCollectionConfig>> = Omit<ContentConfig<TCollections>, 'collections'> & {
+    collections: NamedContentCollections<TCollections>;
+};
 /**
  * Define a content collection in `content.config.ts`.
  *
@@ -221,7 +237,7 @@ type IsI18nConfig<TConfig> = TConfig extends {
  * import { z } from 'zod'
  * import { defineCollection } from '@lupinum/ginko-content/config'
  *
- * export const docs = defineCollection('docs', {
+ * export const docs = defineCollection({
  *   type: 'page',
  *   source: 'docs/**\/*.md',
  *   i18n: { locales: ['en', 'fr', 'de'], defaultLocale: 'en' },
@@ -235,7 +251,8 @@ type IsI18nConfig<TConfig> = TConfig extends {
 type SchemaOf<TConfig> = TConfig extends {
     schema?: infer S;
 } ? S extends ZodType ? S : undefined : undefined;
-export declare function defineCollection<const Name extends string, const TConfig extends DefineCollectionObject<ZodType | undefined>>(name: Name, config: TConfig): ContentCollectionHandle<Name, SchemaOf<TConfig>, IsI18nConfig<TConfig>>;
+export declare function defineCollection<const TConfig extends DefineCollectionObject<ZodType | undefined>>(config: TConfig): ContentCollectionHandle<never, SchemaOf<TConfig>, IsI18nConfig<TConfig>>;
+export declare function normalizeContentConfigCollectionNames<TCollections extends Record<string, ContentCollectionConfig>>(collections: TCollections): NamedContentCollections<TCollections>;
 /**
  * Wrap the root content configuration with full type inference.
  *
@@ -243,7 +260,7 @@ export declare function defineCollection<const Name extends string, const TConfi
  * ```ts
  * import { defineCollection, defineContentConfig } from '@lupinum/ginko-content/config'
  *
- * export const docs = defineCollection('docs', {
+ * export const docs = defineCollection({
  *   type: 'page',
  *   source: 'docs/*.md'
  * })
@@ -253,7 +270,10 @@ export declare function defineCollection<const Name extends string, const TConfi
  * })
  * ```
  */
-export declare function defineContentConfig<TCollections extends Record<string, ContentCollectionConfig>>(config: ContentConfig<TCollections>): ContentConfig<TCollections>;
+export declare function defineContentConfig<const TCollections extends Record<string, ContentCollectionConfig>>(config: Omit<ContentConfig<TCollections>, 'collections'> & {
+    collections: TCollections;
+}): NamedContentConfig<TCollections>;
+export declare function defineContentConfig<const TConfig extends ContentConfig<Record<string, ContentCollectionConfig>>>(config: TConfig): TConfig;
 /**
  * Declare a schema field that stores a reference to another content entry.
  *
@@ -265,7 +285,7 @@ export declare function defineContentConfig<TCollections extends Record<string,
  * import { z } from 'zod'
  * import { defineCollection, defineContentConfig, reference } from '@lupinum/ginko-content/config'
  *
- * export const blog = defineCollection('blog', {
+ * export const blog = defineCollection({
  *   type: 'page',
  *   source: 'blog/*.md',
  *   schema: z.object({

package/dist/types/config.js

@@ -1,10 +1,13 @@
 import { z } from "zod";
 import { CONTENT_REFERENCE_PREFIX } from "./reference.js";
-export function defineCollection(name, config) {
+export function defineCollection(config) {
+  if (typeof config === "string" || arguments.length > 1) {
+    throw new TypeError("@lupinum/ginko-content defineCollection(name, config) was removed. Use defineCollection({ ... }) under the desired defineContentConfig({ collections: { docs: ... } }) map key.");
+  }
   const { type, source, sitemap, ...rest } = config;
   const normalized = normalizeCollectionSource(source);
   return {
-    name,
+    type,
     ...normalized,
     sitemap: sitemap ?? (type === "data" ? false : void 0),
     ...rest
@@ -20,7 +23,28 @@ function normalizeCollectionSource(source) {
   }
   return { source };
 }
+export function normalizeContentConfigCollectionNames(collections) {
+  for (const [key, collection] of Object.entries(collections)) {
+    const authoredName = collection.name;
+    if (typeof authoredName === "string") {
+      if (authoredName !== key) {
+        throw new Error(`@lupinum/ginko-content collection key "${key}" must match collection name "${authoredName}". Use defineCollection({ ... }) under collections: { ${key}: ... }, or rename the collections map key.`);
+      }
+      continue;
+    }
+    Object.defineProperty(collection, "name", {
+      value: key,
+      enumerable: true,
+      configurable: true,
+      writable: true
+    });
+  }
+  return collections;
+}
 export function defineContentConfig(config) {
+  if (config.collections) {
+    normalizeContentConfigCollectionNames(config.collections);
+  }
   return config;
 }
 export function reference(collection) {

package/dist/types/module.d.ts

@@ -160,6 +160,36 @@ export interface ContentSitemapAssertOptions {
      * @default []
      */
     requiredCollections?: string[];
+    /**
+     * Public URL paths that must appear in generated sitemap loc values.
+     *
+     * Values are compared by URL pathname, so absolute sitemap URLs are
+     * normalized before assertion. Use this for release QA of important route
+     * identities; keep `requiredCollections` for the broader content invariant.
+     *
+     * @default []
+     */
+    requiredPaths?: string[];
+    /**
+     * Public URL path prefixes that must not appear in generated sitemap loc
+     * values.
+     *
+     * Use this to guard against internal/generated routes such as `/_payload`,
+     * `/_nuxt`, API routes, or auth-only sections.
+     *
+     * @default []
+     */
+    forbiddenPathPrefixes?: string[];
+    /**
+     * Fail when generated sitemap URLs use placeholder or local hosts such as
+     * `example.com`, `localhost`, `127.0.0.1`, or `.localhost`.
+     *
+     * Enable this for production-like release checks. It is disabled by default
+     * so local examples and template builds can still generate static output.
+     *
+     * @default false
+     */
+    requireProductionSiteUrl?: boolean;
     /**
      * Optional per-sitemap overrides keyed by sitemap name, for example `en-US`.
      *
@@ -195,7 +225,8 @@ export interface ContentSearchOptions {
     /**
      * Collections included in the built-in index.
      *
-     * When omitted, all configured collections are indexed.
+     * When omitted, Ginko indexes route-backed public collections only. Data-only
+     * collections are excluded unless listed explicitly.
      */
     collections?: string[];
     /**
@@ -258,8 +289,9 @@ export interface ModuleOptions {
      * Built-in full-text search configuration.
      *
      * When enabled, Ginko exposes JSON/Pagefind search endpoints under
-     * the content api base route. Import `useContentSearchResults()` from
-     * `@lupinum/ginko-content/client` to consume them from app components.
+     * the content api base route. `useContentSearchData()` and
+     * `useContentSearchResults()` are auto-imported; import the headless
+     * `useContentSearch()` helper from `@lupinum/ginko-content/client`.
      */
     search: false | ContentSearchOptions;
     /**

package/dist/types/query.d.ts

@@ -1,6 +1,6 @@
 import type { ContentQueryResponse } from './api';
 import type { ContentCollectionHandle } from './config';
-import type { ContentNavigationItem, ParsedContent, ParsedContentInternalMeta, ParsedContentMeta, StrictParsedContentMeta } from './content';
+import type { ContentNavigationItem, ParsedContent, ParsedContentInternalMeta, ParsedContentMeta, StrictParsedContent, StrictParsedContentMeta } from './content';
 /**
  * Query
  */
@@ -531,12 +531,20 @@ export interface ContentQueryRequest {
  */
 export type ContentQueryFetcher<T> = (query: ContentQueryRequest) => Promise<ContentQueryResponse<T>>;
 export type QueryMatchOperator = (item: unknown, condition: unknown) => boolean;
-export interface ContentCollectionMap {
+declare global {
+    interface GinkoContentCollectionMap {
+    }
+    interface GinkoContentCollectionI18nMap {
+    }
 }
-export interface ContentCollectionI18nMap {
+export interface ContentCollectionMap extends GinkoContentCollectionMap {
 }
-export type ContentCollectionName = keyof ContentCollectionMap & string;
+export interface ContentCollectionI18nMap extends GinkoContentCollectionI18nMap {
+}
+export type ContentCollectionName = keyof GinkoContentCollectionMap & string;
 export type ContentCollectionItem<K extends ContentCollectionName> = ContentCollectionMap[K];
+export type ContentCollectionStringName = [ContentCollectionName] extends [never] ? string : ContentCollectionName;
+export type ContentCollectionTarget = ContentCollectionHandle | ContentCollectionStringName;
 /**
  * ============================================================================
  *  Unified Query API — public surface (ADR-0016)
@@ -627,8 +635,8 @@ type HandleSchema<H> = H extends {
     __schema: infer S;
 } ? S extends {
     _output: infer O;
-} ? O & StrictParsedContentMeta : StrictParsedContentMeta : StrictParsedContentMeta;
-type SelectFields<H> = H extends string ? ReadonlyArray<string> : ReadonlyArray<Extract<keyof HandleSchema<H>, string>>;
+} ? O & StrictParsedContentMeta : StrictParsedContentMeta : H extends ContentCollectionName ? ContentCollectionMap[H] & StrictParsedContentMeta : StrictParsedContentMeta;
+type SelectFields<H> = string extends H ? ReadonlyArray<string> : ReadonlyArray<Extract<keyof HandleSchema<H>, string>>;
 /**
  * Runtime document shape inferred from a collection handle.
  */
@@ -636,12 +644,12 @@ export type DocumentFromHandle<H> = H extends {
     __schema: {
         _output: infer O;
     };
-} ? O & ParsedContent : ParsedContent;
+} ? O & StrictParsedContent : H extends ContentCollectionName ? ContentCollectionMap[H] : ParsedContent;
 /**
  * Explicit reference population map. Keys are fields on the source document;
  * values are target collection handles.
  */
-export type PopulateSpec = Record<string, ContentCollectionHandle | string>;
+export type PopulateSpec = Record<string, ContentCollectionTarget>;
 export type PopulatedDocument<T, P> = P extends undefined ? T : P extends PopulateSpec ? string extends keyof P ? T : Omit<T, keyof P> & {
     [K in keyof P & keyof T]: T[K] extends ReadonlyArray<unknown> ? Array<LocalizedDoc<DocumentFromHandle<P[K]>>> : LocalizedDoc<DocumentFromHandle<P[K]>> | null;
 } : T;
@@ -656,7 +664,7 @@ type PopulateOption<P extends PopulateSpec | undefined = undefined> = {
  */
 type HandleIsI18n<H> = H extends {
     __i18n: infer I;
-} ? I extends true ? true : false : false;
+} ? I extends true ? true : false : H extends keyof GinkoContentCollectionI18nMap ? true : false;
 /**
  * Locale option made required when the handle is i18n.
  */
@@ -773,7 +781,7 @@ export interface PaginationResult<T = ParsedContentMeta> {
     nextPage: number | null;
     prevPage: number | null;
 }
-export type BacklinkSource = ContentCollectionHandle | string;
+export type BacklinkSource = ContentCollectionTarget;
 type SourceName<S> = S extends string ? S : S extends {
     name: infer N;
 } ? Extract<N, string> : string;
@@ -800,7 +808,7 @@ export type BacklinksOptions<Target = unknown, Source extends BacklinkSource | R
     limit?: number;
     skip?: number;
     fallback?: LocaleFallback;
-    select?: Source extends string ? ReadonlyArray<string> : ReadonlyArray<Extract<keyof DocumentFromSource<Source>, string>>;
+    select?: string extends Source ? ReadonlyArray<string> : ReadonlyArray<Extract<keyof DocumentFromSource<Source>, string>>;
 } & BacklinksLocaleOption<Target, Source> & PopulateOption<P>;
 export type BacklinksResult<Source extends BacklinkSource | ReadonlyArray<BacklinkSource> = BacklinkSource | ReadonlyArray<BacklinkSource>, P extends PopulateSpec | undefined = undefined> = Array<LocalizedDoc<PopulatedDocument<DocumentFromSource<Source>, P>>>;
 /**