@lupinum/ginko-content 0.1.2 → 0.1.4

package/dist/parsers/csv.js

@@ -23,12 +23,13 @@ export default defineTransformer({
   name: "csv",
   extensions: [".csv"],
   parse: async (_id, content, options = {}) => {
-    const tree = fromCSV(content, {
+    const csvOptions = typeof options === "object" && options !== null ? options : {};
+    const tree = fromCSV(String(content ?? ""), {
       delimiter: ",",
       json: true,
-      ...options
+      ...csvOptions
     });
-    const result = options.json === false ? toJsonArray(tree) : toJsonObject(tree);
+    const result = csvOptions.json === false ? toJsonArray(tree) : toJsonObject(tree);
     return {
       _id,
       _type: "csv",

package/dist/parsers/index.d.ts

@@ -1,10 +1,7 @@
 import type { StorageValue } from 'unstorage';
-import type { TransformContentOptions } from '../types/content';
+import type { ParsedContent, TransformContentOptions } from '../types/content';
 /**
  * Parse content file using registered plugins
  */
-export declare function transformContent(id: string, content: StorageValue, options?: TransformContentOptions): Promise<{
-    _id: string;
-    body: StorageValue;
-}>;
+export declare function transformContent(id: string, content: StorageValue, options?: TransformContentOptions): Promise<ParsedContent>;
 export { defineTransformer } from './utils';

package/dist/parsers/index.js

@@ -31,8 +31,8 @@ export async function transformContent(id, content, options = {}) {
   const ext = extname(id);
   const parser = getParser(ext, transformers);
   if (!parser) {
-    console.warn(`${ext} files are not supported, "${id}" falling back to raw content`);
-    return file;
+    console.warn(`${ext} files are not supported, "${id}" storing body as null`);
+    return { _id: file._id, body: null };
   }
   const parserOptions = options[camelCase(parser.name)] || {};
   const parsed = await parser.parse(file._id, file.body, parserOptions);

package/dist/parsers/markdown-plugins.d.ts

@@ -1,3 +1,4 @@
 import type { ComarkPlugin } from 'comark';
 import type { ResolvedMarkdownPlugin } from '../types/content';
+export declare const normalizeMarkdownPluginOptions: (plugin: ResolvedMarkdownPlugin) => import("../types/content").MarkdownPluginOptions;
 export declare function resolveMarkdownPlugins(plugins: ResolvedMarkdownPlugin[]): Promise<ComarkPlugin[]>;

package/dist/parsers/markdown-plugins.js

@@ -1,6 +1,85 @@
 import highlightPlugin from "comark/plugins/highlight";
 import summaryPlugin from "comark/plugins/summary";
 import tocPlugin from "comark/plugins/toc";
+import footnotesPlugin from "comark/plugins/footnotes";
+import materialThemeLighter from "shiki/dist/themes/material-theme-lighter.mjs";
+import materialThemePalenight from "shiki/dist/themes/material-theme-palenight.mjs";
+const shikiTransformerFactories = {
+  "@shikijs/transformers:notation-diff": "transformerNotationDiff",
+  "@shikijs/transformers:notation-highlight": "transformerNotationHighlight"
+};
+const cloneMarkdownPluginOptionValue = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => cloneMarkdownPluginOptionValue(item));
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return value;
+  }
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    cloneMarkdownPluginOptionValue(item)
+  ]));
+};
+const defaultHighlightThemes = () => ({
+  light: cloneMarkdownPluginOptionValue(materialThemeLighter),
+  dark: cloneMarkdownPluginOptionValue(materialThemePalenight)
+});
+const restoreSerializedShikiTransformers = async (transformers) => {
+  if (!Array.isArray(transformers)) {
+    return transformers;
+  }
+  let shikiTransformersModule;
+  return await Promise.all(transformers.map(async (transformer) => {
+    if (typeof transformer !== "object" || transformer === null || typeof transformer.code === "function") {
+      return transformer;
+    }
+    const factoryName = shikiTransformerFactories[transformer.name || ""];
+    if (!factoryName) {
+      return transformer;
+    }
+    shikiTransformersModule ||= await import("@shikijs/transformers");
+    const factory = shikiTransformersModule[factoryName];
+    if (typeof factory !== "function") {
+      throw new TypeError(`[ginko-content] Failed to restore serialized Shiki transformer "${transformer.name}". Install @shikijs/transformers in the app or remove the transformer from content.markdown.plugins.`);
+    }
+    return factory();
+  }));
+};
+export const normalizeMarkdownPluginOptions = (plugin) => {
+  if (plugin.name !== "highlight") {
+    return plugin.options;
+  }
+  const options = plugin.options || {};
+  const normalizedOptions = cloneMarkdownPluginOptionValue(options);
+  const themes = options.themes;
+  if (typeof themes !== "object" || themes === null) {
+    return {
+      ...normalizedOptions,
+      registerDefaultThemes: false,
+      themes: defaultHighlightThemes()
+    };
+  }
+  return {
+    ...normalizedOptions,
+    registerDefaultThemes: false,
+    themes: cloneMarkdownPluginOptionValue(themes)
+  };
+};
+const resolveMarkdownPluginOptions = async (plugin) => {
+  const normalized = normalizeMarkdownPluginOptions(plugin);
+  if (plugin.name !== "highlight" || typeof normalized !== "object" || normalized === null) {
+    return normalized;
+  }
+  const options = normalized;
+  return {
+    ...options,
+    transformers: await restoreSerializedShikiTransformers(options.transformers)
+  };
+};
 const builtinMarkdownPlugins = {
   breaks: {
     load: () => loadModule("comark/plugins/breaks")
@@ -8,6 +87,9 @@ const builtinMarkdownPlugins = {
   emoji: {
     load: () => loadModule("comark/plugins/emoji")
   },
+  footnotes: {
+    load: async () => footnotesPlugin
+  },
   highlight: {
     load: async () => highlightPlugin
   },
@@ -36,7 +118,7 @@ const builtinMarkdownPlugins = {
 export async function resolveMarkdownPlugins(plugins) {
   return await Promise.all(plugins.map(async (plugin) => {
     const factory = await loadMarkdownPluginFactory(plugin.name);
-    return factory(plugin.options);
+    return factory(await resolveMarkdownPluginOptions(plugin));
   }));
 }
 async function loadMarkdownPluginFactory(name) {

package/dist/parsers/markdown.js

@@ -8,7 +8,7 @@ export default defineTransformer({
   name: "markdown",
   extensions: [".md"],
   parse: async (_id, content, options = {}) => {
-    const config = { ...options };
+    const config = { ...typeof options === "object" && options !== null ? options : {} };
     const plugins = await resolveMarkdownPlugins(config.plugins || []);
     const tree = await parse(content, {
       plugins

package/dist/public/client.d.ts

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

package/dist/public/client.js

@@ -9,6 +9,7 @@ export {
   neighbors
 } from "../runtime/app/composables/query-api.js";
 export { getCollectionPath } from "../runtime/query/routes.js";
+export { agentMarkdownPathForRoute, agentRawPathForRoute, normalizeAgentRoutePath } from "../runtime/agent-paths.js";
 export { useContentHead } from "../runtime/app/composables/head.js";
 export {
   useContentPage,
@@ -20,8 +21,7 @@ export {
   useContentVariants,
   useContentTree,
   useContentNavigation,
-  useContentNeighbors,
-  useContentLocaleSwitch
+  useContentNeighbors
 } from "../runtime/app/composables/use-content.js";
 export { useContentSearch, useContentSearchData, useContentSearchResults } from "../runtime/app/composables/search.js";
 export { querySiteData } from "../runtime/app/composables/site-data.js";

package/dist/public/provider-errors.d.ts

@@ -1,4 +1,5 @@
-export type ContentProviderErrorCode = 'unknown_provider' | 'unknown_collection' | 'unsupported_provider_operation' | 'unsupported_query_operator' | 'unsupported_query_shape' | 'data_collection_route_access' | 'data_collection_search_access' | 'data_collection_sitemap_access' | 'missing_locale_route' | 'provider_config_missing' | 'provider_module_missing' | 'provider_module_invalid' | 'unsupported_provider_search_index' | 'unsupported_provider_search' | 'unsupported_provider_site_data' | 'unsupported_provider_prerender';
+import { type ContentProviderErrorCode } from '../core/provider-errors';
+export type { ContentProviderErrorCode } from '../core/provider-errors';
 export declare const createContentProviderError: (code: ContentProviderErrorCode, message: string, details?: Record<string, unknown>) => import("h3").H3Error<{
     code: ContentProviderErrorCode;
 }>;

package/dist/public/provider-errors.js

@@ -1,22 +1,5 @@
 import { createError } from "h3";
-const statusForProviderError = {
-  unknown_provider: 400,
-  unknown_collection: 400,
-  unsupported_provider_operation: 400,
-  unsupported_query_operator: 400,
-  unsupported_query_shape: 400,
-  data_collection_route_access: 400,
-  data_collection_search_access: 400,
-  data_collection_sitemap_access: 400,
-  missing_locale_route: 404,
-  provider_config_missing: 500,
-  provider_module_missing: 500,
-  provider_module_invalid: 500,
-  unsupported_provider_search_index: 400,
-  unsupported_provider_search: 400,
-  unsupported_provider_site_data: 400,
-  unsupported_provider_prerender: 400
-};
+import { statusForProviderError } from "../core/provider-errors";
 export const createContentProviderError = (code, message, details = {}) => createError({
   statusCode: statusForProviderError[code],
   statusMessage: code,

package/dist/public/provider.d.ts

@@ -5,15 +5,8 @@ import type { ContentProviderName } from '../types/config';
 import type { ContentCollectionItemSurroundingsOptions, ContentCollectionNavigationOptions, ContentCollectionPageOptions, ContentCollectionRouteMetaOptions, ContentCollectionSearchSectionsOptions, ContentPageResult, ContentQueryBuilderParams, ContentRouteMeta, ContentSearchSection, ContentSitemapEntry } from '../types/query';
 import type { QueryCollectionsSitemapEntriesOptions } from '../features/sitemap/query';
 import type { ContentProviderSearchRequest, ContentSearchResult } from '../types/search';
-export interface ContentCacheHint {
-    tags?: string[];
-    paths?: string[];
-    maxAge?: number;
-    swr?: number;
-    etag?: string;
-    lastModified?: Date;
-}
-export type ContentCacheHintInput = ContentCacheHint | false;
+import type { ContentCacheHint, ContentCacheHintInput } from '../core/cache-hints';
+export type { ContentCacheHint, ContentCacheHintInput } from '../core/cache-hints';
 export declare const contentProviderResultMarker = "__ginkoContentProviderResult";
 export interface ContentProviderResult<T = unknown> {
     readonly [contentProviderResultMarker]: true;
@@ -60,7 +53,7 @@ export interface ContentProviderCapabilities {
 export interface ContentProvider {
     name: ContentProviderName;
     capabilities: ContentProviderCapabilities;
-    query: <T = ParsedContent>(event: H3Event, query: ContentQueryBuilderParams) => Promise<MaybeContentProviderResult<ContentQueryResponse<T> | T[] | T | number | undefined>>;
+    query: <T = ParsedContent>(event: H3Event, query: ContentQueryBuilderParams) => Promise<MaybeContentProviderResult<ContentQueryResponse<T>>>;
     navigationQuery?: (event: H3Event, query: ContentQueryBuilderParams) => Promise<MaybeContentProviderResult<NavItem[]>>;
     navigation?: (event: H3Event, collection: string, options?: string[] | ContentCollectionNavigationOptions) => Promise<MaybeContentProviderResult<NavItem[]>>;
     surroundings?: (event: H3Event, collection: string, path: string, options?: ContentCollectionItemSurroundingsOptions) => Promise<MaybeContentProviderResult<Array<NavItem | null>>>;

package/dist/public/server.d.ts

@@ -8,7 +8,12 @@
 export { one, many, paginate, backlinks, resolveOne, variants, tree, neighbors, createServerContentQueryContext } from '../runtime/server/query-api.js';
 export { getCollectionPath } from '../runtime/query/routes.js';
 export type { CollectionPathOptions } from '../runtime/query/routes.js';
-export type { QueryWhere, QueryOperators, ContentSelector, ContentPageResult, ContentQueryBuilderParams, ContentRouteMeta, ContentSearchSection, ContentResolvedMeta, ContentSitemapEntry, BacklinkFields, BacklinkSource, BacklinksOptions, BacklinksResult, LocaleFallback, DocumentFromHandle, OneOptions, ManyOptions, PaginationOptions, PaginationResult, PopulateSpec, PopulatedDocument, ResolveOneOptions, ResolveOneResult, LocalizedDoc, LocalePathEntry, NeighborsOptions, NeighborsResult, SortSpec, TreeOptions, VariantsOptions, ContentVariant } from '../types/query.js';
+export { agentMarkdownPathForRoute, agentRawPathForRoute, normalizeAgentRoutePath } from '../runtime/agent-paths.js';
+export { clearAgentMarkdownSerializers, blockquoteMarkdown, defineAgentMarkdownComponent, getMarkdownProp, jsonFenceMarkdown, linkMarkdown, queryMarkdownEnabledContent, registerAgentMarkdownComponent, registerAgentMarkdownComponents, registerAgentMarkdownSerializer, registerAgentMarkdownSerializers, renderMarkdownChildren, resolveAgentMarkdownOptions, resolveContentMarkdown, resolveContentMarkdownByRoute, xmlComponentMarkdown } from '../runtime/server/agent-markdown.js';
+export { buildAgentPageIndex, collectAgentMarkdownPrerenderRoutes, getAgentLocales, isSupportedAgentLocale, localeFromAgentPath, renderAgentMarkdownFrontmatter, renderAgentMarkdownPage, renderLlmsFullTxt, renderLlmsTxt, resolveMarkdownForPublicRoute, routePathFromIndexSlug, routePathFromRawSlug } from '../runtime/server/agent-site.js';
+export type { AgentMarkdown, AgentMarkdownComponent, AgentMarkdownComponentMap, AgentMarkdownContext, AgentMarkdownMeta, AgentMarkdownPublicSignals, AgentMarkdownSerializer, AgentMarkdownSerializerMap, ResolvedAgentMarkdownOptions } from '../runtime/server/agent-markdown.js';
+export type { AgentPage, AgentPageSource } from '../runtime/server/agent-site.js';
+export type { QueryWhere, QueryOperators, ContentSelector, ContentPageResult, ContentQueryBuilderParams, ContentRouteMeta, ContentSearchSection, ContentResolvedMeta, ContentSitemapEntry, BacklinkFields, BacklinkSource, BacklinksOptions, BacklinksResult, LocaleFallback, DocumentFromHandle, OneOptions, ManyOptions, PaginationOptions, PaginationResult, PopulateSpec, PopulatedDocument, ResolveOneOptions, ResolveOneResult, LocalizedDoc, LocalizedContentDocument, LocalePathEntry, NeighborsOptions, NeighborsResult, SortSpec, TreeOptions, VariantsOptions, ContentVariant } from '../types/query.js';
 export type { ContentQueryResponse } from '../types/api.js';
 export declare const queryCollectionsSitemapEntries: typeof import('../runtime/server/sitemap-provider.js').queryCollectionsSitemapEntries;
 export { createContentProviderError } from './provider-errors.js';

package/dist/public/server.js

@@ -10,6 +10,39 @@ export {
   createServerContentQueryContext
 } from "../runtime/server/query-api.js";
 export { getCollectionPath } from "../runtime/query/routes.js";
+export { agentMarkdownPathForRoute, agentRawPathForRoute, normalizeAgentRoutePath } from "../runtime/agent-paths.js";
+export {
+  clearAgentMarkdownSerializers,
+  blockquoteMarkdown,
+  defineAgentMarkdownComponent,
+  getMarkdownProp,
+  jsonFenceMarkdown,
+  linkMarkdown,
+  queryMarkdownEnabledContent,
+  registerAgentMarkdownComponent,
+  registerAgentMarkdownComponents,
+  registerAgentMarkdownSerializer,
+  registerAgentMarkdownSerializers,
+  renderMarkdownChildren,
+  resolveAgentMarkdownOptions,
+  resolveContentMarkdown,
+  resolveContentMarkdownByRoute,
+  xmlComponentMarkdown
+} from "../runtime/server/agent-markdown.js";
+export {
+  buildAgentPageIndex,
+  collectAgentMarkdownPrerenderRoutes,
+  getAgentLocales,
+  isSupportedAgentLocale,
+  localeFromAgentPath,
+  renderAgentMarkdownFrontmatter,
+  renderAgentMarkdownPage,
+  renderLlmsFullTxt,
+  renderLlmsTxt,
+  resolveMarkdownForPublicRoute,
+  routePathFromIndexSlug,
+  routePathFromRawSlug
+} from "../runtime/server/agent-site.js";
 export const queryCollectionsSitemapEntries = async (...args) => {
   const { queryCollectionsSitemapEntries: queryCollectionsSitemapEntries2 } = await import("../runtime/server/sitemap-provider.js");
   return await queryCollectionsSitemapEntries2(...args);

package/dist/runtime/agent-paths

@@ -0,0 +1 @@
+export * from './agent-paths.js'

package/dist/runtime/agent-paths.d.ts

@@ -0,0 +1,6 @@
+export declare const isUnsafeAgentRoutePath: (path: string) => boolean;
+export declare const normalizeAgentRoutePath: (path: string | undefined) => string;
+export declare const agentMarkdownPathForRoute: (path: string) => string;
+export declare const agentRawPathForRoute: (path: string) => string;
+export declare const agentRoutePathFromRawSlug: (slug: string | string[] | undefined) => string;
+export declare const agentRoutePathFromIndexSlug: (slug: string | string[] | undefined) => string;

package/dist/runtime/agent-paths.js

@@ -0,0 +1,41 @@
+const trimSlashes = (value) => value.replace(/^\/+|\/+$/g, "");
+const decodeRoutePath = (path) => {
+  let decoded = path;
+  for (let i = 0; i < 3; i++) {
+    try {
+      const next = decodeURIComponent(decoded);
+      if (next === decoded) return decoded;
+      decoded = next;
+    } catch {
+      return decoded;
+    }
+  }
+  return decoded;
+};
+export const isUnsafeAgentRoutePath = (path) => {
+  const decoded = decodeRoutePath(path);
+  if (decoded.includes("\0")) return true;
+  return decoded.split("/").includes("..");
+};
+export const normalizeAgentRoutePath = (path) => {
+  if (!path || path === "/") return "/";
+  return `/${trimSlashes(path.replace(/\/+/g, "/"))}`;
+};
+export const agentMarkdownPathForRoute = (path) => {
+  const normalized = normalizeAgentRoutePath(path);
+  return normalized === "/" ? "/index.md" : `${normalized}/index.md`;
+};
+export const agentRawPathForRoute = (path) => {
+  const normalized = normalizeAgentRoutePath(path);
+  return normalized === "/" ? "/raw/index.md" : `/raw${normalized}.md`;
+};
+export const agentRoutePathFromRawSlug = (slug) => {
+  const joined = Array.isArray(slug) ? slug.join("/") : slug || "";
+  const withoutExtension = joined.replace(/\.md$/i, "");
+  if (withoutExtension === "index") return "/";
+  return normalizeAgentRoutePath(withoutExtension.replace(/\/index$/i, "") || "/");
+};
+export const agentRoutePathFromIndexSlug = (slug) => {
+  const joined = Array.isArray(slug) ? slug.join("/") : slug || "";
+  return normalizeAgentRoutePath(joined || "/");
+};

package/dist/runtime/app/components/internal/MarkdownRenderer.d.ts

@@ -78,9 +78,9 @@ declare const _default: import("vue").DefineComponent<import("vue").ExtractPropT
         default: () => never[];
     };
 }>> & Readonly<{}>, {
+    locale: string;
     defaultLocale: string;
     locales: string[];
-    locale: string;
     class: string | unknown[] | Record<string, any>;
     components: Record<string, any>;
     prose: boolean | undefined;

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

@@ -20,6 +20,9 @@ type ContentHeadRuntimeConfig = {
         baseURL: string;
     };
     public: {
+        content?: {
+            siteUrl?: unknown;
+        };
         siteUrl?: unknown;
     };
 };

package/dist/runtime/app/composables/head.js

@@ -35,7 +35,8 @@ export const resolveContentHead = (data, to, config) => {
       });
     }
   }
-  const siteUrl = typeof config.public.siteUrl === "string" ? withoutTrailingSlash(config.public.siteUrl) : void 0;
+  const configuredSiteUrl = config.public.content?.siteUrl ?? config.public.siteUrl;
+  const siteUrl = typeof configuredSiteUrl === "string" ? withoutTrailingSlash(configuredSiteUrl) : void 0;
   if (import.meta.server && siteUrl) {
     const url = withoutTrailingSlash(joinURL(siteUrl, appConfig.baseURL, to.fullPath));
     if (!head.meta.some((m) => m.property === "og:url")) {

package/dist/runtime/app/composables/hot-reload

@@ -0,0 +1 @@
+export * from './hot-reload.js'

package/dist/runtime/app/composables/hot-reload.d.ts

@@ -0,0 +1,5 @@
+type ContentHot = {
+    on: (event: 'ginko-content:update', callback: (data: unknown) => void) => void;
+};
+export declare function registerContentHotReload(hot?: ContentHot | undefined, isClient?: boolean | undefined): void;
+export {};

package/dist/runtime/app/composables/hot-reload.js

@@ -0,0 +1,15 @@
+import { refreshNuxtData } from "#imports";
+let registered = false;
+const onContentUpdate = (data) => {
+  if (!data || typeof data !== "object") {
+    return;
+  }
+  refreshNuxtData();
+};
+export function registerContentHotReload(hot = import.meta.hot, isClient = import.meta.client) {
+  if (!hot || !isClient || registered) {
+    return;
+  }
+  registered = true;
+  hot.on("ginko-content:update", onContentUpdate);
+}

package/dist/runtime/app/composables/locale-context.d.ts

@@ -1,5 +1,5 @@
 export declare function getLocaleContext(): {
     route: any;
-    nuxtApp: any;
+    i18nLocale: any;
     resolvedLocaleState: any;
 };

package/dist/runtime/app/composables/locale-context.js

@@ -1,8 +1,9 @@
 import { useNuxtApp, useRoute, useState } from "#imports";
 export function getLocaleContext() {
+  const nuxtApp = useNuxtApp();
   return {
     route: useRoute(),
-    nuxtApp: useNuxtApp(),
+    i18nLocale: nuxtApp.$i18n?.locale,
     resolvedLocaleState: useState("$si18n:resolved-locale")
   };
 }

package/dist/runtime/app/composables/locale.js

@@ -2,8 +2,8 @@ import { getLocaleContext } from "./locale-context.js";
 import { normalizeContentPath, resolveRouteContent as resolveLocalizedRouteContent } from "../../../features/localization/path";
 export { normalizeContentPath };
 export const resolveActiveLocale = (locales, defaultLocale) => {
-  const { route, nuxtApp, resolvedLocaleState } = getLocaleContext();
-  const i18nLocale = nuxtApp.$i18n?.locale;
+  const { route, i18nLocale: capturedI18nLocale, resolvedLocaleState } = getLocaleContext();
+  const i18nLocale = capturedI18nLocale || resolvedLocaleState.value;
   const explicitLocale = typeof i18nLocale === "string" ? i18nLocale : i18nLocale?.value || resolvedLocaleState.value;
   if (explicitLocale && locales.includes(explicitLocale)) {
     return explicitLocale;

package/dist/runtime/app/composables/search.js

@@ -100,7 +100,7 @@ export async function useContentSearchData(collection, options = {}) {
   const name = collectionName(collection);
   const searchTerm = ref("");
   const locale = computed(() => toValue(options.locale));
-  const payload = await useAsyncData(computed(() => `content-search-data:${name}:${locale.value || "default"}`), async () => {
+  const payloadPromise = useAsyncData(computed(() => `content-search-data:${name}:${locale.value || "default"}`), async () => {
     const locale2 = toValue(options.locale);
     const [navigation, files2] = await Promise.all([
       tree(name, locale2 ? { locale: locale2 } : {}),
@@ -113,6 +113,7 @@ export async function useContentSearchData(collection, options = {}) {
   }, {
     watch: [locale]
   });
+  const payload = await payloadPromise;
   const files = computed(() => payload.data.value?.files || []);
   const searchNavigation = computed(() => payload.data.value?.navigation || []);
   return {
@@ -217,7 +218,8 @@ export const useContentSearch = async (options = {}) => {
 const useMiniSearch = async (search, indexURL, minisearch, options) => {
   const locale = computed(() => toValue(options.locale));
   const requestUrl = computed(() => locale.value ? `${indexURL}?locale=${encodeURIComponent(locale.value)}` : indexURL);
-  const { data, pending, error } = await useFetch(requestUrl);
+  const fetchData = useFetch(requestUrl);
+  const { data, pending, error } = await fetchData;
   const results = computed(() => searchRecords(data.value || [], toValue(search), locale.value, minisearch));
   return {
     results,
@@ -239,7 +241,8 @@ const useCmsSearch = async (search, apiBaseURL, options) => {
     const query = params.toString();
     return query ? `${apiBaseURL}?${query}` : apiBaseURL;
   });
-  const { data, pending, error } = await useFetch(requestUrl);
+  const fetchData = useFetch(requestUrl);
+  const { data, pending, error } = await fetchData;
   return {
     results: computed(() => (data.value || []).map((result) => ({
       ...result,
@@ -294,15 +297,16 @@ const usePagefindSearch = (search, pagefindUrl, options) => {
       const response = await pagefind.search(term);
       const normalized = await Promise.all((response?.results || []).map(async (result) => {
         const data = await result.data();
+        const meta = data?.meta;
         const [path = "", anchor] = String(data?.url || "").split("#");
         return {
           path,
-          collection: typeof data?.meta?.collection === "string" ? data.meta.collection : "",
-          title: data?.meta?.title || path,
+          collection: typeof meta?.collection === "string" ? meta.collection : "",
+          title: typeof meta?.title === "string" ? meta.title : path,
           excerpt: data?.excerpt || "",
           score: result.score,
           anchor: anchor || void 0,
-          locale: data?.meta?.locale || deriveLocale(path, contentConfig?.locales || [])
+          locale: typeof meta?.locale === "string" ? meta.locale : deriveLocale(path, contentConfig?.locales || [])
         };
       }));
       if (!cancelled) {

package/dist/runtime/app/composables/use-content-document

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

package/dist/runtime/app/composables/use-content-document.d.ts

@@ -0,0 +1,29 @@
+import type { ComputedRef } from 'vue';
+import type { ContentCollectionTarget, DocumentFromHandle, LocalizedDoc, OneOptions, PopulateFromOptions, PopulateSpec, PopulatedDocument, ResolveOneOptions, ResolveOneResult } from '../../../types/query';
+import { type Reactive } from './use-content-shared';
+type DocFromHandle<H> = DocumentFromHandle<H>;
+interface UseContentOneReturn<T> {
+    data: ComputedRef<LocalizedDoc<T> | null>;
+    pending: ComputedRef<boolean>;
+    status: ComputedRef<string>;
+    error: ComputedRef<unknown>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Reactively resolve a single document. Reruns when any reactive source on
+ * `options` changes. Caching follows Nuxt's standard `useAsyncData` semantics
+ * keyed by `${collection}:${stableHash(options)}`.
+ */
+export declare function useContentOne<const H extends ContentCollectionTarget, O extends OneOptions<H, PopulateSpec | undefined>>(handle: H, options: Reactive<O>): Promise<UseContentOneReturn<PopulatedDocument<DocFromHandle<H>, PopulateFromOptions<O>>>>;
+interface UseContentResolveOneReturn<T> {
+    doc: ComputedRef<LocalizedDoc<T> | null>;
+    explain: ComputedRef<ResolveOneResult<T>['explain'] | null>;
+    status: ComputedRef<string>;
+    error: ComputedRef<unknown>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Reactively resolve a single document with a first-class diagnostic envelope.
+ */
+export declare function useContentResolveOne<const H extends ContentCollectionTarget, O extends ResolveOneOptions<H, PopulateSpec | undefined>>(handle: H, options: Reactive<O>): Promise<UseContentResolveOneReturn<PopulatedDocument<DocFromHandle<H>, PopulateFromOptions<O>>>>;
+export {};

package/dist/runtime/app/composables/use-content-document.js

@@ -0,0 +1,44 @@
+import { computed } from "vue";
+import { useAsyncData } from "#imports";
+import { createClientContentQueryContext } from "./query-api.js";
+import {
+  one as oneWithContext,
+  resolveOne as resolveOneWithContext
+} from "../../query/unified.js";
+import { contentCollectionName, resolveOptions, stableKey } from "./use-content-shared.js";
+export async function useContentOne(handle, options) {
+  const resolved = computed(() => resolveOptions(options));
+  const key = computed(() => stableKey("content-one", contentCollectionName(handle), resolved.value));
+  const context = createClientContentQueryContext();
+  const asyncDataPromise = useAsyncData(
+    key,
+    () => oneWithContext(context, handle, resolved.value),
+    { watch: [resolved], default: () => null }
+  );
+  const asyncData = await asyncDataPromise;
+  return {
+    data: computed(() => asyncData.data.value),
+    pending: computed(() => asyncData.pending.value),
+    status: computed(() => asyncData.status.value),
+    error: computed(() => asyncData.error.value),
+    refresh: () => asyncData.refresh()
+  };
+}
+export async function useContentResolveOne(handle, options) {
+  const resolved = computed(() => resolveOptions(options));
+  const key = computed(() => stableKey("content-resolve-one", contentCollectionName(handle), resolved.value));
+  const context = createClientContentQueryContext();
+  const asyncDataPromise = useAsyncData(
+    key,
+    () => resolveOneWithContext(context, handle, resolved.value),
+    { watch: [resolved] }
+  );
+  const asyncData = await asyncDataPromise;
+  return {
+    doc: computed(() => asyncData.data.value?.doc ?? null),
+    explain: computed(() => asyncData.data.value?.explain ?? null),
+    status: computed(() => asyncData.status.value),
+    error: computed(() => asyncData.error.value),
+    refresh: () => asyncData.refresh()
+  };
+}

package/dist/runtime/app/composables/use-content-list

@@ -0,0 +1 @@
+export * from './use-content-list.js'