comark 0.3.2 → 0.4.0

package/dist/internal/stringify/handlers/template.js

@@ -1,3 +1,4 @@
+import { comarkAttributes } from "../attributes.js";
 // slot template
 export async function template(node, state, parent) {
     const [_, attrs] = node;
@@ -10,5 +11,7 @@ export async function template(node, state, parent) {
             return content + state.context.blockSeparator;
         }
     }
-    return `#${attrs.name}\n${content}` + state.context.blockSeparator;
+    const { name: _name, $: _$, ...rest } = attrs;
+    const extraAttrs = comarkAttributes(rest);
+    return `#${attrs.name}${extraAttrs}\n${content}` + state.context.blockSeparator;
 }

package/dist/internal/stringify/handlers/ul.js

@@ -1,4 +1,5 @@
 import { indent } from "../../../utils/index.js";
+import { comarkAttributes, userBlockAttrs } from "../attributes.js";
 export async function ul(node, state) {
     const children = node.slice(2);
     const revert = state.applyContext({ list: true, order: false, listIndent: 2 });
@@ -7,12 +8,21 @@ export async function ul(node, state) {
         result += await state.one(child, state);
     }
     result = result.trim();
+    state.applyContext(revert);
+    // ul with user attrs round-trips via `::ul{attrs}\n- …\n::` — the native
+    // markdown list syntax has no slot for list-level attrs.
+    const attrs = comarkAttributes(userBlockAttrs('ul', node[1]));
+    if (attrs) {
+        if (revert.list) {
+            return '\n' + indent(`::ul${attrs}\n${result}\n::`, { width: revert.listIndent || 2 });
+        }
+        return `::ul${attrs}\n${result}\n::` + state.context.blockSeparator;
+    }
     if (revert.list) {
         result = '\n' + indent(result, { width: revert.listIndent || 2 });
     }
     else {
         result = result + state.context.blockSeparator;
     }
-    state.applyContext(revert);
     return result;
 }

package/dist/parse.d.ts

@@ -1,4 +1,4 @@
-import type { ComarkParseFn, ParseOptions, ComarkTree } from './types.ts';
+import type { ComarkParseFn, ComarkPlugin, MergePluginFrontmatter, MergePluginMeta, ParseOptions, ResolvedFrontmatter, ResolvedMeta, ComarkTree } from './types.ts';
 export { parseFrontmatter } from './internal/frontmatter.ts';
 export { defineComarkPlugin } from './utils/helpers.ts';
 /**
@@ -30,7 +30,7 @@ export { defineComarkPlugin } from './utils/helpers.ts';
  * const parseNoHtml = createParse({ html: false })
  * ```
  */
-export declare function createParse(options?: ParseOptions): ComarkParseFn;
+export declare function createParse<const TPlugins extends readonly ComarkPlugin<any, any>[] = []>(options?: ParseOptions<TPlugins>): ComarkParseFn<ResolvedMeta<MergePluginMeta<TPlugins>>, ResolvedFrontmatter<MergePluginFrontmatter<TPlugins>>>;
 /**
  * Parse Comark content from a string
  *
@@ -64,7 +64,7 @@ export declare function createParse(options?: ParseOptions): ComarkParseFn;
  * const tree2 = await parse(content, { autoUnwrap: false })
  * ```
  */
-export declare function parse(markdown: string, options?: ParseOptions): Promise<ComarkTree>;
+export declare function parse<const TPlugins extends readonly ComarkPlugin<any, any>[] = []>(markdown: string, options?: ParseOptions<TPlugins>): Promise<ComarkTree<ResolvedMeta<MergePluginMeta<TPlugins>>, ResolvedFrontmatter<MergePluginFrontmatter<TPlugins>>>>;
 /**
  * Creates a serialized parser function for Comark content.
  * This is useful for parsing large files in a streaming manner.
@@ -80,4 +80,4 @@ export declare function parse(markdown: string, options?: ParseOptions): Promise
  * const tree = await parse(content)
  * console.log(tree.nodes)
  */
-export declare function createSerializedParse(options?: ParseOptions): ComarkParseFn;
+export declare function createSerializedParse<const TPlugins extends readonly ComarkPlugin<any, any>[] = []>(options?: ParseOptions<TPlugins>): ComarkParseFn<ResolvedMeta<MergePluginMeta<TPlugins>>, ResolvedFrontmatter<MergePluginFrontmatter<TPlugins>>>;

