@lupinum/ginko-content 0.1.6 → 0.2.0

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

@@ -15,10 +15,10 @@ export default defineEventHandler(async (event) => {
     collection,
     exact: false
   });
-  const locales = resolved ? resolved.variants.filter((doc) => doc._canonicalKey === resolved.canonicalKey && typeof doc._locale === "string").sort((left, right) => String(left._locale).localeCompare(String(right._locale))).map((doc) => ({
+  const locales = resolved ? resolved.variants.filter((doc) => doc.canonicalKey === resolved.canonicalKey && typeof doc.locale === "string").sort((left, right) => String(left.locale).localeCompare(String(right.locale))).map((doc) => ({
     canonicalKey: resolved.canonicalKey,
-    locale: String(doc._locale),
-    ...typeof doc._path === "string" ? { path: doc._path } : {}
+    locale: String(doc.locale),
+    ...typeof doc.path === "string" ? { path: doc.path } : {}
   })) : [];
   if (!locales.length) {
     throw createError({

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

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types").NavItem[]>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types/content").NavItem[]>>;
 export default _default;

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

@@ -1,6 +1,7 @@
 import { defineEventHandler, getQuery } from "h3";
 import { getContentQuery } from "../../utils/query.js";
 import { getContentProvider } from "../providers/index.js";
+import { createProviderNavigationQuery } from "../provider-query.js";
 import { createContentProviderError } from "../../../public/provider-errors";
 export default defineEventHandler(async (event) => {
   const query = getContentQuery(event);
@@ -17,5 +18,6 @@ export default defineEventHandler(async (event) => {
       provider: provider.name
     });
   }
-  return await provider.navigationQuery(event, query);
+  const { query: providerQuery, options } = createProviderNavigationQuery(query);
+  return await provider.navigationQuery(event, providerQuery, options);
 });

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

@@ -1,9 +1,9 @@
 import { defineEventHandler } from "h3";
 import { getContentQuery } from "../../utils/query.js";
 import { getContentProvider } from "../providers/index.js";
-import { normalizeProviderQueryResponse } from "../provider-query.js";
+import { createProviderQuery, normalizeProviderQueryResponse } from "../provider-query.js";
 export default defineEventHandler(async (event) => {
   const query = getContentQuery(event);
   const provider = await getContentProvider(event);
-  return normalizeProviderQueryResponse(query, await provider.query(event, query), provider.name);
+  return normalizeProviderQueryResponse(query, await provider.query(event, createProviderQuery(query)), provider.name);
 });

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

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types").ContentSearchIndexRecord[]>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types/search").ContentSearchIndexRecord[]>>;
 export default _default;

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

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types").ContentSitemapEntry[]>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../../types/query").ContentSitemapEntry[]>>;
 export default _default;

package/dist/runtime/server/cache-adapters.d.ts

@@ -1,5 +1,23 @@
 import type { ContentCacheAdapter, ContentCacheHint } from '../../public/provider';
+/**
+ * Choosing a cache adapter:
+ * - `noopContentCache` — the default. Both `apply` and `invalidate` are intentionally
+ *   inert: the runtime still computes and stores a cache hint per request, but nothing
+ *   is written to the response and no upstream cache is purged. Use when caching is
+ *   handled entirely outside this module (a CDN/edge config you own) or disabled.
+ * - `vercelContentCache` — `apply` is intentionally inert (Vercel ISR revalidation is a
+ *   pull, not a per-response header this module sets); only `invalidate` does work,
+ *   firing prerender-revalidate HEAD requests. Use on Vercel ISR deployments.
+ * - `headersContentCache` — the active-`apply` adapter: writes `Cache-Control`/`ETag`/
+ *   `Last-Modified` onto every content response from the hint. Use when this module
+ *   should own response cache headers directly (self-hosted / generic CDN).
+ */
 export declare const noopContentCache: () => ContentCacheAdapter;
+/**
+ * Emits the per-request cache hint as HTTP response headers via {@link contentCacheHeaders}.
+ * `invalidate` is a no-op: header-based caching has no upstream store to purge.
+ */
+export declare const headersContentCache: () => ContentCacheAdapter;
 export interface VercelContentCacheOptions {
     origin: string;
     bypassToken: string;

package/dist/runtime/server/cache-adapters.js

@@ -1,3 +1,4 @@
+import { setHeader } from "h3";
 export const noopContentCache = () => ({
   name: "noop",
   apply: () => {
@@ -5,6 +6,17 @@ export const noopContentCache = () => ({
   invalidate: async () => {
   }
 });
+export const headersContentCache = () => ({
+  name: "headers",
+  apply: (event, hint) => {
+    const headers = contentCacheHeaders(hint);
+    headers.forEach((value, key) => {
+      setHeader(event, key, value);
+    });
+  },
+  invalidate: async () => {
+  }
+});
 export const vercelContentCache = (options) => {
   const origin = options.origin.replace(/\/$/, "");
   const fetchImpl = options.fetch || globalThis.fetch;

package/dist/runtime/server/collection-helpers.d.ts

@@ -2,10 +2,10 @@ import type { H3Event } from 'h3';
 import type { ParsedContent } from '../../types/content';
 import type { ContentCollectionItemSurroundingsOptions, ContentCollectionNavigationOptions, ContentCollectionPageOptions, ContentCollectionRouteMetaOptions, ContentCollectionSearchSectionsOptions, ContentPageResult, ContentSearchSection } from '../../types/query';
 export declare function queryFilesystemCollectionNavigation(event: H3Event, collection: string, fieldsOrOptions?: string[] | ContentCollectionNavigationOptions): Promise<any[]>;
-export declare function queryFilesystemCollectionItemSurroundings(event: H3Event, collection: string, path: string, opts?: ContentCollectionItemSurroundingsOptions): Promise<(import("../../types").NavItem | null)[]>;
+export declare function queryFilesystemCollectionItemSurroundings(event: H3Event, collection: string, path: string, opts?: ContentCollectionItemSurroundingsOptions): Promise<(import("../../types/content").NavItem | null)[]>;
 export declare function queryFilesystemCollectionSearchSections(event: H3Event, collection: string, opts?: ContentCollectionSearchSectionsOptions): Promise<ContentSearchSection[]>;
 export declare function queryFilesystemCollectionPage<T = ParsedContent>(event: H3Event, collection: string, routeOrPath?: string, options?: ContentCollectionPageOptions): Promise<ContentPageResult<T> | null>;
-export declare function queryFilesystemCollectionRouteMeta(event: H3Event, collection: string, routeOrPath?: string, options?: ContentCollectionRouteMetaOptions): Promise<import("../../types").ContentRouteMeta | null>;
+export declare function queryFilesystemCollectionRouteMeta(event: H3Event, collection: string, routeOrPath?: string, options?: ContentCollectionRouteMetaOptions): Promise<import("../../types/query").ContentRouteMeta | null>;
 export declare const queryCollectionNavigation: typeof queryFilesystemCollectionNavigation;
 export declare const queryCollectionItemSurroundings: typeof queryFilesystemCollectionItemSurroundings;
 export declare const queryCollectionSearchSections: typeof queryFilesystemCollectionSearchSections;

package/dist/runtime/server/collection-helpers.js

@@ -1,20 +1,21 @@
 import { resolveCollectionItemSurroundingsData, resolveCollectionNavigationData, resolveCollectionPageData, resolveCollectionRouteMetaData, resolveCollectionSearchSectionsData } from "../../features/collections/resolve";
 import { resolveContentNavigation } from "./navigation-query.js";
 import { executeFilesystemContentQuery } from "./query-executor.js";
+import { createProviderNavigationQuery, createProviderQuery } from "./provider-query.js";
 import { serverQueryCollection } from "./storage.js";
 import { contentConfig } from "./storage-access.js";
 const isNotFoundError = (error) => {
   return error?.statusCode === 404;
 };
 const searchPageFields = (fields = []) => [
-  "_path",
+  "path",
   "title",
   "description",
   "body",
   ...fields
 ];
 const mergeFilterQuery = (filterQuery, locale) => {
-  const localeFilter = locale ? { _locale: locale } : void 0;
+  const localeFilter = locale ? { locale } : void 0;
   if (filterQuery && localeFilter) {
     return { $and: [filterQuery, localeFilter] };
   }
@@ -25,12 +26,15 @@ export async function queryFilesystemCollectionNavigation(event, collection, fie
   const locale = options.locale;
   return await resolveCollectionNavigationData(collection, contentConfig(), {
     ...options,
-    loadNavigation: () => resolveContentNavigation(event, {
-      collection,
-      ...options.fields?.length ? { navigationFields: options.fields } : {},
-      ...typeof options.canonical === "boolean" ? { canonical: options.canonical } : {},
-      ...locale ? { resolveLocale: { locale, fallback: true } } : {}
-    })
+    loadNavigation: () => {
+      const { query, options: navigationOptions } = createProviderNavigationQuery({
+        collection,
+        ...options.fields?.length ? { navigationFields: options.fields } : {},
+        ...typeof options.canonical === "boolean" ? { canonical: options.canonical } : {},
+        ...locale ? { resolveLocale: { locale, fallback: true } } : {}
+      });
+      return resolveContentNavigation(event, query, navigationOptions);
+    }
   });
 }
 export async function queryFilesystemCollectionItemSurroundings(event, collection, path, opts = {}) {
@@ -57,7 +61,7 @@ export async function queryFilesystemCollectionPage(event, collection, routeOrPa
     ...options,
     loadVariantPage: async (input) => {
       try {
-        const response = await executeFilesystemContentQuery(event, {
+        const response = await executeFilesystemContentQuery(event, createProviderQuery({
           collection,
           first: true,
           resolveVariant: {
@@ -65,7 +69,7 @@ export async function queryFilesystemCollectionPage(event, collection, routeOrPa
             locale: input.locale,
             fallback: input.fallback
           }
-        });
+        }).plan);
         return response.result || null;
       } catch (error) {
         if (isNotFoundError(error)) {
@@ -76,7 +80,7 @@ export async function queryFilesystemCollectionPage(event, collection, routeOrPa
     },
     loadPathPage: async (path) => {
       try {
-        return await serverQueryCollection(event, collection).where("_path", "=", path).first();
+        return await serverQueryCollection(event, collection).where("path", "=", path).first();
       } catch (error) {
         if (isNotFoundError(error)) {
           return null;

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

@@ -1,9 +1,11 @@
 export { one, many, paginate, backlinks, resolveOne, variants, tree, neighbors, createServerContentQueryContext } from './query-api';
-export { getCollectionPath } from '../query/routes';
+export { getCollectionPath } from '../../features/query/routes';
 export { queryCollectionsSitemapEntries } from './sitemap-provider';
-export { contentCacheHeaders, noopContentCache, vercelContentCache, type VercelContentCacheOptions } from './cache-adapters';
+export { contentCacheHeaders, noopContentCache, vercelContentCache, headersContentCache, type VercelContentCacheOptions } from './cache-adapters';
 export { clearContentCacheHint, collectContentCacheHint, getContentCacheHint } from './cache-hints';
 export { createContentProviderError } from '../../public/provider-errors';
-export { withContentCache } from '../../public/provider';
-export type { ContentCacheAdapter, ContentCacheHint, ContentCacheHintInput, ContentCacheInvalidateInput, ContentProvider, ContentProviderCapabilities, ContentProviderResult, MaybeContentProviderResult } from '../../public/provider';
+export { PROVIDER_QUERY_VERSION, toContentProviderNavigationQuery, toContentProviderQuery, withContentCache } from '../../public/provider';
+export { normalizeProviderDocument, shapeProviderDocument } from './provider-document';
+export type { ProviderDocumentInput, ShapeProviderDocumentOptions } from './provider-document';
+export type { ContentCacheAdapter, ContentCacheHint, ContentCacheHintInput, ContentCacheInvalidateInput, ContentProvider, ContentProviderCapabilities, ContentProviderNavigationOptions, ContentProviderQuery, ContentProviderResult, MaybeContentProviderResult } from '../../public/provider';
 export type { ContentProviderErrorCode } from '../../public/provider-errors';

package/dist/runtime/server/index.js

@@ -1,10 +1,11 @@
 export { one, many, paginate, backlinks, resolveOne, variants, tree, neighbors, createServerContentQueryContext } from "./query-api.js";
-export { getCollectionPath } from "../query/routes.js";
+export { getCollectionPath } from "../../features/query/routes";
 export { queryCollectionsSitemapEntries } from "./sitemap-provider.js";
 export {
   contentCacheHeaders,
   noopContentCache,
-  vercelContentCache
+  vercelContentCache,
+  headersContentCache
 } from "./cache-adapters.js";
 export {
   clearContentCacheHint,
@@ -12,4 +13,10 @@ export {
   getContentCacheHint
 } from "./cache-hints.js";
 export { createContentProviderError } from "../../public/provider-errors";
-export { withContentCache } from "../../public/provider";
+export {
+  PROVIDER_QUERY_VERSION,
+  toContentProviderNavigationQuery,
+  toContentProviderQuery,
+  withContentCache
+} from "../../public/provider";
+export { normalizeProviderDocument, shapeProviderDocument } from "./provider-document.js";

package/dist/runtime/server/middleware/agent-link-headers.js

@@ -1,6 +1,6 @@
 import { defineEventHandler, getRequestURL, setHeader } from "h3";
 import { getAgentLocales, localeFromAgentPath, resolveMarkdownForPublicRoute } from "../agent-site.js";
-import { agentRawPathForRoute, normalizeAgentRoutePath } from "../../agent-paths.js";
+import { agentRawPathForRoute, normalizeAgentRoutePath } from "../../../features/agent/agent-paths";
 import { appendResponseHeader } from "../agent-http.js";
 import { contentConfig } from "../storage-access.js";
 const shouldAdvertise = (pathname) => !pathname.startsWith("/_") && !pathname.startsWith("/api/") && !pathname.endsWith(".css") && !pathname.endsWith(".js") && !pathname.endsWith(".png") && !pathname.endsWith(".jpg") && !pathname.endsWith(".jpeg") && !pathname.endsWith(".webp") && !pathname.endsWith(".svg") && !pathname.endsWith(".ico");

package/dist/runtime/server/middleware/agent-markdown.js

@@ -7,7 +7,7 @@ import {
   resolveMarkdownForPublicRoute
 } from "../agent-site.js";
 import { acceptsMarkdown, addVaryHeader, setAgentMarkdownHeaders } from "../agent-http.js";
-import { isUnsafeAgentRoutePath, normalizeAgentRoutePath } from "../../agent-paths.js";
+import { isUnsafeAgentRoutePath, normalizeAgentRoutePath } from "../../../features/agent/agent-paths";
 const shouldSkip = (pathname) => pathname.startsWith("/_") || pathname.startsWith("/api/") || pathname.startsWith("/raw/") || pathname === "/robots.txt" || pathname === "/sitemap.xml" || pathname.endsWith(".txt") || pathname.endsWith(".xml") || pathname.endsWith(".json") || pathname.endsWith(".ico") || pathname.endsWith(".png") || pathname.endsWith(".jpg") || pathname.endsWith(".jpeg") || pathname.endsWith(".webp") || pathname.endsWith(".svg") || pathname.endsWith(".css") || pathname.endsWith(".js");
 export default defineEventHandler(async (event) => {
   const { pathname } = getRequestURL(event);

package/dist/runtime/server/navigation-query.d.ts

@@ -1,4 +1,4 @@
 import type { H3Event } from 'h3';
 import type { NavItem } from '../../types/content';
-import type { ContentQueryBuilderParams } from '../../types/query';
-export declare function resolveContentNavigation(event: H3Event, inputQuery?: ContentQueryBuilderParams): Promise<NavItem[]>;
+import type { ContentProviderNavigationOptions, ContentProviderQuery } from '../../public/provider-query';
+export declare function resolveContentNavigation(event: H3Event, query: ContentProviderQuery, navigationOptions?: ContentProviderNavigationOptions): Promise<NavItem[]>;

package/dist/runtime/server/navigation-query.js

@@ -1,3 +1,4 @@
+import { isPlanRegex } from "../../core/query/plan";
 import { resolveContentNavigationData } from "../../features/navigation/query";
 import { buildCanonicalNavigation } from "../../features/navigation/build";
 import { markCollectionNavigationRoot, projectNavigationTree } from "../../features/navigation/canonical";
@@ -7,7 +8,51 @@ import { isPreview } from "./preview.js";
 import { cacheStorage } from "./storage-access.js";
 import { createServerContentQuery } from "./storage.js";
 import { resolveLocaleChain } from "./manifest.js";
-export async function resolveContentNavigation(event, inputQuery = {}) {
+const reviveFilterValue = (value) => isPlanRegex(value) ? new RegExp(value.source, value.flags) : value;
+const conditionsToWhereCondition = (conditions) => {
+  if (!conditions.length) return {};
+  if (conditions.length === 1) return conditions[0];
+  return { $and: conditions };
+};
+const filterToWhereConditions = (filter) => {
+  switch (filter.type) {
+    case "true":
+      return [];
+    case "compare":
+      return [
+        filter.operator === "eq" ? { [filter.field]: reviveFilterValue(filter.value) } : { [filter.field]: { [`$${filter.operator}`]: reviveFilterValue(filter.value) } }
+      ];
+    case "and":
+      return filter.clauses.flatMap(filterToWhereConditions);
+    case "or":
+      return [{ $or: filter.clauses.map((clause) => conditionsToWhereCondition(filterToWhereConditions(clause))) }];
+    case "not":
+      return [{ $not: conditionsToWhereCondition(filterToWhereConditions(filter.clause)) }];
+    default:
+      throw new TypeError(`Unknown query filter node: ${filter.type}`);
+  }
+};
+const sortClausesToBuilder = (sort) => sort.map((clause) => ({
+  [clause.field]: clause.direction,
+  ...clause.locale ? { $locale: clause.locale } : {},
+  ...typeof clause.numeric === "boolean" ? { $numeric: clause.numeric } : {},
+  ...clause.caseFirst ? { $caseFirst: clause.caseFirst } : {},
+  ...clause.sensitivity ? { $sensitivity: clause.sensitivity } : {}
+}));
+const providerQueryToNavigationParams = (query, options) => {
+  const where = filterToWhereConditions(query.plan.filter);
+  const sort = sortClausesToBuilder(query.plan.sort);
+  return {
+    ...query.collection ? { collection: query.collection } : {},
+    ...where.length ? { where } : {},
+    ...sort.length ? { sort } : {},
+    ...options.resolveLocale ? { resolveLocale: options.resolveLocale } : {},
+    ...options.fields?.length ? { only: options.fields } : {},
+    ...options.canonical ? { canonical: true } : {}
+  };
+};
+export async function resolveContentNavigation(event, query, navigationOptions = {}) {
+  const inputQuery = providerQueryToNavigationParams(query, navigationOptions);
   const runtimeConfig = getContentRuntimeConfig();
   const requestedFields = [
     ...Array.isArray(inputQuery.only) ? inputQuery.only.map(String) : [],
@@ -39,18 +84,18 @@ export async function resolveContentNavigation(event, inputQuery = {}) {
       return cached;
     },
     loadLocaleNavigation: async (locale) => {
-      let contentsQuery = createServerContentQuery(event, sourceQuery).where("_partial", "=", false).where("_type", "=", "markdown").where("navigation", "!=", false);
+      let contentsQuery = createServerContentQuery(event, sourceQuery).where("partial", "=", false).where("type", "=", "markdown").where("navigation", "!=", false);
       if (locale) {
-        contentsQuery = contentsQuery.where("_locale", "=", locale);
+        contentsQuery = contentsQuery.where("locale", "=", locale);
       }
-      let dirConfigsQuery = createServerContentQuery(event).where("_navigation", "=", true).where("_partial", "=", true);
+      let dirConfigsQuery = createServerContentQuery(event).where("navigationFile", "=", true).where("partial", "=", true);
       if (locale) {
-        dirConfigsQuery = dirConfigsQuery.where("_locale", "=", locale);
+        dirConfigsQuery = dirConfigsQuery.where("locale", "=", locale);
       }
       const contents = await contentsQuery.all();
       const dirConfigs = await dirConfigsQuery.all();
       const configs = dirConfigs.reduce((accumulator, config) => {
-        accumulator[config._path || "/"] = {
+        accumulator[config.path || "/"] = {
           ...config,
           ...config.body
         };
@@ -60,7 +105,7 @@ export async function resolveContentNavigation(event, inputQuery = {}) {
       return buildCanonicalNavigation(contents, configs, [.../* @__PURE__ */ new Set([...configuredFields, ...requestedFields])]);
     },
     resolveLocaleChain,
-    localizeNavigation: async (items, locale, _fallback = [], collection, canonical) => {
+    localizeNavigation: async (items, locale, _unusedFallback = [], collection, canonical) => {
       const collectionI18n = collection ? runtimeConfig.content.collections?.[collection]?.i18n : void 0;
       const collectionLocales = collectionI18n && typeof collectionI18n === "object" ? collectionI18n.locales : void 0;
       const collectionDefault = collectionI18n && typeof collectionI18n === "object" ? collectionI18n.defaultLocale : void 0;

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

@@ -1,2 +1,2 @@
 import type { ParsedContentMeta } from '../../types/content';
-export declare function createNav(contents: ParsedContentMeta[], configs: Record<string, ParsedContentMeta>): import("../../types").NavItem[];
+export declare function createNav(contents: ParsedContentMeta[], configs: Record<string, ParsedContentMeta>): import("../../types/content").NavItem[];

package/dist/runtime/server/provider-document

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

package/dist/runtime/server/provider-document.d.ts

@@ -0,0 +1,59 @@
+import type { ContentFileMeta, ParsedContent } from '../../types/content';
+import type { ContentPageResult } from '../../types/query';
+import { type RouteMounts } from '../../features/localization/path';
+/**
+ * Minimal document a third-party provider must emit. Only `collection`,
+ * `locale`, `path` and `body` are strictly required — `id`, `canonicalKey` and
+ * `type` are derived when omitted, and `file` is optional (absent for providers
+ * with no backing file, e.g. CMS-backed documents). Any additional frontmatter
+ * fields are passed through untouched.
+ */
+export interface ProviderDocumentInput extends Record<string, unknown> {
+    /** Collection the document belongs to. */
+    collection: string;
+    /** Locale code for this concrete variant. */
+    locale: string;
+    /** Canonical (source-agnostic) route path this variant serves at. */
+    path: string;
+    /** Parsed body payload (`null` for documents with no renderable body). */
+    body: ParsedContent['body'];
+    /** Fully-qualified system id. Derived from `locale` + `path` when omitted. */
+    id?: string;
+    /**
+     * Opaque, locale-agnostic identity join key. Derived from `collection` +
+     * `path` when omitted. Never parse or render it as a URL.
+     */
+    canonicalKey?: string;
+    /** Document kind. Defaults to `'markdown'`. */
+    type?: ParsedContent['type'];
+    /** Optional file provenance. Absent for providers with no backing file. */
+    file?: ContentFileMeta;
+}
+/**
+ * Options describing the provider's locale/route configuration so core can
+ * derive the localized route envelope. For single-locale providers these can be
+ * omitted entirely.
+ */
+export interface ShapeProviderDocumentOptions {
+    /** Default locale of the site (defaults to the document's own locale). */
+    defaultLocale?: string;
+    /** All configured locales (defaults to the document's own locale). */
+    locales?: string[];
+    /** Route mount(s) for the collection, used to project localized paths. */
+    route?: string | Record<string, string>;
+    /** Pre-computed route mounts (takes precedence over `route`). */
+    routeMounts?: RouteMounts;
+}
+/**
+ * Normalize a provider's raw document into the canonical content envelope,
+ * filling in the derivable identity fields (`id`, `canonicalKey`, `type`) while
+ * leaving `file` absent unless the provider supplied it.
+ */
+export declare const normalizeProviderDocument: (input: ProviderDocumentInput) => ParsedContent;
+/**
+ * Normalize a provider's raw document and derive the full route envelope
+ * (`path`, `variants`, `localePaths`, `resolved`). The result is the canonical
+ * `ContentPageResult` route helpers return, so a provider can back its `page`,
+ * `routeMeta` and `query` methods from the minimal document set alone.
+ */
+export declare const shapeProviderDocument: <T = ParsedContent>(input: ProviderDocumentInput, options?: ShapeProviderDocumentOptions) => ContentPageResult<T>;

package/dist/runtime/server/provider-document.js

@@ -0,0 +1,48 @@
+import { normalizeRouteMounts } from "../../features/localization/path";
+import { localizePageResult } from "../../features/localization/results";
+const trimSlashes = (value) => value.replace(/^\/+|\/+$/g, "");
+const extensionForType = (type) => {
+  switch (type) {
+    case "yaml":
+      return "yml";
+    case "json":
+      return "json";
+    case "csv":
+      return "csv";
+    default:
+      return "md";
+  }
+};
+export const normalizeProviderDocument = (input) => {
+  const collection = input.collection;
+  const locale = input.locale;
+  const path = input.path;
+  const type = input.type ?? "markdown";
+  const canonicalKey = input.canonicalKey ?? `${collection}:${trimSlashes(path) || "index"}`;
+  const extension = input.file?.extension ?? extensionForType(type);
+  const id = input.id ?? `content:${locale}:${trimSlashes(path).replace(/\//g, ":") || "index"}.${extension}`;
+  return {
+    ...input,
+    id,
+    collection,
+    locale,
+    path,
+    canonicalKey,
+    type,
+    ...input.file ? { file: input.file } : {},
+    body: input.body
+  };
+};
+export const shapeProviderDocument = (input, options = {}) => {
+  const document = normalizeProviderDocument(input);
+  const defaultLocale = options.defaultLocale ?? input.locale;
+  const locales = options.locales ?? [input.locale];
+  const routeMounts = options.routeMounts ?? normalizeRouteMounts(options.route, locales, defaultLocale);
+  return localizePageResult(
+    document,
+    input.locale,
+    defaultLocale,
+    locales,
+    routeMounts
+  );
+};

package/dist/runtime/server/provider-query-wire

@@ -0,0 +1 @@
+export * from './provider-query-wire.js'

package/dist/runtime/server/provider-query-wire.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Builder-params → provider-wire lowering seam.
+ *
+ * These helpers translate the internal query IR (`ContentQueryBuilderParams`,
+ * see `../../types/query-parts/transport.ts`) into the closed, JSON-pure
+ * `ContentProviderQuery` wire envelope. They live in the runtime adapter layer
+ * — NOT in the `public/` facade — because the IR is internal plumbing: keeping
+ * its name out of `src/public/` is what makes the IR "not public" while the
+ * lowering functions themselves stay part of the exported surface (re-exported
+ * from `../../public/provider-query`).
+ */
+import type { ContentQueryBuilderParams } from '../../types/query';
+import type { ContentProviderNavigationOptions, ContentProviderQuery } from '../../public/provider-query';
+export declare const PROVIDER_QUERY_VERSION: 1;
+/**
+ * Lower builder params into the wire envelope. This is the single place the
+ * builder → plan translation happens before the provider boundary; providers
+ * receive only the closed, JSON-pure plan.
+ */
+export declare const toContentProviderQuery: (params: ContentQueryBuilderParams) => ContentProviderQuery;
+/**
+ * Split builder params into the navigation wire pair (CS-5): the query plan
+ * (collection + user filter/sort) plus the navigation-only options
+ * (`fields` = `only` ∪ `navigationFields`, `canonical`, and the raw
+ * `resolveLocale`). The nav-only keys are stripped before lowering so they do
+ * not leak into the plan. Pure — the single navigation builder-params → wire
+ * seam, usable by providers and their conformance suites.
+ */
+export declare const toContentProviderNavigationQuery: (params: ContentQueryBuilderParams) => {
+    query: ContentProviderQuery;
+    options: ContentProviderNavigationOptions;
+};

package/dist/runtime/server/provider-query-wire.js

@@ -0,0 +1,27 @@
+import { lowerQueryPlan } from "../../core/query/lower";
+export const PROVIDER_QUERY_VERSION = 1;
+export const toContentProviderQuery = (params) => ({
+  v: PROVIDER_QUERY_VERSION,
+  collection: params.collection ?? null,
+  plan: lowerQueryPlan(params)
+});
+export const toContentProviderNavigationQuery = (params) => {
+  const fields = [
+    ...Array.isArray(params.only) ? params.only.map(String) : [],
+    ...Array.isArray(params.navigationFields) ? params.navigationFields.map(String) : []
+  ];
+  const canonical = params.canonical === true;
+  const resolveLocale = params.resolveLocale;
+  const planParams = { ...params };
+  delete planParams.only;
+  delete planParams.navigationFields;
+  delete planParams.canonical;
+  return {
+    query: toContentProviderQuery(planParams),
+    options: {
+      ...fields.length ? { fields } : {},
+      ...canonical ? { canonical: true } : {},
+      ...resolveLocale ? { resolveLocale } : {}
+    }
+  };
+};

package/dist/runtime/server/provider-query.d.ts

@@ -1,8 +1,21 @@
 import type { H3Event } from 'h3';
-import type { ContentCollectionMap } from '@lupinum/ginko-content';
-import type { ParsedContent } from '../../types/content';
+import type { ContentDocumentResolution, ParsedContent } from '../../types/content';
 import type { ContentQueryResponse } from '../../types/api';
-import type { CollectionQueryBuilder, ContentQueryBuilderParams, ContentQueryRequest, ResolveContentReferenceOptions } from '../../types/query';
+import type { CollectionQueryBuilder, ContentCollectionMap, ContentQueryBuilderParams, ContentQueryRequest, ResolveContentReferenceOptions } from '../../types/query';
+import { type ContentProviderQuery } from '../../public/provider-query';
+export { toContentProviderNavigationQuery as createProviderNavigationQuery } from '../../public/provider-query';
+/**
+ * Build the provider wire query (CS-5) from builder params: reject
+ * globally-invalid operators and malformed `$options` up front (so callers see
+ * a clean typed error rather than a raw lowering `TypeError`), apply the shared
+ * content-query normalization (default sort, locale injection, `fallback: true`
+ * → chain expansion), then lower to a JSON-pure `ContentQueryPlan`.
+ *
+ * This is the single builder-params → plan seam before the provider boundary.
+ * Provider-specific policy (draft hiding, limit clamps, regex rejection) lives
+ * inside each provider, applied to the plan it receives.
+ */
+export declare const createProviderQuery: (params: ContentQueryBuilderParams) => ContentProviderQuery;
 export declare const normalizeProviderQueryResult: <T>(response: ContentQueryResponse<T>) => T[];
 export declare const normalizeProviderQueryResponse: <T>(params: ContentQueryBuilderParams, response: unknown, providerName?: string) => ContentQueryResponse<T>;
 export declare const resolveProviderContentVariants: (event: H3Event, identity: string, options: ResolveContentReferenceOptions) => Promise<{
@@ -18,13 +31,9 @@ export declare const resolveProviderContentVariants: (event: H3Event, identity:
     fallback: boolean;
 } | null>;
 export declare const createServerProviderQueryFetch: <T = ParsedContent>(event: H3Event) => (query: ContentQueryRequest) => Promise<ContentQueryResponse<T>>;
-export declare const createServerContentQuery: <T = ParsedContent>(event: H3Event, query?: string | ContentQueryBuilderParams, ...pathParts: string[]) => import("@lupinum/ginko-content").ContentQueryBuilder<T>;
+export declare const createServerContentQuery: <T = ParsedContent>(event: H3Event, query?: string | ContentQueryBuilderParams, ...pathParts: string[]) => import("../../types/query").ContentQueryBuilder<T>;
 export declare function serverQueryCollection<K extends keyof ContentCollectionMap & string>(event: H3Event, collection: K): CollectionQueryBuilder<ContentCollectionMap[K]>;
 export declare function serverQueryCollection<T = ParsedContent>(event: H3Event, collection: string): CollectionQueryBuilder<T>;
 export declare const resolveContentReference: <T = ParsedContent>(event: H3Event, reference: string, options?: ResolveContentReferenceOptions) => Promise<(T & {
-    _requestedLocale?: string;
-    _resolvedLocale?: string;
-    _fallback?: boolean;
-    _availableLocales?: string[];
-    _variantPaths?: Record<string, string>;
+    resolved?: ContentDocumentResolution;
 }) | null>;