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

package/README.md

@@ -10,7 +10,8 @@ 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 stable `0.3` line.
+This README describes the `0.4.0-rc.1` release candidate. Install it from npm's
+`next` channel; the stable line remains `0.3` until the RC is promoted.
 
 ## Requirements
 
@@ -22,14 +23,14 @@ This README describes the stable `0.3` line.
 ## Install
 
 ```bash
-npx nuxi module add @lupinum/ginko-content
+npx nuxi module add @lupinum/ginko-content@0.4.0-rc.1
 ```
 
 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
+pnpm add @lupinum/ginko-content@0.4.0-rc.1
 ```
 
 ```ts
@@ -80,7 +81,13 @@ Render the current route through the collection:
 <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>
@@ -99,7 +106,7 @@ const { page } = await 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
+- route and search composables, plus one-shot async client query functions for other
   reads
 - search helpers for MiniSearch, Pagefind, and provider-owned search
 - sitemap integration for public content routes
@@ -121,19 +128,25 @@ Do not duplicate docs, blog, pricing, privacy, or translated locale paths in
 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).
+[Sitemap and prerender](https://github.com/lupinum-dev/ginko-content/blob/main/docs/content/docs/4.guides/9.sitemap-and-prerender.md).
 
 ## Integration Dependencies
 
 | Feature | Dependency model |
 | --- | --- |
 | Markdown highlighting and built-in Shiki transformers | Included as runtime dependencies of `@lupinum/ginko-content`. |
+| Math Markdown | Install the optional `katex` peer and add `katex/dist/katex.min.css` to Nuxt's `css` array. |
+| Mermaid Markdown | Install the optional `beautiful-mermaid` peer. |
 | 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. |
 
+Markdown plugins are opt-in. Omitting `content.markdown.plugins` is identical
+to `plugins: []`; add `shiki`, `math`, `mermaid`, `toc`, or `summary` only when
+the application needs that behavior.
+
 ## Scope
 
 The default provider reads files from your Nuxt project. The package does not
@@ -141,7 +154,7 @@ 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)
+- Documentation source: [Getting started](https://github.com/lupinum-dev/ginko-content/blob/main/docs/content/docs/1.get-started/1.quickstart.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)

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/markdown/builtin-render-contracts.d.ts

@@ -0,0 +1,35 @@
+/** Framework-neutral public shapes emitted by configured built-in parsers. */
+export declare const BUILTIN_MARKDOWN_RENDER_CONTRACTS: {
+    readonly math: {
+        readonly tag: "ginko-math";
+        readonly componentPolicy: {
+            kind: "inline";
+            props: {
+                class: {
+                    type: "string";
+                    required: true;
+                };
+                content: {
+                    type: "string";
+                    required: true;
+                };
+            };
+            slots: never[];
+            media: null;
+        };
+    };
+    readonly mermaid: {
+        readonly tag: "ginko-mermaid";
+        readonly componentPolicy: {
+            kind: "block";
+            props: {
+                content: {
+                    type: "string";
+                    required: true;
+                };
+            };
+            slots: never[];
+            media: null;
+        };
+    };
+};

package/dist/core/markdown/builtin-render-contracts.js

@@ -0,0 +1,25 @@
+export const BUILTIN_MARKDOWN_RENDER_CONTRACTS = {
+  math: {
+    tag: "ginko-math",
+    componentPolicy: {
+      kind: "inline",
+      props: {
+        class: { type: "string", required: true },
+        content: { type: "string", required: true }
+      },
+      slots: [],
+      media: null
+    }
+  },
+  mermaid: {
+    tag: "ginko-mermaid",
+    componentPolicy: {
+      kind: "block",
+      props: {
+        content: { type: "string", required: true }
+      },
+      slots: [],
+      media: null
+    }
+  }
+};

package/dist/core/markdown/html-tags.d.ts

@@ -0,0 +1 @@
+export declare const HTML_TAGS: ReadonlySet<string>;

package/dist/{integrations/vue → core/markdown}/html-tags.js

@@ -1,4 +1,4 @@
-export default [
+export const HTML_TAGS = /* @__PURE__ */ new Set([
   "a",
   "abbr",
   "address",
@@ -116,4 +116,4 @@ export default [
   "var",
   "video",
   "wbr"
-];
+]);

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

@@ -1,6 +1,14 @@
+import type { NormalizedComarkNode } from './tree';
 /**
  * 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[];
+export declare function normalizeComarkNodes(nodes: unknown[], options?: {
+    enabledPlugins?: Iterable<string>;
+}): NormalizedComarkNode[];
+export declare const isNormalizedMathProps: (value: unknown) => boolean;
+export declare const isNormalizedMermaidProps: (value: unknown) => boolean;
+export declare const isNormalizedTaskCheckboxProps: (value: unknown) => boolean;
+export declare const isSafeTableAlignmentStyle: (value: unknown) => boolean;
+export declare const isSafeCodeHighlights: (value: unknown) => boolean;

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

@@ -1,15 +1,67 @@
 const GFM_ALERTS = /* @__PURE__ */ new Set(["note", "tip", "important", "warning", "caution"]);
-export function normalizeComarkNodes(nodes) {
+const TASK_CHECKBOX_CLASS = "task-list-item-checkbox";
+const TABLE_ALIGNMENT = /^text-align:(?:left|center|right)$/;
+const MAX_CODE_HIGHLIGHTS = 256;
+const MAX_CODE_LINE = 1e6;
+export function normalizeComarkNodes(nodes, options = {}) {
+  const enabledPlugins = new Set(options.enabledPlugins);
   const normalize = (node) => {
-    if (!Array.isArray(node)) return node;
+    if (typeof node === "string") return node;
+    if (!Array.isArray(node)) throw new TypeError("Comark emitted a malformed Markdown node.");
     const [tag, rawProps, ...children] = node;
-    const props = isRecord(rawProps) ? { ...rawProps } : rawProps;
+    if (tag === null) return void 0;
+    if (typeof tag !== "string" || rawProps !== void 0 && !isRecord(rawProps)) {
+      throw new TypeError("Comark emitted a malformed Markdown tuple.");
+    }
+    const props = isRecord(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)];
+    if (tag === "input" && isComarkTaskCheckboxProps(props)) {
+      delete props[":checked"];
+      delete props[":disabled"];
+      props.disabled = true;
+      if (rawProps && isRecord(rawProps) && rawProps[":checked"] === "true") props.checked = true;
+    }
+    if (tag === "math" && enabledPlugins.has("math") && isComarkMathNode(props, children)) {
+      return ["ginko-math", props, ...children];
+    }
+    if (tag === "mermaid" && enabledPlugins.has("mermaid") && isComarkMermaidNode(props, children)) {
+      return ["ginko-mermaid", props];
+    }
+    return [tag, props, ...children.map(normalize).filter(isPresent)];
   };
-  return nodes.map(normalize);
+  return nodes.map(normalize).filter(isPresent);
 }
+export const isNormalizedMathProps = (value) => {
+  if (!isRecord(value)) return false;
+  const keys = Object.keys(value).sort();
+  return keys.length === 2 && keys[0] === "class" && keys[1] === "content" && (value.class === "math inline" || value.class === "math block") && typeof value.content === "string";
+};
+export const isNormalizedMermaidProps = (value) => {
+  if (!isRecord(value)) return false;
+  const keys = Object.keys(value);
+  return keys.length === 1 && keys[0] === "content" && typeof value.content === "string";
+};
+export const isNormalizedTaskCheckboxProps = (value) => {
+  if (!isRecord(value)) return false;
+  const keys = Object.keys(value).sort();
+  const expected = value.checked === true ? ["checked", "class", "disabled", "type"] : ["class", "disabled", "type"];
+  return keys.length === expected.length && keys.every((key, index) => key === expected[index]) && value.type === "checkbox" && value.class === TASK_CHECKBOX_CLASS && value.disabled === true;
+};
+export const isSafeTableAlignmentStyle = (value) => typeof value === "string" && TABLE_ALIGNMENT.test(value);
+export const isSafeCodeHighlights = (value) => Array.isArray(value) && value.length <= MAX_CODE_HIGHLIGHTS && value.every(
+  (line) => Number.isSafeInteger(line) && Number(line) > 0 && Number(line) <= MAX_CODE_LINE
+);
+const isComarkTaskCheckboxProps = (value) => {
+  if (!isRecord(value)) return false;
+  const keys = Object.keys(value).sort();
+  const checked = value[":checked"] === "true";
+  const expected = checked ? [":checked", ":disabled", "class", "type"] : [":disabled", "class", "type"];
+  return keys.length === expected.length && keys.every((key, index) => key === expected[index]) && value[":disabled"] === "true" && value.type === "checkbox" && value.class === TASK_CHECKBOX_CLASS;
+};
+const isComarkMathNode = (props, children) => isNormalizedMathProps(props) && children.length === 1 && children[0] === props.content;
+const isComarkMermaidNode = (props, children) => isNormalizedMermaidProps(props) && children.length === 0;
+const isPresent = (value) => value !== void 0;
 const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);

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

@@ -1,3 +1,7 @@
+import { createMarkdownParser } from 'comark';
 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>>>;
+export type ComarkParser = ReturnType<typeof createMarkdownParser>;
+/** Create one parser for one resolved plugin-profile lifecycle. */
+export declare const createComarkParser: (plugins?: readonly ComarkPlugin[]) => import("comark").ComarkParseFn<Record<string, any>, Record<string, any>>;
+/** The fixed-profile Comark entry point used by baseline parsing boundaries. */
+export declare const parseComark: (markdown: string) => Promise<import("comark").MarkdownDocument<Record<string, any>, Record<string, any>>>;

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

@@ -1,4 +1,4 @@
-import { createParse, defineComarkPlugin, parseFrontmatter } from "comark";
+import { createMarkdownParser, defineComarkPlugin, parseFrontmatter } from "comark";
 const typedComponentFrontmatter = defineComarkPlugin(() => ({
   name: "ginko-typed-component-frontmatter",
   markdownItPlugins: [
@@ -22,9 +22,8 @@ const typedComponentFrontmatter = defineComarkPlugin(() => ({
     }
   ]
 }));
-export const parseComark = async (markdown, plugins = []) => {
-  const parse = createParse({
-    plugins: [typedComponentFrontmatter(), ...plugins]
-  });
-  return await parse(markdown);
-};
+export const createComarkParser = (plugins = []) => createMarkdownParser({
+  plugins: [typedComponentFrontmatter(), ...plugins]
+});
+const baselineComarkParser = createComarkParser();
+export const parseComark = async (markdown) => await baselineComarkParser(markdown);

package/dist/core/markdown/tree.d.ts

@@ -1,9 +1,9 @@
 import type { MarkdownNode, MarkdownRoot, Toc } from '../../types/content';
-type ComarkTupleNode = string | [string | null, Record<string, unknown>, ...ComarkTupleNode[]];
+/** The exact normalized tuple shape accepted at the Comark boundary. */
+export type NormalizedComarkNode = string | [string, Record<string, unknown>, ...NormalizedComarkNode[]];
 export declare function isMarkdownRoot(value: unknown): value is MarkdownRoot;
-export declare function toMarkdownNode(node: ComarkTupleNode): MarkdownNode;
-export declare function toMarkdownRoot(nodes: ComarkTupleNode[], toc?: Toc): MarkdownRoot;
+export declare function toMarkdownNode(node: NormalizedComarkNode): MarkdownNode;
+export declare function toMarkdownRoot(nodes: NormalizedComarkNode[], toc?: Toc): MarkdownRoot;
 export declare function mapMarkdownNodes(nodes: MarkdownNode[], mapNode: (node: MarkdownNode) => MarkdownNode): MarkdownNode[];
 export declare function mapMarkdownNode(node: MarkdownNode, mapNode: (node: MarkdownNode) => MarkdownNode): MarkdownNode;
 export declare function extractMarkdownText(node: MarkdownNode, ignoredTags?: string[]): string;
-export {};

package/dist/core/markdown/tree.js

@@ -13,9 +13,7 @@ export function toMarkdownNode(node) {
   const [tag, props = {}, ...children] = node;
   return {
     type: "element",
-    // `undefined` is not a JSON-pure value: omit `tag` entirely
-    // rather than set it to `undefined` when the tuple carries no tag.
-    ...tag ? { tag } : {},
+    tag,
     props: { ...props },
     children: children.map((child) => toMarkdownNode(child))
   };