@lupinum/ginko-content 0.1.5 → 0.2.0

package/dist/types/content.d.ts

@@ -12,22 +12,80 @@ export interface ContentSeoMeta {
     image?: string | ContentSeoImage;
 }
 /**
- * Internal metadata attached to every parsed content record.
+ * Optional file-provenance metadata. Absent for non-filesystem providers
+ * (e.g. CMS-backed documents) that have no backing file.
  */
-export interface ParsedContentInternalMeta {
+export interface ContentFileMeta {
     /**
-     * Stable unique id for the parsed source record.
+     * Backing source name when multiple content sources are configured.
      */
-    _id: string;
+    source?: string;
     /**
-     * Backing source name when multiple content sources are configured.
+     * Source file path relative to the content root.
+     */
+    path?: string;
+    /**
+     * Path stem (the source path without its extension).
      */
-    _source?: string;
+    stem?: string;
+    /**
+     * Parent directory segment of the source file.
+     */
+    dir?: string;
+    /**
+     * Source file basename without extension.
+     */
+    basename?: string;
+    /**
+     * Source file extension.
+     */
+    extension?: 'md' | 'yaml' | 'yml' | 'json' | 'json5' | 'csv';
+}
+/**
+ * Per-request locale/reference resolution carrier.
+ *
+ * Folded from the legacy underscore resolution meta into one object. It is the
+ * pre-shaping form of the modern `resolved`/`localePaths`/`variants` envelope:
+ * the query pipeline attaches it, and result shaping reads it to build
+ * `ContentRouteMeta`. Field names mirror `ContentResolvedMeta` so a consumer
+ * can read `resolved.locale`/`resolved.requestedRoute`/… off either a raw
+ * document or a fully shaped result.
+ */
+export interface ContentDocumentResolution {
+    /** Resolved locale after locale fallback. */
+    locale?: string;
+    /** Requested locale before locale fallback. */
+    requestedLocale?: 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>;
+    /** Requested route path before locale fallback. */
+    requestedPath?: string;
+    /** Requested public route before locale fallback. */
+    requestedRoute?: string;
+    /** Requested authored reference before locale fallback. */
+    requestedRef?: string;
+    /** Resolved markdown `$ref` links for the current runtime locale. */
+    resolvedRefs?: Record<string, string>;
+}
+/**
+ * Internal metadata attached to every parsed content record.
+ */
+export interface ParsedContentInternalMeta {
+    /**
+     * Stable, fully-qualified, locale-suffixed system id for the parsed record.
+     * System-computed and reserved: user frontmatter `id` does not override it —
+     * use `ref` for a stable authored alias.
+     */
+    id: 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;
+    path?: string;
     /**
      * Human-readable title resolved from frontmatter or generated metadata.
      */
@@ -47,75 +105,46 @@ export interface ParsedContentInternalMeta {
     /**
      * Marks the document as a draft.
      */
-    _draft?: boolean;
+    draft?: boolean;
     /**
      * Marks the document as a partial that should not become a page by default.
      */
-    _partial?: boolean;
+    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;
+    locale?: string;
     /**
-     * Requested locale before locale fallback.
+     * Opaque, locale-agnostic content identity join key used to resolve variants.
+     * Never parse or render this as a URL — under translated slugs it is a numeric
+     * identity (e.g. `1/1`), not a path.
      */
-    _requestedLocale?: string;
+    canonicalKey?: string;
     /**
-     * Resolved locale after locale fallback.
+     * Per-request locale/reference resolution carrier (folded from the legacy
+     * underscore resolution meta). Absent until the query pipeline resolves a
+     * variant; shaping reads it to build the `resolved`/`localePaths`/`variants`
+     * route envelope.
      */
-    _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>;
+    resolved?: ContentDocumentResolution;
     /**
      * Collection name, when matched by a configured collection glob.
      */
-    _collection?: string;
+    collection?: string;
     /**
-     * Marks folder-scoped navigation metadata documents.
+     * Internal marker: this parsed record is a folder-scoped `.navigation.yml`
+     * configuration document, not a routable page. Providers may expose it so
+     * generic filtering can consistently exclude navigation config records.
      */
-    _navigation?: boolean;
+    navigationFile?: boolean;
     /**
      * Parsed document kind.
      */
-    _type?: 'markdown' | 'yaml' | 'json' | 'csv';
+    type?: 'markdown' | 'yaml' | 'json' | 'csv';
     /**
-     * Source file path relative to the content root.
+     * File-provenance metadata. Optional: absent for providers with no backing file.
      */
-    _file?: string;
-    /**
-     * Source file extension.
-     */
-    _extension?: 'md' | 'yaml' | 'yml' | 'json' | 'json5' | 'csv';
+    file?: ContentFileMeta;
 }
 /**
  * One entry in a generated table of contents.
@@ -194,6 +223,19 @@ export interface ParsedContentMeta extends ParsedContentInternalMeta {
     layout?: LayoutKey;
     [key: string]: unknown;
 }
+/**
+ * Sentinel returned by content loaders for a source id that produced no
+ * servable document — an ignored file, a missing source body, or an
+ * unsupported extension. It carries only the id and a `null` body; the
+ * `missing` flag is the discriminant separating it from a real
+ * {@link ParsedContent}. Use the shared `isRealDocument` guard
+ * (`core/content/document`) to filter these out.
+ */
+export interface MissingDocument {
+    id: string;
+    body: null;
+    missing: true;
+}
 /**
  * Strict parsed content shape with no open-ended index signature.
  */
@@ -233,11 +275,7 @@ export interface StrictParsedContent extends StrictParsedContentMeta {
  * Specialized parsed content shape for markdown sources.
  */
 export interface MarkdownParsedContent extends ParsedContent {
-    _type: 'markdown';
-    /**
-     * Whether the markdown source rendered no meaningful body content.
-     */
-    _empty: boolean;
+    type: 'markdown';
     /**
      * Description resolved from frontmatter or excerpt generation.
      */
@@ -290,17 +328,13 @@ export interface NavItem {
      * 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;
+    id?: string;
+    canonicalKey?: string;
+    locale?: string;
+    fallback?: boolean;
+    draft?: boolean;
     children?: NavItem[];
     [key: string]: unknown;
 }

package/dist/types/fields.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { CONTENT_REFERENCE_PREFIX } from "./reference.js";
-export const CONTENT_FIELD_METADATA_KEY = Symbol.for("lupinum.ginko-content.field-metadata");
+export const CONTENT_FIELD_METADATA_KEY = /* @__PURE__ */ Symbol.for("lupinum.ginko-content.field-metadata");
 function readFieldMetadata(schema) {
   const value = schema?.[CONTENT_FIELD_METADATA_KEY];
   return value ? { ...value } : null;

package/dist/types/module.d.ts

@@ -218,7 +218,7 @@ export interface ContentSearchOptions {
     /**
      * Query predicate applied before records are indexed.
      *
-     * @default { _draft: false, _partial: false }
+     * @default { draft: false, partial: false }
      */
     filterQuery?: ContentQueryBuilderWhere;
     /**

package/dist/types/query-parts/public.d.ts

@@ -76,6 +76,15 @@ type LocaleOption<H, OptKey extends string = 'locale'> = HandleIsI18n<H> extends
 } : {
     [K in OptKey]?: string;
 };
+/**
+ * Argument tuple for verbs whose options parameter is defaulted (`many`, `tree`).
+ *
+ * For i18n handles the options object is REQUIRED (its type already requires
+ * `locale` via `LocaleOption`) — a defaulted `options = {}` parameter would
+ * otherwise silently satisfy the locale obligation and reopen the i18n hole.
+ * For non-i18n handles the options object stays optional. (CS-7, T5.5.)
+ */
+export type OptionsArg<H, O> = HandleIsI18n<H> extends true ? [options: O] : [options?: O];
 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;
@@ -88,7 +97,8 @@ export type LocaleFallback = false | true | 'default' | string | string[];
 export type LocalizedContentDocument<T = ParsedContentMeta> = T & ContentRouteMeta & {
     locale: string;
     path: string;
-    canonicalPath: string;
+    /** the resolved variant's route path before locale prefixing */
+    unprefixedPath: string;
     localePaths: Record<string, LocalePathEntry>;
     stem?: string;
     extension?: string;
@@ -108,7 +118,8 @@ export interface ResolutionEnvelope {
         found: boolean;
         collection: string;
         path?: string;
-        canonicalPath?: string;
+        /** the resolved variant's route path before locale prefixing */
+        unprefixedPath?: string;
         ref?: string;
         locale?: string;
     };
@@ -182,12 +193,10 @@ export type TreeOptions<H = unknown, Fields extends ReadonlyArray<keyof HandleSc
     sort?: SortSpec<HandleSchema<H>>;
     fields?: Fields;
     fallback?: LocaleFallback;
-    locale?: string;
-};
+} & LocaleOption<H>;
 export 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>);
 export type { ContentNavigationItem };

package/dist/types/query-parts/results.d.ts

@@ -40,7 +40,8 @@ export interface ContentLocaleEntry {
 export interface ContentLocaleRoute {
     locale: string;
     path: string;
-    canonicalPath: string;
+    /** the resolved variant's route path before locale prefixing */
+    unprefixedPath: string;
 }
 export interface LocalePathEntry {
     path: string;
@@ -57,12 +58,15 @@ export interface ContentResolvedMeta {
     requestedRoute?: string;
     requestedRef?: string;
     availableLocales: string[];
+    /** Resolved markdown `$ref` links for the current runtime locale. */
+    resolvedRefs?: Record<string, string>;
 }
 export interface ContentRouteMeta {
     locale: string;
     defaultLocale: string;
     path: string;
-    canonicalPath: string;
+    /** the resolved variant's route path before locale prefixing */
+    unprefixedPath: string;
     variants: ContentLocaleRoute[];
     localePaths: Record<string, LocalePathEntry>;
     resolved: ContentResolvedMeta;

package/dist/types/query-parts/transport.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Internal query IR — NOT public, NOT the provider wire contract.
+ *
+ * `ContentQueryBuilderParams` / `ContentQueryBuilderWhere` and the fluent
+ * `ContentQueryBuilder` are the intermediate representation the unified query
+ * grammar (`src/types/query-parts/public.ts`, the public API) lowers through on
+ * its way to the `ContentQueryPlan` AST (`src/core/query/plan.ts`). They are a
+ * compiler IR: fine as internal plumbing, but not part of any boundary.
+ *
+ * - The public query vocabulary is the unified API (`one`/`many`/`paginate`/…
+ *   with `QueryWhere`/`QueryOperators`).
+ * - The provider wire contract is `ContentProviderQuery`
+ *   (`src/public/provider-query.ts`).
+ *
+ * Nothing in this file is exported from `#content/server` or `#content/client`.
+ * Do not re-add these to `meta/public-surface.json`. A future full fluent+IR
+ * cutover (retiring the string-operator API and this IR) is deferred post-0.2.0
+ * — see `future-decisions.md`.
+ */
 import type { ContentQueryResponse } from '../api';
 import type { ParsedContentInternalMeta, ParsedContentMeta } from '../content';
 export interface ContentQuerySortParams {

package/dist/types/virtual.d.ts

@@ -12,6 +12,12 @@ declare module '#content/virtual/providers' {
   export const loadExternalContentProvider: (name: string) => Promise<ContentProvider | undefined> | ContentProvider | undefined
 }
 
+declare module '#content/virtual/transformers' {
+  import type { ContentTransformer } from './content'
+
+  export const transformers: ContentTransformer[]
+}
+
 declare module '#content/virtual/cache-adapter' {
   import type { ContentCacheAdapter } from '../public/provider'
 

package/dist/types.d.mts

@@ -6,6 +6,6 @@ declare module '@nuxt/schema' {
 
 export { type agentMetadataFields, type defineAgentAppPage, type defineAgentMarkdownPolicy, type defineAgentMetadataFields, type defineAgentSection, type defineCollection, type defineContentConfig, type reference } from '../dist/types/config'
 
-export { default, type normalizeContentConfigCollectionNames } from './module.mjs'
+export { default } from './module.mjs'
 
-export { type AgentMetadataField, type AgentMetadataFieldList, type BacklinkFields, type BacklinkSource, type BacklinksOptions, type BacklinksResult, type CollectionQueryBuilder, type CollectionQueryField, type CollectionQueryFieldValue, type CollectionQueryKey, type CollectionQueryOperator, type CollectionQueryValue, type CollectionSchema, type ContentAgentAppPageConfig, type ContentAgentAppPageContext, type ContentAgentCollectionConfig, type ContentAgentConfig, type ContentAgentLocalizedValue, type ContentAgentMarkdownMetadataConfig, type ContentAgentMarkdownOptions, type ContentAgentMarkdownPolicyConfig, type ContentAgentRouteOptions, type ContentAgentSectionConfig, type ContentAgentSiteConfig, type ContentCacheArtifact, type ContentCmsCollectionConfig, type ContentCmsFieldConfig, type ContentCmsFieldType, type ContentCmsRelationConfig, type ContentCollectionConfig, type ContentCollectionHandle, type ContentCollectionI18nConfig, type ContentCollectionI18nMap, type ContentCollectionItem, type ContentCollectionItemSurroundingsOptions, type ContentCollectionKind, type ContentCollectionMap, type ContentCollectionName, type ContentCollectionNavigationOptions, type ContentCollectionPageOptions, type ContentCollectionRouteConfig, type ContentCollectionRouteMetaOptions, type ContentCollectionSearchSectionsOptions, type ContentCollectionSource, type ContentCollectionSourceObject, type ContentCollectionStringName, type ContentCollectionTarget, type ContentConfig, type ContentContext, type ContentI18nOptions, type ContentLinkRouteTarget, type ContentLinksOptions, type ContentLocaleEntry, type ContentLocaleRoute, type ContentManifest, type ContentMiniSearchOptions, type ContentNavigationItem, type ContentPageResult, type ContentPreviewOptions, type ContentProviderName, type ContentProviderSearchRequest, type ContentQueryBuilder, type ContentQueryBuilderParams, type ContentQueryBuilderWhere, type ContentQueryFetcher, type ContentQueryRequest, type ContentQuerySortFields, type ContentQuerySortOptions, type ContentQuerySortParams, type ContentReferenceSchema, type ContentResolvedMeta, type ContentRevalidateOptions, type ContentRouteMeta, type ContentSearchEngine, type ContentSearchIndexRecord, type ContentSearchOptions, type ContentSearchPublicRuntimeConfig, type ContentSearchResult, type ContentSearchSection, type ContentSelector, type ContentSeoImage, type ContentSeoMeta, type ContentSitemapAlternative, type ContentSitemapAssertOptions, type ContentSitemapAssertSitemapOptions, type ContentSitemapEntry, type ContentSitemapImage, type ContentSitemapOptions, type ContentTransformer, type ContentTreeItem, type ContentVariant, type DefineCollectionObject, type DefineCollectionOptions, type DocumentFromHandle, type LocaleFallback, type LocalePathEntry, type LocalizedContentDocument, type LocalizedDoc, type ManifestVariant, type ManyOptions, type MarkdownNode, type MarkdownOptions, type MarkdownParsedContent, type MarkdownPluginDescriptor, type MarkdownPluginOptions, type MarkdownRoot, type ModuleHooks, type ModuleOptions, type MountOptions, type NavItem, type NeighborsOptions, type NeighborsResult, type OneOptions, type PaginationOptions, type PaginationResult, type ParseContentOptions, type ParsedContent, type ParsedContentInternalMeta, type ParsedContentMeta, type PopulateFromOptions, type PopulateSpec, type PopulatedDocument, type QueryGroupBuilder, type QueryGroupFunction, type QueryMatchOperator, type QueryOperators, type QueryOrderDirection, type QueryOrderOptions, type QueryWhere, type ResolutionEnvelope, type ResolveContentReferenceOptions, type ResolveOneOptions, type ResolveOneResult, type ResolvedContentContext, type ResolvedContentI18nOptions, type ResolvedMarkdownPlugin, type ResolvedVariant, type SortDirection, type SortSpec, type StrictParsedContent, type StrictParsedContentMeta, type Toc, type TocLink, type TransformContentOptions, type TransformContentSource, type TreeOptions, type VariantsOptions } from './module.mjs'
+export { type ContentCollectionHandle, type ContentCollectionI18nMap, type ContentCollectionMap, type ContentNavigationItem, type ModuleHooks, type ModuleOptions, type NavItem, type ParsedContent, type StrictParsedContent, type Toc, type TocLink } from './module.mjs'

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "framework": "vue",
   "name": "@lupinum/ginko-content",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "contributions": {
     "html": {
       "description-markup": "markdown",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-content",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Collection-first content engine for Nuxt",
   "homepage": "https://ginko-content.nuxt.dev",
   "bugs": {
@@ -21,6 +21,9 @@
   },
   "license": "MIT",
   "type": "module",
+  "main": "./dist/module.mjs",
+  "module": "./dist/module.mjs",
+  "types": "./dist/module.d.mts",
   "bin": {
     "ginko-content": "./dist/cli.mjs"
   },
@@ -40,15 +43,20 @@
       "import": "./dist/public/server.js",
       "default": "./dist/public/server.js"
     },
+    "./provider": {
+      "types": "./dist/public/provider.d.ts",
+      "import": "./dist/public/provider.js",
+      "default": "./dist/public/provider.js"
+    },
     "./client": {
       "types": "./dist/public/client.d.ts",
       "import": "./dist/public/client.js",
       "default": "./dist/public/client.js"
     },
-    "./toc": {
-      "types": "./dist/runtime/app/composables/toc.d.ts",
-      "import": "./dist/runtime/app/composables/toc.js",
-      "default": "./dist/runtime/app/composables/toc.js"
+    "./agent": {
+      "types": "./dist/public/agent.d.ts",
+      "import": "./dist/public/agent.js",
+      "default": "./dist/public/agent.js"
     },
     "./cms-contract": {
       "types": "./dist/cms-contract/index.d.ts",
@@ -75,7 +83,26 @@
       "import": "./dist/runtime/transformers/define.js",
       "default": "./dist/runtime/transformers/define.js"
     },
-    "./transformers/*": "./dist/runtime/transformers/*.js"
+    "./transformers/markdown": {
+      "types": "./dist/runtime/transformers/markdown.d.ts",
+      "import": "./dist/runtime/transformers/markdown.js",
+      "default": "./dist/runtime/transformers/markdown.js"
+    },
+    "./transformers/yaml": {
+      "types": "./dist/runtime/transformers/yaml.d.ts",
+      "import": "./dist/runtime/transformers/yaml.js",
+      "default": "./dist/runtime/transformers/yaml.js"
+    },
+    "./transformers/json": {
+      "types": "./dist/runtime/transformers/json.d.ts",
+      "import": "./dist/runtime/transformers/json.js",
+      "default": "./dist/runtime/transformers/json.js"
+    },
+    "./transformers/csv": {
+      "types": "./dist/runtime/transformers/csv/index.d.ts",
+      "import": "./dist/runtime/transformers/csv/index.js",
+      "default": "./dist/runtime/transformers/csv/index.js"
+    }
   },
   "web-types": "./dist/web-types.json",
   "files": [
@@ -95,13 +122,12 @@
     "globby": "^16.2.0",
     "h3": "1.15.11",
     "jiti": "^2.7.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.2.0",
     "json5": "^2.2.3",
     "knitwork": "^1.3.0",
     "minisearch": "^7.2.0",
     "nitropack": "^2.13.4",
     "ohash": "^2.0.11",
-    "pagefind": "^1.5.2",
     "pathe": "^2.0.3",
     "picomatch": "^4.0.4",
     "scule": "^1.3.0",
@@ -109,7 +135,7 @@
     "slugify": "^1.6.9",
     "ufo": "^1.6.4",
     "unstorage": "^1.17.5",
-    "ws": "^8.20.1",
+    "ws": "^8.21.0",
     "zod": "4.4.3"
   },
   "devDependencies": {
@@ -120,10 +146,14 @@
   },
   "peerDependencies": {
     "nuxt": ">=4.4.7",
+    "pagefind": "^1.5.2",
     "vitest": ">=4.1.6",
     "vue": "^3.5.0"
   },
   "peerDependenciesMeta": {
+    "pagefind": {
+      "optional": true
+    },
     "vitest": {
       "optional": true
     }

package/dist/runtime/app/plugins/markdown-components

@@ -1 +0,0 @@
-export * from './markdown-components.js'

package/dist/runtime/app/plugins/markdown-components.d.ts

@@ -1,2 +0,0 @@
-declare const _default: any;
-export default _default;

package/dist/runtime/app/plugins/markdown-components.js

@@ -1,19 +0,0 @@
-import { defineNuxtPlugin, useRuntimeConfig } from "#imports";
-export default defineNuxtPlugin(async (nuxtApp) => {
-  const plugins = useRuntimeConfig().public.content?.markdown?.plugins || [];
-  const names = new Set(plugins.map((plugin) => plugin.name));
-  if (names.has("math")) {
-    const { Math } = await import(
-      /* @vite-ignore */
-      ["@comark/vue", "plugins/math"].join("/")
-    );
-    nuxtApp.vueApp.component("Math", Math);
-  }
-  if (names.has("mermaid")) {
-    const { Mermaid } = await import(
-      /* @vite-ignore */
-      ["@comark/vue", "plugins/mermaid"].join("/")
-    );
-    nuxtApp.vueApp.component("Mermaid", Mermaid);
-  }
-});