@lupinum/ginko-content 0.3.0-rc.4 → 0.3.0

package/README.md

@@ -10,8 +10,7 @@ Use it when you want content files to stay simple, but your Nuxt app still
 needs explicit APIs for route resolution, typed frontmatter, localized content,
 and server-side reads.
 
-This README describes the `0.3` prerelease. Install it from npm's `next`
-channel; `latest` remains `0.2.1` until the stable cutover.
+This README describes the stable `0.3` line.
 
 ## Requirements
 
@@ -23,14 +22,14 @@ channel; `latest` remains `0.2.1` until the stable cutover.
 ## Install
 
 ```bash
-npx nuxi module add @lupinum/ginko-content@next
+npx nuxi module add @lupinum/ginko-content
 ```
 
 The Nuxt CLI installs the package and registers the module in `nuxt.config.ts`.
 If you prefer to install by hand:
 
 ```bash
-pnpm add @lupinum/ginko-content@next
+pnpm add @lupinum/ginko-content
 ```
 
 ```ts
@@ -79,7 +78,7 @@ Render the current route through the collection:
 ```vue
 <!-- pages/[...slug].vue -->
 <script setup lang="ts">
-import { pages } from '~/content.config'
+import { pages } from '~~/content.config'
 
 const { page } = await useContentPage(pages)
 </script>

package/dist/cms-contract/index.d.ts

@@ -22,8 +22,8 @@
  */
 export { RESOLVED_CONTENT_CONTRACT_VERSION, buildResolvedContentContract, type BuildResolvedContentContractInput, type BuildResolvedContentContractOptions, } from './build.js';
 export type { PortableComponentPolicyV1, PortableMediaType, ResolvedContentCollectionV1, ResolvedContentContractV1, ResolvedContentFieldTypeV1, ResolvedContentFieldV1, ResolvedContentValidationV1, ContentCmsCollectionConfig, ContentCmsFieldConfig, ContentCmsFieldType, ContentCmsRelationConfig, ContentCollectionConfig, ContentCollectionI18nConfig, } from './types.js';
-export { describeId, generatePath, generateCanonicalKey, generateTitle, isDraftPath, isPartialPath, longestMountForPath, mountContentPath, normalizeContentPath, normalizeRouteMounts, prefixPathWithLocale, refineUrlPart, routeRemainder, routeToContentPathCandidates, slugifyUrlSegment, stripLocalePrefix, } from './path.js';
-export { CONTENT_FIELD_METADATA_KEY, CONTENT_REFERENCE_PREFIX, collectTopLevelReferenceFields, getContentFieldMetadata, getObjectShape, getReferenceDescriptor, getSchemaDef, getSchemaTypeName, unwrapSchema, type ContentFieldMetadata, type ContentFieldSchema, } from './schema.js';
+export { describeId, generatePath, generateCanonicalKey, generateTitle, isDraftPath, isPartialPath, mountContentPath, normalizeContentPath, normalizeRouteMounts, prefixPathWithLocale, refineUrlPart, routeRemainder, routeToContentPathCandidates, slugifyUrlSegment, stripLocalePrefix, } from './path.js';
+export { CONTENT_FIELD_METADATA_KEY, CONTENT_REFERENCE_METADATA_KEY, collectTopLevelReferenceFields, getContentFieldMetadata, getObjectShape, getReferenceDescriptor, getSchemaDef, getSchemaTypeName, unwrapSchema, type ContentFieldMetadata, type ContentFieldSchema, } from './schema.js';
 export { parseMdcBody, type ParseMdcBodyOptions, type ParseMdcBodyResult, } from './mdc.js';
 export { assertPublicMarkdownAst, isSafePublicMarkdownUrl, PublicMarkdownValidationError, validatePublicMarkdownAst, type PublicMarkdownIssue, type PublicMarkdownIssueCode, type PublicMarkdownValidationResult, } from './render-policy.js';
 export { verifyPublicImageBytes, type VerifiedPublicImage, } from './asset-bytes.js';

package/dist/cms-contract/index.js

