@lupinum/ginko-content 0.3.6 → 0.4.0-rc.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026-present Lupinum OG
+Copyright (c) 2026-present Lupinum OG and contributors
 Copyright (c) Nuxt Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

package/README.md

@@ -1,47 +1,62 @@
-# @lupinum/ginko-content
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lupinum-dev/ginko-content/main/docs/public/icon.png" width="128" alt="Ginko Content">
+</p>
 
-Filesystem-first content for Nuxt 4.
+<h1 align="center">@lupinum/ginko-content</h1>
 
-Write Markdown and data files in `content/`, define collections once in
-`content.config.ts`, then use those collection handles for route pages, lists,
-navigation, search, i18n, and sitemap output.
+<p align="center">
+  Use one typed content model for Nuxt pages, queries, navigation, search, localization, and build output.
+</p>
 
-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.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@lupinum/ginko-content"><img src="https://img.shields.io/npm/v/@lupinum/ginko-content?color=315d3b" alt="npm version"></a>
+  <a href="https://github.com/lupinum-dev/ginko-content/actions/workflows/ci.yml"><img src="https://github.com/lupinum-dev/ginko-content/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://github.com/lupinum-dev/ginko-content/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-315d3b" alt="MIT license"></a>
+</p>
 
-This README describes the stable `0.3` line.
+> [!WARNING]
+> Version `0.4.0-rc.2` is a release candidate. Install it from npm's `next`
+> channel. The stable `0.3` line remains on `latest`.
+
+## Why use this package?
+
+Content features become difficult to maintain when routes, lists, search, and
+localization use separate data. This package makes the collection definition
+the source of truth for those features.
+
+Keep Markdown and data files in `content/`. Use typed collection handles in the
+Nuxt application. The same handles also drive server queries and generated
+output.
 
 ## Requirements
 
 - Node.js 22.18–22.x, 24.11–24.x, or 26+
-- Nuxt 4.4.7 through Nuxt 4.x
+- Nuxt 4.5.1 through Nuxt 4.x
 - Vue 3.5.35 through Vue 3.x
 - ESM; CommonJS `require()` is not supported
 
-## Install
+## Installation
+
+Use the Nuxt CLI:
 
 ```bash
-npx nuxi module add @lupinum/ginko-content
+npx nuxi module add @lupinum/ginko-content@0.4.0-rc.2
 ```
 
-The Nuxt CLI installs the package and registers the module in `nuxt.config.ts`.
-If you prefer to install by hand:
+Or install and register the module by hand:
 
 ```bash
-pnpm add @lupinum/ginko-content
+pnpm add @lupinum/ginko-content@0.4.0-rc.2
 ```
 
 ```ts
+// nuxt.config.ts
 export default defineNuxtConfig({
   modules: ['@lupinum/ginko-content'],
-  imports: {
-    autoImport: true
-  }
 })
 ```
 
-## Quick Start
+## Quick start
 
 Define a collection:
 
@@ -51,13 +66,11 @@ import { defineCollection, defineContentConfig } from '@lupinum/ginko-content/co
 
 export const pages = defineCollection({
   type: 'page',
-  source: '**/*.md'
+  source: '**/*.md',
 })
 
 export default defineContentConfig({
-  collections: {
-    pages
-  }
+  collections: { pages },
 })
 ```
 
@@ -69,18 +82,22 @@ title: Welcome
 ---
 
 # Welcome
-
-This file renders at `/`.
 ```
 
-Render the current route through the collection:
+Render the active route:
 
 ```vue
 <!-- pages/[...slug].vue -->
 <script setup lang="ts">
 import { pages } from '~~/content.config'
 
+definePageMeta({ key: route => route.path })
+
 const { page } = await useContentPage(pages)
+
+if (!page.value) {
+  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+}
 </script>
 
 <template>
@@ -88,73 +105,37 @@ const { page } = await useContentPage(pages)
 </template>
 ```
 
