@lupinum/ginko-content 0.1.0

package/dist/module.d.mts

@@ -0,0 +1,2044 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { MarkdownOptions as MarkdownOptions$1, ParsedContent as ParsedContent$1 } from '../dist/types/content';
+import { ContentCollectionConfig as ContentCollectionConfig$1, ContentCollectionI18nConfig as ContentCollectionI18nConfig$1 } from '../dist/types/config';
+export { defineCollection, defineContentConfig, reference } from '../dist/types/config';
+import { StorageValue } from 'unstorage';
+import { ModuleOptions as ModuleOptions$1, ContentContext as ContentContext$1, ContentRevalidateOptions as ContentRevalidateOptions$1 } from '../dist/types/module';
+import { ContentSearchPublicRuntimeConfig as ContentSearchPublicRuntimeConfig$1 } from '../dist/types/search';
+import { ZodType, z } from 'zod';
+import { ListenOptions } from 'listhen';
+
+/**
+ * Locale settings for a collection that ships translated variants.
+ */
+interface ContentCollectionI18nConfig {
+    /**
+     * Locale treated as the canonical variant when no locale is specified.
+     */
+    defaultLocale: string;
+    /**
+     * Every locale code that can produce a concrete variant for the collection.
+     */
+    locales: string[];
+}
+type ContentCollectionSource = string | string[];
+/**
+ * Public route mount for route-backed collections.
+ *
+ * A single string applies to every locale. A locale map lets translated apps
+ * express roots such as `{ en: '/docs', de: '/dokumentation' }`.
+ */
+type ContentCollectionRouteConfig = string | Record<string, string>;
+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';
+interface ContentCmsRelationConfig {
+    collectionId: string;
+    multiple?: boolean;
+}
+interface ContentCmsFieldConfig {
+    type?: ContentCmsFieldType;
+    label?: string | Record<string, string> | null;
+    description?: string | null;
+    required?: boolean;
+    localized?: boolean;
+    hidden?: boolean;
+    searchable?: boolean;
+    sortable?: boolean;
+    order?: number;
+    width?: 'full' | 'half';
+    defaultValue?: unknown;
+    validation?: Record<string, unknown> | null;
+    condition?: Record<string, unknown> | null;
+    options?: string[] | null;
+    relation?: ContentCmsRelationConfig | null;
+    fields?: Record<string, ContentCmsFieldConfig> | ContentCmsFieldConfig[] | null;
+    min?: number | null;
+    max?: number | null;
+    step?: number | null;
+    slugFrom?: string | null;
+    language?: string | null;
+}
+interface ContentCmsCollectionConfig {
+    label?: string | Record<string, string>;
+    type?: 'flat' | 'tree';
+    icon?: string;
+    route?: {
+        mode?: 'route' | 'none';
+        pathPrefix?: string;
+        slugMode?: 'shared' | 'localized' | 'stable' | 'localizedStable';
+        rootSlug?: string | null;
+        singleton?: boolean;
+    };
+    fields?: Record<string, ContentCmsFieldConfig>;
+    settings?: unknown;
+}
+/**
+ * Object source shape accepted for Nuxt Content v3 migration.
+ */
+interface ContentCollectionSourceObject {
+    /**
+     * Source glob or globs included in the collection.
+     */
+    include: ContentCollectionSource;
+    /**
+     * Source glob or globs excluded from the collection.
+     */
+    exclude?: ContentCollectionSource;
+}
+/**
+ * Declarative collection definition used by `content.config.ts`.
+ */
+interface ContentCollectionConfig<TSchema extends ZodType | undefined = ZodType | undefined> {
+    /**
+     * Source glob or source descriptor understood by the filesystem ingestion
+     * layer. CMS-backed projects do not need a runtime source; filesystem
+     * imports/seeding should be modeled by provider-owned import tooling.
+     */
+    source?: ContentCollectionSource;
+    /**
+     * Source glob or globs excluded from this collection.
+     */
+    exclude?: ContentCollectionSource;
+    /**
+     * Optional Zod schema applied to every parsed entry in the collection.
+     */
+    schema?: TSchema;
+    /**
+     * When `true`, reject documents with frontmatter fields not declared in `schema`.
+     */
+    strict?: boolean;
+    /**
+     * Per-collection locale settings. Use `true` to inherit the module-level i18n config.
+     */
+    i18n?: true | ContentCollectionI18nConfig;
+    /**
+     * Public route mount for this collection. Used to resolve `by.route`
+     * selectors and to emit requested-locale URLs for fallback content.
+     */
+    route?: ContentCollectionRouteConfig;
+    /**
+     * Opt-in to fully translated path segments per locale (ADR-0008). When `true`,
+     * the content graph pairs locale variants by numeric prefix on filenames so
+     * each locale can carry its own slug text, e.g. `1.guide/` ↔ `1.documentation/`.
+     *
+     * @default false
+     */
+    translatedSlugs?: boolean;
+    /**
+     * Include this collection in content-owned sitemap output and prerender route
+     * discovery. Route-backed collections are included by default; data-only or
+     * app-internal collections should opt out with `false`.
+     *
+     * @default true
+     */
+    sitemap?: boolean;
+    /**
+     * Optional CMS editor metadata for providers such as `@lupinum/ginko-cms`.
+     *
+     * The content collection remains the source of truth; this metadata only
+     * fills editor-specific gaps that cannot be inferred safely from route,
+     * source, i18n, and schema information.
+     */
+    cms?: ContentCmsCollectionConfig;
+}
+type ContentCollectionKind = 'page' | 'data';
+type BuiltinContentProviderName = 'filesystem' | 'cms' | 'ginko-cms' | 'ginko';
+type ContentProviderName = BuiltinContentProviderName | (string & {});
+type DefineCollectionOptions<TSchema extends ZodType | undefined = ZodType | undefined> = Omit<ContentCollectionConfig<TSchema>, 'source' | 'exclude'>;
+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`.
+     */
+    type: ContentCollectionKind;
+    /**
+     * Source glob, globs, or v3-compatible `{ include, exclude }` object.
+     * Required for filesystem-backed collections; optional for CMS-backed
+     * collections.
+     */
+    source?: ContentCollectionSource | ContentCollectionSourceObject;
+}
+/**
+ * Root object returned from `defineContentConfig`.
+ */
+interface ContentConfig<TCollections extends Record<string, ContentCollectionConfig> = Record<string, ContentCollectionConfig>> {
+    /**
+     * Content backing implementation. `filesystem` is the default. `cms`,
+     * `ginko-cms`, and `ginko` resolve to the official Ginko CMS provider when
+     * `@lupinum/ginko-cms` is installed.
+     */
+    provider?: ContentProviderName;
+    /**
+     * External provider modules keyed by provider name. Built-in providers do not
+     * need to be registered here.
+     */
+    providers?: Record<string, string>;
+    /**
+     * Named content collections keyed by the identifier used at query time.
+     */
+    collections?: TCollections;
+}
+/**
+ * Infer the runtime data shape for a collection from its Zod schema.
+ */
+type CollectionSchema<TCollection> = TCollection extends {
+    schema?: infer TSchema;
+} ? TSchema extends ZodType ? z.infer<TSchema> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Zod string schema tagged as a Nuxt Content reference field.
+ */
+interface ContentReferenceSchema extends z.ZodString {
+    /**
+     * Serialized descriptor in the form `__nuxt_content_ref__:<collection>`.
+     */
+    description: string;
+}
+/**
+ * Typed handle returned by `defineCollection`. Carries the collection's name
+ * and i18n discriminator at the type level so the unified query API
+ * (`one`, `many`, `useContentOne`, ...) can require `locale` only when the
+ * collection is internationalized.
+ *
+ * The handle extends `ContentCollectionConfig` so it can be stored directly
+ * in `defineContentConfig({ collections: ... })`.
+ */
+interface ContentCollectionHandle<Name extends string = string, TSchema extends ZodType | undefined = ZodType | undefined, TI18n extends boolean = boolean> extends ContentCollectionConfig<TSchema> {
+    /**
+     * Stable identifier used at query time, e.g. `'docs'` or `'blog'`.
+     */
+    readonly name: Name;
+    /**
+     * Phantom flag — `true` when the collection ships translated variants.
+     * Used by the type system to make `locale` required on i18n queries.
+     *
+     * @internal
+     */
+    readonly __i18n: TI18n;
+    /**
+     * Phantom marker — Zod schema bound at definition time. Used to infer the
+     * returned document shape at query time.
+     *
+     * @internal
+     */
+    readonly __schema: TSchema;
+}
+
+type LayoutKey = string;
+interface ContentSeoImage {
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+}
+interface ContentSeoMeta {
+    title?: string;
+    description?: string;
+    image?: string | ContentSeoImage;
+}
+/**
+ * Internal metadata attached to every parsed content record.
+ */
+interface ParsedContentInternalMeta {
+    /**
+     * Stable unique id for the parsed source record.
+     */
+    _id: string;
+    /**
+     * Backing source name when multiple content sources are configured.
+     */
+    _source?: string;
+    /**
+     * Canonical content path. This is source-agnostic, so the same route can be
+     * backed by local files, remote storage, or generated data.
+     */
+    _path?: string;
+    /**
+     * Human-readable title resolved from frontmatter or generated metadata.
+     */
+    title?: string;
+    /**
+     * Human-readable summary used in listings, search, and SEO helpers.
+     */
+    description?: string;
+    /**
+     * Conventional SEO frontmatter shared by pages and app templates.
+     */
+    seo?: ContentSeoMeta;
+    /**
+     * Stable authored alias for internal content links.
+     */
+    ref?: string;
+    /**
+     * Marks the document as a draft.
+     */
+    _draft?: boolean;
+    /**
+     * Marks the document as a partial that should not become a page by default.
+     */
+    _partial?: boolean;
+    /**
+     * Locale code for the concrete variant.
+     */
+    _locale?: string;
+    /**
+     * Locale-agnostic content identity used to resolve variants.
+     */
+    _canonicalKey?: string;
+    /**
+     * Requested route path before locale fallback.
+     */
+    _requestedPath?: string;
+    /**
+     * Requested public route before locale fallback.
+     */
+    _requestedRoute?: string;
+    /**
+     * Requested authored reference before locale fallback.
+     */
+    _requestedRef?: string;
+    /**
+     * Requested locale before locale fallback.
+     */
+    _requestedLocale?: string;
+    /**
+     * Resolved locale after locale fallback.
+     */
+    _resolvedLocale?: string;
+    /**
+     * Whether the returned content was resolved through fallback.
+     */
+    _fallback?: boolean;
+    /**
+     * Locales that have a concrete variant for this document.
+     */
+    _availableLocales?: string[];
+    /**
+     * Map of available locale code to its locale-specific path.
+     */
+    _variantPaths?: Record<string, string>;
+    /**
+     * Resolved markdown `$ref` links for the current runtime locale.
+     */
+    _resolvedRefs?: Record<string, string>;
+    /**
+     * Collection name, when matched by a configured collection glob.
+     */
+    _collection?: string;
+    /**
+     * Marks folder-scoped navigation metadata documents.
+     */
+    _navigation?: boolean;
+    /**
+     * Parsed document kind.
+     */
+    _type?: 'markdown' | 'yaml' | 'json' | 'csv';
+    /**
+     * Source file path relative to the content root.
+     */
+    _file?: string;
+    /**
+     * Source file extension.
+     */
+    _extension?: 'md' | 'yaml' | 'yml' | 'json' | 'json5' | 'csv';
+}
+/**
+ * One entry in a generated table of contents.
+ */
+interface TocLink {
+    id: string;
+    text: string;
+    depth: number;
+    children?: TocLink[];
+}
+/**
+ * Parsed table of contents generated from markdown headings.
+ */
+interface Toc {
+    title: string;
+    depth: number;
+    searchDepth: number;
+    links: TocLink[];
+}
+/**
+ * Options object passed to a markdown plugin.
+ */
+type MarkdownPluginOptions = Record<string, unknown>;
+/**
+ * User-authored plugin declaration in module options.
+ */
+type MarkdownPluginDescriptor = string | [string, MarkdownPluginOptions];
+/**
+ * Normalized plugin declaration after resolution.
+ */
+type ResolvedMarkdownPlugin = {
+    name: string;
+    options: MarkdownPluginOptions;
+};
+/**
+ * Object-shaped markdown AST node.
+ */
+interface MarkdownNode {
+    type: string;
+    tag?: string;
+    value?: string;
+    props?: Record<string, unknown>;
+    content?: unknown;
+    children?: MarkdownNode[];
+    attributes?: Record<string, unknown>;
+    fmAttributes?: Record<string, unknown>;
+}
+/**
+ * Root node for the object-based markdown AST.
+ */
+interface MarkdownRoot {
+    type: 'root';
+    children: MarkdownNode[];
+    props?: Record<string, any>;
+    toc?: Toc;
+}
+/**
+ * Resolved markdown runtime options.
+ */
+interface MarkdownOptions {
+    plugins: ResolvedMarkdownPlugin[];
+    tags: Record<string, string>;
+    anchorLinks: {
+        depth: number;
+        exclude: number[];
+    };
+    image?: 'auto' | 'img' | 'nuxt-image';
+}
+/**
+ * Flexible parsed content shape that allows user-defined frontmatter fields.
+ */
+interface ParsedContentMeta extends ParsedContentInternalMeta {
+    /**
+     * Preferred layout key for page rendering.
+     */
+    layout?: LayoutKey;
+    [key: string]: unknown;
+}
+/**
+ * Strict parsed content shape with no open-ended index signature.
+ */
+interface StrictParsedContentMeta extends ParsedContentInternalMeta {
+    /**
+     * Preferred layout key for page rendering.
+     */
+    layout?: LayoutKey;
+}
+/**
+ * Parsed content document including the rendered body payload.
+ */
+interface ParsedContent extends ParsedContentMeta {
+    /**
+     * Optional excerpt payload.
+     */
+    excerpt?: MarkdownRoot;
+    /**
+     * Parsed body payload. `null` means the source had no renderable body.
+     */
+    body: MarkdownRoot | null;
+}
+/**
+ * Strict parsed content document including the rendered body payload.
+ */
+interface StrictParsedContent extends StrictParsedContentMeta {
+    /**
+     * Optional excerpt payload.
+     */
+    excerpt?: MarkdownRoot;
+    /**
+     * Parsed body payload. `null` means the source had no renderable body.
+     */
+    body: MarkdownRoot | null;
+}
+/**
+ * Specialized parsed content shape for markdown sources.
+ */
+interface MarkdownParsedContent extends ParsedContent {
+    _type: 'markdown';
+    /**
+     * Whether the markdown source rendered no meaningful body content.
+     */
+    _empty: boolean;
+    /**
+     * Description resolved from frontmatter or excerpt generation.
+     */
+    description: string;
+    /**
+     * Object AST excerpt generated from the markdown body.
+     */
+    excerpt?: MarkdownRoot;
+    /**
+     * Parsed Markdown body with included table of contents.
+     */
+    body: MarkdownRoot & {
+        toc?: Toc;
+    };
+}
+/**
+ * Transformer hook used during ingestion.
+ */
+interface ContentTransformer {
+    /**
+     * Stable transformer name used in logs and generated manifests.
+     */
+    name: string;
+    /**
+     * File extensions handled by the transformer.
+     */
+    extensions: string[];
+    /**
+     * Optional parse hook that turns raw source content into a parsed document.
+     */
+    parse?(id: string, content: StorageValue, options: unknown): Promise<ParsedContent> | ParsedContent;
+    /**
+     * Optional post-parse hook that mutates or enriches a parsed document.
+     */
+    transform?(content: ParsedContent, options: unknown): Promise<ParsedContent> | ParsedContent;
+}
+/**
+ * Ingestion options passed to the transform pipeline.
+ */
+interface TransformContentOptions {
+    transformers?: ContentTransformer[];
+    [key: string]: unknown;
+}
+/**
+ * Navigation node returned by content navigation helpers.
+ */
+interface NavItem {
+    title: string;
+    /**
+     * Nuxt Content compatible route path used by Nuxt UI content components.
+     */
+    path: string;
+    /**
+     * Canonical content route without locale prefix.
+     */
+    _path: string;
+    stem?: string;
+    page?: false;
+    _id?: string;
+    _canonicalKey?: string;
+    _locale?: string;
+    _fallback?: boolean;
+    _draft?: boolean;
+    children?: NavItem[];
+    [key: string]: unknown;
+}
+/**
+ * Public alias for navigation items returned by query helpers.
+ */
+type ContentNavigationItem = NavItem;
+
+/**
+ * Response envelope returned when a query resolves to a list.
+ */
+interface ContentQueryFindResponse<T> {
+    /**
+     * Matched documents after filtering, sorting, and projection.
+     */
+    result: Array<T>;
+    /**
+     * Number of records skipped before the returned page.
+     */
+    skip: number;
+    /**
+     * Requested page size.
+     */
+    limit: number;
+    /**
+     * Total match count before paging is applied.
+     */
+    total: number;
+}
+/**
+ * Response envelope returned when a query resolves to one document.
+ */
+interface ContentQueryFindOneResponse<T> {
+    /**
+     * First matched document, or `undefined` when nothing matched.
+     */
+    result: T | undefined;
+}
+/**
+ * Response envelope returned when a query resolves to a count.
+ */
+interface ContentQueryCountResponse {
+    /**
+     * Number of matched documents.
+     */
+    result: number;
+}
+/**
+ * Low-level transport response for the content query engine.
+ *
+ * Most application code should use the builder helpers (`.all()`, `.first()`,
+ * `.count()`) instead of reading this union directly.
+ */
+type ContentQueryResponse<T> = ContentQueryFindResponse<T> | ContentQueryFindOneResponse<T> | ContentQueryCountResponse;
+
+/**
+ * Query
+ */
+interface ContentQuerySortParams {
+    /**
+     * Locale specifier for sorting
+     * A string with a BCP 47 language tag
+     *
+     * @default undefined
+     */
+    $locale?: string;
+    /**
+     * Whether numeric collation should be used, such that "1" < "2" < "10".
+     * Possible values are `true` and `false`;
+     *
+     * @default false
+     */
+    $numeric?: boolean;
+    /**
+     * Whether upper case or lower case should sort first.
+     * Possible values are `"upper"`, `"lower"`, or `"false"`
+     *
+     * @default "depends on locale"
+     */
+    $caseFirst?: 'upper' | 'lower' | 'false';
+    /**
+     * Which differences in the strings should lead to non-zero result values. Possible values are:
+     *  - "base": Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A.
+     *  - "accent": Only strings that differ in base letters or accents and other diacritic marks compare as unequal. Examples: a ≠ b, a ≠ á, a = A.
+     *  - "case": Only strings that differ in base letters or case compare as unequal. Examples: a ≠ b, a = á, a ≠ A.
+     *  - "variant": Strings that differ in base letters, accents and other diacritic marks, or case compare as unequal. Other differences may also be taken into consideration. Examples: a ≠ b, a ≠ á, a ≠ A.
+     *
+     * @default "variant"
+     */
+    $sensitivity?: 'base' | 'accent' | 'case' | 'variant';
+}
+interface ContentQuerySortFields {
+    [field: string]: -1 | 1;
+}
+type ContentQuerySortOptions = ContentQuerySortParams | ContentQuerySortFields;
+/**
+ * @internal
+ */
+interface ContentQueryBuilderWhere extends Partial<Record<keyof ParsedContentInternalMeta, string | number | boolean | RegExp | ContentQueryBuilderWhere>> {
+    /**
+     * Match only if all nested conditions are true.
+     **/
+    $and?: ContentQueryBuilderWhere[];
+    /**
+     * Match if any nested condition is true.
+     **/
+    $or?: ContentQueryBuilderWhere[];
+    /**
+     * Match when the nested condition is false.
+     **/
+    $not?: string | number | boolean | RegExp | ContentQueryBuilderWhere;
+    /**
+     * Match if item equals condition.
+     **/
+    $eq?: string | number | boolean | RegExp;
+    /**
+     * Match if item does not equal condition.
+     **/
+    $ne?: string | number | boolean | RegExp;
+    /**
+     * Check if item is greater than condition.
+     */
+    $gt?: number | string;
+    /**
+     * Check if item is greater than or equal to condition.
+     */
+    $gte?: number | string;
+    /**
+     * Check if item is less than condition.
+     */
+    $lt?: number | string;
+    /**
+     * Check if item is less than or equal to condition.
+     */
+    $lte?: number | string;
+    /**
+     * Provides regular expression capabilities for pattern matching strings.
+     */
+    $regex?: RegExp | string;
+    /**
+     * Match when a string field starts with the given prefix.
+     */
+    $prefix?: string;
+    /**
+     * Match if type of item equals condition.
+     */
+    $type?: string;
+    /**
+     * Check key existence.
+     */
+    $exists?: boolean;
+    /**
+     * Match if item contains every condition or every rule in the condition array.
+     **/
+    $contains?: Array<string | number | boolean> | string | number | boolean;
+    /**
+     * Match if item contains at least one rule from the condition array.
+     */
+    $containsAny?: Array<string | number | boolean>;
+    /**
+     * Ignore case when checking string containment.
+     **/
+    $icontains?: string;
+    /**
+     * Match if item is in condition array.
+     **/
+    $in?: Array<string | number | boolean>;
+    [key: string]: string | number | boolean | RegExp | ContentQueryBuilderWhere | Array<string | number | boolean | ContentQueryBuilderWhere> | undefined;
+}
+/**
+ * @internal
+ */
+interface ContentQueryBuilderParams {
+    collection?: string;
+    first?: boolean;
+    skip?: number;
+    limit?: number;
+    only?: string[];
+    without?: string[];
+    sort?: ContentQuerySortOptions[];
+    where?: ContentQueryBuilderWhere[] | ContentQueryBuilderWhere;
+    canonical?: boolean;
+    navigationFields?: string[];
+    resolveLocale?: {
+        locale?: string;
+        fallback?: string[] | boolean;
+        exact?: boolean;
+    };
+    [key: string]: unknown;
+}
+type QueryScalar = string | number | boolean | Date;
+type InternalQueryKeys = Extract<keyof ParsedContentInternalMeta, `_${string}`>;
+type CollectionQueryKey<T> = Extract<keyof T, string> | InternalQueryKeys;
+type CollectionQueryField<T> = CollectionQueryKey<T>;
+type CollectionQueryFieldValue<T, K extends CollectionQueryField<T>> = K extends keyof T ? NonNullable<T[K]> : K extends InternalQueryKeys ? NonNullable<ParsedContentInternalMeta[K]> : never;
+type EqualityValue<T> = T extends QueryScalar ? T | RegExp : T;
+type ComparableValue<T> = T extends string | number | Date ? T : never;
+type MembershipValue<T> = T extends Array<infer U> ? Array<U> : T extends QueryScalar ? Array<T> : never;
+type ContainsValue<T> = T extends string ? string : T extends Array<infer U> ? U | Array<U> : never;
+type ContainsAnyValue<T> = T extends Array<infer U> ? Array<U> : never;
+type RegexValue<T> = T extends string ? RegExp | string : never;
+type IContainsValue<T> = T extends string ? string : never;
+type TypeValue = 'string' | 'number' | 'boolean' | 'object' | 'undefined';
+type CollectionQueryOperator<T> = '=' | '!=' | 'EXISTS' | 'TYPE' | (ComparableValue<T> extends never ? never : '>' | '>=' | '<' | '<=') | (MembershipValue<T> extends never ? never : 'IN' | 'NOT IN') | (ContainsValue<T> extends never ? never : 'CONTAINS') | (ContainsAnyValue<T> extends never ? never : 'CONTAINS_ANY') | (RegexValue<T> extends never ? never : 'REGEX') | (IContainsValue<T> extends never ? never : 'ICONTAINS');
+type CollectionQueryValue<T, O extends CollectionQueryOperator<T>> = O extends '=' | '!=' ? EqualityValue<T> : O extends '>' | '>=' | '<' | '<=' ? ComparableValue<T> : O extends 'IN' | 'NOT IN' ? MembershipValue<T> : O extends 'CONTAINS' ? ContainsValue<T> : O extends 'CONTAINS_ANY' ? ContainsAnyValue<T> : O extends 'REGEX' ? RegexValue<T> : O extends 'ICONTAINS' ? IContainsValue<T> : O extends 'EXISTS' ? boolean | undefined : O extends 'TYPE' ? TypeValue : never;
+type QueryOrderDirection = 'ASC' | 'DESC';
+interface QueryOrderOptions {
+    /**
+     * BCP 47 locale passed to `Intl.Collator` for string ordering.
+     */
+    locale?: string;
+    /**
+     * Enable numeric ordering so `"2"` sorts before `"10"`.
+     */
+    numeric?: boolean;
+    /**
+     * Control whether upper- or lower-case letters sort first.
+     */
+    caseFirst?: ContentQuerySortParams['$caseFirst'];
+    /**
+     * Collation sensitivity used by string comparison.
+     */
+    sensitivity?: ContentQuerySortParams['$sensitivity'];
+}
+/**
+ * Builder passed to grouped `andWhere` / `orWhere` callbacks.
+ */
+interface QueryGroupBuilder<T = ParsedContentMeta> {
+    where<K extends CollectionQueryField<T>, O extends CollectionQueryOperator<CollectionQueryFieldValue<T, K>>>(field: K, operator: O, value?: CollectionQueryValue<CollectionQueryFieldValue<T, K>, O>): QueryGroupBuilder<T>;
+    andWhere(groupFactory: QueryGroupFunction<T>): QueryGroupBuilder<T>;
+    orWhere(groupFactory: QueryGroupFunction<T>): QueryGroupBuilder<T>;
+}
+/**
+ * Factory used to build grouped nested conditions.
+ */
+type QueryGroupFunction<T = ParsedContentMeta> = (group: QueryGroupBuilder<T>) => QueryGroupBuilder<T>;
+/**
+ * Options for locale-aware navigation queries.
+ */
+interface ContentCollectionNavigationOptions<TField extends string = string> {
+    /**
+     * Extra document fields to merge onto each returned navigation item.
+     */
+    fields?: TField[];
+    /**
+     * Locale to resolve against for translated collections.
+     */
+    locale?: string;
+    /**
+     * When `true`, keep canonical paths instead of locale-prefixed paths.
+     */
+    canonical?: boolean;
+}
+/**
+ * Options for previous/next navigation helpers.
+ */
+type ContentCollectionItemSurroundingsOptions<TField extends string = string> = ContentCollectionNavigationOptions<TField>;
+/**
+ * Options for extracting searchable sections from collection pages.
+ */
+interface ContentCollectionSearchSectionsOptions {
+    /**
+     * Tags ignored while flattening page content into search text.
+     */
+    ignoredTags?: string[];
+    /**
+     * Extra top-level fields copied from each page onto every emitted section.
+     */
+    extraFields?: string[];
+    /**
+     * Query predicate applied before extracting searchable sections.
+     */
+    filterQuery?: ContentQueryBuilderWhere;
+    /**
+     * Lowest heading level that starts a new section.
+     */
+    minHeading?: `h${1 | 2 | 3 | 4 | 5 | 6}`;
+    /**
+     * Highest heading level that starts a new section.
+     */
+    maxHeading?: `h${1 | 2 | 3 | 4 | 5 | 6}`;
+    /**
+     * Locale to resolve against for translated collections.
+     */
+    locale?: string;
+    /**
+     * When `true`, keep canonical paths instead of locale-prefixed paths.
+     */
+    canonical?: boolean;
+}
+/**
+ * Options for locale-aware page resolution.
+ */
+interface ContentCollectionPageOptions {
+    /**
+     * Preferred locale to resolve.
+     */
+    locale?: string;
+    /**
+     * Enable or customize locale fallback resolution.
+     *
+     * Pass `true` to use configured fallbacks, or an explicit locale list to
+     * override the configured chain for this query.
+     */
+    fallback?: string[] | boolean;
+    /**
+     * When `true`, keep canonical paths in the returned route metadata.
+     */
+    canonical?: boolean;
+}
+/**
+ * Options for route metadata resolution without loading full page content.
+ */
+interface ContentCollectionRouteMetaOptions {
+    /**
+     * Preferred locale to resolve.
+     */
+    locale?: string;
+    /**
+     * Enable or customize locale fallback resolution.
+     */
+    fallback?: string[] | boolean;
+}
+/**
+ * Options for resolving an authored reference value into a document.
+ */
+interface ResolveContentReferenceOptions {
+    /**
+     * Preferred locale to resolve.
+     */
+    locale?: string;
+    /**
+     * Enable or customize locale fallback resolution.
+     */
+    fallback?: string[] | boolean;
+    /**
+     * When `true`, require an exact locale match and skip fallback lookup.
+     */
+    exact?: boolean;
+    /**
+     * Restrict resolution to a single collection.
+     */
+    collection?: string;
+}
+/**
+ * Locale variant entry returned by the internal locale-variant endpoint.
+ */
+interface ContentLocaleEntry {
+    /**
+     * Stable locale-agnostic identity shared by every translated variant.
+     */
+    canonicalKey: string;
+    /**
+     * Locale code for the matching variant.
+     */
+    locale: string;
+    /**
+     * Resolved route path for the variant, when the variant is routable.
+     */
+    path?: string;
+}
+/**
+ * Route metadata for a single locale variant of a page.
+ */
+interface ContentLocaleRoute {
+    locale: string;
+    path: string;
+    canonicalPath: string;
+}
+/**
+ * One entry in the per-locale path map attached to a localized document.
+ *
+ * `translated` is `true` when a concrete variant exists in that locale, `false`
+ * when the resolver fell back to another locale's path. `fallback` names the
+ * locale that supplied the path when `translated` is false.
+ */
+interface LocalePathEntry {
+    /**
+     * Locale-prefixed route path (the URL the user navigates to).
+     */
+    path: string;
+    /**
+     * `true` when this locale has its own variant; `false` when the path was
+     * supplied by a fallback locale.
+     */
+    translated: boolean;
+    /**
+     * Locale that backed this entry when `translated` is `false`.
+     */
+    fallback?: string;
+}
+/**
+ * Public resolution metadata attached to localized content results.
+ *
+ * Internal `_requestedLocale`, `_resolvedLocale`, and `_fallback` fields remain
+ * storage/query implementation details. UI code should read this object.
+ */
+interface ContentResolvedMeta {
+    /**
+     * Locale of the concrete content variant that backed this result.
+     */
+    locale: string;
+    /**
+     * Locale requested by the caller, when locale resolution was part of the
+     * query.
+     */
+    requestedLocale?: string;
+    /**
+     * `true` when the concrete content variant came from a different locale than
+     * the requested locale.
+     */
+    fallback: boolean;
+    /**
+     * Locale that supplied the content when `fallback` is true.
+     */
+    fallbackLocale?: string;
+    /**
+     * Public route path returned to the user.
+     */
+    path: string;
+    /**
+     * Requested route path before locale fallback, when known.
+     */
+    requestedPath?: string;
+    /**
+     * Requested public route before locale fallback, when known.
+     */
+    requestedRoute?: string;
+    /**
+     * Requested authored ref before locale fallback, when known.
+     */
+    requestedRef?: string;
+    /**
+     * Locales that have concrete variants for this content identity.
+     */
+    availableLocales: string[];
+}
+/**
+ * Locale-aware routing metadata attached to route-backed page payloads.
+ */
+interface ContentRouteMeta {
+    locale: string;
+    defaultLocale: string;
+    path: string;
+    canonicalPath: string;
+    variants: ContentLocaleRoute[];
+    /**
+     * Map of every configured locale to its localized path. Includes a
+     * `translated` flag and a `fallback` source when a locale has no variant.
+     */
+    localePaths: Record<string, LocalePathEntry>;
+    /**
+     * Public explanation of the locale/path resolution used for this result.
+     */
+    resolved: ContentResolvedMeta;
+}
+/**
+ * Full page payload returned by route-aware unified query helpers and internal route helpers.
+ */
+type ContentPageResult<T = ParsedContentMeta> = T & ContentRouteMeta & {
+    /**
+     * Locale-agnostic path stem derived from the source file.
+     */
+    stem: string;
+    /**
+     * Source file extension when it can be inferred.
+     */
+    extension?: string;
+};
+/**
+ * Alternate locale entry used in sitemap output.
+ */
+interface ContentSitemapAlternative {
+    hreflang: string;
+    href: string;
+}
+/**
+ * Sitemap image entry discovered from page content or metadata.
+ */
+interface ContentSitemapImage {
+    loc: string;
+}
+/**
+ * Sitemap entry produced by `queryCollectionsSitemapEntries`.
+ */
+interface ContentSitemapEntry {
+    loc: string;
+    _sitemap?: string;
+    alternatives?: ContentSitemapAlternative[];
+    images?: ContentSitemapImage[];
+}
+/**
+ * Searchable document section produced by the internal search-section builder.
+ */
+interface ContentSearchSection {
+    /**
+     * Stable section id, usually the page path or path plus anchor hash.
+     */
+    id: string;
+    /**
+     * Heading or page title for the section.
+     */
+    title: string;
+    /**
+     * Ancestor heading trail leading to this section.
+     */
+    titles: string[];
+    /**
+     * Heading depth that opened the section.
+     */
+    level: number;
+    /**
+     * Flattened text content used by the search index.
+     */
+    content: string;
+    [key: string]: unknown;
+}
+interface ContentQueryBuilder<T = ParsedContentMeta> {
+    /**
+     * Filter results with an explicit field/operator/value clause.
+     */
+    where<K extends CollectionQueryField<T>, O extends CollectionQueryOperator<CollectionQueryFieldValue<T, K>>>(field: K, operator: O, value?: CollectionQueryValue<CollectionQueryFieldValue<T, K>, O>): ContentQueryBuilder<T>;
+    /**
+     * Add a grouped AND clause.
+     */
+    andWhere(groupFactory: QueryGroupFunction<T>): ContentQueryBuilder<T>;
+    /**
+     * Add a grouped OR clause.
+     */
+    orWhere(groupFactory: QueryGroupFunction<T>): ContentQueryBuilder<T>;
+    /**
+     * Select a subset of fields.
+     */
+    select<const K extends readonly Extract<keyof T, string>[]>(...fields: K): ContentQueryBuilder<Pick<T, K[number]>>;
+    /**
+     * Order the result set by a field.
+     */
+    order<K extends CollectionQueryField<T>>(field: K, direction: QueryOrderDirection, options?: QueryOrderOptions): ContentQueryBuilder<T>;
+    /**
+     * Limit number of results.
+     */
+    limit(count: number): ContentQueryBuilder<T>;
+    /**
+     * Skip number of results.
+     */
+    skip(count: number): ContentQueryBuilder<T>;
+    /**
+     * Retrieve query builder params.
+     * @internal
+     */
+    params: () => ContentQueryBuilderParams;
+    /**
+     * Filter contents based on locale.
+     */
+    locale(locale: string, options?: {
+        fallback?: boolean | string[];
+    }): ContentQueryBuilder<T>;
+    /**
+     * Fetch list of contents.
+     */
+    all(): Promise<Array<T>>;
+    /**
+     * Fetch the first matched content.
+     */
+    first(): Promise<T | undefined>;
+    /**
+     * Count matched contents.
+     */
+    count(): Promise<number>;
+}
+interface CollectionQueryBuilder<T = ParsedContentMeta> extends ContentQueryBuilder<T> {
+    select<const K extends readonly Extract<keyof T, string>[]>(...fields: K): CollectionQueryBuilder<Pick<T, K[number]>>;
+}
+/**
+ * Minimal request shape consumed by the query transport.
+ */
+interface ContentQueryRequest {
+    params(): ContentQueryBuilderParams;
+}
+/**
+ * Internal transport used by the immutable query builder.
+ */
+type ContentQueryFetcher<T> = (query: ContentQueryRequest) => Promise<ContentQueryResponse<T>>;
+type QueryMatchOperator = (item: unknown, condition: unknown) => boolean;
+interface ContentCollectionMap {
+}
+interface ContentCollectionI18nMap {
+}
+type ContentCollectionName = keyof ContentCollectionMap & string;
+type ContentCollectionItem<K extends ContentCollectionName> = ContentCollectionMap[K];
+/**
+ * ============================================================================
+ *  Unified Query API — public surface (ADR-0016)
+ * ============================================================================
+ *
+ * The types below back the unified query API exposed via `one`, `many`,
+ * `resolveOne`, `variants`, `tree`, `neighbors` and their `useContent*`
+ * composable mirrors. The public vocabulary is deliberately split:
+ *
+ *   - `by` identifies exactly one document by route path or authored ref.
+ *   - `where` filters a result set by document fields.
+ *   - `resolveOne` returns diagnostics; `one` is the ergonomic doc-only view.
+ */
+/**
+ * MongoDB-style operator object applied to a single field. Mirrors the subset
+ * of `ContentQueryBuilderWhere` operators that are safe for public use.
+ *
+ * @template TValue Concrete field value type (used to narrow operator operands).
+ */
+interface QueryOperators<TValue = unknown> {
+    $eq?: TValue;
+    $ne?: TValue;
+    $gt?: TValue;
+    $gte?: TValue;
+    $lt?: TValue;
+    $lte?: TValue;
+    $in?: TValue[];
+    $nin?: TValue[];
+    $exists?: boolean;
+    $contains?: TValue | TValue[];
+    $containsAny?: TValue[];
+    $icontains?: string;
+    $type?: 'string' | 'number' | 'boolean' | 'object' | 'undefined';
+    $prefix?: TValue extends string ? string : never;
+    $not?: TValue | QueryOperators<TValue>;
+}
+/**
+ * Identify exactly one document. `path` is stored content `_path`, `route` is
+ * public app URL, and `ref` is authored stable identity. They are mutually
+ * exclusive at the type level.
+ */
+type ContentSelector = {
+    path: string;
+    route?: never;
+    ref?: never;
+} | {
+    route: string;
+    path?: never;
+    ref?: never;
+} | {
+    ref: string;
+    path?: never;
+    route?: never;
+};
+type WhereValue<T> = T | QueryOperators<T>;
+type PathWhere = string | QueryOperators<string>;
+/**
+ * MongoDB-style filter object generic on the document shape. `where.path` is a
+ * documented route-path filter and compiles to the internal `_path` field.
+ */
+type QueryWhere<T = ParsedContentMeta> = {
+    path?: PathWhere;
+    $and?: QueryWhere<T>[];
+    $or?: QueryWhere<T>[];
+    $not?: QueryWhere<T>;
+} & {
+    [K in Exclude<keyof T, 'path'>]?: WhereValue<NonNullable<T[K]>>;
+};
+/**
+ * Sort spec: `asc` / `desc` are preferred; `1` / `-1` remain accepted because
+ * they map directly to the transport shape.
+ */
+type SortDirection = 'asc' | 'desc' | 1 | -1;
+type SortSpec<T = ParsedContentMeta> = string extends keyof T ? {
+    [key: string]: SortDirection | undefined;
+} : {
+    [K in keyof T]?: SortDirection;
+};
+/**
+ * Schema of a collection handle (recovered from its `__schema` phantom).
+ *
+ * Uses `StrictParsedContentMeta` (no `[key: string]: unknown` index signature)
+ * as the base so `keyof HandleSchema<H>` is a finite union of the user's
+ * declared schema fields plus the internal `_*` meta fields. This is what
+ * makes `QueryWhere<HandleSchema<H>>` reject typo'd field names at compile time.
+ */
+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>>;
+/**
+ * Runtime document shape inferred from a collection handle.
+ */
+type DocumentFromHandle<H> = H extends {
+    __schema: {
+        _output: infer O;
+    };
+} ? O & ParsedContent : ParsedContent;
+/**
+ * Explicit reference population map. Keys are fields on the source document;
+ * values are target collection handles.
+ */
+type PopulateSpec = Record<string, ContentCollectionHandle | string>;
+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;
+type PopulateFromOptions<O> = O extends {
+    populate?: infer P;
+} ? P : undefined;
+type PopulateOption<P extends PopulateSpec | undefined = undefined> = {
+    populate?: P;
+};
+/**
+ * Whether a collection handle declares i18n at the type level.
+ */
+type HandleIsI18n<H> = H extends {
+    __i18n: infer I;
+} ? I extends true ? true : false : false;
+/**
+ * Locale option made required when the handle is i18n.
+ */
+type LocaleOption<H, OptKey extends string = 'locale'> = HandleIsI18n<H> extends true ? {
+    [K in OptKey]: string;
+} : {
+    [K in OptKey]?: string;
+};
+type SourceIsI18n<S> = S extends ReadonlyArray<infer I> ? true extends HandleIsI18n<I> ? true : false : HandleIsI18n<S>;
+type BacklinksLocaleOption<Target, Source> = HandleIsI18n<Target> extends true ? {
+    locale: string;
+} : SourceIsI18n<Source> extends true ? {
+    locale: string;
+} : {
+    locale?: string;
+};
+type LocaleFallback = false | true | 'default' | string | string[];
+/**
+ * Document shape returned from `one`, `many` and `resolveOne`. Every doc carries the
+ * route metadata (`path`, `localePaths`, `locale`, ...) the route resolver
+ * already produces, so locale switching needs no extra round trip.
+ */
+type LocalizedDoc<T = ParsedContentMeta> = T & ContentRouteMeta & {
+    /**
+     * Locale-agnostic path stem derived from the source file.
+     */
+    stem?: string;
+    /**
+     * Source file extension when it can be inferred.
+     */
+    extension?: string;
+};
+/**
+ * Explain how `resolveOne` interpreted the request and what it matched.
+ */
+interface ResolutionEnvelope {
+    requested: {
+        collection: string;
+        by: ContentSelector;
+        locale?: string;
+        fallback?: LocaleFallback;
+    };
+    normalized: {
+        by: ContentSelector;
+    };
+    matched: {
+        found: boolean;
+        collection: string;
+        path?: string;
+        canonicalPath?: string;
+        ref?: string;
+        locale?: string;
+    };
+    fallback: {
+        used: boolean;
+        locale?: string;
+    };
+}
+/**
+ * Result returned by `resolveOne`.
+ */
+interface ResolveOneResult<T = ParsedContentMeta> {
+    doc: LocalizedDoc<T> | null;
+    explain: ResolutionEnvelope;
+}
+/**
+ * Options accepted by `resolveOne(handle, options)` and `one(handle, options)`.
+ */
+type ResolveOneOptions<H = unknown, P extends PopulateSpec | undefined = undefined> = {
+    by: ContentSelector;
+    fallback?: LocaleFallback;
+    select?: SelectFields<H>;
+} & LocaleOption<H> & PopulateOption<P>;
+type OneOptions<H = unknown, P extends PopulateSpec | undefined = undefined> = ResolveOneOptions<H, P>;
+/**
+ * Options accepted by `many(handle, options)`.
+ */
+type ManyOptions<H = unknown, P extends PopulateSpec | undefined = undefined> = {
+    where?: QueryWhere<HandleSchema<H>>;
+    sort?: SortSpec<HandleSchema<H>>;
+    limit?: number;
+    skip?: number;
+    fallback?: LocaleFallback;
+    select?: SelectFields<H>;
+} & LocaleOption<H> & PopulateOption<P>;
+/**
+ * Options accepted by `paginate(handle, options)`.
+ */
+type PaginationOptions<H = unknown, P extends PopulateSpec | undefined = undefined> = Omit<ManyOptions<H, P>, 'skip' | 'limit'> & {
+    /**
+     * One-based page number.
+     *
+     * @default 1
+     */
+    page?: number;
+    /**
+     * Number of documents per page.
+     *
+     * @default 10
+     */
+    limit?: number;
+};
+/**
+ * Result returned by `paginate()` and `useContentPagination()`.
+ */
+interface PaginationResult<T = ParsedContentMeta> {
+    data: Array<LocalizedDoc<T>>;
+    page: number;
+    limit: number;
+    total: number;
+    pageCount: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+    nextPage: number | null;
+    prevPage: number | null;
+}
+type BacklinkSource = ContentCollectionHandle | string;
+type SourceName<S> = S extends string ? S : S extends {
+    name: infer N;
+} ? Extract<N, string> : string;
+type BacklinkFields<S = BacklinkSource | ReadonlyArray<BacklinkSource>> = ReadonlyArray<string> | Partial<Record<SourceName<S extends ReadonlyArray<infer I> ? I : S>, ReadonlyArray<string>>>;
+type DocumentFromSource<S> = S extends ReadonlyArray<infer I> ? DocumentFromHandle<I> : DocumentFromHandle<S>;
+/**
+ * Options accepted by `backlinks(targetHandle, options)`.
+ */
+type BacklinksOptions<Target = unknown, Source extends BacklinkSource | ReadonlyArray<BacklinkSource> = BacklinkSource | ReadonlyArray<BacklinkSource>, P extends PopulateSpec | undefined = undefined> = {
+    /**
+     * Target document to find incoming references for.
+     */
+    by: ContentSelector;
+    /**
+     * Source collection handle(s) to scan for references.
+     */
+    from: Source;
+    /**
+     * Explicit reference fields on the source collection(s). When omitted,
+     * fields are inferred from source handles that use `reference()`.
+     */
+    fields?: BacklinkFields<Source>;
+    sort?: SortSpec<DocumentFromSource<Source>>;
+    limit?: number;
+    skip?: number;
+    fallback?: LocaleFallback;
+    select?: Source extends string ? ReadonlyArray<string> : ReadonlyArray<Extract<keyof DocumentFromSource<Source>, string>>;
+} & BacklinksLocaleOption<Target, Source> & PopulateOption<P>;
+type BacklinksResult<Source extends BacklinkSource | ReadonlyArray<BacklinkSource> = BacklinkSource | ReadonlyArray<BacklinkSource>, P extends PopulateSpec | undefined = undefined> = Array<LocalizedDoc<PopulatedDocument<DocumentFromSource<Source>, P>>>;
+/**
+ * Options accepted by `variants(handle, options)`.
+ */
+type VariantsOptions<H = unknown> = {
+    by: ContentSelector;
+    /**
+     * Restrict to a subset of locales. Defaults to all configured locales.
+     */
+    locales?: string[];
+} & LocaleOption<H>;
+/**
+ * Variant entry returned by `variants()` and `useContentVariants()`.
+ */
+interface ContentVariant<_T = ParsedContentMeta> {
+    locale: string;
+    path: string;
+    translated: boolean;
+    fallback?: string;
+}
+/**
+ * Options accepted by `tree(handle, options)`.
+ */
+type TreeOptions<H = unknown, Fields extends ReadonlyArray<keyof HandleSchema<H> | string> | undefined = undefined> = {
+    where?: QueryWhere<HandleSchema<H>>;
+    sort?: SortSpec<HandleSchema<H>>;
+    fields?: Fields;
+    fallback?: LocaleFallback;
+} & LocaleOption<H>;
+/**
+ * Typed navigation item. Requested `fields` are preserved in the return type
+ * without keeping the old open index signature.
+ */
+type ContentTreeItem<T = ParsedContentMeta, Fields extends ReadonlyArray<keyof T | string> | undefined = undefined> = {
+    title: string;
+    path: string;
+    _path?: string;
+    children?: Array<ContentTreeItem<T, Fields>>;
+} & (Fields extends ReadonlyArray<infer K> ? Pick<T, Extract<K, keyof T>> : Record<never, never>);
+
+/**
+ * Options accepted by `neighbors(handle, options)`.
+ *
+ * Identifying the anchor document lives in `filter`, same as every other
+ * verb. Only the reserved selectors `path` and `ref` are accepted.
+ */
+type NeighborsOptions<H = unknown> = {
+    by: ContentSelector;
+    fallback?: LocaleFallback;
+    fields?: SelectFields<H>;
+} & LocaleOption<H>;
+/**
+ * Result of `neighbors()` and `useContentNeighbors()`.
+ */
+interface NeighborsResult<T = ParsedContentMeta> {
+    prev: ContentTreeItem<T> | null;
+    next: ContentTreeItem<T> | null;
+}
+
+type ContentSearchEngine = 'minisearch' | 'pagefind' | 'cms';
+interface ContentMiniSearchOptions {
+    /**
+     * Fields indexed by MiniSearch.
+     *
+     * @default ['title', 'content', 'headings']
+     */
+    fields: string[];
+    /**
+     * Fields copied into search result payloads.
+     *
+     * @default ['path', 'title', 'excerpt', 'anchor', 'locale']
+     */
+    storeFields: string[];
+    /**
+     * Per-field relevance boosts.
+     *
+     * @default { title: 4, headings: 2, content: 1 }
+     */
+    boost: Record<string, number>;
+    /**
+     * MiniSearch fuzzy search setting.
+     *
+     * @default 0.2
+     */
+    fuzzy: number | boolean;
+    /**
+     * Enable prefix matching.
+     *
+     * @default true
+     */
+    prefix: boolean;
+}
+interface ContentSearchPublicRuntimeConfig {
+    apiBaseURL: string;
+    indexURL: string;
+    engine: ContentSearchEngine;
+    minisearch: ContentMiniSearchOptions;
+}
+interface ContentSearchIndexRecord {
+    id: string;
+    path: string;
+    title: string;
+    excerpt: string;
+    content: string;
+    headings: string[];
+    anchor?: string;
+    locale?: string;
+    [field: string]: unknown;
+}
+interface ContentSearchResult {
+    path: string;
+    title: string;
+    excerpt: string;
+    score: number;
+    anchor?: string;
+    locale?: string;
+    [field: string]: unknown;
+}
+interface ContentProviderSearchRequest {
+    term: string;
+    locale?: string;
+    collections?: string[];
+}
+
+type MountOptions = {
+    driver: 'fs' | 'http' | string;
+    name?: string;
+    prefix?: string;
+    [options: string]: unknown;
+};
+interface ContentI18nOptions {
+    /**
+     * Enable locale-aware content behavior.
+     *
+     * `true` means "detect from Nuxt I18n and/or content.config".
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * List of locale codes used by content.
+     *
+     * @default []
+     */
+    locales?: string[];
+    /**
+     * Default locale for top level contents.
+     *
+     * @default undefined
+     */
+    defaultLocale?: string;
+    /**
+     * Ordered locale fallback chains keyed by locale code.
+     *
+     * @default {}
+     */
+    fallback?: Record<string, string[]>;
+    /**
+     * Use numeric prefixes as the canonical cross-locale identity source.
+     *
+     * Example:
+     * `en/1.guide/1.getting-started.md` and `de/1.leitfaden/1.erste-schritte.md`
+     * share the same canonical key `1/1`.
+     *
+     * This is intentionally opt-in.
+     *
+     * @default false
+     */
+    translatedSlugs?: boolean;
+    /**
+     * Treat translated-slug warnings as build/runtime validation errors.
+     *
+     * @default false
+     */
+    strictTranslatedSlugs?: boolean;
+}
+interface ContentSitemapOptions {
+    /**
+     * Route suffix appended to `content.api.baseURL`.
+     *
+     * @default '/sitemap'
+     */
+    path?: string;
+    /**
+     * Collections to include in the generated content sitemap source.
+     *
+     * When omitted, all configured collections are considered.
+     *
+     * @default undefined
+     */
+    include?: string[];
+    /**
+     * Collections to exclude from the generated content sitemap source.
+     *
+     * @default []
+     */
+    exclude?: string[];
+    /**
+     * Include draft content in sitemap entries.
+     *
+     * Production default is `false`.
+     * Development remains permissive for easier debugging.
+     *
+     * @default undefined
+     */
+    includeDrafts?: boolean;
+    /**
+     * Optional build-time validation for generated sitemap output.
+     *
+     * This is intended as a release-safety check for content-heavy sites where
+     * shipping an empty docs/blog sitemap is a production failure.
+     *
+     * @default disabled
+     */
+    assert?: ContentSitemapAssertOptions;
+}
+interface ContentSitemapAssertSitemapOptions {
+    /**
+     * Allow this sitemap to contain zero URLs.
+     *
+     * When `true`, URL count assertions are skipped for this sitemap.
+     *
+     * @default inherits global `allowEmpty`
+     */
+    allowEmpty?: boolean;
+    /**
+     * Minimum number of URLs required for this sitemap.
+     *
+     * @default inherits global `minUrlsPerSitemap`
+     */
+    minUrls?: number;
+    /**
+     * Require at least one image entry in this sitemap.
+     *
+     * @default inherits global `requireImages`
+     */
+    requireImages?: boolean;
+}
+interface ContentSitemapAssertOptions {
+    /**
+     * Enable sitemap artifact assertions.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Which build path should enforce assertions.
+     *
+     * `generate` maps to static generation, `build` maps to non-static builds,
+     * and `both` enables both paths.
+     *
+     * @default 'generate'
+     */
+    mode?: 'generate' | 'build' | 'both';
+    /**
+     * Allow discovered sitemap files to contain zero URLs.
+     *
+     * @default false
+     */
+    allowEmpty?: boolean;
+    /**
+     * Minimum number of URLs required in each discovered sitemap.
+     *
+     * @default 1
+     */
+    minUrlsPerSitemap?: number;
+    /**
+     * Require at least one image entry in each discovered sitemap.
+     *
+     * @default false
+     */
+    requireImages?: boolean;
+    /**
+     * Collections that must contribute at least one route to the content sitemap.
+     *
+     * This is preferred over hardcoded URL checks because it asserts the real
+     * content invariant rather than a single route sample.
+     *
+     * @default []
+     */
+    requiredCollections?: string[];
+    /**
+     * Optional per-sitemap overrides keyed by sitemap name, for example `en-US`.
+     *
+     * @default {}
+     */
+    sitemaps?: Record<string, ContentSitemapAssertSitemapOptions>;
+}
+interface ContentSearchOptions {
+    /**
+     * Base route used for the built-in search api.
+     *
+     * Defaults to `${content.api.baseURL}/search`.
+     */
+    apiBaseURL?: string;
+    /**
+     * Search engine used by `useContentSearchResults`.
+     *
+     * @default 'minisearch'
+     */
+    engine?: ContentSearchEngine;
+    /**
+     * HTML tags ignored when flattening rich content into search text.
+     *
+     * @default ['script', 'style', 'pre']
+     */
+    ignoredTags?: string[];
+    /**
+     * Query predicate applied before records are indexed.
+     *
+     * @default { _draft: false, _partial: false }
+     */
+    filterQuery?: ContentQueryBuilderWhere;
+    /**
+     * Collections included in the built-in index.
+     *
+     * When omitted, all configured collections are indexed.
+     */
+    collections?: string[];
+    /**
+     * Extra top-level document fields copied into each generated search record.
+     *
+     * Use this when `minisearch.fields`, `minisearch.storeFields`, or
+     * `minisearch.boost` refer to frontmatter fields such as `tags`.
+     *
+     * @default []
+     */
+    extraFields?: string[];
+    /**
+     * MiniSearch index and ranking options.
+     */
+    minisearch?: Partial<ContentMiniSearchOptions>;
+}
+interface ContentPreviewOptions {
+    /**
+     * Server-side token required before preview storage can be read.
+     */
+    token?: string;
+}
+interface ContentRevalidateOptions {
+    /**
+     * Server-side token required before the built-in revalidation endpoint accepts
+     * tag/path invalidation requests.
+     */
+    token: string;
+    /**
+     * Allow token-only revalidation requests without HMAC headers.
+     *
+     * This is intended for local/dev compatibility only. Production CMS delivery
+     * should leave this disabled so requests are timestamped and signed.
+     *
+     * @default false
+     */
+    allowUnsigned?: boolean;
+}
+interface ModuleOptions {
+    api: {
+        /**
+         * Base route that will be used for content api
+         *
+         * @default '/api/_content'
+         */
+        baseURL: string;
+    };
+    /**
+     * Locale-aware content behavior.
+     */
+    i18n: boolean | ContentI18nOptions;
+    /**
+     * Content-owned sitemap source configuration for Nuxt SEO.
+     *
+     * When enabled, Ginko exposes a JSON endpoint that can be consumed by
+     * `@nuxtjs/sitemap` through `sitemap.sources`.
+     */
+    sitemap: boolean | ContentSitemapOptions;
+    /**
+     * 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.
+     */
+    search: false | ContentSearchOptions;
+    /**
+     * Preview storage access configuration.
+     *
+     * Preview mode is disabled unless a token is configured and the incoming
+     * preview token matches it.
+     */
+    preview?: false | ContentPreviewOptions;
+    /**
+     * Built-in cache revalidation endpoint configuration.
+     *
+     * When a token is configured, callers must send it as
+     * `x-ginko-revalidate-token` or `authorization: Bearer <token>`.
+     */
+    revalidate?: false | ContentRevalidateOptions;
+    /**
+     * Optional server-side cache adapter module.
+     *
+     * The module must default-export a `ContentCacheAdapter`, or export one as
+     * `contentCacheAdapter` or `cacheAdapter`.
+     */
+    cache?: false | string;
+    /**
+     * Disable content watcher and hot content reload.
+     * Note: Watcher is a development feature and will not includes in the production.
+     *
+     * @default true
+     */
+    watch: false | {
+        ws: Partial<ListenOptions>;
+    };
+    /**
+     * Contents can be located in multiple places, in multiple directories or even in remote git repositories.
+     * Using sources option you can tell Content module where to look for contents.
+     *
+     * @default ['content']
+     */
+    sources: Record<string, MountOptions>;
+    /**
+     * List of ignore patterns that will be used to exclude content from parsing, rendering and watching.
+     *
+     * Note that files with a leading . or - are ignored by default
+     *
+     * @default []
+     */
+    ignores: Array<string>;
+    /**
+     * Content module uses Comark under the hood to parse markdown files.
+     */
+    markdown: {
+        /**
+         * Tags will be used to replace markdown components and render custom components instead of default ones.
+         *
+         * @default {}
+         */
+        tags?: Record<string, string>;
+        /**
+         * Ordered list of Comark plugin descriptors.
+         *
+         * @default []
+         */
+        plugins?: MarkdownPluginDescriptor[];
+        /**
+         * Anchor link generation config
+         *
+         * @default {}
+         */
+        anchorLinks?: boolean | {
+            /**
+              * Sets the maximal depth for anchor link generation
+              *
+              * @default 4
+              */
+            depth?: number;
+            /**
+             * Excludes headings from link generation when they are in the depth range.
+             *
+             * @default [1]
+             */
+            exclude?: number[];
+        };
+        /**
+         * Markdown image renderer.
+         *
+         * `auto` uses Nuxt Image when `<NuxtImg>` is available and otherwise
+         * falls back to a native `<img>`.
+         *
+         * @default 'auto'
+         */
+        image?: 'auto' | 'img' | 'nuxt-image';
+    };
+    /**
+     * Options for yaml parser.
+     *
+     * @default {}
+     */
+    yaml: false | Record<string, unknown>;
+    /**
+     * Options for yaml parser.
+     *
+     * @default {}
+     */
+    csv: false | {
+        json?: boolean;
+        delimiter?: string;
+    };
+    /**
+     * Enable/Disable navigation.
+     *
+     * @default {}
+     */
+    navigation: false | {
+        fields: Array<string>;
+    };
+    /**
+     * Typed collection definitions loaded from `content.config.*`.
+     *
+     * Globs are relative to the content source root.
+     *
+     * @default {}
+     */
+    collections?: Record<string, ContentCollectionConfig>;
+    /**
+     * Backing implementation for public content reads.
+     *
+     * `filesystem` is the default. `cms`, `ginko-cms`, and `ginko` resolve to the
+     * official Ginko CMS provider when `@lupinum/ginko-cms` is installed.
+     */
+    provider?: ContentProviderName;
+    /**
+     * External provider modules keyed by provider name.
+     */
+    providers?: Record<string, string>;
+    /**
+     * Enable automatic usage of `useContentHead`
+     *
+     * @default true
+     */
+    contentHead?: boolean;
+    /**
+     * Enable to keep uppercase characters in the generated routes.
+     *
+     * @default false
+     */
+    respectPathCase: boolean;
+    experimental: {
+        stripQueryParameters?: boolean;
+    };
+}
+interface ResolvedContentI18nOptions {
+    locales: string[];
+    defaultLocale?: string;
+    fallback: Record<string, string[]>;
+    translatedSlugs: boolean;
+    strictTranslatedSlugs: boolean;
+}
+interface ContentContext extends ModuleOptions {
+    transformers: Array<string>;
+    sitemap: false | ContentSitemapOptions;
+    locales: string[];
+    defaultLocale?: string;
+    localeFallback: Record<string, string[]>;
+    translatedSlugs: boolean;
+    strictTranslatedSlugs: boolean;
+}
+
+interface ContentCacheArtifact<T = ParsedContent> {
+    parsed: T;
+    hash: string;
+}
+interface ManifestVariant {
+    canonicalKey: string;
+    contentId: string;
+    locale: string;
+    path?: string;
+}
+interface ContentManifest {
+    byCanonical: Record<string, Record<string, ManifestVariant>>;
+    byRef: Record<string, string>;
+    byRoute: Record<string, string>;
+    paths: Record<string, string[]>;
+    collections: Record<string, string[]>;
+}
+interface ResolvedVariant extends ManifestVariant {
+    requestedLocale?: string;
+    resolvedLocale?: string;
+    fallback: boolean;
+    availableLocales: string[];
+}
+interface ParseContentOptions {
+    validate?: boolean;
+    csv?: ModuleOptions['csv'];
+    yaml?: ModuleOptions['yaml'];
+    markdown?: ModuleOptions['markdown'];
+    transformers?: ContentTransformer[];
+    pathMeta?: {
+        locales?: ContentContext['locales'];
+        defaultLocale?: ContentContext['defaultLocale'];
+        translatedSlugs?: ContentContext['translatedSlugs'];
+        respectPathCase?: ModuleOptions['respectPathCase'];
+        collections?: Record<string, ContentCollectionConfig>;
+        collectionResolver?: (file: string) => string | undefined;
+    };
+    [key: string]: unknown;
+}
+type TransformContentSource = string | StorageValue;
+
+declare function createSearchRuntimeConfig(search: Exclude<ModuleOptions$1['search'], false>, apiBaseURL: string): ContentSearchPublicRuntimeConfig$1;
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions$1, ModuleOptions$1, false>;
+
+interface ModuleHooks {
+    'content:context'(ctx: ContentContext$1): void;
+}
+interface ModulePublicRuntimeConfig {
+    experimental: {
+        stripQueryParameters: boolean;
+    };
+    api: {
+        baseURL: string;
+    };
+    sitemap: {
+        path: string;
+        include?: string[];
+        exclude?: string[];
+        includeDrafts?: boolean;
+    } | false;
+    integrity: number | undefined;
+    respectPathCase: boolean;
+    defaultLocale: ContentContext$1['defaultLocale'];
+    locales: ContentContext$1['locales'];
+    provider: ContentContext$1['provider'];
+    providers: ContentContext$1['providers'];
+    collections: Record<string, {
+        source: ContentCollectionConfig$1['source'];
+        exclude?: ContentCollectionConfig$1['exclude'];
+        strict: boolean;
+        i18n?: ContentCollectionI18nConfig$1;
+        sitemap?: boolean;
+    }>;
+    localeFallback: ContentContext$1['localeFallback'];
+    translatedSlugs: ContentContext$1['translatedSlugs'];
+    strictTranslatedSlugs: ContentContext$1['strictTranslatedSlugs'];
+    markdown: MarkdownOptions$1;
+    wsUrl?: string;
+    navigation: ModuleOptions$1['navigation'];
+    search: ReturnType<typeof createSearchRuntimeConfig> | false;
+    contentHead: ModuleOptions$1['contentHead'];
+}
+interface ModulePrivateRuntimeConfig {
+    /**
+     * Internal version that represents cache format.
+     * This is used to invalidate cache when the format changes.
+     */
+    cacheVersion: string;
+    cacheIntegrity: string;
+    revalidate?: false | ContentRevalidateOptions$1;
+}
+declare module '@nuxt/schema' {
+    interface NuxtHooks {
+        'content:context': (ctx: ContentContext$1) => void | Promise<void>;
+    }
+    interface PublicRuntimeConfig {
+        content: ModulePublicRuntimeConfig;
+    }
+    interface PrivateRuntimeConfig {
+        content: ModulePrivateRuntimeConfig & ContentContext$1;
+    }
+}
+declare module 'nitropack' {
+    interface NitroRuntimeHooks {
+        'content:file:beforeParse': (file: {
+            _id: string;
+            body: StorageValue;
+        }) => void;
+        'content:file:afterParse': (file: ParsedContent$1) => void;
+    }
+}
+
+export { _default as default };
+export type { BacklinkFields, BacklinkSource, BacklinksOptions, BacklinksResult, BuiltinContentProviderName, CollectionQueryBuilder, CollectionQueryOperator, CollectionQueryValue, CollectionSchema, ContentCacheArtifact, ContentCmsCollectionConfig, ContentCmsFieldConfig, ContentCmsFieldType, ContentCmsRelationConfig, ContentCollectionConfig, ContentCollectionHandle, ContentCollectionI18nConfig, ContentCollectionI18nMap, ContentCollectionItem, ContentCollectionItemSurroundingsOptions, ContentCollectionKind, ContentCollectionMap, ContentCollectionName, ContentCollectionNavigationOptions, ContentCollectionPageOptions, ContentCollectionRouteConfig, ContentCollectionRouteMetaOptions, ContentCollectionSearchSectionsOptions, ContentCollectionSource, ContentCollectionSourceObject, ContentConfig, ContentContext, ContentI18nOptions, ContentLocaleEntry, ContentLocaleRoute, ContentManifest, ContentMiniSearchOptions, ContentNavigationItem, ContentPageResult, ContentPreviewOptions, ContentProviderName, ContentProviderSearchRequest, ContentQueryBuilder, ContentQueryBuilderParams, ContentQueryBuilderWhere, ContentQueryFetcher, ContentQueryRequest, ContentQuerySortFields, ContentQuerySortOptions, ContentQuerySortParams, ContentReferenceSchema, ContentResolvedMeta, ContentRevalidateOptions, ContentRouteMeta, ContentSearchEngine, ContentSearchIndexRecord, ContentSearchOptions, ContentSearchPublicRuntimeConfig, ContentSearchResult, ContentSearchSection, ContentSelector, ContentSeoImage, ContentSeoMeta, ContentSitemapAlternative, ContentSitemapAssertOptions, ContentSitemapAssertSitemapOptions, ContentSitemapEntry, ContentSitemapImage, ContentSitemapOptions, ContentTransformer, ContentTreeItem, ContentVariant, DefineCollectionObject, DefineCollectionOptions, DocumentFromHandle, LocaleFallback, LocalePathEntry, LocalizedDoc, ManifestVariant, ManyOptions, MarkdownNode, MarkdownOptions, MarkdownParsedContent, MarkdownPluginDescriptor, MarkdownPluginOptions, MarkdownRoot, ModuleHooks, ModuleOptions, MountOptions, NavItem, NeighborsOptions, NeighborsResult, OneOptions, PaginationOptions, PaginationResult, ParseContentOptions, ParsedContent, ParsedContentInternalMeta, ParsedContentMeta, PopulateFromOptions, PopulateSpec, PopulatedDocument, QueryGroupBuilder, QueryGroupFunction, QueryMatchOperator, QueryOperators, QueryOrderDirection, QueryOrderOptions, QueryWhere, ResolutionEnvelope, ResolveContentReferenceOptions, ResolveOneOptions, ResolveOneResult, ResolvedContentI18nOptions, ResolvedMarkdownPlugin, ResolvedVariant, SortDirection, SortSpec, StrictParsedContent, StrictParsedContentMeta, Toc, TocLink, TransformContentOptions, TransformContentSource, TreeOptions, VariantsOptions };