@@ -9,7 +9,6 @@ export {
   generateTitle,
   isDraftPath,
   isPartialPath,
-  longestMountForPath,
   mountContentPath,
   normalizeContentPath,
   normalizeRouteMounts,
@@ -22,7 +21,7 @@ export {
 } from "./path.js";
 export {
   CONTENT_FIELD_METADATA_KEY,
-  CONTENT_REFERENCE_PREFIX,
+  CONTENT_REFERENCE_METADATA_KEY,
   collectTopLevelReferenceFields,
   getContentFieldMetadata,
   getObjectShape,

package/dist/cms-contract/mdc.js

@@ -1,9 +1,11 @@
-import { parse } from "comark";
+import { normalizeComarkNodes } from "../core/markdown/normalize-comark.js";
+import { parseComark } from "../core/markdown/parse-comark.js";
 import { mapMarkdownNodes, toMarkdownRoot } from "../core/markdown/tree.js";
 export async function parseMdcBody(raw, options = {}) {
-  const tree = await parse(raw ?? "");
-  const toc = deriveToc(tree.nodes, options);
-  const body = toMarkdownRoot(tree.nodes, toc);
+  const tree = await parseComark(raw ?? "");
+  const nodes = normalizeComarkNodes(tree.nodes);
+  const toc = deriveToc(nodes, options);
+  const body = toMarkdownRoot(nodes, toc);
   const searchText = renderPlainText(body);
   return { body, toc, searchText };
 }

package/dist/cms-contract/path.d.ts

@@ -6,5 +6,5 @@
  *
  * All re-exports MUST be runtime-pure (no Node, no Nuxt, no h3). They are.
  */
-export { describeId, generatePath, generateCanonicalKey, generateTitle, isDraftPath, isPartialPath, normalizeContentPath, normalizeRouteMounts, longestMountForPath, routeRemainder, mountContentPath, prefixPathWithLocale, stripLocalePrefix, refineUrlPart, routeToContentPathCandidates, } from '../core/content/path.js';
+export { describeId, generatePath, generateCanonicalKey, generateTitle, isDraftPath, isPartialPath, normalizeContentPath, normalizeRouteMounts, routeRemainder, mountContentPath, prefixPathWithLocale, stripLocalePrefix, refineUrlPart, routeToContentPathCandidates, } from '../core/content/path.js';
 export { slugifyUrlSegment } from '../core/content/slug.js';

package/dist/cms-contract/path.js

@@ -7,7 +7,6 @@ export {
   isPartialPath,
   normalizeContentPath,
   normalizeRouteMounts,
-  longestMountForPath,
   routeRemainder,
   mountContentPath,
   prefixPathWithLocale,

package/dist/cms-contract/render-policy.js

@@ -226,6 +226,10 @@ export function validatePublicMarkdownAst(value, policy = { components: {} }) {
         continue;
       }
       if (name === "style" && tag === "span" && isSafeShikiStyle(propValue)) continue;
+      if (tag === "blockquote" && name === "data-alert") {
+        if (typeof propValue !== "string" || !["note", "tip", "important", "warning", "caution"].includes(propValue)) report("invalid_prop_value", propPath, "Blockquote alert metadata is invalid.");
+        continue;
+      }
       if (!name || /^on/i.test(name) || /^v-|^@|^:|^#/.test(name) || FORBIDDEN_PROPS.has(lower)) {
         report("unsafe_prop", propPath, `Property "${name}" is not render-safe.`);
         continue;

package/dist/cms-contract/schema.d.ts

@@ -15,4 +15,4 @@ export { getSchemaDef, getSchemaTypeName, unwrapSchema, getObjectShape, getRefer
  */
 export { CONTENT_FIELD_METADATA_KEY, type ContentFieldMetadata, type ContentFieldSchema, } from '../types/fields.js';
 export { getContentFieldMetadata } from '../types/fields.js';
-export { CONTENT_REFERENCE_PREFIX } from '../types/reference.js';
+export { CONTENT_REFERENCE_METADATA_KEY, } from '../types/reference.js';

package/dist/cms-contract/schema.js

@@ -10,4 +10,6 @@ export {
   CONTENT_FIELD_METADATA_KEY
 } from "../types/fields.js";
 export { getContentFieldMetadata } from "../types/fields.js";
-export { CONTENT_REFERENCE_PREFIX } from "../types/reference.js";
+export {
+  CONTENT_REFERENCE_METADATA_KEY
+} from "../types/reference.js";

package/dist/core/content/graph.d.ts

@@ -14,7 +14,7 @@
  *    Canonical keys are only unique within a collection.
  *  - **`byCanonical`**: a derived convenience index containing only keys
  *    that occur in one collection. Ambiguous unscoped lookups fail closed.
- *  - **`byRoute`**: route path (user-visible URL) → content id. Used by the
+ *  - **`byRoute`**: locale plus route path → canonical key. Used by the
  *    page resolver when the request arrives as a localized URL.
  *  - **`byRef`**: normalized ref string → canonical key. This is how
  *    markdown links such as `[Ada]($authors.ada)` find their target without a scan.
@@ -28,8 +28,8 @@
  */
 import type { ParsedContent } from '../../types/content';
 import type { ContentLocaleEntry } from '../../types/query';
-import type { ContentManifest, ManifestVariant, ResolvedVariant } from '../../types/runtime';
-export interface ContentGraphVariant extends ManifestVariant {
+import type { ContentVariantIdentity, ResolvedVariant } from '../../types/runtime';
+export interface ContentGraphVariant extends ContentVariantIdentity {
     document: ParsedContent;
 }
 export interface ContentGraph {
@@ -44,7 +44,9 @@ export interface ContentGraph {
     byCollectionCanonical: Record<string, Record<string, Record<string, ContentGraphVariant>>>;
     /** Unambiguous canonical keys only. Derived from `byCollectionCanonical`. */
     byCanonical: Record<string, Record<string, ContentGraphVariant>>;
-    /** route path → content id. Used by page resolution. */
+    /** Exact collection → ref → canonical key alias index. */
+    byCollectionRef: Record<string, Record<string, string>>;
+    /** `"<locale>:<route path>"` → canonical key. Used by page resolution. */
     byRoute: Record<string, string>;
     /** normalized ref string → canonical key. */
     byRef: Record<string, string>;
@@ -54,7 +56,6 @@ export interface ContentGraph {
     referenceTargets: Map<string, string>;
     /** Exact collection-scoped user-writable reference targets. */
     referenceTargetsByCollection: Record<string, Map<string, string>>;
-    manifest: ContentManifest;
 }
 /**
  * Build a `ContentGraph` from a flat list of parsed documents.
@@ -71,6 +72,7 @@ export interface ContentGraph {
 export declare const buildContentGraph: (documents: ParsedContent[], options?: {
     locales?: string[];
     defaultLocale?: string;
+    referencePathAliases?: (document: ParsedContent) => readonly string[];
 }) => ContentGraph;
 /** Resolve the exact collection-scoped variant set, or an unambiguous one. */
 export declare const getGraphCanonicalVariants: (graph: ContentGraph, canonicalKey: string, collection?: string) => Record<string, ContentGraphVariant> | undefined;

package/dist/core/content/graph.js

@@ -7,20 +7,15 @@ const normalizePath = (path) => {
   }
   return path.startsWith("/") ? path.endsWith("/") ? path.slice(0, -1) || "/" : path : `/${path.replace(/\/+$/, "")}`;
 };
-const emptyManifest = () => ({
-  byCollectionCanonical: {},
-  byCanonical: {},
-  byCollectionRef: {},
-  byRef: {},
-  byRoute: {},
-  paths: {},
-  collections: {}
-});
 export const buildContentGraph = (documents, options = {}) => {
-  const manifest = emptyManifest();
   const byId = {};
+  const byCollection = {};
+  const byPath = {};
   const byCollectionCanonical = {};
   const byCanonical = {};
+  const byCollectionRef = {};
+  const byRef = {};
+  const byRoute = {};
   const byNavigationPath = {};
   const defaultLocale = options.defaultLocale || "";
   for (const document of documents) {
@@ -30,15 +25,15 @@ export const buildContentGraph = (documents, options = {}) => {
       continue;
     }
     const path = normalizePath(document.path);
-    manifest.paths[path] ||= [];
+    byPath[path] ||= [];
     if (document.locale === defaultLocale) {
-      manifest.paths[path].unshift(documentId);
+      byPath[path].unshift(documentId);
     } else {
-      manifest.paths[path].push(documentId);
+      byPath[path].push(documentId);
     }
     if (document.collection) {
-      manifest.collections[document.collection] ||= [];
-      manifest.collections[document.collection].push(documentId);
+      byCollection[document.collection] ||= [];
+      byCollection[document.collection].push(documentId);
     }
     if (isNavigationFile(document)) {
       const locale2 = document.locale || defaultLocale;
@@ -58,45 +53,43 @@ export const buildContentGraph = (documents, options = {}) => {
       path,
       document
     };
-    manifest.byCollectionCanonical[collection] ||= {};
-    manifest.byCollectionCanonical[collection][document.canonicalKey] ||= {};
-    manifest.byCollectionCanonical[collection][document.canonicalKey][locale] = variant;
-    manifest.byRoute[`${locale}:${path}`] = document.canonicalKey;
+    byCollectionCanonical[collection] ||= {};
+    byCollectionCanonical[collection][document.canonicalKey] ||= {};
+    byCollectionCanonical[collection][document.canonicalKey][locale] = variant;
+    byRoute[`${locale}:${path}`] = document.canonicalKey;
     if (document.type === "markdown" && typeof document.ref === "string" && document.ref.length) {
-      manifest.byCollectionRef[collection] ||= {};
-      manifest.byCollectionRef[collection][document.ref] = document.canonicalKey;
+      byCollectionRef[collection] ||= {};
+      byCollectionRef[collection][document.ref] = document.canonicalKey;
     }
   }
   const collectionsByCanonical = /* @__PURE__ */ new Map();
-  for (const [collection, canonicalEntries] of Object.entries(manifest.byCollectionCanonical)) {
-    byCollectionCanonical[collection] = {};
-    for (const [canonicalKey, variants] of Object.entries(canonicalEntries)) {
-      const graphVariants = Object.fromEntries(
-        Object.entries(variants).map(([locale, variant]) => [locale, { ...variant, document: byId[variant.contentId] }])
-      );
-      byCollectionCanonical[collection][canonicalKey] = graphVariants;
+  for (const [collection, canonicalEntries] of Object.entries(byCollectionCanonical)) {
+    for (const canonicalKey of Object.keys(canonicalEntries)) {
       collectionsByCanonical.set(canonicalKey, [...collectionsByCanonical.get(canonicalKey) || [], collection]);
     }
   }
   for (const [canonicalKey, collections] of collectionsByCanonical) {
     if (collections.length !== 1) continue;
     const collection = collections[0];
-    manifest.byCanonical[canonicalKey] = manifest.byCollectionCanonical[collection][canonicalKey];
     byCanonical[canonicalKey] = byCollectionCanonical[collection][canonicalKey];
   }
   const collectionsByRef = /* @__PURE__ */ new Map();
-  for (const [collection, refs] of Object.entries(manifest.byCollectionRef)) {
+  for (const [collection, refs] of Object.entries(byCollectionRef)) {
     for (const ref of Object.keys(refs)) {
       collectionsByRef.set(ref, [...collectionsByRef.get(ref) || [], collection]);
     }
   }
   for (const [ref, collections] of collectionsByRef) {
-    if (collections.length === 1) manifest.byRef[ref] = manifest.byCollectionRef[collections[0]][ref];
+    if (collections.length === 1) byRef[ref] = byCollectionRef[collections[0]][ref];
   }
   const referenceTargetsByCollection = Object.fromEntries(
-    Object.keys(manifest.byCollectionCanonical).map((collection) => [
+    Object.keys(byCollectionCanonical).map((collection) => [
       collection,
-      buildReferenceTargets(documents.filter((document) => (document.collection || "content") === collection && !document.partial && !isNavigationFile(document)), options.locales || [])
+      buildReferenceTargets(
+        documents.filter((document) => (document.collection || "content") === collection && !document.partial && !isNavigationFile(document)),
+        options.locales || [],
+        options.referencePathAliases
+      )
     ])
   );
   const referenceTargetCollections = /* @__PURE__ */ new Map();
@@ -112,16 +105,16 @@ export const buildContentGraph = (documents, options = {}) => {
   return {
     documents,
     byId,
-    byCollection: manifest.collections,
-    byPath: manifest.paths,
+    byCollection,
+    byPath,
     byCollectionCanonical,
     byCanonical,
-    byRoute: manifest.byRoute,
-    byRef: manifest.byRef,
+    byCollectionRef,
+    byRoute,
+    byRef,
     byNavigationPath,
     referenceTargets,
-    referenceTargetsByCollection,
-    manifest
+    referenceTargetsByCollection
   };
 };
 export const getGraphCanonicalVariants = (graph, canonicalKey, collection) => {
@@ -180,7 +173,7 @@ export const resolveGraphCanonicalKey = (graph, identity, collection) => {
   if (hasCollectionVariant(normalizedIdentity)) {
     return normalizedIdentity;
   }
-  const refCanonicalKey = collection ? graph.manifest.byCollectionRef[collection]?.[normalizedIdentity] : graph.byRef[normalizedIdentity];
+  const refCanonicalKey = collection ? graph.byCollectionRef[collection]?.[normalizedIdentity] : graph.byRef[normalizedIdentity];
   if (refCanonicalKey && hasCollectionVariant(refCanonicalKey)) {
     return refCanonicalKey;
   }

package/dist/core/content/locale.d.ts

@@ -27,7 +27,7 @@ export declare const INLINE_LOCALE_ID_SEPARATOR = "#__locale=";
  * configured fallbacks, and default locale are ordered by priority and
  * deduplicated without reordering.
  */
-export declare const resolveLocaleChain: (requestedLocale: string | undefined, defaultLocale?: string, fallback?: Record<string, string[]>) => string[];
+export declare const resolveLocaleChain: (requestedLocale: string | undefined, defaultLocale?: string, fallback?: Readonly<Record<string, readonly string[]>>) => string[];
 /**
  * Produce the fallback portion of the canonical locale chain, excluding the
  * requested locale itself.
@@ -68,3 +68,5 @@ export declare const splitInlineLocaleVariantId: (id: string) => {
  * override should not fail ingest for the whole document.
  */
 export declare const expandDataLocaleVariants: (document: ParsedContent, i18nConfig?: ContentCollectionI18nConfig) => ParsedContent[];
+/** Physical locale identity used when content has no configured locale authority. */
+export declare const DEFAULT_CONTENT_LOCALE = "en";

package/dist/core/content/locale.js

@@ -94,3 +94,4 @@ export const expandDataLocaleVariants = (document, i18nConfig) => {
   }
   return variants;
 };
+export const DEFAULT_CONTENT_LOCALE = "en";

package/dist/core/content/path.d.ts

@@ -29,14 +29,39 @@ export declare const generateCanonicalKey: (parts: string[], { translatedSlugs,
 export declare const generateTitle: (path: string) => string;
 export type RouteMounts = Record<string, string>;
 export declare const normalizeRouteMounts: (route: string | Record<string, string> | undefined, locales?: string[], defaultLocale?: string) => RouteMounts | undefined;
-export declare const longestMountForPath: (path: string, mounts: RouteMounts) => [string, string];
 export declare const routeRemainder: (path: string, mount: string) => string;
+/**
+ * Remove a configured route mount from a filesystem-derived path when that
+ * exact mount is present. Source layouts are allowed to live elsewhere, so
+ * unlike provider unmounting this operation leaves non-matching paths intact.
+ */
+export declare const canonicalizeSourcePath: (path: string, mount?: string) => {
+    path: string;
+    removedSegments: number;
+};
 export declare const mountContentPath: (remainder: string, locale: string | undefined, mounts?: RouteMounts) => string;
 export declare const prefixPathWithLocale: (path: string, locale?: string, defaultLocale?: string) => string;
 export declare const stripLocalePrefix: (path: string, locales?: string[], defaultLocale?: string, explicitLocale?: string) => {
     locale: string | undefined;
     path: string;
 };
+export declare const lowerRouteToCanonicalCandidates: (route: string, requestedLocale: string | undefined, localeChain: readonly string[], defaultLocale: string, locales: readonly string[], mountForLocale: (locale: string) => string) => {
+    locale: string;
+    contentPath: string;
+}[];
+/**
+ * Released CMS-contract adapter returning mounted provider coordinates.
+ *
+ * This function GUESSES: it unions locales from the mount map, the requested
+ * chain, and the default locale, and it substitutes `/` for any locale with no
+ * declared mount. The content engine deliberately does not call it — route
+ * lowering goes through `lowerRouteToCandidates`
+ * (`features/localization/route-projector.ts`), which validates the resolved
+ * locale's configured mount and fails instead of substituting one.
+ *
+ * It exists only so CMS adapters compiled against the released contract keep
+ * working. New code should use the resolved collection locale policy.
+ */
 export declare const routeToContentPathCandidates: (route: string, requestedLocale: string | undefined, localeChain: string[], defaultLocale?: string, mounts?: RouteMounts) => {
     locale: string;
     path: string;

package/dist/core/content/path.js

@@ -103,25 +103,37 @@ export const normalizeRouteMounts = (route, locales = [], defaultLocale) => {
   const entries = Object.entries(route).filter(([, mount]) => typeof mount === "string" && mount.length > 0).map(([locale, mount]) => [locale, normalizeContentPath(mount)]);
   return entries.length ? Object.fromEntries(entries) : void 0;
 };
-export const longestMountForPath = (path, mounts) => {
-  const normalized = normalizeContentPath(path);
-  return Object.entries(mounts).filter(([, mount]) => normalized === mount || normalized.startsWith(`${mount}/`)).sort((a, b) => b[1].length - a[1].length)[0];
-};
 export const routeRemainder = (path, mount) => {
   const normalizedPath = normalizeContentPath(path);
   const normalizedMount = normalizeContentPath(mount);
+  if (normalizedMount === "/") {
+    return normalizedPath;
+  }
   if (normalizedPath === normalizedMount) {
     return "/";
   }
   return normalizeContentPath(normalizedPath.slice(normalizedMount.length) || "/");
 };
+export const canonicalizeSourcePath = (path, mount) => {
+  const normalizedPath = normalizeContentPath(path);
+  const normalizedMount = mount ? normalizeContentPath(mount) : "/";
+  const removesMount = normalizedMount !== "/" && (normalizedPath === normalizedMount || normalizedPath.startsWith(`${normalizedMount}/`));
+  return {
+    path: removesMount ? routeRemainder(normalizedPath, normalizedMount) : normalizedPath,
+    removedSegments: removesMount ? normalizedMount.split("/").filter(Boolean).length : 0
+  };
+};
 export const mountContentPath = (remainder, locale, mounts) => {
   const mount = locale && mounts?.[locale];
   if (!mount) {
     return normalizeContentPath(remainder);
   }
   const suffix = normalizeContentPath(remainder);
-  return normalizeContentPath(suffix === "/" ? mount : `${mount}${suffix}`);
+  const normalizedMount = normalizeContentPath(mount);
+  if (normalizedMount === "/") {
+    return suffix;
+  }
+  return normalizeContentPath(suffix === "/" ? normalizedMount : `${normalizedMount}${suffix}`);
 };
 const isLocalePrefixedPath = (path, locales) => {
   const segments = path.split("/").filter(Boolean);
@@ -142,19 +154,37 @@ export const stripLocalePrefix = (path, locales = [], defaultLocale, explicitLoc
   const routePath = routeLocale ? normalizeContentPath("/" + segments.slice(1).join("/")) : normalized;
   return { locale, path: routePath };
 };
+export const lowerRouteToCanonicalCandidates = (route, requestedLocale, localeChain, defaultLocale, locales, mountForLocale) => {
+  const stripped = stripLocalePrefix(route, [...locales], defaultLocale, requestedLocale);
+  const activeLocale = stripped.locale || requestedLocale || defaultLocale;
+  const activeMount = normalizeContentPath(mountForLocale(activeLocale));
+  const path = normalizeContentPath(stripped.path);
+  const matchesExpectedMount = activeMount === "/" || path === activeMount || path.startsWith(`${activeMount}/`);
+  if (!matchesExpectedMount) {
+    return [];
+  }
+  const contentPath = routeRemainder(path, activeMount);
+  return localeChain.map((locale) => ({
+    locale,
+    contentPath
+  }));
+};
 export const routeToContentPathCandidates = (route, requestedLocale, localeChain, defaultLocale, mounts) => {
   const locales = Array.from(new Set([...Object.keys(mounts || {}), ...localeChain, defaultLocale].filter(Boolean)));
-  const stripped = stripLocalePrefix(route, locales, defaultLocale, requestedLocale);
   if (!mounts) {
+    const stripped = stripLocalePrefix(route, locales, defaultLocale, requestedLocale);
     return localeChain.map((locale) => ({ locale, path: stripped.path }));
   }
-  const activeLocale = stripped.locale || requestedLocale || defaultLocale;
-  const activeMount = activeLocale ? mounts[activeLocale] : void 0;
-  const matchedMount = activeMount && (stripped.path === activeMount || stripped.path.startsWith(`${activeMount}/`)) ? activeMount : longestMountForPath(stripped.path, mounts)?.[1];
-  const remainder = matchedMount ? routeRemainder(stripped.path, matchedMount) : stripped.path;
-  return localeChain.map((locale) => ({
-    locale,
-    path: mountContentPath(remainder, locale, mounts)
+  return lowerRouteToCanonicalCandidates(
+    route,
+    requestedLocale,
+    localeChain,
+    defaultLocale || localeChain[0] || "",
+    locales,
+    (locale) => mounts[locale] || "/"
+  ).map((candidate) => ({
+    locale: candidate.locale,
+    path: mountContentPath(candidate.contentPath, candidate.locale, mounts)
   }));
 };
 export const pathHasLocalePrefix = isLocalePrefixedPath;

package/dist/core/content/structural.d.ts

@@ -1,7 +1,6 @@
-import type { ParsedContent } from '../../types/content';
 /**
  * Module-private source classification. `navigationFile` intentionally does
  * not belong to the public `ParsedContent` contract: it only exists between
  * parsing and structural graph/navigation processing.
  */
-export declare const isNavigationFile: (document: ParsedContent) => boolean;
+export declare const isNavigationFile: (document: unknown) => boolean;

package/dist/core/content/structural.js

@@ -1 +1 @@
-export const isNavigationFile = (document) => document.navigationFile === true;
+export const isNavigationFile = (document) => Boolean(document) && typeof document === "object" && document.navigationFile === true;

package/dist/core/data-source-error.d.ts

@@ -0,0 +1,5 @@
+export type ContentDataSourceErrorCode = 'QUERY_CURSOR_INVALID' | 'BACKEND_FAILURE';
+export declare const createContentDataSourceError: (code: ContentDataSourceErrorCode) => Error;
+export declare const isContentDataSourceError: (value: unknown) => value is Error & {
+    code: ContentDataSourceErrorCode;
+};

package/dist/core/data-source-error.js

@@ -0,0 +1,10 @@
+class ContentDataSourceError extends Error {
+  code;
+  constructor(code) {
+    super(code === "QUERY_CURSOR_INVALID" ? "Content data-source query cursor is invalid." : "Content data-source operation failed.");
+    this.name = "ContentDataSourceError";
+    this.code = code;
+  }
+}
+export const createContentDataSourceError = (code) => new ContentDataSourceError(code);
+export const isContentDataSourceError = (value) => value instanceof ContentDataSourceError;

package/dist/core/errors.d.ts

@@ -5,7 +5,7 @@
  * a `ContentError` with one of the codes below. Boundary code (HTTP handler,
  * CLI) maps codes to user-facing responses; tests pattern-match on `.code`.
  */
-export type ContentErrorCode = 'PARSE_FAILED' | 'TRANSFORM_FAILED' | 'VALIDATION_FAILED' | 'INVALID_CONTENT' | 'DUPLICATE_CANONICAL_ID' | 'DUPLICATE_LOCALIZED_PATH' | 'CONFLICTING_REFS' | 'INVALID_REF_VALUE' | 'INVALID_NAVIGATION_YAML' | 'SCHEMA_VALIDATION_FAILED' | 'NON_JSON_VALUE' | 'CONFLICTING_COLLECTION_MATCH' | 'TRANSLATED_SLUG_CONFLICT';
+export type ContentErrorCode = 'PARSE_FAILED' | 'TRANSFORM_FAILED' | 'VALIDATION_FAILED' | 'INVALID_CONTENT' | 'DUPLICATE_CANONICAL_ID' | 'DUPLICATE_LOCALIZED_PATH' | 'CONFLICTING_REFS' | 'INVALID_REF_VALUE' | 'INVALID_NAVIGATION_YAML' | 'INVALID_NAVIGATION_METADATA' | 'SCHEMA_VALIDATION_FAILED' | 'NON_JSON_VALUE' | 'CONFLICTING_COLLECTION_MATCH' | 'TRANSLATED_SLUG_CONFLICT';
 export declare class ContentError extends Error {
     readonly code: ContentErrorCode;
     readonly context: Record<string, unknown>;

package/dist/core/markdown/normalize-comark.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Normalizes parser-owned Comark metadata into the inert public AST contract.
+ * Keep this deliberately narrow: authored structural props such as `as` remain
+ * untouched and are rejected by the render and portability policies.
+ */
+export declare function normalizeComarkNodes(nodes: unknown[]): unknown[];

package/dist/core/markdown/normalize-comark.js

@@ -0,0 +1,15 @@
+const GFM_ALERTS = /* @__PURE__ */ new Set(["note", "tip", "important", "warning", "caution"]);
+export function normalizeComarkNodes(nodes) {
+  const normalize = (node) => {
+    if (!Array.isArray(node)) return node;
+    const [tag, rawProps, ...children] = node;
+    const props = isRecord(rawProps) ? { ...rawProps } : rawProps;
+    if (tag === "blockquote" && isRecord(props) && typeof props.as === "string" && GFM_ALERTS.has(props.as.toLowerCase())) {
+      props["data-alert"] = props.as.toLowerCase();
+      delete props.as;
+    }
+    return [tag, props, ...children.map(normalize)];
+  };
+  return nodes.map(normalize);
+}
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);

package/dist/core/markdown/parse-comark.d.ts

@@ -0,0 +1,3 @@
+import type { ComarkPlugin } from 'comark';
+/** The single configured Comark entry point used by every parsing boundary. */
+export declare const parseComark: (markdown: string, plugins?: readonly ComarkPlugin[]) => Promise<import("comark").ComarkTree<Record<string, any>, Record<string, any>>>;

package/dist/core/markdown/parse-comark.js

@@ -0,0 +1,30 @@
+import { createParse, defineComarkPlugin, parseFrontmatter } from "comark";
+const typedComponentFrontmatter = defineComarkPlugin(() => ({
+  name: "ginko-typed-component-frontmatter",
+  markdownItPlugins: [
+    (markdown) => {
+      markdown.core.ruler.after("block", "ginko_typed_component_frontmatter", (state) => {
+        const lines = state.src.split(/\r?\n/);
+        for (const token of state.tokens) {
+          if (token.type !== "mdc_block_open" || !token.map) continue;
+          const [startLine, endLine] = token.map;
+          if (lines[startLine + 1]?.trim() !== "---") continue;
+          const parsed = parseFrontmatter(lines.slice(startLine + 1, endLine).join("\n"));
+          if (!parsed.frontmatterText) continue;
+          const yamlEntries = Object.entries(parsed.data);
+          const yamlKeys = new Set(yamlEntries.map(([key]) => key));
+          token.attrs = [
+            ...(token.attrs ?? []).filter(([key]) => !yamlKeys.has(key)),
+            ...yamlEntries
+          ];
+        }
+      });
+    }
+  ]
+}));
+export const parseComark = async (markdown, plugins = []) => {
+  const parse = createParse({
+    plugins: [typedComponentFrontmatter(), ...plugins]
+  });
+  return await parse(markdown);
+};

package/dist/core/provider-route-record.d.ts

@@ -0,0 +1,18 @@
+import type { ContentProviderRouteFact, ContentRouteRecord } from '../public/provider-contract';
+export declare const CONTENT_ROUTE_LIMITS: Readonly<{
+    maxRouteRecordBytes: number;
+    maxTotalRouteBytes: number;
+    maxSitemapImagesPerRoute: 16;
+    maxSitemapImageLocationBytes: number;
+}>;
+export type ContentRouteRecordValidationCode = 'RESPONSE_INVALID' | 'RESULT_LIMIT_EXCEEDED';
+export declare class ContentRouteRecordValidationError extends Error {
+    readonly code: ContentRouteRecordValidationCode;
+    readonly field: string;
+    constructor(code: ContentRouteRecordValidationCode, field: string, message: string);
+}
+export declare const normalizeRawProviderRouteFact: (value: unknown, field?: string) => ContentProviderRouteFact;
+export declare const normalizeRawContentRouteRecord: (value: unknown, field?: string) => {
+    record: ContentRouteRecord;
+    serializedBytes: number;
+};