+ children: Node[]
+ /** True once this frame has survived past the paragraph that opened it. */
+ block: boolean
+ /** Bare-inline nodes waiting to be flushed as a single on a block frame. */
+ pendingInline: Node[]
+}
+
+/** Shared mutable context for a whole document walk. */
+interface ProcessState {
+ preservePositions: boolean
+ headingIds: boolean
+ startLine: number
+ headingSlugCounts: Map
+ headingStack: Array<{ level: number; id: string }>
+ /** Unclosed HTML open tags, outer → inner. Lives across blocks like headingStack. */
+ htmlStack: HtmlOpenFrame[]
+ /**
+ * > 0 while building a nested markdown container (list, blockquote, table…).
+ * Free paragraphs inside those containers keep ownership of their children
+ * instead of nesting into the HTML stack; the finished container lands on the
+ * stack as a whole unit via deliverBlock.
+ */
+ insideMarkdownContainer: number
+}
+
+type Processor = (tokens: Token[], start: number, state: ProcessState) => ProcessorResult
+
+function makeHtmlAttrs(attrs: Record, block: boolean): Record {
+ return {
+ $: block ? { html: 1, block: 1 } : { html: 1, block: 0 },
+ ...attrs,
+ }
+}
+
+function pushNode(nodes: Node[], node: Node) {
+ if (node[0] === 'fragment') nodes.push(...(node.slice(2) as Node[]))
+ else nodes.push(node)
+}
+
+function isInlineish(node: Node): boolean {
+ if (typeof node === 'string') return true
+ if (!Array.isArray(node)) return false
+ const tag = node[0]
+ return tag === null || inlineTags.has(tag as string)
+}
+
+function flushPendingInline(frame: HtmlOpenFrame) {
+ if (frame.pendingInline.length === 0) return
+ const pending = frame.pendingInline
+ frame.pendingInline = []
+ frame.children.push(['p', {}, ...pending] as ElementNode)
+}
+
+/** Flatten nested nodes to text — used when emitting comment frames. */
+function flattenText(nodes: Node[]): string {
+ let out = ''
+ for (const n of nodes) {
+ if (typeof n === 'string') out += n
+ else if (Array.isArray(n)) out += flattenText(n.slice(2) as Node[])
+ }
+ return out
+}
+
+function frameToNode(frame: HtmlOpenFrame): ElementNode | CommentNode {
+ flushPendingInline(frame)
+ // Comments (`tag === null`): flatten children to a body string.
+ // Blank lines between the source paragraphs become `\n\n` between chunks.
+ if (frame.tag === null) {
+ const chunks = frame.children.map((c) =>
+ typeof c === 'string' ? c : flattenText(Array.isArray(c) && c[0] === 'p' ? (c.slice(2) as Node[]) : [c])
+ )
+ // Spanned comments always had a blank line after ``
+ const body = chunks.length > 0 ? `\n\n${chunks.join('\n\n')}\n\n` : ''
+ return [null, {}, body] as CommentNode
+ }
+ return [frame.tag as string, makeHtmlAttrs(frame.attrs, frame.block), ...frame.children]
+}
+
+/** Nest a finished block node into the open HTML frame, or return it free. */
+function deliverBlock(state: ProcessState, node: Node | undefined): Node | undefined {
+ if (node === undefined) return undefined
+ if (state.htmlStack.length === 0) return node
+ const top = state.htmlStack[state.htmlStack.length - 1]
+ flushPendingInline(top)
+ top.children.push(node)
+ return undefined
+}
+
+/** Nest an inline/finished node into the open HTML frame during processInline. */
+function deliverInline(state: ProcessState, node: Node | undefined): Node | undefined {
+ if (node === undefined) return undefined
+ if (state.htmlStack.length === 0) return node
+ const top = state.htmlStack[state.htmlStack.length - 1]
+ if (top.block && isInlineish(node)) {
+ top.pendingInline.push(node)
+ } else {
+ flushPendingInline(top)
+ top.children.push(node)
+ }
+ return undefined
+}
+
+/**
+ * `` are just HTML open/close with `tag === null`.
+ * When blank lines split them into plain text tokens, map those tokens onto the
+ * same push/pop path html_inline uses for elements.
+ */
+function tryCommentTag(content: string, state: ProcessState): ProcessorResult | null {
+ const top = state.htmlStack[state.htmlStack.length - 1]
+
+ // Close comment
+ if (top?.tag === null && content.includes('-->')) {
+ const i = content.indexOf('-->')
+ if (i > 0) deliverInline(state, content.slice(0, i))
+ const frame = state.htmlStack.pop()!
+ return { nextIndex: -1, node: frameToNode(frame) } // nextIndex filled by caller
+ }
+
+ // Open comment (no close in this chunk)
+ if (content.startsWith('')) {
+ const body = content.slice(4)
+ state.htmlStack.push({ tag: null, attrs: {}, children: body ? [body] : [], block: true, pendingInline: [] })
+ return { nextIndex: -1, node: undefined }
+ }
+
+ // Complete comment in one chunk
+ if (content.startsWith('')) {
+ const end = content.indexOf('-->')
+ return { nextIndex: -1, node: [null, {}, content.slice(4, end)] as CommentNode }
+ }
+
+ return null
+}
+
+function processToken(tokens: Token[], i: number, state: ProcessState): ProcessorResult | undefined {
+ return processors[tokens[i].type]?.(tokens, i, state)
+}
+
+/**
+ * Walk inline tokens. HTML open/close tags drive `state.htmlStack`.
+ * @param nestHtml When true (free paragraph / top-level), free nodes nest into
+ * the open HTML stack. When false (nested markdown containers like strong/li),
+ * free nodes return to the parent container — the container itself later lands
+ * on the HTML stack as a whole unit via deliverBlock.
+ */
+function processInline(inlineTokens: Token[], state: ProcessState, nestHtml = true): Node[] {
+ const nodes: Node[] = []
+ let i = 0
+
+ while (i < inlineTokens.length) {
+ const result = processToken(inlineTokens, i, state)
+ if (!result) {
+ i += 1
+ continue
+ }
+ const node = nestHtml ? deliverInline(state, result.node) : result.node
+ if (node !== undefined) pushNode(nodes, node)
+ i = result.nextIndex
+ }
+
+ return nodes
+}
+
+function preserveLineNumber(tokens: Token[], node: Node, start: number, nextIndex: number, state: ProcessState) {
+ let endLine = state.startLine
+ if (!Array.isArray(node)) return
+
+ for (let j = start; j < nextIndex; j++) {
+ if (tokens[j].map && tokens[j].map?.[1]) {
+ endLine = (tokens[j].map?.[1] as number) + state.startLine + (tokens[j].type?.endsWith('_close') ? 1 : 0)
+ }
+ }
+ if (!(node[1] as Record).$) {
+ ;(node[1] as Record).$ = {}
+ }
+ ;((node[1] as Record).$ as Record).line = endLine
+}
+
+/** Walk children of an open/close pair until `closeType`. */
+function processChildren(
+ tokens: Token[],
+ start: number,
+ closeType: string,
+ state: ProcessState,
+ nestHtml = false
+): { children: Node[]; nextIndex: number } {
+ const children: Node[] = []
+ let i = start + 1
+
+ while (i < tokens.length) {
+ const token = tokens[i]
+ if (token.type === closeType) {
+ return { children, nextIndex: i + 1 }
+ }
+
+ if (token.type === 'inline') {
+ children.push(...processInline(token.children ?? [], state, nestHtml))
+ i += 1
+ continue
+ }
+
+ const result = processToken(tokens, i, state)
+ if (result) {
+ if (result.node !== undefined) pushNode(children, result.node)
+ i = result.nextIndex
+ } else {
+ i += 1
+ }
+ }
+
+ return { children, nextIndex: i }
+}
+
+function processPossibleAttributesSyntax(tokens: Token[], value: { nextIndex: number; node: Node }) {
+ const extractedAttributes = extractAttributes(tokens, value.nextIndex)
+ if (value.nextIndex < extractedAttributes.nextIndex) {
+ ;(value.node as ElementNode)[1] = Object.assign(value.node[1], extractedAttributes.attrs)
+ value.nextIndex = extractedAttributes.nextIndex
+ }
+
+ return value
+}
+
+function processBlockChildrenWithSlots(
+ tokens: Token[],
+ start: number,
+ closeType: string,
+ state: ProcessState
+): { children: Node[]; nextIndex: number } {
+ const nodes: Node[] = []
+ let i = start + 1
+ let currentSlot: { tag: string; attrs: Record; children: Node[] } | null = null
+
+ const flushSlot = () => {
+ if (!currentSlot) return
+ nodes.push([currentSlot.tag, currentSlot.attrs, ...mergeAdjacentTextNodes(currentSlot.children)] as ElementNode)
+ currentSlot = null
+ }
+
+ const pushChild = (node: Node | undefined) => {
+ if (node === undefined) return
+
+ pushNode(currentSlot ? currentSlot.children : nodes, node)
+ }
+
+ while (i < tokens.length) {
+ const token = tokens[i]
+
+ if (token.type === closeType) {
+ flushSlot()
+ return { children: nodes, nextIndex: i + 1 }
+ }
+
+ if (token.type === 'mdc_block_slot_open') {
+ flushSlot()
+ currentSlot = {
+ tag: token.tag || 'template',
+ attrs: processAttributes(token.attrs),
+ children: [],
+ }
+ i += 1
+ continue
+ }
+
+ if (token.type === 'mdc_block_slot_close') {
+ i += 1
+ continue
+ }
+
+ if (token.type === 'inline') {
+ const free = processInline(token.children ?? [], state)
+ if (currentSlot) currentSlot.children.push(...free)
+ else nodes.push(...free)
+ i += 1
+ continue
+ }
+
+ const result = processToken(tokens, i, state)
+ if (result) {
+ pushChild(result.node)
+ i = result.nextIndex
+ } else {
+ i += 1
+ }
+ }
+
+ flushSlot()
+ return { children: nodes, nextIndex: i }
+}
+
+function processMdcBlock(tokens: Token[], start: number, state: ProcessState): ProcessorResult {
+ const open = tokens[start]
+ // Own child paragraphs/inlines so an outer unclosed HTML tag (e.g. ``)
+ // doesn't steal `::component` body content off the stack.
+ state.insideMarkdownContainer += 1
+ const { children, nextIndex } = processBlockChildrenWithSlots(tokens, start, 'mdc_block_close', state)
+ state.insideMarkdownContainer -= 1
+ const attrs = processAttributes(open.attrs)
+
+ let node = [open.tag || 'div', attrs, ...mergeAdjacentTextNodes(children)] as ElementNode
+ if (WRAPPER_TAGS.has(node[0])) {
+ if (children.length === 1 && children[0][0] === node[0]) {
+ node = node[2] as ElementNode
+ node[1] = { ...node[1], ...attrs }
+ }
+ }
+ return processPossibleAttributesSyntax(tokens, {
+ nextIndex,
+ node,
+ })
+}
+
+function codeBlockProcessor(tokens: Token[], start: number, _state: ProcessState): ProcessorResult {
+ const token = tokens[start]
+ const content = token.content || ''
+ const info = token.info || (token as Token & { params?: string }).params || ''
+
+ const parsed = parseCodeblockInfo(info)
+
+ const preAttrs: Record = parsed
+ const codeAttrs: Record = {}
+ if (parsed.language && parsed.language.trim()) {
+ preAttrs.language = parsed.language
+ codeAttrs['class'] = `language-${parsed.language}`
+ }
+
+ const codeContentWithoutLastNewline = content.endsWith('\n') ? content.slice(0, -1) : content
+ return {
+ nextIndex: start + 1,
+ node: ['pre', preAttrs, ['code', codeAttrs, codeContentWithoutLastNewline]],
+ }
+}
+
+function uniqueSlug(slug: string, level: number, state: ProcessState): string {
+ while (state.headingStack.length > 0 && state.headingStack[state.headingStack.length - 1].level >= level) {
+ state.headingStack.pop()
+ }
+ if (state.headingStack.length > 0) {
+ const parent = state.headingStack[state.headingStack.length - 1]
+ if (parent.level >= 2) {
+ slug = parent.id + '-' + slug
+ }
+ }
+
+ state.headingStack.push({ level, id: slug })
+
+ const count = state.headingSlugCounts.get(slug) ?? 0
+ state.headingSlugCounts.set(slug, count + 1)
+ return count === 0 ? slug : `${slug}-${count}`
+}
+
+function singleToken(fn: (token: Token) => Node) {
+ return (tokens: Token[], start: number): ProcessorResult =>
+ processPossibleAttributesSyntax(tokens, { nextIndex: start + 1, node: fn(tokens[start]) })
+}
+
+function openCloseToken(closeType: string, tag: string = '', nest = false) {
+ return (tokens: Token[], start: number, state: ProcessState) => {
+ const open = tokens[start]
+ if (nest) state.insideMarkdownContainer += 1
+ const { children, nextIndex } = processChildren(tokens, start, closeType, state)
+ if (nest) state.insideMarkdownContainer -= 1
+ const attrs = processAttributes(open.attrs)
+ return processPossibleAttributesSyntax(tokens, {
+ nextIndex,
+ node: [tag || open.tag, attrs, ...mergeAdjacentTextNodes(children)],
+ })
+ }
+}
+
+const processors: Record = {
+ // nest=true: containers that own child paragraphs/inlines (so free HTML stack
+ // doesn't steal their content while a block-level HTML tag is open above them).
+ mdc_block_slot_open: openCloseToken('mdc_block_slot_close'),
+ mdc_inline_span_open: openCloseToken('mdc_inline_span_close'),
+ mdc_block_shorthand_open: openCloseToken('mdc_block_shorthand_close'),
+ mdc_inline_component_open: openCloseToken('mdc_inline_component_close'),
+ blockquote_open: openCloseToken('blockquote_close', '', true),
+ bullet_list_open: openCloseToken('bullet_list_close', '', true),
+ ordered_list_open: openCloseToken('ordered_list_close', '', true),
+ list_item_open: openCloseToken('list_item_close', '', true),
+ strong_open: openCloseToken('strong_close'),
+ link_open: openCloseToken('link_close'),
+ em_open: openCloseToken('em_close'),
+ table_open: openCloseToken('table_close', '', true),
+ thead_open: openCloseToken('thead_close', '', true),
+ tbody_open: openCloseToken('tbody_close', '', true),
+ tr_open: openCloseToken('tr_close', '', true),
+ th_open: openCloseToken('th_close', '', true),
+ td_open: openCloseToken('td_close', '', true),
+ sub_open: openCloseToken('sub_close'),
+ sup_open: openCloseToken('sup_close'),
+ s_open: openCloseToken('s_close', 'del'),
+ mdc_block_open: processMdcBlock,
+ code_inline: singleToken((t) => ['code', {}, t.content]),
+ math_inline: singleToken((t) => ['math', { class: 'math inline', content: t.content }, t.content]),
+ math_block: singleToken((t) => ['math', { class: 'math block', content: t.content }, t.content]),
+ emoji: singleToken((t) => t.content),
+ hr: singleToken(() => ['hr', {}]),
+ hardbreak: singleToken(() => ['br', {}]),
+ reference: (_, s) => ({ node: undefined, nextIndex: s + 1 }),
+ // Softbreaks inside open HTML are paragraph separators, not text content
+ softbreak: (tokens, start, state) => ({
+ nextIndex: start + 1,
+ node: state.htmlStack.length > 0 || tokens[start - 1].type === 'html_inline' ? undefined : '\n',
+ }),
+ code_block: codeBlockProcessor,
+ fenced_code_block: codeBlockProcessor,
+ fence: codeBlockProcessor,
+ mdc_block_shorthand: singleToken((t) => [t.tag, processAttributes(t.attrs)]),
+ heading_open(tokens, start, state) {
+ const { nextIndex, node } = openCloseToken('heading_close')(tokens, start, state)
+ if (node.length === 2) return { node: undefined, nextIndex }
+
+ if (state.headingIds) {
+ const level = Number.parseInt((tokens[start].tag || 'h1').replace('h', ''), 10) || 1
+ const _textContent = textContent(node)
+ const headingId = uniqueSlug(slugify(_textContent), level, state)
+ ;(node as ElementNode)[1] = { id: headingId, ...(node[1] as Record) }
+ }
+
+ return { nextIndex, node }
+ },
+
+ paragraph_open(tokens, start, state) {
+ const inline = tokens[start + 1]
+ const depthBefore = state.htmlStack.length
+ const nestHtml = state.insideMarkdownContainer === 0
+ const { children, nextIndex } = processChildren(tokens, start, 'paragraph_close', state, nestHtml)
+ const asParagraph = (): ProcessorResult =>
+ children.length === 0
+ ? { nextIndex, node: undefined }
+ : {
+ nextIndex,
+ node: ['p', processAttributes(tokens[start].attrs), ...mergeAdjacentTextNodes(children)],
+ }
+
+ // Closed HTML root that started before this paragraph.
+ if (depthBefore > 0 && state.htmlStack.length === 0) {
+ if (children.length === 1 && Array.isArray(children[0])) {
+ return { nextIndex, node: children[0] as ElementNode }
+ }
+ return asParagraph()
+ }
+
+ // Stack still open — free content already nested via deliverInline.
+ if (state.htmlStack.length > 0) {
+ if (nestHtml) {
+ for (const frame of state.htmlStack) flushPendingInline(frame)
+ return { nextIndex, node: undefined }
+ }
+ return asParagraph()
+ }
+
+ const empty = asParagraph()
+ if (empty.node === undefined) return empty
+
+ const result = processPossibleAttributesSyntax(tokens, { nextIndex, node: empty.node })
+ const final = result.node
+ const canUnwrap =
+ Array.isArray(final) &&
+ final.length === 3 &&
+ inline?.type === 'inline' &&
+ inline.children?.[0]?.type === 'html_inline' &&
+ (!inlineTags.has((final[2] as ElementNode)?.[0] as string) ||
+ Boolean((empty.node[2][1] as ElementNodeAttributes)?.$?.block))
+
+ if (canUnwrap) {
+ const unwrapped = final[2] as ElementNode
+ if ((unwrapped[1] as ElementNodeAttributes).$) {
+ ;(unwrapped[1] as ElementNodeAttributes).$!.block = 1
+ }
+ return { nextIndex: result.nextIndex, node: unwrapped }
+ }
+
+ if ((result.node as ElementNode).every((n, i) => i < 2 || (n?.[1] as ElementNodeAttributes)?.$?.html)) {
+ ;(result.node as ElementNode)[0] = 'fragment'
+ }
+
+ return result
+ },
+ mdc_inline_component(tokens, start) {
+ const token = tokens[start]
+ const tokenAttrs = processAttributes(token.attrs)
+ const { attrs, nextIndex } = extractAttributes(tokens, start + 1, false)
+ return { node: [token.tag, { ...tokenAttrs, ...attrs }] as Node, nextIndex }
+ },
+
+ image(tokens, start) {
+ const token = tokens[start]
+ const attrs = processAttributes(token.attrs, { handleJSON: false, filterEmpty: true })
+ if (token.content) {
+ attrs.alt = token.content
+ }
+ return processPossibleAttributesSyntax(tokens, { node: ['img', attrs] as Node, nextIndex: start + 1 })
+ },
+
+ text(tokens, start, state) {
+ const content = tokens[start].content
+ if (content === '') return { nextIndex: start + 1, node: undefined }
+
+ // `` are HTML open/close with tag null (may arrive as plain text
+ // when blank lines split a multi-line comment).
+ const comment = tryCommentTag(content, state)
+ if (comment) return { nextIndex: start + 1, node: comment.node }
+
+ return { nextIndex: start + 1, node: content }
+ },
+ // html_inline drives the document-wide HTML open stack.
+ // - self-closing / void → single element
+ // - open → push frame (siblings / later blocks fill children)
+ // - matching close → pop frame and emit completed element
+ html_inline(tokens, start, state) {
+ const raw = tokens[start].content || ''
+ const parsed = parseHtmlInline(raw)
+
+ if (parsed.kind === 'comment') {
+ return { nextIndex: start + 1, node: [null, {}, parsed.content] }
+ }
+ if (parsed.kind === 'other') {
+ // Bare `` fragments use the same stack as elements.
+ const comment = tryCommentTag(raw, state)
+ if (comment) return { nextIndex: start + 1, node: comment.node }
+ return { nextIndex: start + 1, node: [null, {}, raw] }
+ }
+
+ if (parsed.kind === 'close') {
+ const top = state.htmlStack[state.htmlStack.length - 1]
+ if (top && top.tag === parsed.tag) {
+ return { nextIndex: start + 1, node: frameToNode(state.htmlStack.pop()!) }
+ }
+ return { nextIndex: start + 1, node: undefined }
+ }
+
+ if (parsed.selfClosing) {
+ return {
+ nextIndex: start + 1,
+ node: [parsed.tag, makeHtmlAttrs(parsed.attrs, false)],
+ }
+ }
+
+ state.htmlStack.push({
+ tag: parsed.tag,
+ attrs: parsed.attrs,
+ children: [],
+ block: false,
+ pendingInline: [],
+ })
+ return { nextIndex: start + 1, node: undefined }
+ },
+}
+
+export function tokenListToTree(tokens: Token[], options: ProcessorOptions = {}): Node[] {
+ const state: ProcessState = {
+ preservePositions: options.preservePositions ?? false,
+ headingIds: options.headingIds ?? true,
+ startLine: options.startLine ?? 0,
+ headingSlugCounts: new Map(),
+ headingStack: [],
+ htmlStack: [],
+ insideMarkdownContainer: 0,
+ }
+ const nodes: Node[] = []
+ let i = 0
+
+ while (i < tokens.length) {
+ const token = tokens[i]
+
+ if (token.type === 'inline') {
+ const free = processInline(token.children ?? [], state)
+ // Free inline at block level (rare) — if stack open, nest; else emit
+ if (state.htmlStack.length > 0) {
+ for (const n of free) state.htmlStack[state.htmlStack.length - 1].children.push(n)
+ } else {
+ nodes.push(...free)
+ }
+ i += 1
+ continue
+ }
+
+ const result = processToken(tokens, i, state)
+ if (result) {
+ // Remaining open frames span past this block.
+ for (const frame of state.htmlStack) frame.block = true
+
+ if (result.node !== undefined) {
+ if (state.preservePositions) {
+ preserveLineNumber(tokens, result.node, i, result.nextIndex, state)
+ }
+ const free = deliverBlock(state, result.node)
+ if (free !== undefined) pushNode(nodes, free)
+ }
+ i = result.nextIndex
+ } else {
+ nodes.push([token.tag || 'component', processAttributes(token.attrs, { handleJSON: false })])
+ i += 1
+ }
+ }
+
+ // EOF — close remaining unclosed HTML tags (outermost last).
+ // Incomplete openers with only text leaves stay block: 0 (inline-like).
+ // Anything with element children (markdown, nested HTML, lists) is block: 1.
+ while (state.htmlStack.length > 0) {
+ const frame = state.htmlStack.pop()!
+ frame.block = true
+ const node = frameToNode(frame)
+ if (state.htmlStack.length > 0) {
+ state.htmlStack[state.htmlStack.length - 1].children.push(node)
+ } else {
+ nodes.push(node)
+ }
+ }
+
+ return nodes
+}
diff --git a/packages/comark/src/internal/parse/utils.ts b/packages/comark/src/internal/parse/utils.ts
new file mode 100644
index 00000000..a93f2206
--- /dev/null
+++ b/packages/comark/src/internal/parse/utils.ts
@@ -0,0 +1,205 @@
+import type { Node, ElementNode, ElementNodeAttributes, MarkdownDocument } from 'comark'
+import { decodeHTML, TREE_WALK_MAX_DEPTH } from 'comark/utils'
+
+/** HTML void elements — never have children / closing tags. */
+const HTML_VOID_ELEMENTS = new Set([
+ 'area',
+ 'base',
+ 'br',
+ 'col',
+ 'embed',
+ 'hr',
+ 'img',
+ 'input',
+ 'link',
+ 'meta',
+ 'param',
+ 'source',
+ 'track',
+ 'wbr',
+])
+
+export type ParsedHtmlTag =
+ | { kind: 'open'; tag: string; attrs: Record; selfClosing: boolean }
+ | { kind: 'close'; tag: string }
+ | { kind: 'comment'; content: string }
+ | { kind: 'other'; content: string }
+
+/**
+ * Applies automatic unwrapping to container components.
+ *
+ * This utility removes unnecessary paragraph wrappers from container component children.
+ * If a container has only a single paragraph child (and no other block elements),
+ * the paragraph is unwrapped and its children are hoisted up to be direct children
+ * of the container.
+ *
+ * Recursion is capped at {@link TREE_WALK_MAX_DEPTH} element levels; deeper subtrees are left as-is.
+ *
+ * @param node - The Comark element to process
+ * @returns The node with auto-unwrapped children (if applicable)
+ *
+ * @example
+ * // Before:
+ * { tag: 'alert', children: [{ type: 'element', tag: 'p', children: [{ type: 'text', value: 'Text' }] }] }
+ *
+ * // After:
+ * { tag: 'alert', children: [{ type: 'text', value: 'Text' }] }
+ */
+function isBlankText(value: string): boolean {
+ for (let i = 0; i < value.length; i++) {
+ const c = value.charCodeAt(i)
+ if (c !== 32 && c !== 10 && c !== 9 && c !== 13 && c !== 12) return false
+ }
+ return true
+}
+
+export function applyAutoUnwrap(node: Node): Node {
+ return applyAutoUnwrapAt(node, 0)
+}
+
+function applyAutoUnwrapAt(node: Node, depth: number): Node {
+ if (depth >= TREE_WALK_MAX_DEPTH || typeof node === 'string' || node[0] === 'p' || node[0] == null) {
+ return node
+ }
+
+ const length = node.length
+ if (length < 3) {
+ return node
+ }
+
+ let significant: Node | undefined
+ let significantCount = 0
+ for (let i = 2; i < length; i++) {
+ const child = node[i] as Node
+ if (typeof child === 'string' && isBlankText(child)) continue
+ significant = child
+ if (++significantCount > 1) break
+ }
+
+ if (significantCount === 0) {
+ return node
+ }
+
+ if (significantCount === 1 && Array.isArray(significant) && significant[0] === 'p') {
+ // Lift the paragraph's attrs onto the parent so trailing `{attr}` survives the unwrap.
+ // Parent attrs take precedence so explicit component props aren't overridden.
+ const paragraphAttrs = significant[1] as Record | undefined
+ let mergedProps = node[1]
+ if (paragraphAttrs) {
+ for (const key in paragraphAttrs) {
+ if (key !== undefined) {
+ mergedProps = { ...paragraphAttrs, ...node[1] }
+ break
+ }
+ }
+ }
+ const unwrapped = significant.slice() as unknown as ElementNode
+ unwrapped[0] = node[0] as string
+ unwrapped[1] = mergedProps
+ return unwrapped
+ }
+
+ let copy: Node[] | undefined
+ for (let i = 2; i < length; i++) {
+ const child = node[i] as Node
+ const next = applyAutoUnwrapAt(child, depth + 1)
+ if (copy !== undefined) {
+ copy.push(next)
+ } else if (next !== child) {
+ copy = node.slice(0, i) as unknown as Node[]
+ copy.push(next)
+ }
+ }
+ return copy !== undefined ? (copy as Node) : node
+}
+
+/**
+ * Extracts reusable nodes from the last output tree
+ * @param markdown - The markdown to parse
+ * @param lastOutput - The last output tree
+ * @returns The reusable nodes and the remaining markdown
+ */
+export function extractReusableNodes(markdown: string, lastOutput: MarkdownDocument) {
+ let lastValidNodeIndex = -1
+ let i = lastOutput.nodes.length - 1
+ let lastNodeIgnored = false
+ while (i >= 0) {
+ const node = lastOutput.nodes[i] as ElementNode
+ if (node[1] && node[1].$?.line) {
+ if (lastNodeIgnored) {
+ lastValidNodeIndex = i
+ break
+ } else {
+ lastNodeIgnored = true
+ }
+ }
+ i--
+ }
+ const lastNode = lastValidNodeIndex !== -1 ? lastOutput.nodes[lastValidNodeIndex] : null
+ if (lastNode) {
+ const remainingMarkdownStartLine = (lastNode[1] as ElementNodeAttributes).$?.line ?? 0
+ return {
+ remainingMarkdownStartLine,
+ reusedNodes: lastOutput.nodes.slice(0, lastValidNodeIndex + 1),
+ remainingMarkdown: markdown.split('\n').slice(remainingMarkdownStartLine).join('\n') || '',
+ }
+ }
+
+ return {
+ remainingMarkdownStartLine: 0,
+ remainingMarkdown: markdown,
+ reusedNodes: [],
+ }
+}
+
+/**
+ * Parse a single html_inline token content into a structured tag description.
+ * Handles open tags (with attrs), close tags, self-closing syntax, and comments.
+ */
+export function parseHtmlInline(content: string): ParsedHtmlTag {
+ const trimmed = content.trim()
+
+ if (trimmed.startsWith('')) {
+ return { kind: 'comment', content: trimmed.slice(4, -3) }
+ }
+
+ const closeMatch = trimmed.match(/^<\/\s*([A-Za-z][\w:-]*)\s*>$/)
+ if (closeMatch) {
+ return { kind: 'close', tag: closeMatch[1] }
+ }
+
+ const openMatch = trimmed.match(/^<\s*([A-Za-z][\w:-]*)((?:\s+[\s\S]*?)?)\s*(\/?)>$/)
+ if (openMatch) {
+ const tag = openMatch[1]
+ const attrsStr = openMatch[2] || ''
+ const slash = openMatch[3] === '/'
+ const selfClosing = slash || HTML_VOID_ELEMENTS.has(tag.toLowerCase())
+ return {
+ kind: 'open',
+ tag,
+ attrs: parseHtmlAttributes(attrsStr),
+ selfClosing,
+ }
+ }
+
+ return { kind: 'other', content: trimmed }
+}
+
+/**
+ * Parse HTML attribute string into a key/value map.
+ * Supports `key="value"`, `key='value'`, bare `key=value`, and boolean attributes.
+ */
+export function parseHtmlAttributes(attrsStr: string): Record {
+ const attrs: Record = {}
+ if (!attrsStr || !attrsStr.trim()) return attrs
+
+ const re = /([:\w.-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g
+ let match: RegExpExecArray | null
+ while ((match = re.exec(attrsStr)) !== null) {
+ const key = match[1]
+ const value = match[2] ?? match[3] ?? match[4]
+ attrs[key] = value === undefined ? true : decodeHTML(value)
+ }
+
+ return attrs
+}
diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts
index 7869b489..2b555566 100644
--- a/packages/comark/src/parse.ts
+++ b/packages/comark/src/parse.ts
@@ -11,20 +11,19 @@ import type {
MarkdownDocument,
Node,
} from './types.ts'
-import MarkdownExit from 'markdown-exit'
+import MarkdownExit, { type Token } from 'markdown-exit'
import components from './plugins/components.ts'
import attributes from './plugins/attributes.ts'
import taskList from './plugins/task-list.ts'
import alert from './plugins/alert.ts'
import html from './plugins/html.ts'
import frontmatterPlugin from './plugins/frontmatter.ts'
-import { applyAutoUnwrap } from './internal/parse/auto-unwrap.ts'
+import { applyAutoUnwrap, extractReusableNodes } from './internal/parse/utils.ts'
import { applyUnwrap, resolveUnwrapTags } from './internal/parse/unwrap.ts'
-import { marmdownItTokensToMarkdownDocument } from './internal/parse/token-processor.ts'
import { autoCloseMarkdown } from './internal/parse/auto-close/index.ts'
-import { extractReusableNodes } from './internal/parse/incremental.ts'
import { createSerializedTask, dedupePlugins } from './utils/helpers.ts'
import { noopTracer, withSpan } from './utils/trace.ts'
+import { tokenListToTree } from './internal/parse/tree.ts'
// Re-export frontmatter utilities
export { parseFrontmatter } from './internal/frontmatter.ts'
@@ -113,7 +112,7 @@ export function createMarkdownParser {
const state = {
options,
- tokens: [] as unknown[],
+ tokens: [] as Token[],
markdown,
tree: null as MarkdownDocument | null,
parsedLines: 0,
@@ -176,9 +175,15 @@ export function createMarkdownParser
+ plugin.markdownItPost!(state as ComarkParsePostState)
+ )
+ }
+
const nodesSpan = tracer.startSpan('comark:nodes')
- let nodes = marmdownItTokensToMarkdownDocument(state.tokens, {
+ let nodes = tokenListToTree(state.tokens, {
startLine: state.parsedLines,
preservePositions: opts.streaming ?? false,
headingIds: options.headingIds ?? true,
diff --git a/packages/comark/src/plugins/components.ts b/packages/comark/src/plugins/components.ts
index 4e514c9a..9db23767 100644
--- a/packages/comark/src/plugins/components.ts
+++ b/packages/comark/src/plugins/components.ts
@@ -62,7 +62,7 @@ const markdownItComarkBlock: PluginSimple = (md) => {
if (!silent) {
if (content !== undefined) {
- const tokenOpen = state.push('mdc_block_shorthand', name, 1)
+ const tokenOpen = state.push('mdc_block_shorthand_open', name, 1)
props?.forEach(([key, value]) => {
if (key === 'class') tokenOpen.attrJoin(key, value)
else tokenOpen.attrSet(key, value)
@@ -73,7 +73,7 @@ const markdownItComarkBlock: PluginSimple = (md) => {
inline.content = content
inline.children = []
- const tokenClose = state.push('mdc_block_shorthand', name, -1)
+ const tokenClose = state.push('mdc_block_shorthand_close', name, -1)
tokenClose.map = [startLine, startLine + 1]
} else {
const token = state.push('mdc_block_shorthand', name, 0)
@@ -381,8 +381,8 @@ const markdownItComarkBlock: PluginSimple = (md) => {
// Restore lineMax after tokenizing so it doesn't leak a narrower bound to
// whatever comes after this slot (see `comark_block`'s save/restore above).
const oldLineMax = state.lineMax
- const slot = state.push('mdc_block_slot', 'template', 1)
- slot.attrSet(`#${name}`, '')
+ const slot = state.push('mdc_block_slot_open', 'template', 1)
+ slot.attrSet('name', `${name}`)
props?.forEach(([key, value]) => {
if (key === 'class') slot.attrJoin(key, value)
else slot.attrSet(key, value)
@@ -393,7 +393,7 @@ const markdownItComarkBlock: PluginSimple = (md) => {
state.md.block.tokenize(state, startLine + 1, lineEnd)
- state.push('mdc_block_slot', 'template', -1)
+ state.push('mdc_block_slot_close', 'template', -1)
state.line = lineEnd
state.lineMax = oldLineMax
@@ -448,7 +448,7 @@ const markdownItInlineComponent: PluginSimple = (md) => {
if (silent) return true
if (contentStart !== -1) {
- state.push('mdc_inline_component', name, 1)
+ state.push('mdc_inline_component_open', name, 1)
const oldPos = state.pos
const oldPosMax = state.posMax
@@ -458,7 +458,7 @@ const markdownItInlineComponent: PluginSimple = (md) => {
state.pos = oldPos
state.posMax = oldPosMax
- state.push('mdc_inline_component', name, -1)
+ state.push('mdc_inline_component_close', name, -1)
} else {
state.push('mdc_inline_component', name, 0)
}
@@ -489,7 +489,7 @@ const markdownItInlineSpan: PluginSimple = (md) => {
// Returning `false` lets `parseLinkLabel`'s own depth tracking consume nested brackets and the outer link parse
if (silent) return false
- state.push('mdc_inline_span', 'span', 1)
+ state.push('mdc_inline_span_open', 'span', 1)
const oldPos = state.pos
const oldPosMax = state.posMax
@@ -499,7 +499,7 @@ const markdownItInlineSpan: PluginSimple = (md) => {
state.pos = oldPos
state.posMax = oldPosMax
- state.push('mdc_inline_span', 'span', -1)
+ state.push('mdc_inline_span_close', 'span', -1)
state.pos = index + 1
diff --git a/packages/comark/src/plugins/html.ts b/packages/comark/src/plugins/html.ts
index fdc1e4ed..8ab8a7d6 100644
--- a/packages/comark/src/plugins/html.ts
+++ b/packages/comark/src/plugins/html.ts
@@ -8,6 +8,13 @@
* Pass `registerDefaultPlugins: false` (and omit this plugin) to treat HTML
* tags as plain text.
*
+ * Options:
+ * - `markdown` (default `true`): expand text leaves inside closed HTML
+ * fragments as inline markdown (`Hello **World**
` → strong).
+ * When `false`, text inside HTML stays literal (CommonMark default for
+ * closed html_blocks). Blank-line bodies still nest as markdown tokens
+ * via bare open/close pairing.
+ *
* @example
* ```ts
* import { parseMarkdown } from 'comark'
@@ -21,21 +28,148 @@
* ```
*/
-import type { MarkdownExit } from 'markdown-exit'
-import type { MarkdownItPlugin } from '../types.ts'
+import { type StateBlock, Token, type MarkdownExit } from 'markdown-exit'
+import type { ComarkParseTokensState, MarkdownItPlugin } from '../types.ts'
import { defineComarkPlugin } from '../utils/helpers.ts'
-import html_block from '../internal/parse/html/html_block_rule.ts'
-import html_inline from '../internal/parse/html/html_inline_rule.ts'
-
-function markdownItHtml(md: MarkdownExit) {
- md.set({ html: true })
- md.inline.ruler.before('text', 'comark_html_inline', html_inline)
- md.block.ruler.before('html_block', 'comark_html_block', html_block, {
- alt: ['paragraph', 'reference', 'blockquote'],
- })
+
+export interface HtmlPluginOptions {
+ /**
+ * Expand text leaves inside closed HTML fragments as inline markdown.
+ * @default true
+ */
+ markdown?: boolean
+}
+
+export default defineComarkPlugin((opts: HtmlPluginOptions = {}) => {
+ const markdown = opts.markdown !== false
+
+ function markdownItHtml(md: MarkdownExit) {
+ md.set({ html: true })
+
+ // Opt-out marker read by createMarkdownParser: when present, closed HTML
+ // body text stays literal instead of being re-parsed as inline markdown.
+ if (markdown) {
+ // @ts-expect-error - internal utils
+ const html_block = md.block.ruler.__rules__.find((r) => r.name === 'html_block')
+ const fn = html_block.fn
+ html_block.fn = (state: StateBlock, startLine: number, endLine: number, silent: boolean) => {
+ let pos = state.bMarks[startLine] + state.tShift[startLine]
+
+ const tag = state.src.substring(pos, pos + 7)
+ if (tag === '`) {
+ return fn(state, startLine, endLine, silent)
+ }
+ }
+ }
+ }
+
+ return {
+ name: 'html',
+ markdownItPlugins: [markdownItHtml as unknown as MarkdownItPlugin],
+ markdownItPost: markdownItPost,
+ }
+})
+
+function markdownItPost(state: ComarkParseTokensState) {
+ let i = 0
+ while (i < state.tokens.length) {
+ const token = state.tokens[i]
+ if (token.type !== 'html_block') {
+ i += 1
+ continue
+ }
+
+ // Expand raw CommonMark html_block into html_inline + text, wrapped as a
+ // paragraph so the tree walk pairs open/close the same way as html_inline.
+ // Body text stays literal (no markdown re-parse).
+ const children = htmlToTokens(token.content || '')
+ const open = new Token('paragraph_open', 'p', 1)
+ const inline = new Token('inline', '', 0)
+ const close = new Token('paragraph_close', 'p', -1)
+ inline.children = children
+ inline.content = token.content || ''
+ if (token.map) {
+ open.map = token.map
+ inline.map = token.map
+ }
+ state.tokens.splice(i, 1, open, inline, close)
+ i += 3
+ }
}
-export default defineComarkPlugin(() => ({
- name: 'html',
- markdownItPlugins: [markdownItHtml as unknown as MarkdownItPlugin],
-}))
+// region - https://github.com/markdown-it/markdown-it/blob/master/src/common/html_re.ts#L21
+
+const attr_name = '[a-zA-Z_:][a-zA-Z0-9:._-]*'
+
+const unquoted = '[^"\'=<>`\\x00-\\x20]+'
+const single_quoted = "'[^']*'"
+const double_quoted = '"[^"]*"'
+
+const attr_value = `(?:${unquoted}|${single_quoted}|${double_quoted})`
+
+const attribute = `(?:\\s+${attr_name}(?:\\s*=\\s*${attr_value})?)`
+
+const open_tag = `<[A-Za-z][A-Za-z0-9\\-]*${attribute}*\\s*\\/?>`
+
+const close_tag = '<\\/[A-Za-z][A-Za-z0-9\\-]*\\s*>'
+const comment = ''
+const processing = '<[?][\\s\\S]*?[?]>'
+const declaration = ']*>'
+const cdata = ''
+
+const HTML_TAG_RE = new RegExp(`^(?:${open_tag}|${close_tag}|${comment}|${processing}|${declaration}|${cdata})`)
+
+// end region
+
+function isLetter(code: number): boolean {
+ return (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a)
+}
+
+function pushText(tokens: Token[], content: string) {
+ // Mirror htmlparser2's ontext trim: drop whitespace-only runs between tags and
+ // strip structural indentation / surrounding newlines from body text.
+ const trimmed = content.trim()
+ if (!trimmed) return
+ const text = new Token('text', '', 0)
+ text.content = trimmed
+ tokens.push(text)
+}
+
+/**
+ * Split an HTML fragment into markdown-exit tokens.
+ * Each recognized tag becomes `html_inline`; intervening runs become `text`.
+ *
+ * @example
+ * htmlToTokens('\n**bold**')
+ * // → [html_inline "", text "**bold**"]
+ */
+export function htmlToTokens(str: string): Token[] {
+ const tokens: Token[] = []
+ const len = str.length
+ let pos = 0
+ let textStart = 0
+
+ while (pos < len) {
+ // Candidate HTML tag starts with '<' followed by letter, '/', '!', or '?'
+ if (str.charCodeAt(pos) === 0x3c /* < */ && pos + 1 < len) {
+ const next = str.charCodeAt(pos + 1)
+ if (next === 0x21 /* ! */ || next === 0x3f /* ? */ || next === 0x2f /* / */ || isLetter(next)) {
+ const match = str.slice(pos).match(HTML_TAG_RE)
+ if (match) {
+ if (pos > textStart) pushText(tokens, str.slice(textStart, pos))
+ const html = new Token('html_inline', '', 0)
+ html.content = match[0]
+ tokens.push(html)
+ pos += match[0].length
+ textStart = pos
+ continue
+ }
+ }
+ }
+ pos++
+ }
+
+ if (textStart < len) pushText(tokens, str.slice(textStart))
+
+ return tokens
+}
diff --git a/packages/comark/src/plugins/summary.ts b/packages/comark/src/plugins/summary.ts
index bb390983..90de97a3 100644
--- a/packages/comark/src/plugins/summary.ts
+++ b/packages/comark/src/plugins/summary.ts
@@ -1,6 +1,4 @@
import type { Node } from 'comark'
-import { applyAutoUnwrap } from '../internal/parse/auto-unwrap.ts'
-import { marmdownItTokensToMarkdownDocument } from '../internal/parse/token-processor.ts'
import { defineComarkPlugin } from '../utils/helpers.ts'
export default defineComarkPlugin<{ delimiter?: string }, { summary: Node[] }>((options = {}) => {
@@ -10,18 +8,10 @@ export default defineComarkPlugin<{ delimiter?: string }, { summary: Node[] }>((
post(state) {
let summary: Node[] | undefined
- const delimiterIndex = state.tokens.findIndex(
- (token: any) => token.type === 'html_block' && token.content?.includes(delimiter)
- )
+ const delimiterIndex = state.tree.nodes.findIndex((node) => node[0] === null && delimiter === ``)
if (delimiterIndex !== -1) {
- const summaryTokens = state.tokens.slice(0, delimiterIndex)
- summary = marmdownItTokensToMarkdownDocument(summaryTokens)
-
- // Apply auto-unwrap to summary as well
- if (state.options.autoUnwrap) {
- summary = summary?.map((child: Node) => applyAutoUnwrap(child))
- }
+ summary = state.tree.nodes.slice(0, delimiterIndex)
if (summary) {
state.tree.meta.summary = summary
diff --git a/packages/comark/src/types.ts b/packages/comark/src/types.ts
index 50ceeae9..c282138f 100644
--- a/packages/comark/src/types.ts
+++ b/packages/comark/src/types.ts
@@ -1,5 +1,6 @@
import type { DumpOptions } from 'js-yaml'
import type MarkdownExit from 'markdown-exit'
+import type { Token } from 'markdown-exit'
import type MarkdownIt from 'markdown-it'
// #region Utility Types
@@ -282,18 +283,22 @@ export type MarkdownExitPlugin = (md: MarkdownExit) => void
export type MarkdownItPlugin = (md: MarkdownIt) => void
export type MarkdownItPluginWithOptions = (md: MarkdownIt, options: T) => void
-export type ComarkParsePreState = {
+export interface ComarkParsePreState {
markdown: string
options: ParserOptions
[key: string]: any
}
-export type ComarkParsePostState, TFrontmatter = Record> = {
- markdown: string
+export interface ComarkParseTokensState extends ComarkParsePreState {
+ tokens: Token[]
+}
+
+export interface ComarkParsePostState<
+ TMeta = Record,
+ TFrontmatter = Record,
+> extends ComarkParseTokensState {
tree: MarkdownDocument
- options: ParserOptions
- tokens: unknown[]
[key: string]: any
}
@@ -361,6 +366,7 @@ export interface ComarkTracer {
export type ComarkPlugin = {
name: string
markdownItPlugins?: MarkdownItPlugin[]
+ markdownItPost?: (state: ComarkParseTokensState) => void
pre?: (state: ComarkParsePreState) => Promise | void
post?: (state: ComarkParsePostState, Writable>) => Promise | void
/** Phantom — used for type inference only. Never set at runtime. */
diff --git a/packages/comark/src/utils/index.ts b/packages/comark/src/utils/index.ts
index 76790343..76ec9522 100644
--- a/packages/comark/src/utils/index.ts
+++ b/packages/comark/src/utils/index.ts
@@ -3,6 +3,8 @@
import { decodeHTML } from 'entities'
import type { Node, MarkdownDocument } from 'comark'
+export { decodeHTML } from 'entities'
+
type VisitResult = Node | false | undefined | void
/**
@@ -35,11 +37,21 @@ export function textContent(node: Node, options: { decodeUnicodeEntities?: boole
return out
}
+/** Walk at most this many element levels. Typical markdown trees are much shallower. */
+export const TREE_WALK_MAX_DEPTH = 50
+
function* walkGenerator(
document: MarkdownDocument,
checker: (node: Node) => boolean
): Generator {
- function* walk(node: Node, parent: Node | Node[], index: number): Generator {
+ function* walk(
+ node: Node,
+ parent: Node | Node[],
+ index: number,
+ depth: number
+ ): Generator {
+ if (depth >= TREE_WALK_MAX_DEPTH) return false
+
let currentNode = node
if (checker(node)) {
@@ -61,7 +73,7 @@ function* walkGenerator(
// Use a while loop to handle removals correctly - don't increment if node was removed
let i = 2
while (i < currentNode.length) {
- const childRemoved = yield* walk(currentNode[i] as Node, currentNode, i)
+ const childRemoved = yield* walk(currentNode[i] as Node, currentNode, i, depth + 1)
if (childRemoved) {
// If removed, i stays the same (next node is now at this index)
continue
@@ -76,7 +88,7 @@ function* walkGenerator(
// Use a while loop to handle removals correctly - don't increment if node was removed
let i = 0
while (i < document.nodes.length) {
- const removed = yield* walk(document.nodes[i], document.nodes, i)
+ const removed = yield* walk(document.nodes[i], document.nodes, i, 0)
if (removed) {
// If removed, i stays the same (next node is now at this index)
continue
@@ -86,7 +98,8 @@ function* walkGenerator(
}
/**
- * Visit a Markdown document and apply a visitor function to each node
+ * Visit a Markdown document and apply a visitor function to each node.
+ * Recursion is capped at {@link TREE_WALK_MAX_DEPTH} element levels; deeper subtrees are left as-is.
*
* @param document - The Markdown document
* @param checker - A function that checks if a node should be visited
@@ -107,6 +120,7 @@ export function visit(
}
}
+/** Recursion is capped at {@link TREE_WALK_MAX_DEPTH} element levels; deeper subtrees are left as-is. */
export async function visitAsync(
document: MarkdownDocument,
checker: (node: Node) => boolean,
diff --git a/packages/comark/test/auto-close.test.ts b/packages/comark/test/auto-close.test.ts
index 68a11174..ae71f4b9 100644
--- a/packages/comark/test/auto-close.test.ts
+++ b/packages/comark/test/auto-close.test.ts
@@ -32,7 +32,11 @@ $$formula → $$formula
_ not valid → _ not valid
__ not valid → __ not valid
~ not valid → ~ not valid
-~~ not valid → ~~ not valid`
+~~ not valid → ~~ not valid
+The cost is $ → The cost is $
+~Hello → ~Hello
+~~Hello~~ → ~~Hello~~
+~~ Hello → ~~ Hello`
const multilines = `
| Month | Savings
diff --git a/packages/comark/test/auto-unwrap.test.ts b/packages/comark/test/auto-unwrap.test.ts
index d7585f1e..0bf3e16e 100644
--- a/packages/comark/test/auto-unwrap.test.ts
+++ b/packages/comark/test/auto-unwrap.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it } from 'vitest'
-import { applyAutoUnwrap } from '../src/internal/parse/auto-unwrap'
+import { applyAutoUnwrap } from '../src/internal/parse/utils'
+import { TREE_WALK_MAX_DEPTH } from 'comark/utils'
import type { Node } from 'comark'
describe('applyAutoUnwrap', () => {
@@ -84,4 +85,61 @@ describe('applyAutoUnwrap', () => {
// Should unwrap the paragraph and filter out whitespace
expect(result).toEqual(['warning', {}, 'Warning text'])
})
+
+ it('should not unwrap a markdown paragraph next to HTML siblings', () => {
+ const node: Node = [
+ 'details',
+ { $: { html: 1, block: 1 } },
+ ['summary', { $: { html: 1, block: 0 } }, 'Top'],
+ ['p', {}, 'Body'],
+ ]
+
+ const result = applyAutoUnwrap(node)
+ // Paragraph is not the sole child — keep the wrapper.
+ expect(result).toEqual([
+ 'details',
+ { $: { html: 1, block: 1 } },
+ ['summary', { $: { html: 1, block: 0 } }, 'Top'],
+ ['p', {}, 'Body'],
+ ])
+ })
+
+ it('should still unwrap a sole markdown paragraph under an HTML container', () => {
+ const node: Node = ['details', { $: { html: 1, block: 1 } }, ['p', {}, 'Only body']]
+
+ const result = applyAutoUnwrap(node)
+ expect(result).toEqual(['details', { $: { html: 1, block: 1 } }, 'Only body'])
+ })
+
+ it('should unwrap a nested paragraph within the depth cap', () => {
+ // TREE_WALK_MAX_DEPTH wrappers (d0…dN-1) + paragraph — last wrapper is still processed.
+ let node: Node = ['p', {}, 'Deep']
+ for (let i = TREE_WALK_MAX_DEPTH - 1; i >= 0; i--) {
+ node = [`d${i}`, {}, node]
+ }
+
+ const result = applyAutoUnwrap(node)
+ let cursor = result as Node[]
+ for (let i = 0; i < TREE_WALK_MAX_DEPTH; i++) {
+ expect(cursor[0]).toBe(`d${i}`)
+ cursor = cursor[2] as Node[]
+ }
+ expect(cursor).toBe('Deep')
+ })
+
+ it('should not walk past TREE_WALK_MAX_DEPTH element levels', () => {
+ // TREE_WALK_MAX_DEPTH + 1 wrappers (d0…dN) + paragraph — last wrapper is past the cap.
+ let node: Node = ['p', {}, 'Too deep']
+ for (let i = TREE_WALK_MAX_DEPTH; i >= 0; i--) {
+ node = [`d${i}`, {}, node]
+ }
+
+ const result = applyAutoUnwrap(node)
+ let cursor = result as Node[]
+ for (let i = 0; i <= TREE_WALK_MAX_DEPTH; i++) {
+ expect(cursor[0]).toBe(`d${i}`)
+ cursor = cursor[2] as Node[]
+ }
+ expect(cursor).toEqual(['p', {}, 'Too deep'])
+ })
})
diff --git a/packages/comark/test/html-block.test.ts b/packages/comark/test/html-block.test.ts
index c19b8748..0205dd47 100644
--- a/packages/comark/test/html-block.test.ts
+++ b/packages/comark/test/html-block.test.ts
@@ -1,14 +1,76 @@
import { describe, expect, it } from 'vitest'
import { parseMarkdown } from '../src/index'
+import html from '../src/plugins/html'
const sponsorsUrl = 'https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg'
+describe('html({ markdown })', () => {
+ it('parses markdown inside incomplete HTML by default', async () => {
+ const result = await parseMarkdown('\n**bold**')
+
+ expect(result.nodes).toEqual([['ai-thinking', { $: { html: 1, block: 1 } }, ['strong', {}, 'bold']]])
+ })
+
+ it('parses markdown inside closed HTML without a blank line by default', async () => {
+ const result = await parseMarkdown('\nHello **World**\n
')
+
+ expect(result.nodes).toEqual([['div', { $: { html: 1, block: 1 } }, 'Hello ', ['strong', {}, 'World']]])
+ })
+
+ it('keeps markdown literal inside incomplete HTML when markdown: false', async () => {
+ const result = await parseMarkdown('\n**bold**', {
+ // Replace the default html plugin so only this config is active.
+ plugins: [html({ markdown: false })],
+ })
+
+ // Body is a single text leaf → block: 0 (inline-like incomplete opener).
+ expect(result.nodes).toEqual([['ai-thinking', { $: { html: 1, block: 1 } }, '**bold**']])
+ })
+
+ it('still parses markdown after a blank line when markdown: false', async () => {
+ const result = await parseMarkdown('\n\n**bold**\n\n', {
+ plugins: [html({ markdown: false })],
+ })
+
+ expect(result.nodes).toEqual([['ai-thinking', { $: { html: 1, block: 1 } }, ['strong', {}, 'bold']]])
+ })
+
+ it('still keeps closed HTML body literal without a blank line when markdown: false', async () => {
+ const result = await parseMarkdown('\nHello **World**\n
', {
+ plugins: [html({ markdown: false })],
+ })
+
+ expect(result.nodes).toEqual([['div', { $: { html: 1, block: 1 } }, 'Hello **World**']])
+ })
+
+ it('parses markdown inside closed HTML after a blank line when markdown: false', async () => {
+ const result = await parseMarkdown('\n\nHello **World**\n\n
', {
+ plugins: [html({ markdown: false })],
+ })
+
+ expect(result.nodes).toEqual([['div', { $: { html: 1, block: 1 } }, 'Hello ', ['strong', {}, 'World']]])
+ })
+
+ it('nests following markdown under an incomplete bare HTML opener (EOF)', async () => {
+ const result = await parseMarkdown('\n\n**bold** and more\n\n- list\n- **item**')
+
+ expect(result.nodes).toEqual([
+ [
+ 'ai-thinking',
+ { $: { html: 1, block: 1 } },
+ ['p', {}, ['strong', {}, 'bold'], ' and more'],
+ ['ul', {}, ['li', {}, 'list'], ['li', {}, ['strong', {}, 'item']]],
+ ],
+ ])
+ })
+})
+
describe('block-level raw HTML', () => {
it('preserves inline children inside a self-contained block-level ', async () => {
const result = await parseMarkdown('
')
expect(result.nodes).toEqual([
- ['p', { $: { html: 1, block: 1 } }, ['img', { $: { html: 1, block: 1 }, src: '/foo.png', alt: 'x' }]],
+ ['p', { $: { html: 1, block: 1 } }, ['img', { $: { html: 1, block: 0 }, src: '/foo.png', alt: 'x' }]],
])
})
@@ -19,9 +81,9 @@ describe('block-level raw HTML', () => {
[
'p',
{ $: { html: 1, block: 1 } },
- 'hello',
- ['img', { $: { html: 1, block: 1 }, src: '/foo.png', alt: 'x' }],
- 'world',
+ 'hello ',
+ ['img', { $: { html: 1, block: 0 }, src: '/foo.png', alt: 'x' }],
+ ' world',
],
])
})
@@ -37,7 +99,7 @@ That is some text here.`
expect(result.nodes).toEqual([
['h1', { id: 'hello' }, 'Hello'],
- ['p', { $: { html: 1, block: 1 } }, ['img', { $: { html: 1, block: 1 }, src: '/foo.png', alt: 'x' }]],
+ ['p', { $: { html: 1, block: 1 } }, ['img', { $: { html: 1, block: 0 }, src: '/foo.png', alt: 'x' }]],
['p', {}, 'That is some text here.'],
])
})
@@ -48,47 +110,72 @@ That is some text here.`
expect(result.nodes).toEqual([['div', { $: { html: 1, block: 1 } }, 'foo']])
})
- it('preserves text inside a multiline raw HTML verbatim — no markdown re-parsing', async () => {
+ it('parses markdown inside a tight multiline HTML
by default', async () => {
const result = await parseMarkdown(`
this is **markdown**
`)
- expect(result.nodes).toEqual([['p', { $: { html: 1, block: 1 } }, 'this is **markdown**']])
+ expect(result.nodes).toEqual([['p', { $: { html: 1, block: 1 } }, 'this is ', ['strong', {}, 'markdown']]])
})
- it('parses markdown as a sibling when a blank line separates it from the HTML tags', async () => {
- const result = await parseMarkdown(`
+ it('nests blank-line markdown body under a matching HTML open/close pair', async () => {
+ const result = await parseMarkdown(`
this is **markdown**
-
`)
+`)
+
+ expect(result.nodes).toEqual([['main', { $: { html: 1, block: 1 } }, 'this is ', ['strong', {}, 'markdown']]])
+ })
+
+ it.skip('pairs HTML open/close split across paragraphs (inline opener + blank line)', async () => {
+ // CommonMark leaves `` / `
` in different paragraphs when a blank line
+ // sits between them. html_balance lifts both to html_block so the body nests.
+ const result = await parseMarkdown('dsd Real paragraph\n\nwith `code x` inside.
')
expect(result.nodes).toEqual([
- ['p', { $: { html: 1, block: 1 } }],
- ['p', {}, 'this is ', ['strong', {}, 'markdown']],
- ['p', { $: { html: 1, block: 1 } }],
+ ['p', {}, 'dsd '],
+ [
+ 'p',
+ { $: { html: 1, block: 1 } },
+ ['p', {}, 'Real paragraph'],
+ ['p', {}, 'with ', ['code', {}, 'code x'], ' inside.'],
+ ],
])
})
- it('preserves mixed text and raw HTML children verbatim inside a multiline raw HTML block', async () => {
+ it.skip('keeps trailing text after a cross-boundary HTML closer outside the element', async () => {
+ const result = await parseMarkdown('before \n\n**bold**\n\n
after')
+
+ expect(result.nodes).toEqual([
+ ['p', {}, 'before '],
+ ['div', { $: { html: 1, block: 1 } }, ['strong', {}, 'bold']],
+ ['p', {}, 'after'],
+ ])
+ })
+
+ it('parses markdown among mixed HTML children inside a closed multiline HTML block', async () => {
const result = await parseMarkdown(`
before **strong**
after \`code\`
before **strong**
@@ -100,14 +187,19 @@ after \`code\`
`)
expect(result.nodes).toEqual([
- ['div', { $: { html: 1, block: 1 } }],
- ['p', {}, 'before ', ['strong', {}, 'strong']],
- ['img', { $: { html: 1, block: 1 }, src: '/x.png', alt: 'x' }],
- ['p', {}, 'after ', ['code', {}, 'code']],
+ [
+ 'div',
+ { $: { html: 1, block: 1 } },
+ ['p', {}, 'before ', ['strong', {}, 'strong']],
+ ['img', { $: { html: 1, block: 0 }, src: '/x.png', alt: 'x' }],
+ ['p', {}, 'after ', ['code', {}, 'code']],
+ ],
])
})
- it('keeps indented non-HTML content inside a multiline raw HTML block as raw text', async () => {
+ it('keeps indented non-HTML content inside a closed multiline HTML block as raw text', async () => {
+ // No blank line before closer → CommonMark span; text leaves stay literal
+ // (no block-level code fence from 4-space indent).
const result = await parseMarkdown(`
const value = 1
`)
@@ -122,11 +214,23 @@ after \`code\`
`)
expect(result.nodes).toEqual([
- ['div', { $: { html: 1, block: 1 } }, [null, {}, ' note '], ['img', { $: { html: 1, block: 1 }, src: '/x.png' }]],
+ ['div', { $: { html: 1, block: 1 } }, [null, {}, ' note '], ['img', { $: { html: 1, block: 0 }, src: '/x.png' }]],
])
})
- it('preserves nested indented raw HTML children inside a multiline ', async () => {
+ it('multi ', async () => {
+ const result = await parseMarkdown(`
This is a warning message.
+ Your changes have been saved.
+ More information is available here.
`)
+
+ expect(result.nodes).toEqual([
+ ['p', { $: { html: 1, block: 0 }, class: 'warning' }, 'This is a warning message.'],
+ ['p', { $: { html: 1, block: 0 }, class: 'success' }, 'Your changes have been saved.'],
+ ['p', { $: { html: 1, block: 0 }, class: 'info' }, 'More information is available here.'],
+ ])
+ })
+
+ it.skip('preserves nested indented raw HTML children inside a multiline ', async () => {
const result = await parseMarkdown(`
`)
@@ -135,18 +239,19 @@ after \`code\`
[
'a',
{ $: { html: 1, block: 1 }, href: sponsorsUrl },
- ['img', { $: { html: 1, block: 1 }, src: sponsorsUrl, alt: 'Sponsors' }],
+ ['img', { $: { html: 1, block: 0 }, src: sponsorsUrl, alt: 'Sponsors' }],
],
])
})
- it('preserves nested indented raw HTML children inside a wrapped multiline ', async () => {
+ it.skip('preserves nested indented raw HTML children inside a wrapped multiline
', async () => {
const result = await parseMarkdown(`
`)
+ // Nested spans multiple lines → block: 1; void ![]()
is single-line → block: 0
expect(result.nodes).toEqual([
[
'p',
@@ -154,7 +259,7 @@ after \`code\`
[
'a',
{ $: { html: 1, block: 1 }, href: sponsorsUrl },
- ['img', { $: { html: 1, block: 1 }, src: sponsorsUrl, alt: 'Sponsors' }],
+ ['img', { $: { html: 1, block: 0 }, src: sponsorsUrl, alt: 'Sponsors' }],
],
],
])
@@ -181,4 +286,48 @@ after \`code\`
expect(result.nodes).toEqual([['pre', {}, ['code', {}, '']]])
})
+
+ it('styles', async () => {
+ const result = await parseMarkdown(`
+
+ This is a warning message.
+ Your changes have been saved.
+ More information is available here.
`)
+
+ expect(result.nodes).toEqual([
+ [
+ 'style',
+ {
+ $: {
+ block: 1,
+ html: 1,
+ },
+ },
+ `.warning {
+ color: red;
+ }
+ .success {
+ color: green;
+ }
+
+ .info {
+ color: blue;
+ }`,
+ ],
+ ['p', { $: { html: 1, block: 0 }, class: 'warning' }, 'This is a warning message.'],
+ ['p', { $: { html: 1, block: 0 }, class: 'success' }, 'Your changes have been saved.'],
+ ['p', { $: { html: 1, block: 0 }, class: 'info' }, 'More information is available here.'],
+ ])
+ })
})
diff --git a/packages/comark/test/html-escape.test.ts b/packages/comark/test/html-escape.test.ts
index 6551678d..f0fb8593 100644
--- a/packages/comark/test/html-escape.test.ts
+++ b/packages/comark/test/html-escape.test.ts
@@ -17,6 +17,18 @@ describe('HTML attribute escaping', () => {
expect(html).not.toContain('title="a" onmouseover=alert(1)"')
})
+ it('decodes " inside quoted HTML attribute values', async () => {
+ const tree = await parseMarkdown('hi')
+ const p = tree.nodes[0] as [string, Record, ...Node[]]
+ const span = (Array.isArray(p[2]) ? p[2] : p) as [string, Record, ...Node[]]
+ expect(span[0]).toBe('span')
+ expect(span[1].title).toBe('A "quote"')
+
+ const html = await renderHtml('hi')
+ expect(html).toContain('title="A "quote""')
+ expect(html).not.toContain('title="A "quote""')
+ })
+
it('escapes quotes in component attribute props', async () => {
const html = await renderHtml(`:span[hi]{title='a" onmouseover=alert(1) x="b'}`)
expect(html).toContain('title="a" onmouseover=alert(1) x="b"')
@@ -49,6 +61,16 @@ describe('HTML attribute escaping', () => {
expect(html).toContain('title="a&b<c>d"')
})
+ it('escapes bare ampersands in URL attribute values', async () => {
+ // Query-string `&` must become `&` in HTML attrs (HTML5).
+ // Re-parse still yields bare `&` because htmlparser2 decodes entities.
+ const html = await renderHtml(`
`)
+ expect(html).toContain('src="https://x.com/?a=1&b=2"')
+ const tree = await parseMarkdown(html)
+ const img = tree.nodes[0] as [string, Record]
+ expect(img[1].src).toBe('https://x.com/?a=1&b=2')
+ })
+
it('escapes object attribute values as JSON with entities', async () => {
const html = await renderNodes([['div', { ':data': { x: '">
' } }, 'hi']])
expect(html).not.toContain('')
diff --git a/packages/comark/test/plugins/default-plugins.test.ts b/packages/comark/test/plugins/default-plugins.test.ts
index d47605e5..bcd97005 100644
--- a/packages/comark/test/plugins/default-plugins.test.ts
+++ b/packages/comark/test/plugins/default-plugins.test.ts
@@ -25,7 +25,7 @@ describe('default plugin options', () => {
it('parses HTML by default', async () => {
const tree = await parseMarkdown('Hello')
- expect(tree.nodes).toEqual([['p', {}, ['strong', { class: 'bold', $: { html: 1, block: 0 } }, 'Hello']]])
+ expect(tree.nodes).toEqual([['strong', { class: 'bold', $: { html: 1, block: 0 } }, 'Hello']])
})
it('parses frontmatter by default', async () => {
@@ -64,7 +64,7 @@ describe('default plugin options', () => {
registerDefaultPlugins: false,
plugins: [html()],
})
- expect(tree.nodes).toEqual([['p', {}, ['em', { $: { html: 1, block: 0 } }, 'hi']]])
+ expect(tree.nodes).toEqual([['em', { $: { html: 1, block: 0 } }, 'hi']])
})
it('treats attribute braces as plain text when registerDefaultPlugins is false', async () => {
diff --git a/packages/comark/test/plugins/summary.test.ts b/packages/comark/test/plugins/summary.test.ts
index c820e45f..fca097c3 100644
--- a/packages/comark/test/plugins/summary.test.ts
+++ b/packages/comark/test/plugins/summary.test.ts
@@ -13,7 +13,6 @@ After the fold.
describe('summary plugin', () => {
it('writes the nodes before the delimiter to tree.meta.summary', async () => {
const tree = await parseMarkdown(CONTENT, { plugins: [summary()] })
-
expect(tree.meta.summary).toEqual([['p', {}, 'Intro paragraph.']])
})
diff --git a/packages/comark/test/visit.test.ts b/packages/comark/test/visit.test.ts
index a6b6df40..6326b18c 100644
--- a/packages/comark/test/visit.test.ts
+++ b/packages/comark/test/visit.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest'
-import { visit } from 'comark/utils'
+import { TREE_WALK_MAX_DEPTH, visit } from 'comark/utils'
import type { MarkdownDocument, Node } from 'comark'
describe('visit', () => {
@@ -409,4 +409,53 @@ describe('visit', () => {
expect(tree.nodes[1]).toEqual(['section', {}, 'Replaced'])
expect(tree.nodes[2]).toEqual(['span', {}, 'Keep'])
})
+
+ it('should visit nodes within the depth cap', () => {
+ // TREE_WALK_MAX_DEPTH - 1 wrappers + text — text is at depth N-1 and still visited.
+ let node: Node = 'Deep'
+ for (let i = TREE_WALK_MAX_DEPTH - 2; i >= 0; i--) {
+ node = [`d${i}`, {}, node]
+ }
+
+ const tree: MarkdownDocument = { nodes: [node], frontmatter: {}, meta: {} }
+ const visited: string[] = []
+ visit(
+ tree,
+ () => true,
+ (n) => {
+ visited.push(typeof n === 'string' ? n : String(n[0]))
+ }
+ )
+
+ const expected = Array.from({ length: TREE_WALK_MAX_DEPTH - 1 }, (_, i) => `d${i}`)
+ expected.push('Deep')
+ expect(visited).toEqual(expected)
+ })
+
+ it('should not walk past TREE_WALK_MAX_DEPTH element levels', () => {
+ // TREE_WALK_MAX_DEPTH + 1 wrappers + text — last wrapper and its children are past the cap.
+ let node: Node = 'Too deep'
+ for (let i = TREE_WALK_MAX_DEPTH; i >= 0; i--) {
+ node = [`d${i}`, {}, node]
+ }
+
+ const tree: MarkdownDocument = { nodes: [node], frontmatter: {}, meta: {} }
+ const visited: string[] = []
+ visit(
+ tree,
+ () => true,
+ (n) => {
+ visited.push(typeof n === 'string' ? n : String(n[0]))
+ }
+ )
+
+ expect(visited).toEqual(Array.from({ length: TREE_WALK_MAX_DEPTH }, (_, i) => `d${i}`))
+
+ let cursor = tree.nodes[0] as Node[]
+ for (let i = 0; i <= TREE_WALK_MAX_DEPTH; i++) {
+ expect(cursor[0]).toBe(`d${i}`)
+ cursor = cursor[2] as Node[]
+ }
+ expect(cursor).toBe('Too deep')
+ })
})
+