package/dist/parse.js

@@ -44,7 +44,10 @@ export { defineComarkPlugin } from "./utils/helpers.js";
  * ```
  */
 export function createParse(options = {}) {
-    const { autoUnwrap = true, autoClose = true, plugins = [] } = options;
+    const { autoUnwrap = true, autoClose = true } = options;
+    // Make a mutable working copy so the inferred (possibly readonly) user tuple
+    // isn't mutated by the unshift calls below.
+    const plugins = options.plugins ? [...options.plugins] : [];
     plugins.unshift(syntax());
     plugins.unshift(taskList());
     plugins.unshift(alert());
@@ -65,7 +68,7 @@ export function createParse(options = {}) {
     }
     let lastOutput = null;
     let lastInput = null;
-    return async (markdown, opts = {}) => {
+    const parseFn = async (markdown, opts = {}) => {
         const state = {
             options,
             tokens: [],
@@ -143,6 +146,7 @@ export function createParse(options = {}) {
         }
         return state.tree;
     };
+    return parseFn;
 }
 /**
  * Parse Comark content from a string

package/dist/plugins/alert.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("comark").ComarkPluginFactory<unknown>;
+declare const _default: import("comark").ComarkPluginFactory<unknown, {}, {}>;
 export default _default;

package/dist/plugins/binding.d.ts

@@ -7,7 +7,7 @@ export interface MdcInlineBindingOptions {
      */
     tag?: string;
 }
-declare const _default: import("../types").ComarkPluginFactory<MdcInlineBindingOptions>;
+declare const _default: import("../types").ComarkPluginFactory<MdcInlineBindingOptions, {}, {}>;
 export default _default;
 /**
  * Markdown-format handler that renders a `binding` node back to the

package/dist/plugins/breaks.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("../types.ts").ComarkPluginFactory<unknown>;
+declare const _default: import("../types.ts").ComarkPluginFactory<unknown, {}, {}>;
 export default _default;

package/dist/plugins/emoji.d.ts

@@ -1,4 +1,4 @@
 import type { MarkdownItPlugin } from 'comark';
 export declare const markdownItEmoji: MarkdownItPlugin;
-declare const _default: import("comark").ComarkPluginFactory<unknown>;
+declare const _default: import("comark").ComarkPluginFactory<unknown, {}, {}>;
 export default _default;

package/dist/plugins/footnotes.d.ts

@@ -35,7 +35,7 @@ export interface FootnotesConfig {
  * })
  * ```
  */
-declare const _default: import("comark").ComarkPluginFactory<FootnotesConfig>;
+declare const _default: import("comark").ComarkPluginFactory<FootnotesConfig, {}, {}>;
 export default _default;
 /**
  * Conditional stringify handler for footnotes.

package/dist/plugins/headings.d.ts

@@ -1,15 +1,17 @@
 export interface HeadingsOptions {
     /**
      * Tag to extract as title and set to `tree.meta.title`.
+     * Set to `false` to disable title extraction.
      * @default 'h1'
      */
-    titleTag?: string;
+    titleTag?: string | false;
     /**
      * Tag to extract as description and set to `tree.meta.description`.
      * Useful alternatives: `'blockquote'`
+     * Set to `false` to disable description extraction.
      * @default 'p'
      */
-    descriptionTag?: string;
+    descriptionTag?: string | false;
     /**
      * Whether to remove the extracted nodes from the tree.
      * @default false
@@ -29,20 +31,29 @@ export interface HeadingsOptions {
  *    content is written to `tree.meta.description`. When no title was found,
  *    this check starts from the very first content node.
  *
- * Both nodes are removed from the tree by default so they are not rendered
- * twice. Set `remove: false` to keep them in place.
+ * By default the extracted nodes are kept in the tree. Set `remove: true`
+ * to strip them so they are not rendered twice.
  *
  * @example
  * ```ts
- * // Default — h1 as title, first paragraph as description
+ * // Default — h1 as title, first paragraph as description, nodes kept in tree
  * headings()
  *
  * // Use a blockquote as the description instead of a paragraph
  * headings({ descriptionTag: 'blockquote' })
  *
- * // Extract metadata without removing the nodes from the tree
- * headings({ remove: false })
+ * // Extract metadata and remove the matched nodes from the tree
+ * headings({ remove: true })
+ *
+ * // Disable title extraction, only extract description
+ * headings({ titleTag: false })
+ *
+ * // Disable description extraction, only extract title
+ * headings({ descriptionTag: false })
  * ```
  */