-## Features
-
-- file-authored pages and navigation from `content/`
-- collection definitions as the source of truth for content shape and source
-  files
-- Markdown, Comark component tags, YAML, JSON, and CSV ingestion
-- locale-aware content routing
-- route-aware page loading with `useContentPage(pages)`
-- semantic previous/next route-page data through `useContentPage(pages, { surround })`
-- server reads through `one`, `many`, `paginate`, `resolveOne`, `navigation`,
-  and `surround`
-- route and search composables, plus pure client query functions for other
-  reads
-- search helpers for MiniSearch, Pagefind, and provider-owned search
-- sitemap integration for public content routes
-- a server-side provider contract for advanced custom sources
-
-## I18n, Sitemap, and Prerender Ownership
-
-For localized Nuxt apps, keep one source of truth per route type:
-
-- Static Nuxt page paths belong in Nuxt I18n `i18n.pages`.
-- Content page paths belong in Ginko collection routes and content files.
-- Sitemap XML is generated by `@nuxtjs/sitemap`.
-- Ginko registers the content sitemap source and contributes content prerender
-  routes.
-
-Do not duplicate docs, blog, pricing, privacy, or translated locale paths in
-`sitemap.urls` or app-owned `nitro.prerender.routes` arrays. Use
-`@nuxtjs/sitemap >= 8.0.15 < 9` when translated static app slugs such as `/preise`
-and `/en/pricing` need cross-locale sitemap alternates.
-
-See the public guide:
-[Sitemap and prerender](https://github.com/lupinum-dev/ginko-content/blob/main/docs/content/docs/4.guides/4.routing-and-seo/3.sitemap-and-prerender.md).
-
-## Integration Dependencies
-
-| Feature | Dependency model |
-| --- | --- |
-| Markdown highlighting and built-in Shiki transformers | Included as runtime dependencies of `@lupinum/ginko-content`. |
-| MiniSearch backend | Included as a runtime dependency and used by the default search backend. |
-| Pagefind backend | Install the optional `pagefind` peer when `content.search.engine` is `'pagefind'`. |
-| Provider-owned search | No extra package. The active content provider must advertise and implement `search`. |
-| Content i18n | Install and configure `@nuxtjs/i18n` 10.x when the app uses Nuxt locale routes. |
-| Sitemap XML output | Install and configure `@nuxtjs/sitemap`; Ginko contributes the content sitemap source. |
-
-## Scope
-
-The default provider reads files from your Nuxt project. The package does not
-include a CMS UI, Studio, admin panel, or content editing workflow.
-
-## Project links
-
-- Documentation source: [Getting started](https://github.com/lupinum-dev/ginko-content/blob/main/docs/content/docs/3.get-started/1.installation.md)
-- Repository: [github.com/lupinum-dev/ginko-content](https://github.com/lupinum-dev/ginko-content)
-- Issues: [GitHub issues](https://github.com/lupinum-dev/ginko-content/issues)
-- Contributing: [CONTRIBUTING.md](https://github.com/lupinum-dev/ginko-content/blob/main/CONTRIBUTING.md)
-- Security: [SECURITY.md](https://github.com/lupinum-dev/ginko-content/blob/main/SECURITY.md)
-
-## Credits
-
-Ginko Content is an independently maintained fork derived from
-[Nuxt Content](https://content.nuxt.com/). It has substantially diverged while
-retaining upstream-derived parser, MDC, and rendering foundations. Credits also
-go to [Nuxt UI](https://ui.nuxt.com/) and [Comark](https://comark.dev/), the
-successor to the previous MDC work.
+## Main capabilities
+
+- Markdown and Comark component rendering.
+- YAML, JSON, and CSV ingestion.
+- Typed collections and frontmatter.
+- Route-aware pages and server-side queries.
+- Locale-aware routes and fallback rules.
+- Navigation, search, sitemap, and prerender helpers.
+- A provider contract for remote or database-backed sources.
+
+Optional features stay explicit. Install `pagefind`, `katex`, or
+`beautiful-mermaid` only when the application uses the related search, math, or
+diagram integration.
+
+## Documentation
+
+- [Documentation](https://ginko-content.lupinum.com)
+- [Quick start](https://ginko-content.lupinum.com/docs/get-started/quickstart)
+- [Guides](https://ginko-content.lupinum.com/docs/guides)
+- [API reference](https://ginko-content.lupinum.com/docs/reference)
+- [Repository](https://github.com/lupinum-dev/ginko-content)
+
+## Support and security
+
+Open a [GitHub issue](https://github.com/lupinum-dev/ginko-content/issues) for a
+reproducible defect. Join the [Lupinum OSS Discord](https://discord.gg/RPH6SeA36N)
+for usage questions.
+
+Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/lupinum-dev/ginko-content/security/advisories/new).
 
 ## License
 
-[MIT](./LICENSE)
+This package is available under the [MIT License](https://github.com/lupinum-dev/ginko-content/blob/main/LICENSE).
+It is developed by [Lupinum OG](https://lupinum.com).

package/dist/cms-contract/build.js

@@ -1,6 +1,11 @@
 import { getObjectShape, getReferenceDescriptor, getSchemaDef, getSchemaTypeName, unwrapSchema } from "../core/references/schema.js";
 import { getContentFieldMetadata } from "../types/fields.js";
 import { canonicalJsonBytes } from "./hash.js";
+import {
+  canonicalizePortableComponentName,
+  isReservedPortableComponentName,
+  isValidPortableComponentName
+} from "./render-policy.js";
 export const RESOLVED_CONTENT_CONTRACT_VERSION = 1;
 export function buildResolvedContentContract(config, options) {
   const locales = unique(options.locales);
@@ -374,9 +379,19 @@ function portableMediaTypes(values) {
 }
 function normalizeComponentPolicy(policy) {
   const components = {};
-  for (const [componentName, component] of Object.entries(policy.components)) {
-    if (!componentName || eventLike(componentName) || /[:@]/.test(componentName)) {
-      throw new Error(`Invalid portable component name "${componentName}".`);
+  for (const [authoredName, component] of Object.entries(policy.components)) {
+    if (!authoredName || eventLike(authoredName) || /[:@]/.test(authoredName)) {
+      throw new Error(`Invalid portable component name "${authoredName}".`);
+    }
+    const componentName = canonicalizePortableComponentName(authoredName);
+    if (!isValidPortableComponentName(componentName)) {
+      throw new Error(`Invalid portable component name "${authoredName}".`);
+    }
+    if (isReservedPortableComponentName(authoredName)) {
+      throw new Error(`Portable component name "${authoredName}" is reserved.`);
+    }
+    if (!componentName || ["__proto__", "prototype", "constructor"].includes(authoredName.toLowerCase()) || Object.prototype.hasOwnProperty.call(components, componentName)) {
+      throw new Error(`Portable component name "${authoredName}" conflicts after canonicalization.`);
     }
     const props = {};
     for (const [propName, prop] of Object.entries(component.props)) {

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

@@ -15,7 +15,8 @@
  *    (`unwrapSchema`, `getObjectShape`, `getReferenceDescriptor`, ...),
  *  - generate paths consistently with how the filesystem provider does
  *    (`generatePath`, `generateCanonicalKey`, `slugifyUrlSegment`),
- *  - parse MDC into the same AST the filesystem provider uses (`parseMdcBody`).
+ *  - parse MDC with the fixed portable-baseline profile (`parseMdcBody`); site
+ *    filesystem plugins may intentionally produce an enriched AST.
  *
  * If a future change introduces a Node/Nuxt dependency anywhere in this
  * tree, isolate builds will break loudly. That's intentional.

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

@@ -17,7 +17,9 @@ export interface ParseMdcBodyResult {
     searchText: string;
 }
 /**
- * Parse a raw MDC string into a normalized AST + TOC + searchable plaintext.
+ * Parse a raw MDC string with Ginko's fixed portable-baseline profile into a
+ * normalized AST + TOC + searchable plaintext. Site-configured filesystem
+ * plugins are intentionally not applied at this CMS publishing boundary.
  *
  * The function is async because comark's parser is async (frontmatter
  * extraction, plugin pipeline). It is safe to call from a Convex mutation

package/dist/cms-contract/render-policy.d.ts

@@ -17,6 +17,30 @@ export declare class PublicMarkdownValidationError extends Error {
     readonly issues: PublicMarkdownIssue[];
     constructor(issues: PublicMarkdownIssue[]);
 }
+export declare const canonicalizePortableComponentName: (value: string) => string;
+/** Names authored component policies may never claim. */
+export declare const isReservedPortableComponentName: (value: string) => boolean;
+/** Canonical names supported by Comark MDC and Vue component resolution. */
+export declare const isValidPortableComponentName: (value: string) => boolean;
+/** Internal canonical lookup shared by render validation and portable asset traversal. */
+export declare const indexPortableComponentPolicies: (policy: PortableComponentPolicyV1) => Map<string, {
+    kind: "block" | "inline";
+    props: Record<string, {
+        type: "string" | "number" | "boolean" | "json" | "asset";
+        required: boolean;
+    }>;
+    slots: string[];
+    media: {
+        sourceProp: string;
+        altProp: string | null;
+        titleProp: string | null;
+        filenameProp: string | null;
+    } | null;
+}>;
+/** Package-private grammar used only while resolving stored portable assets. */
+export declare const isStoredPortableAssetIdentity: (value: string) => boolean;
 export declare function isSafePublicMarkdownUrl(value: string, kind?: 'href' | 'asset'): boolean;
 export declare function validatePublicMarkdownAst(value: unknown, policy?: PortableComponentPolicyV1): PublicMarkdownValidationResult;
+/** Internal portability entry point; intentionally absent from the public facade. */
+export declare function validateStoredPortableMarkdownAst(value: unknown, policy: PortableComponentPolicyV1): PublicMarkdownValidationResult;
 export declare function assertPublicMarkdownAst(value: unknown, policy?: PortableComponentPolicyV1): asserts value is MarkdownRoot;

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

@@ -1,3 +1,12 @@
+import {
+  isNormalizedTaskCheckboxProps,
+  isNormalizedMathProps,
+  isNormalizedMermaidProps,
+  isSafeCodeHighlights,
+  isSafeTableAlignmentStyle
+} from "../core/markdown/normalize-comark.js";
+import { BUILTIN_MARKDOWN_RENDER_CONTRACTS } from "../core/markdown/builtin-render-contracts.js";
+import { HTML_TAGS } from "../core/markdown/html-tags.js";
 export class PublicMarkdownValidationError extends Error {
   issues;
   constructor(issues) {
@@ -128,12 +137,13 @@ const HTML_PROPS = {
   ins: /* @__PURE__ */ new Set(["cite", "datetime"]),
   li: /* @__PURE__ */ new Set(["value"]),
   ol: /* @__PURE__ */ new Set(["start", "reversed", "type"]),
-  pre: /* @__PURE__ */ new Set(["language", "filename"]),
+  pre: /* @__PURE__ */ new Set(["language", "filename", "meta", "highlights"]),
   td: /* @__PURE__ */ new Set(["colspan", "rowspan", "headers"]),
   th: /* @__PURE__ */ new Set(["colspan", "rowspan", "headers", "scope"]),
   time: /* @__PURE__ */ new Set(["datetime"])
 };
 const URL_PROPS = /* @__PURE__ */ new Set(["href", "src", "cite"]);
+const UNSUPPORTED_NETWORK_PROPS = /* @__PURE__ */ new Set(["ping", "srcset"]);
 const FORBIDDEN_PROPS = /* @__PURE__ */ new Set([
   "__proto__",
   "prototype",
@@ -146,7 +156,20 @@ const FORBIDDEN_PROPS = /* @__PURE__ */ new Set([
   "ref",
   "key"
 ]);
-const componentName = (value) => value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_.\s]+/g, "-").toLowerCase();
+export const canonicalizePortableComponentName = (value) => value.replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_.\s]+/g, "-").toLowerCase();
+const BUILTIN_RENDER_TAGS = new Set(
+  Object.values(BUILTIN_MARKDOWN_RENDER_CONTRACTS).map((contract) => contract.tag)
+);
+export const isReservedPortableComponentName = (value) => {
+  const name = canonicalizePortableComponentName(value);
+  const nativeName = value.toLowerCase();
+  return nativeName === "template" || ACTIVE_TAGS.has(nativeName) || BUILTIN_RENDER_TAGS.has(name);
+};
+export const isValidPortableComponentName = (value) => /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value);
+export const indexPortableComponentPolicies = (policy) => new Map(
+  Object.entries(policy.components).map(([name, component]) => [canonicalizePortableComponentName(name), component])
+);
+export const isStoredPortableAssetIdentity = (value) => /^[a-z0-9;:_-]{1,512}$/i.test(value) && !/^(?:javascript|vbscript|data|file|https?):/i.test(value);
 const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 const isSafeBindingValue = (value) => {
   if (value === null || ["string", "number", "boolean"].includes(typeof value)) return true;
@@ -208,19 +231,52 @@ export function isSafePublicMarkdownUrl(value, kind = "href") {
     return false;
   }
 }
-export function validatePublicMarkdownAst(value, policy = { components: {} }) {
+function validateMarkdownAst(value, policy, allowStoredAssets) {
   const issues = [];
   const report = (code, path, message) => issues.push({ code, path, message });
-  const components = new Map(
-    Object.entries(policy.components).map(([name, component]) => [componentName(name), component])
-  );
+  const components = indexPortableComponentPolicies(policy);
+  const validatePropInvariant = (tag, name, value2, path, component) => {
+    const declaredAsAsset = component?.props[name]?.type === "asset";
+    if (declaredAsAsset && typeof value2 === "string") {
+      const storedAsset2 = allowStoredAssets && isStoredPortableAssetIdentity(value2);
+      if (!storedAsset2 && !isSafePublicMarkdownUrl(value2, "asset")) {
+        report("unsafe_url", path, `Component property "${name}" contains an unsafe URL.`);
+      }
+    }
+    if (!HTML_TAGS.has(tag)) return;
+    const lower = name.toLowerCase();
+    if (tag === "pre" && (name === "language" || name === "filename" || name === "meta") && typeof value2 !== "string") {
+      report("invalid_prop_value", path, `HTML property "${name}" on <pre> must be a string.`);
+    }
+    if (tag === "pre" && name === "highlights" && !isSafeCodeHighlights(value2)) {
+      report("invalid_prop_value", path, 'HTML property "highlights" on <pre> contains invalid line numbers.');
+    }
+    if (tag === "pre" && name === "meta" && typeof value2 === "string" && value2.length > 2048) {
+      report("invalid_prop_value", path, 'HTML property "meta" on <pre> is too long.');
+    }
+    if (UNSUPPORTED_NETWORK_PROPS.has(lower)) {
+      report("unsafe_prop", path, `Native network property "${name}" is not supported by the portable policy.`);
+      return;
+    }
+    if (!URL_PROPS.has(lower)) return;
+    if (typeof value2 !== "string") {
+      report("invalid_prop_value", path, `HTML URL property "${name}" must be a string.`);
+      return;
+    }
+    if (declaredAsAsset) return;
+    const storedAsset = allowStoredAssets && tag === "img" && lower === "src" && isStoredPortableAssetIdentity(value2);
+    const kind = lower === "src" ? "asset" : "href";
+    if (!storedAsset && !isSafePublicMarkdownUrl(value2, kind)) {
+      report("unsafe_url", path, `Property "${name}" contains an unsafe URL.`);
+    }
+  };
   const validateProps = (node, path, component) => {
     const props = node.props ?? {};
     if (!isRecord(props)) {
       report("invalid_node", [...path, "props"], "Node props must be an object.");
       return;
     }
-    const tag = String(node.tag);
+    const tag = String(node.tag).toLowerCase();
     for (const [name, propValue] of Object.entries(props)) {
       const propPath = [...path, "props", name];
       const lower = name.toLowerCase();
@@ -229,6 +285,7 @@ export function validatePublicMarkdownAst(value, policy = { components: {} }) {
         continue;
       }
       if (name === "style" && tag === "span" && isSafeShikiStyle(propValue)) continue;
+      if ((tag === "th" || tag === "td") && name === "style" && isSafeTableAlignmentStyle(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;
@@ -241,6 +298,7 @@ export function validatePublicMarkdownAst(value, policy = { components: {} }) {
         report("invalid_prop_value", propPath, `Property "${name}" is not JSON-safe.`);
         continue;
       }
+      validatePropInvariant(tag, name, propValue, propPath, component);
       if (component) {
         const declared = component.props[name];
         if (!declared) {
@@ -249,9 +307,6 @@ export function validatePublicMarkdownAst(value, policy = { components: {} }) {
         }
         const valid = declared.type === "json" || declared.type === "asset" && typeof propValue === "string" && propValue.length > 0 || declared.type !== "asset" && typeof propValue === declared.type;
         if (!valid) report("invalid_prop_value", propPath, `Component property "${name}" has the wrong type.`);
-        else if (declared.type === "asset" && !isSafePublicMarkdownUrl(propValue, "asset")) {
-          report("unsafe_url", propPath, `Component property "${name}" contains an unsafe URL.`);
-        }
         continue;
       }
       const allowed = COMMON_HTML_PROPS.has(name) || name.startsWith("aria-") || name.startsWith("data-") || HTML_PROPS[tag]?.has(name);
@@ -259,16 +314,6 @@ export function validatePublicMarkdownAst(value, policy = { components: {} }) {
         report("unknown_prop", propPath, `HTML property "${name}" is not allowed on <${tag}>.`);
         continue;
       }
-      if (tag === "pre" && (name === "language" || name === "filename") && typeof propValue !== "string") {
-        report("invalid_prop_value", propPath, `HTML property "${name}" on <pre> must be a string.`);
-        continue;
-      }
-      if (URL_PROPS.has(lower) && typeof propValue === "string") {
-        const kind = lower === "src" ? "asset" : "href";
-        if (!isSafePublicMarkdownUrl(propValue, kind)) {
-          report("unsafe_url", propPath, `Property "${name}" contains an unsafe URL.`);
-        }
-      }
     }
     if (component) {
       for (const [name, definition] of Object.entries(component.props)) {
@@ -278,7 +323,7 @@ export function validatePublicMarkdownAst(value, policy = { components: {} }) {
       }
     }
   };
-  const visit = (node, path) => {
+  const visit = (node, path, parentComponent) => {
     if (!isRecord(node) || typeof node.type !== "string") {
       report("invalid_node", path, "Markdown nodes must be objects with a type.");
       return;
@@ -297,15 +342,39 @@ export function validatePublicMarkdownAst(value, policy = { components: {} }) {
     if (Object.keys(node).some((key) => !["type", "tag", "props", "children"].includes(key))) {
       report("invalid_node", path, "Element nodes contain unsupported fields.");
     }
-    const normalizedTag = componentName(node.tag);
+    const normalizedTag = canonicalizePortableComponentName(node.tag);
+    const nativeTag = node.tag.toLowerCase();
+    if (nativeTag === "template") {
+      if (node.tag !== "template") {
+        report("unsafe_tag", [...path, "tag"], "Named slot template tags must use the canonical lowercase spelling.");
+        node.children.forEach((child, index) => visit(child, [...path, "children", index]));
+        return;
+      }
+      const props = node.props ?? {};
+      const slotName = isRecord(props) && Object.keys(props).length === 1 && typeof props.name === "string" ? props.name : void 0;
+      if (!parentComponent || !slotName || !parentComponent.slots.includes(slotName)) {
+        report("unsafe_tag", [...path, "tag"], "Named slot templates must be direct children of a component and declare an allowed slot name.");
+      }
+      node.children.forEach((child, index) => visit(child, [...path, "children", index]));
+      return;
+    }
     const component = components.get(normalizedTag);
-    if (ACTIVE_TAGS.has(normalizedTag)) {
+    const exactMathNode = isNormalizedMathProps(node.props) && node.children.length === 1 && isExactTextNode(node.children[0], node.props.content);
+    const exactMermaidNode = isNormalizedMermaidProps(node.props) && node.children.length === 0;
+    if (normalizedTag === BUILTIN_MARKDOWN_RENDER_CONTRACTS.math.tag && component && !exactMathNode) {
+      report("invalid_prop_value", path, "Generated Math node is malformed.");
+    }
+    if (normalizedTag === BUILTIN_MARKDOWN_RENDER_CONTRACTS.mermaid.tag && component && !exactMermaidNode) {
+      report("invalid_prop_value", path, "Generated Mermaid node is malformed.");
+    }
+    const isTaskCheckbox = nativeTag === "input" && isNormalizedTaskCheckboxProps(node.props) && node.children.length === 0;
+    if (ACTIVE_TAGS.has(nativeTag) && !isTaskCheckbox) {
       report("unsafe_tag", [...path, "tag"], `Tag <${node.tag}> is not render-safe.`);
-    } else if (!SAFE_HTML_TAGS.has(normalizedTag) && !component) {
+    } else if (!isTaskCheckbox && !SAFE_HTML_TAGS.has(nativeTag) && !component) {
       report("unknown_component", [...path, "tag"], `Component <${node.tag}> is not registered.`);
     }
-    validateProps(node, path, component);
-    node.children.forEach((child, index) => visit(child, [...path, "children", index]));
+    if (!isTaskCheckbox) validateProps(node, path, component);
+    node.children.forEach((child, index) => visit(child, [...path, "children", index], component));
   };
   if (!isRecord(value) || value.type !== "root" || !Array.isArray(value.children)) {
     report("invalid_node", [], "Markdown root must contain a children array.");
@@ -320,7 +389,14 @@ export function validatePublicMarkdownAst(value, policy = { components: {} }) {
   }
   return issues.length ? { ok: false, issues } : { ok: true, value };
 }
+export function validatePublicMarkdownAst(value, policy = { components: {} }) {
+  return validateMarkdownAst(value, policy, false);
+}
+export function validateStoredPortableMarkdownAst(value, policy) {
+  return validateMarkdownAst(value, policy, true);
+}
 export function assertPublicMarkdownAst(value, policy = { components: {} }) {
   const result = validatePublicMarkdownAst(value, policy);
   if (!result.ok) throw new PublicMarkdownValidationError(result.issues);
 }
+const isExactTextNode = (value, expected) => isRecord(value) && Object.keys(value).length === 2 && value.type === "text" && value.value === expected;

package/dist/cms-contract/validate.js

@@ -1,4 +1,9 @@
 import { canonicalJsonBytes } from "./hash.js";
+import {
+  canonicalizePortableComponentName,
+  isReservedPortableComponentName,
+  isValidPortableComponentName
+} from "./render-policy.js";
 const fieldTypes = /* @__PURE__ */ new Set([
   "text",
   "textarea",
@@ -163,7 +168,11 @@ function validateFieldPolicy(input, path) {
 function componentPolicy(value, path) {
   const input = record(value, path);
   exact(input, ["components"], path);
+  const canonicalNames = /* @__PURE__ */ new Set();
   for (const [name, rawComponent] of Object.entries(record(input.components, `${path}.components`))) {
+    const canonicalName = canonicalizePortableComponentName(name);
+    if (!canonicalName || name !== canonicalName || !isValidPortableComponentName(canonicalName) || isReservedPortableComponentName(canonicalName) || ["__proto__", "prototype", "constructor"].includes(name.toLowerCase()) || canonicalNames.has(canonicalName)) throw new Error(`${path}.components.${name} conflicts after canonicalization.`);
+    canonicalNames.add(canonicalName);
     const component = record(rawComponent, `${path}.components.${name}`);
     exact(component, ["kind", "props", "slots", "media"], `${path}.components.${name}`);
     if (!["block", "inline"].includes(String(component.kind))) throw new Error(`${path}.components.${name}.kind is invalid.`);

package/dist/core/content/graph.js

@@ -1,11 +1,13 @@
 import { isNavigationFile } from "./structural.js";
 import { normalizeReferenceValue, buildReferenceTargets } from "../references/resolve.js";
 import { resolveLocaleChain, sortLocalesCanonically } from "./locale.js";
+import { trimTrailingSlashes } from "./path.js";
 const normalizePath = (path) => {
   if (!path || path === "/") {
     return "/";
   }
-  return path.startsWith("/") ? path.endsWith("/") ? path.slice(0, -1) || "/" : path : `/${path.replace(/\/+$/, "")}`;
+  const normalized = trimTrailingSlashes(path) || "/";
+  return normalized.startsWith("/") ? normalized : `/${normalized}`;
 };
 export const buildContentGraph = (documents, options = {}) => {
   const byId = {};

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

@@ -1,7 +1,9 @@
+export declare const trimSlashes: (value: string) => string;
+export declare const trimTrailingSlashes: (value: string) => string;
 export declare const describeId: (id: string) => {
     source: string;
     path: string;
-    extension: string;
+    extension: string | undefined;
     file: string;
     basename: string;
 };