-declare const _default: import("comark").ComarkPluginFactory<HeadingsOptions>;
+declare const _default: import("comark").ComarkPluginFactory<HeadingsOptions, {
+    title?: string;
+    description?: string;
+}, {}>;
 export default _default;

package/dist/plugins/headings.js

@@ -35,19 +35,25 @@ function flattenNodeText(node) {
  *    content is written to `tree.meta.description`. When no title was found,
  *    this check starts from the very first content node.
  *
- * Both nodes are removed from the tree by default so they are not rendered
- * twice. Set `remove: false` to keep them in place.
+ * By default the extracted nodes are kept in the tree. Set `remove: true`
+ * to strip them so they are not rendered twice.
  *
  * @example
  * ```ts
- * // Default — h1 as title, first paragraph as description
+ * // Default — h1 as title, first paragraph as description, nodes kept in tree
  * headings()
  *
  * // Use a blockquote as the description instead of a paragraph
  * headings({ descriptionTag: 'blockquote' })
  *
- * // Extract metadata without removing the nodes from the tree
- * headings({ remove: false })
+ * // Extract metadata and remove the matched nodes from the tree
+ * headings({ remove: true })
+ *
+ * // Disable title extraction, only extract description
+ * headings({ titleTag: false })
+ *
+ * // Disable description extraction, only extract title
+ * headings({ descriptionTag: false })
  * ```
  */
 export default defineComarkPlugin((options = {}) => {
@@ -60,17 +66,21 @@ export default defineComarkPlugin((options = {}) => {
             const contentNodes = nodes.filter((node) => Array.isArray(node) && getTag(node) !== 'hr');
             let titleNodeIndex = -1;
             let descriptionNodeIndex = -1;
-            const first = contentNodes[0];
-            if (first && getTag(first) === titleTag) {
-                titleNodeIndex = nodes.indexOf(first);
-                state.tree.meta.title = flattenNodeText(first);
+            let nextContentIndex = 0;
+            if (titleTag !== false) {
+                const first = contentNodes[0];
+                if (first && getTag(first) === titleTag) {
+                    titleNodeIndex = nodes.indexOf(first);
+                    state.tree.meta.title = flattenNodeText(first);
+                    nextContentIndex = 1;
+                }
             }
-            // Description is the first content node after the (optional) title
-            const afterTitle = titleNodeIndex !== -1 ? contentNodes.slice(1) : contentNodes;
-            const second = afterTitle[0];
-            if (second && getTag(second) === descriptionTag) {
-                descriptionNodeIndex = nodes.indexOf(second);
-                state.tree.meta.description = flattenNodeText(second);
+            if (descriptionTag !== false) {
+                const candidate = contentNodes[nextContentIndex];
+                if (candidate && getTag(candidate) === descriptionTag) {
+                    descriptionNodeIndex = nodes.indexOf(candidate);
+                    state.tree.meta.description = flattenNodeText(candidate);
+                }
             }
             if (remove) {
                 // Remove in reverse order to preserve indices

package/dist/plugins/highlight.d.ts

@@ -56,5 +56,5 @@ export declare function highlightCodeBlocks(tree: ComarkTree, options?: Highligh
  * Useful for testing or when you want to reconfigure
  */
 export declare function resetHighlighter(): void;
-declare const _default: import("comark").ComarkPluginFactory<HighlightOptions>;
+declare const _default: import("comark").ComarkPluginFactory<HighlightOptions, {}, {}>;
 export default _default;

package/dist/plugins/highlight.js

@@ -278,9 +278,12 @@ export async function highlightCodeBlocks(tree, options = {}) {
                 line += 1;
             }
         }
+        // Merge highlighter class with any user-supplied class (e.g. from
+        // `::pre{.user-class}`) so the wrapper's class isn't lost.
+        const userClass = typeof preAttrs.class === 'string' ? preAttrs.class.trim() : '';
         const newPreAttrs = {
             ...preAttrs,
-            class: classStr,
+            class: userClass ? `${classStr} . ${userClass}` : classStr,
             tabindex: '0',
         };
         if (options.preStyles) {

package/dist/plugins/json-render.d.ts

@@ -49,5 +49,5 @@ interface JsonRenderConfig {
  * </template>
  * ```
  */
-declare const _default: import("../types").ComarkPluginFactory<JsonRenderConfig>;
+declare const _default: import("../types").ComarkPluginFactory<JsonRenderConfig, {}, {}>;
 export default _default;

package/dist/plugins/math.d.ts

@@ -55,5 +55,5 @@ export declare function validateMath(code: string): boolean;
  * })
  * ```
  */
-declare const _default: import("comark").ComarkPluginFactory<MathConfig>;
+declare const _default: import("comark").ComarkPluginFactory<MathConfig, {}, {}>;
 export default _default;

package/dist/plugins/mermaid.d.ts

@@ -34,5 +34,5 @@ export declare function searchProps(content: string, index?: number): {
  * })
  * ```
  */
-declare const _default: import("comark").ComarkPluginFactory<MermaidConfig>;
+declare const _default: import("comark").ComarkPluginFactory<MermaidConfig, {}, {}>;
 export default _default;

package/dist/plugins/punctuation.d.ts

@@ -63,5 +63,5 @@ export interface PunctuationOptions {
  * })
  * ```
  */
-declare const _default: import("comark").ComarkPluginFactory<PunctuationOptions>;
+declare const _default: import("comark").ComarkPluginFactory<PunctuationOptions, {}, {}>;
 export default _default;

package/dist/plugins/security.d.ts

@@ -6,5 +6,5 @@ interface SecurityOptions extends PropsValidationOptions {
      */
     blockedTags?: string[];
 }
-declare const _default: import("comark").ComarkPluginFactory<SecurityOptions>;
+declare const _default: import("comark").ComarkPluginFactory<SecurityOptions, {}, {}>;
 export default _default;

package/dist/plugins/summary.d.ts

@@ -1,4 +1,7 @@
+import type { ComarkNode } from 'comark';
 declare const _default: import("comark").ComarkPluginFactory<{
     delimiter?: string;
-}>;
+}, {
+    summary: ComarkNode[];
+}, {}>;
 export default _default;

package/dist/plugins/syntax.d.ts

@@ -44,6 +44,6 @@ export interface SyntaxOptions {
      */
     bindingTag?: string;
 }
-declare const _default: import("../types.ts").ComarkPluginFactory<SyntaxOptions>;
+declare const _default: import("../types.ts").ComarkPluginFactory<SyntaxOptions, {}, {}>;
 export default _default;
 export declare const markdownItComark: MarkdownItPluginWithOptions<SyntaxOptions>;

package/dist/plugins/syntax.js

@@ -201,6 +201,12 @@ const markdownItComarkBlock = (md) => {
         const blockAttributesClosingFence = blockYamlLines[line] || '';
         if (!blockAttributesClosingFence)
             return false;
+        // The `---` fence is only valid on the line immediately after the component opener. Any other `---` is a thematic break.
+        if (line === '---') {
+            const parentOpenLine = state.env.comarkBlockTokens[0].map?.[0];
+            if (parentOpenLine === undefined || startLine !== parentOpenLine + 1)
+                return false;
+        }
         let lineEnd = startLine + 1;
         let found = false;
         while (lineEnd < endLine) {
@@ -237,8 +243,38 @@ const markdownItComarkBlock = (md) => {
         const line = state.src.slice(start, state.eMarks[startLine]);
         const { name, props } = parseBlockParams(line.slice(1));
         let lineEnd = startLine + 1;
+        let inCodeFence = false;
+        let codeFenceChar = '';
+        let codeFenceCount = 0;
         while (lineEnd < endLine) {
             const inner = state.src.slice(state.bMarks[lineEnd] + state.tShift[startLine], state.eMarks[lineEnd]);
+            if (inCodeFence) {
+                // Look for matching closing fence (same char, >= opening count, nothing but spaces after)
+                if (inner[0] === codeFenceChar) {
+                    let fencePos = 1;
+                    while (fencePos < inner.length && inner[fencePos] === codeFenceChar)
+                        fencePos++;
+                    if (fencePos >= codeFenceCount && inner.slice(fencePos).trim() === '') {
+                        inCodeFence = false;
+                    }
+                }
+                lineEnd += 1;
+                continue;
+            }
+            // Detect opening code fence (``` or ~~~, length >= 3)
+            if (inner[0] === '`' || inner[0] === '~') {
+                const ch = inner[0];
+                let fencePos = 1;
+                while (fencePos < inner.length && inner[fencePos] === ch)
+                    fencePos++;
+                if (fencePos >= 3) {
+                    inCodeFence = true;
+                    codeFenceChar = ch;
+                    codeFenceCount = fencePos;
+                    lineEnd += 1;
+                    continue;
+                }
+            }
             if (/^#\w+/.test(inner) || inner.startsWith('::'))
                 break;
             lineEnd += 1;
@@ -397,52 +433,52 @@ const markdownItInlineProps = (md) => {
     const _parse = md.parse;
     md.parse = function (src, env) {
         const tokens = _parse.call(this, src, env);
-        // When the props token is the only inline child of a heading/paragraph/list_item,
-        // apply it to the parent block tag instead of producing a `span`
+        // When the trailing inline child is a props token directly after a text
+        // node, lift the props onto the surrounding heading/paragraph/list_item.
+        // (If the props follow a closing tag, they belong to that inline tag, not
+        // the parent — leave them alone.)
         tokens.forEach((token, index) => {
             const prev = tokens[index - 1];
             const next = tokens[index + 1];
             if (!prev || !['heading_open', 'paragraph_open', 'list_item_open'].includes(prev.type) || prev.hidden)
                 return;
-            // list item handling
+            // Tight-list paragraph: the inline lives one slot ahead
             if (token.hidden && next?.type === 'inline')
                 token = next;
-            if (token.type === 'inline' &&
-                token.children?.length === 2 &&
-                token.children[0].type === 'text' &&
-                token.children[1].type === 'mdc_inline_props') {
-                const props = token.children[1].attrs;
-                token.children.splice(1, 1);
-                props?.forEach(([key, value]) => {
-                    if (key === 'class')
-                        prev.attrJoin('class', value);
-                    else
-                        prev.attrSet(key, value);
-                });
-            }
-        });
-        // Deduplicate `ul` wrapping when `::ul` is used and contains exactly one bullet list
-        tokens.forEach((tokenOpen, index) => {
-            if (tokenOpen.type !== 'bullet_list_open')
+            if (token.type !== 'inline' || !token.children?.length)
                 return;
-            const prev = tokens[index - 1];
-            if (!prev || prev.type !== 'mdc_block_open' || prev.tag !== 'ul')
+            const last = token.children[token.children.length - 1];
+            if (last.type !== 'mdc_inline_props')
                 return;
-            let closeIndex = index + 1;
-            while (closeIndex < tokens.length) {
-                const close = tokens[closeIndex];
-                if (close.type === 'bullet_list_close' && close.level === tokenOpen.level)
-                    break;
-                closeIndex += 1;
+            // Find the previous non-empty child. Markdown-it's emphasis tokenizer
+            // can leave an empty text token between the closing delimiter and the
+            // props — skipping it lets us distinguish "props on the parent" from
+            // "props on the preceding inline tag".
+            let beforeIdx = token.children.length - 2;
+            while (beforeIdx >= 0) {
+                const child = token.children[beforeIdx];
+                if (child.type === 'text' && !child.content) {
+                    beforeIdx--;
+                    continue;
+                }
+                break;
             }
-            const tokenClose = tokens[closeIndex];
-            if (tokenClose?.type !== 'bullet_list_close')
+            const beforeProps = beforeIdx >= 0 ? token.children[beforeIdx] : undefined;
+            if (!beforeProps || beforeProps.type !== 'text')
                 return;
-            const next = tokens[closeIndex + 1];
-            if (next?.type === 'mdc_block_close' && next.tag === 'ul') {
-                tokenOpen.hidden = true;
-                tokenClose.hidden = true;
+            // Strip the trailing space the text picked up before the `{...}` token.
+            if (typeof beforeProps.content === 'string') {
+                beforeProps.content = beforeProps.content.replace(/[ \t]+$/, '');
             }
+            const props = last.attrs;
+            // Drop the props token (last) plus any empty text tokens it left behind.
+            token.children.length = beforeProps.content ? beforeIdx + 1 : beforeIdx;
+            props?.forEach(([key, value]) => {
+                if (key === 'class')
+                    prev.attrJoin('class', value);
+                else
+                    prev.attrSet(key, value);
+            });
         });
         return tokens;
     };

package/dist/plugins/task-list.d.ts

@@ -4,5 +4,5 @@
  * This plugin runs before inline parsing to prevent Comark from interpreting
  * task list markers [X] and [ ] as Comark inline span syntax.
  */
-declare const _default: import("../types.ts").ComarkPluginFactory<unknown>;
+declare const _default: import("../types.ts").ComarkPluginFactory<unknown, {}, {}>;
 export default _default;

package/dist/plugins/toc.d.ts

@@ -12,5 +12,7 @@ export interface Toc {
     links: TocLink[];
 }
 export declare function generateFlatToc(body: ComarkTree, options: Toc): Toc;
-declare const _default: import("comark").ComarkPluginFactory<Partial<Toc>>;
+declare const _default: import("comark").ComarkPluginFactory<Partial<Toc>, {
+    toc: Toc;
+}, {}>;
 export default _default;

package/dist/types.d.ts

@@ -1,6 +1,12 @@
 import type { DumpOptions } from 'js-yaml';
 import type MarkdownExit from 'markdown-exit';
 import type MarkdownIt from 'markdown-it';
+/**
+ * The `[keyof T] extends [never]` form (rather than `keyof T extends never`)
+ * is the standard trick to prevent TS from distributing the check over a
+ * union — we want to test "is T's keyset empty?" as one yes/no question.
+ */
+type Writable<T> = [keyof T] extends [never] ? Record<string, any> : T;
 /**
  * The Comark text
  * @param string - The text content
@@ -43,11 +49,14 @@ export type ComarkNode = ComarkElement | ComarkText | ComarkComment;
  * @param nodes - The nodes of the tree
  * @param frontmatter - The frontmatter data which is the data at the top of the file
  * @param meta - The meta data of tree, it can be used to store additional data for the tree
+ *
+ * The `TMeta` and `TFrontmatter` type parameters allow `parse` / `createParse`
+ * to surface plugin-contributed keys with narrow types (see `MergePluginMeta`).
  */
-export interface ComarkTree {
+export interface ComarkTree<TMeta = Record<string, any>, TFrontmatter = Record<string, any>> {
     nodes: ComarkNode[];
-    frontmatter: Record<string, any>;
-    meta: Record<string, any>;
+    frontmatter: TFrontmatter;
+    meta: TMeta;
 }
 export interface ContextBase {
     /**
@@ -234,26 +243,60 @@ export type ComarkParsePreState = {
     options: ParseOptions;
     [key: string]: any;
 };
-export type ComarkParsePostState = {
+export type ComarkParsePostState<TMeta = Record<string, any>, TFrontmatter = Record<string, any>> = {
     markdown: string;
-    tree: ComarkTree;
+    tree: ComarkTree<TMeta, TFrontmatter>;
     options: ParseOptions;
     tokens: unknown[];
     [key: string]: any;
 };
-export type ComarkPlugin = {
+/**
+ * A Comark plugin.
+ *
+ * `TMeta` / `TFrontmatter` are phantom type parameters that record what this
+ * plugin contributes to `tree.meta` / `tree.frontmatter`. They are surfaced
+ * only via the optional `__meta` / `__frontmatter` markers — implementations
+ * never set these at runtime; they exist purely so the contribution survives
+ * `ReturnType<typeof factory>` inference and can be merged in `createParse`.
+ */
+export type ComarkPlugin<TMeta = {}, TFrontmatter = {}> = {
     name: string;
     markdownItPlugins?: MarkdownItPlugin[];
     pre?: (state: ComarkParsePreState) => Promise<void> | void;
-    post?: (state: ComarkParsePostState) => Promise<void> | void;
+    post?: (state: ComarkParsePostState<Writable<TMeta>, Writable<TFrontmatter>>) => Promise<void> | void;
+    /** Phantom — used for type inference only. Never set at runtime. */
+    __meta?: TMeta;
+    /** Phantom — used for type inference only. Never set at runtime. */
+    __frontmatter?: TFrontmatter;
 };
-export type ComarkPluginFactory<Options> = (opts?: Options) => ComarkPlugin;
-export type ComponentManifest = (name: string) => Promise<unknown> | undefined | null;
+export type ComarkPluginFactory<Options, TMeta = {}, TFrontmatter = {}> = (opts?: Options) => ComarkPlugin<TMeta, TFrontmatter>;
+type PluginMetaOf<P> = P extends ComarkPlugin<infer M, any> ? M : {};
+type PluginFrontmatterOf<P> = P extends ComarkPlugin<any, infer F> ? F : {};
+/**
+ * Walk a tuple of plugins and intersect their meta contributions.
+ * Returns `{}` when the tuple is empty or when nothing was contributed.
+ */
+export type MergePluginMeta<TPlugins extends readonly unknown[]> = TPlugins extends readonly [infer Head, ...infer Rest] ? PluginMetaOf<Head> & MergePluginMeta<Rest extends readonly unknown[] ? Rest : []> : {};
+/**
+ * Walk a tuple of plugins and intersect their frontmatter contributions.
+ */
+export type MergePluginFrontmatter<TPlugins extends readonly unknown[]> = TPlugins extends readonly [
+    infer Head,
+    ...infer Rest
+] ? PluginFrontmatterOf<Head> & MergePluginFrontmatter<Rest extends readonly unknown[] ? Rest : []> : {};
+/**
+ * When no plugin contributed meta keys, fall back to the permissive
+ * `Record<string, any>` (backwards-compatible). Otherwise, preserve narrow
+ * keys and type unknown accesses as `unknown` (safer than `any`).
+ */
+export type ResolvedMeta<T> = [keyof T] extends [never] ? Record<string, any> : T & Record<string, unknown>;
+export type ResolvedFrontmatter<T> = [keyof T] extends [never] ? Record<string, any> : T & Record<string, unknown>;
+export type ComponentManifest = (name: string) => unknown | Promise<unknown> | undefined | null;
 export interface ComarkContextProvider {
     components: Record<string, any>;
     componentManifest: ComponentManifest;
 }
-export interface ParseOptions {
+export interface ParseOptions<TPlugins extends readonly ComarkPlugin<any, any>[] = readonly ComarkPlugin<any, any>[]> {
     /**
      * Whether to automatically unwrap single paragraphs in container components.
      * When enabled, if a container component (alert, card, callout, note, warning, tip, info)
@@ -300,7 +343,7 @@ export interface ParseOptions {
      * Additional plugins to use
      * @default []
      */
-    plugins?: ComarkPlugin[];
+    plugins?: TPlugins;
 }
 /**
  * Type signature for the options object passed to the Comark parser function returned by createParse().
@@ -312,4 +355,5 @@ export type ComarkParseFnOptions = {
  * Type signature for the async Comark parser function returned by createParse().
  * Accepts a markdown string and optional parsing options, and returns a Promise of ComarkTree.
  */
-export type ComarkParseFn = (markdown: string, opts?: ComarkParseFnOptions) => Promise<ComarkTree>;
+export type ComarkParseFn<TMeta = Record<string, any>, TFrontmatter = Record<string, any>> = (markdown: string, opts?: ComarkParseFnOptions) => Promise<ComarkTree<TMeta, TFrontmatter>>;
+export {};

package/dist/utils/helpers.d.ts

@@ -5,8 +5,20 @@ import type { ComarkPluginFactory } from '../types.ts';
  */
 export declare function createSerializedTask<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;
 /**
- * Define a Comark plugin
- * @param fn - The plugin factory function
- * @returns The defined plugin
+ * Define a Comark plugin.
+ *
+ * `TMeta` and `TFrontmatter` declare what the plugin contributes to
+ * `tree.meta` / `tree.frontmatter`. They are inferred from the factory's
+ * return type when set via the `__meta` / `__frontmatter` phantom markers,
+ * or can be passed explicitly. Plugins that don't contribute typed keys can
+ * omit them entirely.
+ *
+ * @example
+ * ```ts
+ * defineComarkPlugin<Options, { toc: Toc }>((opts) => ({
+ *   name: 'toc',
+ *   post(state) { state.tree.meta.toc = ... },
+ * }))
+ * ```
  */
-export declare function defineComarkPlugin<Options>(fn: ComarkPluginFactory<Options>): ComarkPluginFactory<Options>;
+export declare function defineComarkPlugin<Options, TMeta = {}, TFrontmatter = {}>(fn: ComarkPluginFactory<Options, TMeta, TFrontmatter>): ComarkPluginFactory<Options, TMeta, TFrontmatter>;