From 6505abb37fd25702c8ef8971e0640ca39fe23565 Mon Sep 17 00:00:00 2001
From: ocavue <ocavue@gmail.com>
Date: Wed, 8 Jul 2026 03:48:17 +1000
Subject: [PATCH 1/9] feat(core): add `htmlBlock` node for raw HTML blocks

---
 packages/core/src/converters/md-to-pm.test.ts | 58 ++++++++++++++-
 packages/core/src/converters/md-to-pm.ts      | 73 ++++++++++++-------
 packages/core/src/converters/pm-to-md.ts      |  4 +
 .../core/src/converters/roundtrip.test.ts     | 18 +++++
 packages/core/src/extensions/extension.ts     |  2 +
 .../core/src/extensions/html-block.test.ts    | 49 +++++++++++++
 packages/core/src/extensions/html-block.ts    | 61 ++++++++++++++++
 packages/core/src/extensions/node-names.ts    |  1 +
 packages/core/src/index.ts                    |  1 +
 9 files changed, 237 insertions(+), 30 deletions(-)
 create mode 100644 packages/core/src/extensions/html-block.test.ts
 create mode 100644 packages/core/src/extensions/html-block.ts

diff --git a/packages/core/src/converters/md-to-pm.test.ts b/packages/core/src/converters/md-to-pm.test.ts
index 52d867c3..a023e5e4 100644
--- a/packages/core/src/converters/md-to-pm.test.ts
+++ b/packages/core/src/converters/md-to-pm.test.ts
@@ -824,19 +824,69 @@ describe('markdownToDoc', () => {
     })
   })
 
-  it('keeps a raw HTML block', () => {
+  it('maps a raw HTML block onto an htmlBlock node', () => {
     expect(markdownToDoc('<div>html</div>').toJSON()).toEqual({
       type: 'doc',
       attrs: { frontmatter: null },
-      content: [{ type: 'paragraph', content: [{ type: 'text', text: '<div>html</div>' }] }],
+      content: [{ type: 'htmlBlock', content: [{ type: 'text', text: '<div>html</div>' }] }],
     })
   })
 
-  it('keeps a processing instruction', () => {
+  it('keeps a multi-line HTML block in one htmlBlock node', () => {
+    expect(markdownToDoc('<div class="x">\nhello\n</div>').toJSON()).toEqual({
+      type: 'doc',
+      attrs: { frontmatter: null },
+      content: [
+        { type: 'htmlBlock', content: [{ type: 'text', text: '<div class="x">\nhello\n</div>' }] },
+      ],
+    })
+  })
+
+  it('keeps a blank line inside a type-1 HTML block', () => {
+    // `<pre>` blocks end on `</pre>`, not on a blank line (CommonMark 4.6
+    // type 1), so the blank line is block content.
+    expect(markdownToDoc('<pre>\none\n\ntwo\n</pre>').toJSON()).toEqual({
+      type: 'doc',
+      attrs: { frontmatter: null },
+      content: [
+        { type: 'htmlBlock', content: [{ type: 'text', text: '<pre>\none\n\ntwo\n</pre>' }] },
+      ],
+    })
+  })
+
+  it('swallows markdown lines into an unclosed type-6 block', () => {
+    // `<div>` without a following blank line absorbs the next lines up to the
+    // first blank line, heading syntax included (CommonMark 4.6).
+    expect(markdownToDoc('<div>\n# heading\n</div>\n\nafter').toJSON()).toEqual({
+      type: 'doc',
+      attrs: { frontmatter: null },
+      content: [
+        { type: 'htmlBlock', content: [{ type: 'text', text: '<div>\n# heading\n</div>' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'after' }] },
+      ],
+    })
+  })
+
+  it('dedents a multi-line HTML block inside a blockquote', () => {
+    expect(markdownToDoc('> <div>\n> hello\n> </div>').toJSON()).toEqual({
+      type: 'doc',
+      attrs: { frontmatter: null },
+      content: [
+        {
+          type: 'blockquote',
+          content: [
+            { type: 'htmlBlock', content: [{ type: 'text', text: '<div>\nhello\n</div>' }] },
+          ],
+        },
+      ],
+    })
+  })
+
+  it('maps a processing instruction onto an htmlBlock node', () => {
     expect(markdownToDoc('<?php echo 1; ?>').toJSON()).toEqual({
       type: 'doc',
       attrs: { frontmatter: null },
-      content: [{ type: 'paragraph', content: [{ type: 'text', text: '<?php echo 1; ?>' }] }],
+      content: [{ type: 'htmlBlock', content: [{ type: 'text', text: '<?php echo 1; ?>' }] }],
     })
   })
 
diff --git a/packages/core/src/converters/md-to-pm.ts b/packages/core/src/converters/md-to-pm.ts
index 04a337c1..f1086ce0 100644
--- a/packages/core/src/converters/md-to-pm.ts
+++ b/packages/core/src/converters/md-to-pm.ts
@@ -158,14 +158,13 @@ function convertBlock(
     case LEZER_NODE_IDS.CommentBlock:
       // A comment is not rendered output: map it onto the invisible `htmlComment`
       // node so it stays in the document (and round-trips) without reading as
-      // body text. Raw HTML / processing-instruction blocks fall through to a
-      // paragraph - they can carry content a reader expects to see.
+      // body text.
       return [convertHTMLComment(nodes, cursor, text)]
     case LEZER_NODE_IDS.HTMLBlock:
     case LEZER_NODE_IDS.ProcessingInstructionBlock:
-      // The schema has no HTML node, so keep the raw block as literal paragraph
-      // text; it survives verbatim through a round-trip.
-      return [convertParagraph(nodes, cursor, text)]
+      // Raw HTML keeps its literal source as an `htmlBlock` node: byte-exact
+      // round trip, and no markdown parsing inside (CommonMark 4.6).
+      return [convertHTMLBlock(nodes, cursor, text)]
     case LEZER_NODE_IDS.Blockquote:
       return [convertBlockquote(nodes, cursor, text)]
     case LEZER_NODE_IDS.BulletList:
@@ -340,32 +339,54 @@ function buildParagraph(
   return nodes.paragraph(dedentContinuation(content, column))
 }
 
+/**
+ * A leaf block's literal source: the block's span, dedented like a paragraph's.
+ * In block-only parsing a leaf block has no inline children, with one
+ * exception: lezer leaves the container `QuoteMark`s of a multi-line block
+ * inside a blockquote (`> l1\n> l2`) embedded in the block's span, so they are
+ * stripped here.
+ */
+function sliceLeafBlockText(cursor: TreeCursor, text: string): string {
+  const from = cursor.from
+  const to = cursor.to
+  const column = measureContentColumn(text, from)
+  if (!cursor.firstChild()) {
+    return dedentContinuation(text.slice(from, to), column)
+  }
+  let content = ''
+  let pos = from
+  do {
+    if (cursor.type.id === LEZER_NODE_IDS.QuoteMark) {
+      content += text.slice(pos, cursor.from)
+      pos = cursor.to
+      if (isSpaceChar(text.charCodeAt(pos))) pos += 1
+    }
+  } while (cursor.nextSibling())
+  cursor.parent()
+  content += text.slice(pos, to)
+  return dedentContinuation(content, column)
+}
+
 function convertParagraph(
   nodes: TypedNodeBuilders,
   cursor: TreeCursor,
   text: string,
 ): ProseMirrorNode {
-  const from = cursor.from
-  const to = cursor.to
-  const column = measureContentColumn(text, from)
-  // In block-only parsing a paragraph has no inline children, with one
-  // exception: lezer leaves the lazy-continuation `QuoteMark`s of a multi-line
-  // blockquote (`> l1\n> l2`) embedded in the paragraph's span.
-  if (cursor.firstChild()) {
-    let content = ''
-    let pos = from
-    do {
-      if (cursor.type.id === LEZER_NODE_IDS.QuoteMark) {
-        content += text.slice(pos, cursor.from)
-        pos = cursor.to
-        if (isSpaceChar(text.charCodeAt(pos))) pos += 1
-      }
-    } while (cursor.nextSibling())
-    cursor.parent()
-    content += text.slice(pos, to)
-    return buildParagraph(nodes, content, column)
-  }
-  return buildParagraph(nodes, text.slice(from, to), column)
+  // An empty string adds no child (the builder skips falsy text), so this also
+  // covers the empty-paragraph case.
+  return nodes.paragraph(sliceLeafBlockText(cursor, text))
+}
+
+/**
+ * Build the `htmlBlock` node from a raw HTML block. The literal source becomes
+ * the node's text content, so the round trip is byte-exact.
+ */
+function convertHTMLBlock(
+  nodes: TypedNodeBuilders,
+  cursor: TreeCursor,
+  text: string,
+): ProseMirrorNode {
+  return nodes.htmlBlock(sliceLeafBlockText(cursor, text))
 }
 
 /**
diff --git a/packages/core/src/converters/pm-to-md.ts b/packages/core/src/converters/pm-to-md.ts
index e0046cdc..66918ba5 100644
--- a/packages/core/src/converters/pm-to-md.ts
+++ b/packages/core/src/converters/pm-to-md.ts
@@ -260,6 +260,10 @@ function emit(node: ProseMirrorNode, out: MdOut): void {
       out.closeBlock()
       return
     }
+    case 'htmlBlock':
+      out.write(node.textContent)
+      out.closeBlock()
+      return
     case 'htmlComment': {
       const { content } = node.attrs as MeowdownHTMLCommentAttrs
       out.write(content)
diff --git a/packages/core/src/converters/roundtrip.test.ts b/packages/core/src/converters/roundtrip.test.ts
index 9a8a5d36..0a82e7f2 100644
--- a/packages/core/src/converters/roundtrip.test.ts
+++ b/packages/core/src/converters/roundtrip.test.ts
@@ -198,6 +198,24 @@ describe('inline', () => {
     expect(roundtrip('<div>html</div>')).toBe('<div>html</div>\n')
   })
 
+  it('keeps a multi-line HTML block', () => {
+    expect(roundtrip('<div class="x">\nhello\n</div>')).toBe('<div class="x">\nhello\n</div>\n')
+  })
+
+  it('keeps a blank line inside a type-1 HTML block', () => {
+    expect(roundtrip('<pre>\none\n\ntwo\n</pre>')).toBe('<pre>\none\n\ntwo\n</pre>\n')
+  })
+
+  it('keeps an HTML block inside a blockquote', () => {
+    expect(roundtrip('> <div>\n> hello\n> </div>')).toBe('> <div>\n> hello\n> </div>\n')
+  })
+
+  it('keeps an unclosed type-6 block that swallowed markdown lines', () => {
+    expect(roundtrip('<div>\n# heading\n</div>\n\nafter')).toBe(
+      '<div>\n# heading\n</div>\n\nafter\n',
+    )
+  })
+
   it('keeps an HTML comment', () => {
     expect(roundtrip('<!-- comment -->')).toBe('<!-- comment -->\n')
   })
diff --git a/packages/core/src/extensions/extension.ts b/packages/core/src/extensions/extension.ts
index a3e64a09..59090379 100644
--- a/packages/core/src/extensions/extension.ts
+++ b/packages/core/src/extensions/extension.ts
@@ -21,6 +21,7 @@ import { defineDocFrontmatterAttr } from './frontmatter.ts'
 import { defineHeading } from './heading.ts'
 import { defineHiddenRunCaret } from './hidden-run-caret.ts'
 import { defineMeowdownHorizontalRule } from './horizontal-rule.ts'
+import { defineHTMLBlock } from './html-block.ts'
 import { defineHTMLComment } from './html-comment.ts'
 import { defineInlineMarkPlugin } from './inline-mark-plugin.ts'
 import { defineInlineMarks } from './inline-marks.ts'
@@ -51,6 +52,7 @@ function defineEditorExtensionImpl(options: EditorExtensionOptions) {
     defineTable(),
     defineCodeBlock(),
     defineMeowdownHorizontalRule(),
+    defineHTMLBlock(),
     defineHTMLComment(),
 
     // marks
diff --git a/packages/core/src/extensions/html-block.test.ts b/packages/core/src/extensions/html-block.test.ts
new file mode 100644
index 00000000..049d5bca
--- /dev/null
+++ b/packages/core/src/extensions/html-block.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+
+import { getHTMLBlockKind } from './html-block.ts'
+
+describe('getHTMLBlockKind', () => {
+  it('classifies an element block', () => {
+    expect(getHTMLBlockKind('<div>hello</div>')).toBe('element')
+  })
+
+  it('classifies a closing-tag block as element', () => {
+    expect(getHTMLBlockKind('</div>')).toBe('element')
+  })
+
+  it('classifies a pre block as element', () => {
+    expect(getHTMLBlockKind('<pre>code</pre>')).toBe('element')
+  })
+
+  it('classifies a custom tag block as element', () => {
+    expect(getHTMLBlockKind('<my-widget prop="1"></my-widget>')).toBe('element')
+  })
+
+  it('classifies a comment', () => {
+    expect(getHTMLBlockKind('<!-- note -->')).toBe('comment')
+  })
+
+  it('classifies a processing instruction', () => {
+    expect(getHTMLBlockKind('<?php echo 1; ?>')).toBe('instruction')
+  })
+
+  it('classifies a declaration', () => {
+    expect(getHTMLBlockKind('<!DOCTYPE html>')).toBe('declaration')
+  })
+
+  it('classifies a CDATA section', () => {
+    expect(getHTMLBlockKind('<![CDATA[x < y]]>')).toBe('cdata')
+  })
+
+  it('classifies a script block as metadata', () => {
+    expect(getHTMLBlockKind('<script>\nlet x = 1\n</script>')).toBe('metadata')
+  })
+
+  it('classifies a style block as metadata', () => {
+    expect(getHTMLBlockKind('<style>\nbody { color: red }\n</style>')).toBe('metadata')
+  })
+
+  it('does not mistake a script-prefixed tag for metadata', () => {
+    expect(getHTMLBlockKind('<scripture>text</scripture>')).toBe('element')
+  })
+})
diff --git a/packages/core/src/extensions/html-block.ts b/packages/core/src/extensions/html-block.ts
new file mode 100644
index 00000000..f4762846
--- /dev/null
+++ b/packages/core/src/extensions/html-block.ts
@@ -0,0 +1,61 @@
+import { defineNodeSpec, type Extension } from '@prosekit/core'
+import type { Attrs } from '@prosekit/pm/model'
+
+import type { NodeName } from './node-names.ts'
+
+/**
+ * What a raw HTML block is, derived from its opening characters. Only an
+ * `element` block can produce visible output, so only it gets a rendered
+ * preview; every other kind stays as always-visible source.
+ */
+export type HTMLBlockKind =
+  | 'element'
+  | 'comment'
+  | 'instruction'
+  | 'declaration'
+  | 'cdata'
+  | 'metadata'
+
+/**
+ * Classify a raw HTML block's source. The boundaries follow the CommonMark
+ * HTML block start conditions as `@lezer/markdown` implements them (spec 0.30:
+ * `<textarea>` is not part of the script/pre/style group), so the editor and
+ * the parser always agree on what a block is.
+ */
+export function getHTMLBlockKind(source: string): HTMLBlockKind {
+  const start = source.trimStart()
+  if (start.startsWith('<!--')) return 'comment'
+  if (start.startsWith('<![CDATA[')) return 'cdata'
+  if (/^<![A-Z]/i.test(start)) return 'declaration'
+  if (start.startsWith('<?')) return 'instruction'
+  if (/^<(?:script|style)(?:[\s>]|$)/i.test(start)) return 'metadata'
+  return 'element'
+}
+
+type HTMLBlockExtension = Extension<{
+  Nodes: { htmlBlock: Attrs }
+}>
+
+/**
+ * A raw HTML block (CommonMark 4.6), including HTML comments and processing
+ * instructions. The node's text content is the literal markdown source, so a
+ * round trip is byte-exact. `code: true` keeps the inline-mark plugin from
+ * parsing markdown inside it (CommonMark suppresses inline parsing in raw
+ * HTML) and enrolls it in the shared code-block behaviors: the caret-inside
+ * preview decoration and the trailing-blank-line Enter exit.
+ */
+export function defineHTMLBlock(): HTMLBlockExtension {
+  return defineNodeSpec({
+    name: 'htmlBlock' satisfies NodeName,
+    content: 'text*',
+    group: 'block',
+    code: true,
+    defining: true,
+    marks: '',
+    parseDOM: [
+      // `codeBlock` claims every bare `pre`; outrank it for the tagged form.
+      { tag: 'pre[data-html-block]', preserveWhitespace: 'full', priority: 100 },
+    ],
+    toDOM: () => ['pre', { 'data-html-block': '' }, ['code', 0]],
+  })
+}
diff --git a/packages/core/src/extensions/node-names.ts b/packages/core/src/extensions/node-names.ts
index 7cf31837..72e7fb79 100644
--- a/packages/core/src/extensions/node-names.ts
+++ b/packages/core/src/extensions/node-names.ts
@@ -10,6 +10,7 @@ export const NODE_NAMES = [
   'list',
   'codeBlock',
   'horizontalRule',
+  'htmlBlock',
   'htmlComment',
   'table',
   'tableRow',
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 9663ac8f..725c9a5b 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -54,6 +54,7 @@ export {
 } from './extensions/file-view.ts'
 export { defineFollowLinkHandler, type FollowLinkHandlers } from './extensions/follow-link.ts'
 export { getLinkUnitAt, type LinkUnit } from './extensions/get-link-unit-at.ts'
+export { defineHTMLBlock, getHTMLBlockKind, type HTMLBlockKind } from './extensions/html-block.ts'
 export { defineHTMLComment, type MeowdownHTMLCommentAttrs } from './extensions/html-comment.ts'
 export { defineHTMLPaste } from './extensions/html-paste.ts'
 export {

From 4528ff0fa428e7f4538337a2097e646db7e0befc Mon Sep 17 00:00:00 2001
From: ocavue <ocavue@gmail.com>
Date: Wed, 8 Jul 2026 03:51:31 +1000
Subject: [PATCH 2/9] feat(core)!: fold HTML comments into `htmlBlock`, drop
 the `htmlComment` node

---
 packages/core/README.md                       |  1 +
 packages/core/src/converters/md-to-pm.test.ts | 14 +--
 packages/core/src/converters/md-to-pm.ts      | 20 -----
 packages/core/src/converters/pm-to-md.ts      |  7 --
 .../core/src/extensions/extension.test.ts     | 13 +--
 packages/core/src/extensions/extension.ts     |  2 -
 .../core/src/extensions/html-comment.test.ts  | 87 -------------------
 packages/core/src/extensions/html-comment.ts  | 64 --------------
 packages/core/src/extensions/node-names.ts    |  1 -
 packages/core/src/index.ts                    |  1 -
 10 files changed, 17 insertions(+), 193 deletions(-)
 delete mode 100644 packages/core/src/extensions/html-comment.test.ts
 delete mode 100644 packages/core/src/extensions/html-comment.ts

diff --git a/packages/core/README.md b/packages/core/README.md
index 2ea77847..20da3e6c 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -39,6 +39,7 @@ const markdown = docToMarkdown(editor.state.doc)
   - Bold (`**bold**`), italic (`*italic*`), and inline code
   - Links (`[text](url)`), images (`![alt](src)`), and autolinks (`<https://example.com>`)
   - Hard line breaks
+  - HTML blocks (`<div>`, `<details>`, `<!-- comments -->`, `<?instructions?>`, ...): the raw source lives on a dedicated `htmlBlock` node, byte-exact through a round-trip, with no markdown parsing inside (per CommonMark). Use [`getHTMLBlockKind`](https://npmx.dev/package-docs/@meowdown%2Fcore#function-getHTMLBlockKind) to classify a block's source; only an `element` block produces visible output. Inline HTML tags stay literal text.
 - GitHub Flavored Markdown (GFM)
   - Tables, including column alignment (`:--`, `:-:`, `--:`)
   - Strikethrough (`~~text~~`)
diff --git a/packages/core/src/converters/md-to-pm.test.ts b/packages/core/src/converters/md-to-pm.test.ts
index a023e5e4..e5ef7bd5 100644
--- a/packages/core/src/converters/md-to-pm.test.ts
+++ b/packages/core/src/converters/md-to-pm.test.ts
@@ -890,19 +890,21 @@ describe('markdownToDoc', () => {
     })
   })
 
-  it('maps an HTML comment onto an invisible htmlComment node', () => {
+  it('maps an HTML comment onto an htmlBlock node', () => {
     expect(markdownToDoc('<!-- a comment -->').toJSON()).toEqual({
       type: 'doc',
       attrs: { frontmatter: null },
-      content: [{ type: 'htmlComment', attrs: { content: '<!-- a comment -->' } }],
+      content: [{ type: 'htmlBlock', content: [{ type: 'text', text: '<!-- a comment -->' }] }],
     })
   })
 
-  it('keeps a multi-line HTML comment verbatim on the node', () => {
+  it('keeps a multi-line HTML comment in one htmlBlock node', () => {
     expect(markdownToDoc('<!-- line one\nline two -->').toJSON()).toEqual({
       type: 'doc',
       attrs: { frontmatter: null },
-      content: [{ type: 'htmlComment', attrs: { content: '<!-- line one\nline two -->' } }],
+      content: [
+        { type: 'htmlBlock', content: [{ type: 'text', text: '<!-- line one\nline two -->' }] },
+      ],
     })
   })
 
@@ -913,9 +915,9 @@ describe('markdownToDoc', () => {
       type: 'doc',
       attrs: { frontmatter: null },
       content: [
-        { type: 'htmlComment', attrs: { content: '<!-- start -->' } },
+        { type: 'htmlBlock', content: [{ type: 'text', text: '<!-- start -->' }] },
         { type: 'paragraph', content: [{ type: 'text', text: 'body text' }] },
-        { type: 'htmlComment', attrs: { content: '<!-- end -->' } },
+        { type: 'htmlBlock', content: [{ type: 'text', text: '<!-- end -->' }] },
       ],
     })
   })
diff --git a/packages/core/src/converters/md-to-pm.ts b/packages/core/src/converters/md-to-pm.ts
index f1086ce0..deee291a 100644
--- a/packages/core/src/converters/md-to-pm.ts
+++ b/packages/core/src/converters/md-to-pm.ts
@@ -156,10 +156,6 @@ function convertBlock(
     case LEZER_NODE_IDS.Paragraph:
       return [convertParagraph(nodes, cursor, text)]
     case LEZER_NODE_IDS.CommentBlock:
-      // A comment is not rendered output: map it onto the invisible `htmlComment`
-      // node so it stays in the document (and round-trips) without reading as
-      // body text.
-      return [convertHTMLComment(nodes, cursor, text)]
     case LEZER_NODE_IDS.HTMLBlock:
     case LEZER_NODE_IDS.ProcessingInstructionBlock:
       // Raw HTML keeps its literal source as an `htmlBlock` node: byte-exact
@@ -389,22 +385,6 @@ function convertHTMLBlock(
   return nodes.htmlBlock(sliceLeafBlockText(cursor, text))
 }
 
-/**
- * Build the invisible `htmlComment` node from a `CommentBlock`. The raw comment
- * (delimiters included) is kept verbatim on the node's `content` attribute;
- * continuation lines are dedented like a paragraph's so the serializer's own
- * line prefix re-applies the container indent instead of doubling it.
- */
-function convertHTMLComment(
-  nodes: TypedNodeBuilders,
-  cursor: TreeCursor,
-  text: string,
-): ProseMirrorNode {
-  const column = measureContentColumn(text, cursor.from)
-  const content = dedentContinuation(text.slice(cursor.from, cursor.to), column)
-  return nodes.htmlComment({ content })
-}
-
 function convertBlockquote(
   nodes: TypedNodeBuilders,
   cursor: TreeCursor,
diff --git a/packages/core/src/converters/pm-to-md.ts b/packages/core/src/converters/pm-to-md.ts
index 66918ba5..35b63035 100644
--- a/packages/core/src/converters/pm-to-md.ts
+++ b/packages/core/src/converters/pm-to-md.ts
@@ -4,7 +4,6 @@ import type { MeowdownCodeBlockAttrs } from '../extensions/code-block.ts'
 import type { Frontmatter } from '../extensions/frontmatter.ts'
 import type { MeowdownHeadingAttrs } from '../extensions/heading.ts'
 import type { MeowdownHorizontalRuleAttrs } from '../extensions/horizontal-rule.ts'
-import type { MeowdownHTMLCommentAttrs } from '../extensions/html-comment.ts'
 import type { MeowdownListAttrs } from '../extensions/list.ts'
 import type { NodeName } from '../extensions/node-names.ts'
 import type { MeowdownTableCellAttrs, TableColumnAlign } from '../extensions/table-column-align.ts'
@@ -264,12 +263,6 @@ function emit(node: ProseMirrorNode, out: MdOut): void {
       out.write(node.textContent)
       out.closeBlock()
       return
-    case 'htmlComment': {
-      const { content } = node.attrs as MeowdownHTMLCommentAttrs
-      out.write(content)
-      out.closeBlock()
-      return
-    }
     case 'table':
       emitTable(node, out)
       return
diff --git a/packages/core/src/extensions/extension.test.ts b/packages/core/src/extensions/extension.test.ts
index 1d3fb124..5a9b62cd 100644
--- a/packages/core/src/extensions/extension.test.ts
+++ b/packages/core/src/extensions/extension.test.ts
@@ -22,7 +22,7 @@ describe('defineEditorExtension', () => {
         n.tableRow(n.tableCell(n.paragraph('A1')), n.tableCell(n.paragraph('B1'))),
       ),
       n.horizontalRule(),
-      n.htmlComment({ content: '<!-- a comment -->' }),
+      n.htmlBlock('<!-- a comment -->'),
     )
 
     expect(doc.toJSON()).toMatchInlineSnapshot(`
@@ -253,10 +253,13 @@ describe('defineEditorExtension', () => {
             "type": "horizontalRule",
           },
           {
-            "attrs": {
-              "content": "<!-- a comment -->",
-            },
-            "type": "htmlComment",
+            "content": [
+              {
+                "text": "<!-- a comment -->",
+                "type": "text",
+              },
+            ],
+            "type": "htmlBlock",
           },
         ],
         "type": "doc",
diff --git a/packages/core/src/extensions/extension.ts b/packages/core/src/extensions/extension.ts
index 59090379..01881bf8 100644
--- a/packages/core/src/extensions/extension.ts
+++ b/packages/core/src/extensions/extension.ts
@@ -22,7 +22,6 @@ import { defineHeading } from './heading.ts'
 import { defineHiddenRunCaret } from './hidden-run-caret.ts'
 import { defineMeowdownHorizontalRule } from './horizontal-rule.ts'
 import { defineHTMLBlock } from './html-block.ts'
-import { defineHTMLComment } from './html-comment.ts'
 import { defineInlineMarkPlugin } from './inline-mark-plugin.ts'
 import { defineInlineMarks } from './inline-marks.ts'
 import type { FileLinkOptions } from './inline-text-to-mark-chunks.ts'
@@ -53,7 +52,6 @@ function defineEditorExtensionImpl(options: EditorExtensionOptions) {
     defineCodeBlock(),
     defineMeowdownHorizontalRule(),
     defineHTMLBlock(),
-    defineHTMLComment(),
 
     // marks
     defineInlineMarks(),
diff --git a/packages/core/src/extensions/html-comment.test.ts b/packages/core/src/extensions/html-comment.test.ts
deleted file mode 100644
index 7a1a286e..00000000
--- a/packages/core/src/extensions/html-comment.test.ts
+++ /dev/null
@@ -1,87 +0,0 @@
-import { createEditor } from '@prosekit/core'
-import { DOMParser, DOMSerializer } from '@prosekit/pm/model'
-import { describe, expect, it } from 'vitest'
-
-import { docToMarkdown } from '../converters/pm-to-md.ts'
-import { setupFixture } from '../testing/index.ts'
-
-import { defineEditorExtension } from './extension.ts'
-
-function setupEditor() {
-  const editor = createEditor({ extension: defineEditorExtension() })
-  return { editor, schema: editor.schema, n: editor.nodes }
-}
-
-describe('html comment node', () => {
-  it('serializes to a hidden element and recovers its content from the DOM', () => {
-    const { schema, n } = setupEditor()
-    const doc = n.doc(n.htmlComment({ content: '<!-- marker -->' }))
-
-    const dom = DOMSerializer.fromSchema(schema).serializeFragment(doc.content)
-    const container = document.createElement('div')
-    container.appendChild(dom)
-
-    const element = container.querySelector<HTMLElement>('[data-html-comment]')
-    expect(element).not.toBeNull()
-    expect(element?.style.display).toBe('none')
-
-    const parsed = DOMParser.fromSchema(schema).parse(container)
-    expect(parsed.child(0).type.name).toBe('htmlComment')
-    expect(parsed.child(0).attrs.content).toBe('<!-- marker -->')
-  })
-})
-
-describe('html comment in a mounted editor', () => {
-  it('renders the comment invisibly without spilling into the visible text', () => {
-    using fixture = setupFixture()
-    const { n } = fixture
-    fixture.set(
-      n.doc(
-        n.paragraph('before'),
-        n.htmlComment({ content: '<!-- reflect-capture-page-text:start -->' }),
-        n.paragraph('after'),
-      ),
-    )
-
-    const element = fixture.dom.querySelector<HTMLElement>('[data-html-comment]')
-    expect(element).not.toBeNull()
-    expect(getComputedStyle(element as HTMLElement).display).toBe('none')
-    // The raw comment must not read as body text in the editor.
-    expect(fixture.dom.textContent).not.toContain('reflect-capture-page-text')
-    expect(fixture.dom.textContent).toContain('before')
-    expect(fixture.dom.textContent).toContain('after')
-  })
-
-  it('keeps the comment in the document so it round-trips to markdown', () => {
-    using fixture = setupFixture()
-    const { n } = fixture
-    fixture.set(
-      n.doc(
-        n.htmlComment({ content: '<!-- start -->' }),
-        n.paragraph('body text'),
-        n.htmlComment({ content: '<!-- end -->' }),
-      ),
-    )
-
-    expect(docToMarkdown(fixture.doc)).toBe('<!-- start -->\n\nbody text\n\n<!-- end -->\n')
-  })
-
-  it('steps the caret past the hidden comment without error', async () => {
-    using fixture = setupFixture()
-    const { n } = fixture
-    fixture.set(
-      n.doc(
-        n.paragraph('first<a>'),
-        n.htmlComment({ content: '<!-- between -->' }),
-        n.paragraph('second'),
-      ),
-    )
-    fixture.view.focus()
-    // Arrow-down across the invisible node lands in the next paragraph; the
-    // comment survives, proving navigation neither crashes nor drops it.
-    const { userEvent } = await import('vitest/browser')
-    await userEvent.keyboard('{ArrowDown}{ArrowDown}')
-
-    expect(docToMarkdown(fixture.doc)).toBe('first\n\n<!-- between -->\n\nsecond\n')
-  })
-})
diff --git a/packages/core/src/extensions/html-comment.ts b/packages/core/src/extensions/html-comment.ts
deleted file mode 100644
index 7e5481e1..00000000
--- a/packages/core/src/extensions/html-comment.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-import { defineNodeSpec, type Extension } from '@prosekit/core'
-
-import type { NodeName } from './node-names.ts'
-
-export interface MeowdownHTMLCommentAttrs {
-  /**
-   * The literal markdown comment, including its delimiters, e.g.
-   * `<!-- reflect-capture-page-text:start -->`. A multi-line comment keeps its
-   * embedded newlines verbatim so the round-trip is lossless.
-   */
-  content: string
-}
-
-type HTMLCommentExtension = Extension<{
-  Nodes: { htmlComment: MeowdownHTMLCommentAttrs }
-}>
-
-/**
- * A block-level HTML comment (`<!-- ... -->`) as an invisible, atomic node.
- *
- * Markdown is the source of truth, so a comment must survive a round-trip, but
- * a comment is, by definition, not rendered output. Rather than spilling the raw
- * `<!-- ... -->` into a paragraph (where it reads as body text), the parser maps
- * a `CommentBlock` onto this node: the text rides on the `content` attribute and
- * `toDOM` hides it with `display: none`, so it stays in the document and
- * serializes back verbatim while never showing in the editor. Useful for
- * sentinel markers that tools embed around a region of a note.
- *
- * Only block-level comments (a `<!-- ... -->` that owns its line) become this
- * node. An inline comment in the middle of a paragraph is left as literal text,
- * and raw HTML blocks (`<div>…`) stay visible paragraphs — they can carry
- * content a reader expects to see.
- *
- * The node is `atom` (no editable content) and not selectable: it is an opaque,
- * invisible marker the cursor steps over rather than a block the user edits.
- */
-export function defineHTMLComment(): HTMLCommentExtension {
-  return defineNodeSpec({
-    name: 'htmlComment' satisfies NodeName,
-    group: 'block',
-    atom: true,
-    selectable: false,
-    attrs: {
-      content: { default: '' },
-    },
-    // Hidden from view, but kept in the DOM so an editor copy/paste or a
-    // serialize → re-parse cycle recovers the raw comment from the data attr.
-    toDOM: (node) => [
-      'div',
-      {
-        'data-html-comment': (node.attrs as MeowdownHTMLCommentAttrs).content,
-        style: 'display: none',
-      },
-    ],
-    parseDOM: [
-      {
-        tag: 'div[data-html-comment]',
-        getAttrs: (dom) => ({
-          content: dom.getAttribute('data-html-comment') ?? '',
-        }),
-      },
-    ],
-  })
-}
diff --git a/packages/core/src/extensions/node-names.ts b/packages/core/src/extensions/node-names.ts
index 72e7fb79..65a5f4c7 100644
--- a/packages/core/src/extensions/node-names.ts
+++ b/packages/core/src/extensions/node-names.ts
@@ -11,7 +11,6 @@ export const NODE_NAMES = [
   'codeBlock',
   'horizontalRule',
   'htmlBlock',
-  'htmlComment',
   'table',
   'tableRow',
   'tableCell',
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 725c9a5b..fab71751 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -55,7 +55,6 @@ export {
 export { defineFollowLinkHandler, type FollowLinkHandlers } from './extensions/follow-link.ts'
 export { getLinkUnitAt, type LinkUnit } from './extensions/get-link-unit-at.ts'
 export { defineHTMLBlock, getHTMLBlockKind, type HTMLBlockKind } from './extensions/html-block.ts'
-export { defineHTMLComment, type MeowdownHTMLCommentAttrs } from './extensions/html-comment.ts'
 export { defineHTMLPaste } from './extensions/html-paste.ts'
 export {
   defineImageClickHandler,

From 09f5fa10e315e448aa89151e479d17923255196c Mon Sep 17 00:00:00 2001
From: ocavue <ocavue@gmail.com>
Date: Wed, 8 Jul 2026 03:53:26 +1000
Subject: [PATCH 3/9] feat(core): highlight `htmlBlock` source as HTML

---
 .../extensions/code-block-highlight.test.ts   | 45 +++++++++++++++++++
 .../src/extensions/code-block-highlight.ts    | 27 +++++++----
 2 files changed, 64 insertions(+), 8 deletions(-)

diff --git a/packages/core/src/extensions/code-block-highlight.test.ts b/packages/core/src/extensions/code-block-highlight.test.ts
index d93faae4..4a061ff5 100644
--- a/packages/core/src/extensions/code-block-highlight.test.ts
+++ b/packages/core/src/extensions/code-block-highlight.test.ts
@@ -34,6 +34,51 @@ describe('defineCodeBlockSyntaxHighlight', () => {
     `)
   })
 
+  it('renders HTML syntax token spans for an html block', async () => {
+    using fixture = setupFixture()
+    const { n } = fixture
+    fixture.set(n.doc(n.htmlBlock('<div class="box">hi</div>')))
+    const selector = '.ProseMirror pre[data-html-block] code [class*="tok-"]'
+    const locator = page.locate(selector).first()
+    await expect.element(locator, { timeout: 15000 }).toBeInTheDocument()
+    expect(formatHTML(fixture.dom.innerHTML)).toMatchInlineSnapshot(`
+      "
+      <pre data-html-block>
+        <code>
+          <span class="tok-punctuation">
+            &lt;
+          </span>
+          <span class="tok-typeName">
+            div
+          </span>
+          <span class="tok-propertyName">
+            class
+          </span>
+          <span class="tok-operator">
+            =
+          </span>
+          <span class="tok-string">
+            "box"
+          </span>
+          <span class="tok-punctuation">
+            &gt;
+          </span>
+          hi
+          <span class="tok-punctuation">
+            &lt;/
+          </span>
+          <span class="tok-typeName">
+            div
+          </span>
+          <span class="tok-punctuation">
+            &gt;
+          </span>
+        </code>
+      </pre>
+      "
+    `)
+  })
+
   it('does not crash on an unknown language and leaves the text intact', async () => {
     using fixture = setupFixture()
     const { n } = fixture
diff --git a/packages/core/src/extensions/code-block-highlight.ts b/packages/core/src/extensions/code-block-highlight.ts
index 7f1779bc..2e6bba03 100644
--- a/packages/core/src/extensions/code-block-highlight.ts
+++ b/packages/core/src/extensions/code-block-highlight.ts
@@ -1,8 +1,9 @@
 import { LanguageDescription, type LanguageSupport } from '@codemirror/language'
 import { languages } from '@codemirror/language-data'
 import { classHighlighter, highlightTree } from '@lezer/highlight'
-import type { Extension } from '@prosekit/core'
+import { definePlugin, union, type Extension } from '@prosekit/core'
 import { defineCodeBlockHighlight, type HighlightParser } from '@prosekit/extensions/code-block'
+import { createHighlightPlugin } from 'prosemirror-highlight'
 import { createParser } from 'prosemirror-highlight/lezer'
 
 import type { NodeName } from './node-names.ts'
@@ -74,16 +75,26 @@ const lazyParser: HighlightParser = (options) => {
 }
 
 /**
- * Adds syntax highlighting to `codeBlock` nodes, parsing each block with the
- * matching CodeMirror/Lezer grammar (loaded on demand from
+ * Adds syntax highlighting to `codeBlock` and `htmlBlock` nodes, parsing each
+ * block with the matching CodeMirror/Lezer grammar (loaded on demand from
  * `@codemirror/language-data`). Tokens are tagged with `@lezer/highlight`
- * `tok-*` classes; the default theme colors them per color scheme.
+ * `tok-*` classes; the default theme colors them per color scheme. An
+ * `htmlBlock` has no `language` attr, so its plugin pins the language.
  */
 export function defineCodeBlockSyntaxHighlight(): Extension {
-  return defineCodeBlockHighlight({
-    parser: lazyParser,
-    nodeTypes: ['codeBlock' satisfies NodeName],
-  })
+  return union(
+    defineCodeBlockHighlight({
+      parser: lazyParser,
+      nodeTypes: ['codeBlock' satisfies NodeName],
+    }),
+    definePlugin(
+      createHighlightPlugin({
+        parser: lazyParser,
+        nodeTypes: ['htmlBlock' satisfies NodeName],
+        languageExtractor: () => 'html',
+      }),
+    ),
+  )
 }
 
 /** A highlighted span of code: `[from, to)` carries the `@lezer/highlight` classes. */

From f232174cdc0f87f7194ce41504d8181eac2dc82b Mon Sep 17 00:00:00 2001
From: ocavue <ocavue@gmail.com>
Date: Wed, 8 Jul 2026 04:04:03 +1000
Subject: [PATCH 4/9] feat(core): enter rule turning an HTML start line into
 `htmlBlock`

---
 .../extensions/html-block-enter-rule.test.ts  |  83 ++++++++++++
 packages/core/src/extensions/html-block.ts    | 118 +++++++++++++++++-
 2 files changed, 199 insertions(+), 2 deletions(-)
 create mode 100644 packages/core/src/extensions/html-block-enter-rule.test.ts

diff --git a/packages/core/src/extensions/html-block-enter-rule.test.ts b/packages/core/src/extensions/html-block-enter-rule.test.ts
new file mode 100644
index 00000000..38a52162
--- /dev/null
+++ b/packages/core/src/extensions/html-block-enter-rule.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest'
+import { userEvent } from 'vitest/browser'
+
+import { setupFixture } from '../testing/index.ts'
+
+describe('html block enter rule', () => {
+  it('turns an open element start line into an htmlBlock with the caret inside', async () => {
+    using fixture = setupFixture()
+    const { n } = fixture
+    fixture.set(n.doc(n.paragraph('<div class="x"><a>')))
+    fixture.view.focus()
+    await userEvent.keyboard('{Enter}')
+    await userEvent.keyboard('hello')
+    const expected = n.doc(n.htmlBlock('<div class="x">\nhello'))
+    expect(fixture.doc.eq(expected)).toBe(true)
+  })
+
+  it('keeps the start line as content rather than deleting it', async () => {
+    using fixture = setupFixture()
+    const { n } = fixture
+    fixture.set(n.doc(n.paragraph('<section><a>')))
+    fixture.view.focus()
+    await userEvent.keyboard('{Enter}')
+    const expected = n.doc(n.htmlBlock('<section>\n'))
+    expect(fixture.doc.eq(expected)).toBe(true)
+  })
+
+  it('drops the caret into a fresh paragraph after a complete comment', async () => {
+    using fixture = setupFixture()
+    const { n } = fixture
+    fixture.set(n.doc(n.paragraph('<!-- note --><a>')))
+    fixture.view.focus()
+    await userEvent.keyboard('{Enter}')
+    await userEvent.keyboard('after')
+    const expected = n.doc(n.htmlBlock('<!-- note -->'), n.paragraph('after'))
+    expect(fixture.doc.eq(expected)).toBe(true)
+  })
+
+  it('keeps the caret inside an unterminated comment', async () => {
+    using fixture = setupFixture()
+    const { n } = fixture
+    fixture.set(n.doc(n.paragraph('<!-- open<a>')))
+    fixture.view.focus()
+    await userEvent.keyboard('{Enter}')
+    await userEvent.keyboard('body')
+    const expected = n.doc(n.htmlBlock('<!-- open\nbody'))
+    expect(fixture.doc.eq(expected)).toBe(true)
+  })
+
+  it('does not convert an autolink', async () => {
+    using fixture = setupFixture()
+    const { n } = fixture
+    fixture.set(n.doc(n.paragraph('<https://example.com><a>')))
+    fixture.view.focus()
+    await userEvent.keyboard('{Enter}')
+    // The default Enter splits the paragraph; nothing becomes an htmlBlock.
+    expect(fixture.doc.firstChild?.type.name).toBe('paragraph')
+  })
+
+  it('does not convert when the caret is not at the end of the line', async () => {
+    using fixture = setupFixture()
+    const { n } = fixture
+    fixture.set(n.doc(n.paragraph('<div><a>tail')))
+    fixture.view.focus()
+    await userEvent.keyboard('{Enter}')
+    expect(fixture.doc.firstChild?.type.name).toBe('paragraph')
+  })
+
+  it('exits the block when Enter is pressed on a trailing blank line', async () => {
+    using fixture = setupFixture()
+    const { n } = fixture
+    fixture.set(n.doc(n.paragraph('<div><a>')))
+    fixture.view.focus()
+    await userEvent.keyboard('{Enter}')
+    // Inside the block now, on a new line. A second Enter leaves a lone
+    // trailing newline; a third exits (the code-block Enter needs `\n\n`).
+    await userEvent.keyboard('{Enter}')
+    await userEvent.keyboard('{Enter}')
+    const doc = fixture.doc
+    expect(doc.firstChild?.type.name).toBe('htmlBlock')
+    expect(doc.lastChild?.type.name).toBe('paragraph')
+  })
+})
diff --git a/packages/core/src/extensions/html-block.ts b/packages/core/src/extensions/html-block.ts
index f4762846..e8d873cc 100644
--- a/packages/core/src/extensions/html-block.ts
+++ b/packages/core/src/extensions/html-block.ts
@@ -1,5 +1,7 @@
-import { defineNodeSpec, type Extension } from '@prosekit/core'
+import { defineNodeSpec, getNodeType, union, type Extension } from '@prosekit/core'
+import { defineEnterRule } from '@prosekit/extensions/enter-rule'
 import type { Attrs } from '@prosekit/pm/model'
+import { TextSelection } from '@prosekit/pm/state'
 
 import type { NodeName } from './node-names.ts'
 
@@ -32,6 +34,49 @@ export function getHTMLBlockKind(source: string): HTMLBlockKind {
   return 'element'
 }
 
+/**
+ * The seven CommonMark HTML block start conditions, in spec order, as
+ * `@lezer/markdown` spells them (spec 0.30: `<textarea>` is not in the type-1
+ * group and the type-6 tag list is 0.30's). Keeping these identical to the
+ * parser's is what lets the enter rule agree with a later reparse. `line` must
+ * already have its leading indentation removed.
+ */
+const HTML_BLOCK_STARTS: readonly RegExp[] = [
+  /^<(?:script|pre|style)(?:\s|>|$)/i,
+  /^<!--/,
+  /^<\?/,
+  /^<![A-Z]/i,
+  /^<!\[CDATA\[/,
+  /^<\/?(?:address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h1|h2|h3|h4|h5|h6|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|section|source|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul)(?:\s|\/?>|$)/i,
+  /^(?:<\/[a-z][\w-]*\s*>|<[a-z][\w-]*(?:\s+[a-z:_][\w.-]*(?:\s*=\s*(?:[^\s"'=<>`]+|'[^']*'|"[^"]*"))?)*\s*\/?>)\s*$/i,
+]
+
+/**
+ * The inline end condition for each start type. Types 1-5 close on the same
+ * line when this matches; types 6-7 (undefined) only close at a blank line, so
+ * they never complete inline.
+ */
+const HTML_BLOCK_INLINE_ENDS: ReadonlyArray<RegExp | undefined> = [
+  /<\/(?:script|pre|style)>/i,
+  /-->/,
+  /\?>/,
+  />/,
+  /\]\]>/,
+  undefined,
+  undefined,
+]
+
+/** The matched start type (0-6) of an HTML block line, or -1 for none. */
+function matchHTMLBlockStart(line: string): number {
+  return HTML_BLOCK_STARTS.findIndex((regex) => regex.test(line))
+}
+
+/** Strip up to three leading spaces (CommonMark's HTML block indentation). */
+function stripBlockIndent(line: string): string {
+  const match = /^ {0,3}/.exec(line)
+  return match ? line.slice(match[0].length) : line
+}
+
 type HTMLBlockExtension = Extension<{
   Nodes: { htmlBlock: Attrs }
 }>
@@ -44,7 +89,7 @@ type HTMLBlockExtension = Extension<{
  * HTML) and enrolls it in the shared code-block behaviors: the caret-inside
  * preview decoration and the trailing-blank-line Enter exit.
  */
-export function defineHTMLBlock(): HTMLBlockExtension {
+function defineHTMLBlockSpec(): HTMLBlockExtension {
   return defineNodeSpec({
     name: 'htmlBlock' satisfies NodeName,
     content: 'text*',
@@ -59,3 +104,72 @@ export function defineHTMLBlock(): HTMLBlockExtension {
     toDOM: () => ['pre', { 'data-html-block': '' }, ['code', 0]],
   })
 }
+
+/**
+ * Turn a single-line paragraph into an `htmlBlock` when Enter is pressed at its
+ * end and the line begins a CommonMark HTML block (`<div>`, `<!-- ... -->`,
+ * `<?php ... ?>`, ...). Unlike a fenced code block, the start line is content,
+ * so it is kept, not deleted. A block whose start line already closes inline
+ * (types 1-5, e.g. `<!-- x -->`) drops the caret into a fresh paragraph after
+ * it; an open block (types 6-7, or an unterminated 1-5) keeps the caret inside
+ * on a new line so the user can fill it in.
+ */
+function defineHTMLBlockEnterRule() {
+  return defineEnterRule({
+    // Broad gate: any single line that starts with `<`. The handler runs the
+    // precise start conditions, so an autolink like `<https://x>` is declined.
+    regex: /^ {0,3}<[^\n]*$/,
+    handler: ({ state }) => {
+      const { selection } = state
+      if (!selection.empty) return null
+      const { $head } = selection
+      const parent = $head.parent
+      if (parent.type.name !== ('paragraph' satisfies NodeName)) return null
+      // Only a single-line paragraph, with the caret at its very end.
+      if ($head.parentOffset !== parent.content.size) return null
+      const line = parent.textContent
+      if (line.includes('\n')) return null
+
+      const stripped = stripBlockIndent(line)
+      const startType = matchHTMLBlockStart(stripped)
+      if (startType < 0) return null
+
+      const htmlBlockType = getNodeType(state.schema, 'htmlBlock' satisfies NodeName)
+      if (!$head.node(-1).canReplaceWith($head.index(-1), $head.indexAfter(-1), htmlBlockType)) {
+        return null
+      }
+
+      const inlineEnd = HTML_BLOCK_INLINE_ENDS[startType]
+      const closedInline = inlineEnd ? inlineEnd.test(stripped) : false
+
+      const tr = state.tr
+      tr.setBlockType($head.pos, $head.pos, htmlBlockType)
+
+      if (closedInline) {
+        // A complete block: continue in a fresh paragraph after it.
+        const paragraphType = getNodeType(state.schema, 'paragraph' satisfies NodeName)
+        const afterBlock = tr.mapping.map($head.after())
+        const paragraph = paragraphType.createAndFill()
+        if (!paragraph) return null
+        tr.insert(afterBlock, paragraph)
+        tr.setSelection(TextSelection.create(tr.doc, afterBlock + 1))
+      } else {
+        // An open block: keep filling it in on a new line inside.
+        const endOfContent = tr.mapping.map($head.pos)
+        tr.insertText('\n', endOfContent)
+        tr.setSelection(TextSelection.create(tr.doc, endOfContent + 1))
+      }
+
+      return tr.scrollIntoView()
+    },
+    stop: true,
+  })
+}
+
+/**
+ * Adds the `htmlBlock` node and the enter rule that creates one from an HTML
+ * start line.
+ */
+export function defineHTMLBlock() {
+  return union(defineHTMLBlockSpec(), defineHTMLBlockEnterRule())
+}

From 70085b49fa964b89cdcee8a95dfc00acfd427b73 Mon Sep 17 00:00:00 2001
From: ocavue <ocavue@gmail.com>
Date: Wed, 8 Jul 2026 04:05:30 +1000
Subject: [PATCH 5/9] feat(react): add `sanitizeHTMLBlock` via DOMPurify

---
 packages/react/package.json                   |  1 +
 .../react/src/utils/sanitize-html.test.ts     | 61 +++++++++++++++++++
 packages/react/src/utils/sanitize-html.ts     | 34 +++++++++++
 pnpm-lock.yaml                                | 16 +++++
 4 files changed, 112 insertions(+)
 create mode 100644 packages/react/src/utils/sanitize-html.test.ts
 create mode 100644 packages/react/src/utils/sanitize-html.ts

diff --git a/packages/react/package.json b/packages/react/package.json
index c1588ce5..934a057d 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -28,6 +28,7 @@
     "@prosekit/pm": "^0.1.19-beta.2",
     "@prosekit/react": "^0.8.0-beta.19",
     "clsx": "^2.1.1",
+    "dompurify": "^3.4.11",
     "lucide-react": "^1.21.0",
     "react-property": "^2.0.2"
   },
diff --git a/packages/react/src/utils/sanitize-html.test.ts b/packages/react/src/utils/sanitize-html.test.ts
new file mode 100644
index 00000000..00160eec
--- /dev/null
+++ b/packages/react/src/utils/sanitize-html.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+
+import { sanitizeHTMLBlock } from './sanitize-html.ts'
+
+/** Serialize the sanitized fragment to an HTML string for assertions. */
+function sanitizeToHTML(source: string): string {
+  const container = document.createElement('div')
+  container.append(sanitizeHTMLBlock(source))
+  return container.innerHTML
+}
+
+describe('sanitizeHTMLBlock', () => {
+  it('keeps a plain element', () => {
+    expect(sanitizeToHTML('<div>hello</div>')).toBe('<div>hello</div>')
+  })
+
+  it('drops a script tag', () => {
+    expect(sanitizeToHTML('<div>ok</div><script>alert(1)</script>')).toBe('<div>ok</div>')
+  })
+
+  it('drops an inline event handler', () => {
+    const html = sanitizeToHTML('<img src="x.png" onerror="alert(1)">')
+    expect(html).toContain('src="x.png"')
+    expect(html).not.toContain('onerror')
+  })
+
+  it('drops a javascript: href', () => {
+    const html = sanitizeToHTML('<a href="javascript:alert(1)">click</a>')
+    expect(html).not.toContain('javascript:')
+  })
+
+  it('drops an iframe', () => {
+    expect(sanitizeToHTML('<iframe src="https://evil.example"></iframe>')).toBe('')
+  })
+
+  it('drops a form control', () => {
+    expect(sanitizeToHTML('<input value="x">')).toBe('')
+  })
+
+  it('keeps a style attribute', () => {
+    expect(sanitizeToHTML('<span style="color: red">hi</span>')).toContain('style="color: red"')
+  })
+
+  it('keeps details and summary with the open attribute', () => {
+    const html = sanitizeToHTML('<details open><summary>More</summary>body</details>')
+    expect(html).toContain('<details open="">')
+    expect(html).toContain('<summary>More</summary>')
+  })
+
+  it('keeps sizing and alignment attributes on an image', () => {
+    const html = sanitizeToHTML('<img src="a.png" width="100" align="left">')
+    expect(html).toContain('width="100"')
+    expect(html).toContain('align="left"')
+  })
+
+  it('renders nothing visible for a comment', () => {
+    const container = document.createElement('div')
+    container.append(sanitizeHTMLBlock('<!-- just a note -->'))
+    expect(container.textContent).toBe('')
+  })
+})
diff --git a/packages/react/src/utils/sanitize-html.ts b/packages/react/src/utils/sanitize-html.ts
new file mode 100644
index 00000000..cc7c241f
--- /dev/null
+++ b/packages/react/src/utils/sanitize-html.ts
@@ -0,0 +1,34 @@
+import DOMPurify from 'dompurify'
+
+// Tags that never belong in a note preview. Scripts and event handlers are
+// already stripped by DOMPurify's defaults; these are the extras a notes app
+// does not want to render: embeds that load remote content or run scripts, and
+// interactive form controls that would swallow clicks. Listed explicitly so the
+// policy survives a DOMPurify default change.
+const FORBID_TAGS = [
+  'iframe',
+  'frame',
+  'frameset',
+  'object',
+  'embed',
+  'form',
+  'input',
+  'button',
+  'select',
+  'option',
+  'textarea',
+]
+
+/**
+ * Sanitize a raw HTML block's source into a `DocumentFragment` safe to insert
+ * into the editor. The `style` attribute is kept (a real notes need), while
+ * `<script>`, event handlers, `javascript:` URLs, remote embeds, and form
+ * controls are removed. The original markdown source is never touched; only
+ * this rendered copy is sanitized.
+ */
+export function sanitizeHTMLBlock(source: string): DocumentFragment {
+  return DOMPurify.sanitize(source, {
+    RETURN_DOM_FRAGMENT: true,
+    FORBID_TAGS,
+  })
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8ec168dd..42715606 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -178,6 +178,9 @@ importers:
       clsx:
         specifier: ^2.1.1
         version: 2.1.1
+      dompurify:
+        specifier: ^3.4.11
+        version: 3.4.11
       lucide-react:
         specifier: ^1.21.0
         version: 1.21.0(react@19.2.7)
@@ -1533,6 +1536,9 @@ packages:
   '@types/react@19.2.17':
     resolution: {integrity: sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==}
 
+  '@types/trusted-types@2.0.7':
+    resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
+
   '@types/unist@3.0.3':
     resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
 
@@ -1998,6 +2004,9 @@ packages:
     resolution: {integrity: sha512-gYzvtM72ZtxQO0T048kd6HWSbbGCNOUwcnfQ01cqIJ4X2IYKFFHZ5mKvrQETcFXxsRObZulDaKmy//R7TPtsBg==}
     engines: {node: '>=20.19.0'}
 
+  dompurify@3.4.11:
+    resolution: {integrity: sha512-zhlUV12GsaRzMsf9q5M254YhA4+VuF0fG+QFqu6aYpoGlKtz+w8//jBcGVYBgQkR5GHjUomejY84AV+/uPbWdw==}
+
   domutils@4.0.2:
     resolution: {integrity: sha512-qI4JLRKnSzqFqr7hAlS5xQDusBCjKSEG4t4+7aNrIQMHBcsC2TGEhuyABJdYkgSewL57PNLYEiibY2iPKhKpaA==}
     engines: {node: '>=20.19.0'}
@@ -5059,6 +5068,9 @@ snapshots:
     dependencies:
       csstype: 3.2.3
 
+  '@types/trusted-types@2.0.7':
+    optional: true
+
   '@types/unist@3.0.3': {}
 
   '@typescript-eslint/eslint-plugin@8.62.0(@typescript-eslint/parser@8.62.0)(eslint@10.6.0)(typescript@6.0.3)':
@@ -5599,6 +5611,10 @@ snapshots:
     dependencies:
       domelementtype: 3.0.0
 
+  dompurify@3.4.11:
+    optionalDependencies:
+      '@types/trusted-types': 2.0.7
+
   domutils@4.0.2:
     dependencies:
       dom-serializer: 3.1.1

From b78c168d969a713c88226c7c93adacd46f6babab Mon Sep 17 00:00:00 2001
From: ocavue <ocavue@gmail.com>
Date: Wed, 8 Jul 2026 04:12:09 +1000
Subject: [PATCH 6/9] feat(react): render `htmlBlock` with stacked sanitized
 preview

---
 packages/core/src/style.css                   |  13 +++
 packages/react/src/components/editor.tsx      |   9 ++
 .../src/components/html-block-render.tsx      |  45 ++++++++
 .../src/components/html-block-view.module.css |  24 +++++
 .../html-block-view.module.d.css.ts           |   9 ++
 .../src/components/html-block-view.test.tsx   | 100 ++++++++++++++++++
 .../react/src/components/html-block-view.tsx  |  70 ++++++++++++
 .../react/src/components/prosekit-editor.tsx  |  14 ++-
 .../react/src/extensions/html-block-view.tsx  |  26 +++++
 9 files changed, 309 insertions(+), 1 deletion(-)
 create mode 100644 packages/react/src/components/html-block-render.tsx
 create mode 100644 packages/react/src/components/html-block-view.module.css
 create mode 100644 packages/react/src/components/html-block-view.module.d.css.ts
 create mode 100644 packages/react/src/components/html-block-view.test.tsx
 create mode 100644 packages/react/src/components/html-block-view.tsx
 create mode 100644 packages/react/src/extensions/html-block-view.tsx

diff --git a/packages/core/src/style.css b/packages/core/src/style.css
index c8158328..aa2bc42d 100644
--- a/packages/core/src/style.css
+++ b/packages/core/src/style.css
@@ -504,6 +504,19 @@
   .ProseMirror pre code .tok-link {
     text-decoration: underline;
   }
+  .ProseMirror pre code .tok-tagName {
+    color: light-dark(#116329, #7ee787);
+  }
+  .ProseMirror pre code .tok-attributeName {
+    color: light-dark(#0550ae, #79c0ff);
+  }
+  .ProseMirror pre code .tok-attributeValue {
+    color: light-dark(#0a3069, #a5d6ff);
+  }
+  .ProseMirror pre code .tok-angleBracket,
+  .ProseMirror pre code .tok-punctuation {
+    color: var(--meowdown-muted);
+  }
 
   .ProseMirror hr {
     margin: 1.5em 0;
diff --git a/packages/react/src/components/editor.tsx b/packages/react/src/components/editor.tsx
index 432ef234..979eeb25 100644
--- a/packages/react/src/components/editor.tsx
+++ b/packages/react/src/components/editor.tsx
@@ -48,6 +48,13 @@ export interface EditorProps {
    */
   initialMarkdown?: string
 
+  /**
+   * Whether raw HTML blocks render a sanitized preview. When false, every HTML
+   * block stays source-only (raw HTML shown as code). Read once at editor
+   * creation. Defaults to `true`.
+   */
+  renderHTMLPreview?: boolean
+
   /**
    * Called on every user-driven document change. Programmatic `setMarkdown` and
    * `setState` on the handle do not fire it.
@@ -271,6 +278,7 @@ export interface EditorProps {
 export function MeowdownEditor({
   mode = 'focus',
   initialMarkdown,
+  renderHTMLPreview,
   onDocChange,
   onSlashMenuSearch,
   onTagSearch,
@@ -382,6 +390,7 @@ export function MeowdownEditor({
         ref={childRef}
         markMode={mode}
         initialMarkdown={initialMarkdown}
+        renderHTMLPreview={renderHTMLPreview}
         onDocChange={onDocChange}
         onSlashMenuSearch={onSlashMenuSearch}
         onTagSearch={onTagSearch}
diff --git a/packages/react/src/components/html-block-render.tsx b/packages/react/src/components/html-block-render.tsx
new file mode 100644
index 00000000..b0a5dc5c
--- /dev/null
+++ b/packages/react/src/components/html-block-render.tsx
@@ -0,0 +1,45 @@
+import { useLayoutEffect, useRef, type MouseEventHandler, type ReactElement } from 'react'
+
+import { sanitizeHTMLBlock } from '../utils/sanitize-html.ts'
+
+interface HTMLBlockRenderProps {
+  /** The raw HTML block source. Sanitized before it reaches the DOM. */
+  source: string
+  className?: string
+  'data-testid'?: string
+  onMouseDown?: MouseEventHandler
+}
+
+/**
+ * Whether a raw HTML block would render anything visible. An element block that
+ * sanitizes to nothing (e.g. a lone `<iframe>`) keeps showing its source
+ * instead of collapsing into an empty, unclickable preview.
+ */
+export function htmlBlockHasVisiblePreview(source: string): boolean {
+  const fragment = sanitizeHTMLBlock(source)
+  return fragment.childElementCount > 0 || (fragment.textContent?.trim().length ?? 0) > 0
+}
+
+/**
+ * The sanitized preview of a raw HTML block, injected into a real element (not
+ * `dangerouslySetInnerHTML`). Shared by the editor node view and the read-only
+ * `MarkdownView`, so both surfaces render HTML the same way.
+ */
+export function HTMLBlockRender(props: HTMLBlockRenderProps): ReactElement {
+  const { source, className, onMouseDown } = props
+  const ref = useRef<HTMLDivElement>(null)
+  useLayoutEffect(() => {
+    const element = ref.current
+    if (!element) return
+    element.replaceChildren(sanitizeHTMLBlock(source))
+  }, [source])
+  return (
+    <div
+      ref={ref}
+      className={className}
+      contentEditable={false}
+      data-testid={props['data-testid']}
+      onMouseDown={onMouseDown}
+    />
+  )
+}
diff --git a/packages/react/src/components/html-block-view.module.css b/packages/react/src/components/html-block-view.module.css
new file mode 100644
index 00000000..d1fd6e61
--- /dev/null
+++ b/packages/react/src/components/html-block-view.module.css
@@ -0,0 +1,24 @@
+.Root {
+  position: relative;
+}
+
+/* Preview-only state: the caret is outside an element block, so the source
+ * gives way to the rendered HTML. The caret can never sit in the hidden source
+ * (entering it flips the state back), so the missing box does not disturb caret
+ * geometry. */
+.Root[data-preview] pre {
+  display: none;
+}
+
+.Preview {
+  padding: 0.5rem 0.25rem 0;
+  overflow-x: auto;
+  cursor: text;
+}
+
+/* Stacked state: with the caret inside, the live preview sits below the source,
+ * separated from it. */
+.Root:not([data-preview]) .Preview {
+  margin-top: 0.5rem;
+  border-top: 1px solid var(--meowdown-border);
+}
diff --git a/packages/react/src/components/html-block-view.module.d.css.ts b/packages/react/src/components/html-block-view.module.d.css.ts
new file mode 100644
index 00000000..edd8748b
--- /dev/null
+++ b/packages/react/src/components/html-block-view.module.d.css.ts
@@ -0,0 +1,9 @@
+// @ts-nocheck
+declare const styles = {
+  'Root': '' as string,
+  'Root': '' as string,
+  'Preview': '' as string,
+  'Root': '' as string,
+  'Preview': '' as string,
+} as const;
+export default styles;
diff --git a/packages/react/src/components/html-block-view.test.tsx b/packages/react/src/components/html-block-view.test.tsx
new file mode 100644
index 00000000..bd96a3a9
--- /dev/null
+++ b/packages/react/src/components/html-block-view.test.tsx
@@ -0,0 +1,100 @@
+import '../testing/index.ts'
+
+import { isApple } from '@prosekit/core'
+import { describe, expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { page, userEvent } from 'vitest/browser'
+
+import { ProseKitEditor } from './prosekit-editor.tsx'
+
+const source = page.getByTestId('html-block-source')
+const preview = page.getByTestId('html-block-preview')
+
+// A leading paragraph keeps the initial caret outside the HTML block.
+const DIV_BLOCK_MD = 'before\n\n<div class="box">hello</div>'
+const COMMENT_MD = 'before\n\n<!-- a note -->'
+
+describe('html block preview', () => {
+  it('shows only the rendered HTML when the caret is outside', async () => {
+    await render(<ProseKitEditor initialMarkdown={DIV_BLOCK_MD} />)
+    await expect.element(preview.locate('.box')).toBeInTheDocument()
+    await expect.element(preview).toBeVisible()
+    await expect.element(source).not.toBeVisible()
+  })
+
+  it('shows the source above the preview once the caret enters', async () => {
+    await render(<ProseKitEditor initialMarkdown={DIV_BLOCK_MD} />)
+    await expect.element(preview).toBeVisible()
+
+    await preview.click()
+
+    await expect.element(source).toBeVisible()
+    await expect.element(preview).toBeVisible()
+    const sourceEl = source.element()
+    const previewEl = preview.element()
+    const position = sourceEl.compareDocumentPosition(previewEl)
+    expect(position & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+  })
+
+  it('updates the preview live while editing the source', async () => {
+    await render(<ProseKitEditor initialMarkdown={DIV_BLOCK_MD} />)
+    await preview.click()
+    await expect.element(source).toBeVisible()
+
+    // Caret lands at the block start; type inside the tag text.
+    await userEvent.keyboard('{End}')
+    await userEvent.keyboard('!')
+
+    await expect.element(preview).toHaveTextContent('hello!')
+  })
+
+  it('lets a details block toggle open on click without entering the source', async () => {
+    await render(
+      <ProseKitEditor
+        initialMarkdown={'before\n\n<details><summary>More</summary>body</details>'}
+      />,
+    )
+    const details = preview.locate('details')
+    await expect.element(details).toBeInTheDocument()
+    await expect.element(details).not.toHaveAttribute('open')
+
+    await preview.locate('summary').click()
+
+    await expect.element(details).toHaveAttribute('open')
+    await expect.element(source).not.toBeVisible()
+  })
+
+  it('forces the source open on Mod-click of the preview', async () => {
+    await render(<ProseKitEditor initialMarkdown={DIV_BLOCK_MD} />)
+    await expect.element(preview).toBeVisible()
+
+    const modifier = isApple ? 'Meta' : 'Control'
+    await userEvent.keyboard(`{${modifier}>}`)
+    await preview.click()
+    await userEvent.keyboard(`{/${modifier}}`)
+
+    await expect.element(source).toBeVisible()
+  })
+
+  it('always shows the source for a comment block', async () => {
+    await render(<ProseKitEditor initialMarkdown={COMMENT_MD} />)
+    await expect.element(source).toBeVisible()
+    await expect.element(source).toHaveTextContent('<!-- a note -->')
+    await expect.element(preview).not.toBeInTheDocument()
+  })
+
+  it('strips a script tag from the preview', async () => {
+    await render(
+      <ProseKitEditor initialMarkdown={'before\n\n<div>ok<script>alert(1)</script></div>'} />,
+    )
+    await expect.element(preview.locate('div')).toBeInTheDocument()
+    expect(preview.element().querySelector('script')).toBeNull()
+  })
+
+  it('keeps every block source-only when renderHTMLPreview is false', async () => {
+    await render(<ProseKitEditor initialMarkdown={DIV_BLOCK_MD} renderHTMLPreview={false} />)
+    await expect.element(source).toBeVisible()
+    await expect.element(source).toHaveTextContent('<div class="box">hello</div>')
+    await expect.element(preview).not.toBeInTheDocument()
+  })
+})
diff --git a/packages/react/src/components/html-block-view.tsx b/packages/react/src/components/html-block-view.tsx
new file mode 100644
index 00000000..5443f945
--- /dev/null
+++ b/packages/react/src/components/html-block-view.tsx
@@ -0,0 +1,70 @@
+import { getHTMLBlockKind, isCodeBlockPreviewHiddenDecoration } from '@meowdown/core'
+import { isApple } from '@prosekit/core'
+import { TextSelection } from '@prosekit/pm/state'
+import type { ReactNodeViewProps } from '@prosekit/react'
+import { useMemo, type MouseEvent } from 'react'
+
+import { htmlBlockHasVisiblePreview, HTMLBlockRender } from './html-block-render.tsx'
+import styles from './html-block-view.module.css'
+
+// Interactive preview content that should respond to a plain click instead of
+// dropping the caret into the source.
+const INTERACTIVE_SELECTOR = 'details, summary, video, audio'
+
+/**
+ * Node view for a raw HTML block: the editable source stacked with a live,
+ * sanitized preview. With the caret outside, an element block shows only its
+ * preview; move the caret in and the source appears above it (the MarkText
+ * "stacked" model, matching the math block). Comments, processing instructions,
+ * and script/style metadata render nothing, so they always stay source-only.
+ */
+export function HTMLBlockView(props: ReactNodeViewProps & { renderPreview: boolean }) {
+  const { renderPreview } = props
+  const source = props.node.textContent
+  const kind = getHTMLBlockKind(source)
+
+  const caretInside = props.decorations.some(isCodeBlockPreviewHiddenDecoration)
+
+  // Only an element block can render; a comment/PI/metadata block never gets a
+  // preview, and an element that sanitizes to nothing keeps its source visible.
+  const hasPreview = useMemo(
+    () => renderPreview && kind === 'element' && htmlBlockHasVisiblePreview(source),
+    [renderPreview, kind, source],
+  )
+
+  const previewOnly = hasPreview && !caretInside
+
+  const focusSource = () => {
+    const pos = props.getPos()
+    if (pos == null) return
+    const { view } = props
+    const selection = TextSelection.near(view.state.doc.resolve(pos + 1), 1)
+    view.dispatch(view.state.tr.setSelection(selection))
+    view.focus()
+  }
+
+  const onPreviewMouseDown = (event: MouseEvent) => {
+    const forceEdit = isApple ? event.metaKey : event.ctrlKey
+    // Let interactive widgets (a `<details>` toggle, a video control) handle a
+    // plain click; `Mod`-click always forces editing.
+    if (!forceEdit && (event.target as HTMLElement).closest(INTERACTIVE_SELECTOR)) {
+      return
+    }
+    event.preventDefault()
+    focusSource()
+  }
+
+  return (
+    <div className={styles.Root} data-preview={previewOnly || undefined} data-kind={kind}>
+      <pre ref={props.contentRef} data-html-block data-testid="html-block-source"></pre>
+      {hasPreview && (
+        <HTMLBlockRender
+          source={source}
+          className={styles.Preview}
+          data-testid="html-block-preview"
+          onMouseDown={onPreviewMouseDown}
+        />
+      )}
+    </div>
+  )
+}
diff --git a/packages/react/src/components/prosekit-editor.tsx b/packages/react/src/components/prosekit-editor.tsx
index 906c73c8..9dd025b3 100644
--- a/packages/react/src/components/prosekit-editor.tsx
+++ b/packages/react/src/components/prosekit-editor.tsx
@@ -38,6 +38,7 @@ import {
 } from 'react'
 
 import { defineCodeBlockView } from '../extensions/code-block-view.ts'
+import { defineHTMLBlockView } from '../extensions/html-block-view.tsx'
 import type { TimeFormat } from '../utils/date-format.ts'
 
 import { BlockHandle } from './block-handle.tsx'
@@ -81,6 +82,12 @@ function resolveSelection(doc: EditorNode, selection: SelectionHint): Selection
 export interface ProseKitEditorProps {
   markMode?: MarkMode
 
+  /**
+   * Whether raw HTML blocks render a sanitized preview. When false, every HTML
+   * block stays source-only. Read once at editor creation. Defaults to `true`.
+   */
+  renderHTMLPreview?: boolean
+
   /**
    * The initial Markdown text of the editor. Only the value provided on the
    * first render is used; later changes are ignored.
@@ -186,6 +193,7 @@ export interface ProseKitEditorProps {
 
 export function ProseKitEditor({
   markMode = 'focus',
+  renderHTMLPreview = true,
   initialMarkdown,
   onDocChange,
   onSlashMenuSearch,
@@ -222,7 +230,11 @@ export function ProseKitEditor({
 }: ProseKitEditorProps) {
   const [editor] = useState((): TypedEditor => {
     const baseExtension: EditorExtension = defineEditorExtension({ resolveFileLink, markMode })
-    const extension = union(baseExtension, defineCodeBlockView())
+    const extension = union(
+      baseExtension,
+      defineCodeBlockView(),
+      defineHTMLBlockView({ renderPreview: renderHTMLPreview }),
+    )
     const editor: TypedEditor = createEditor({ extension })
     if (initialMarkdown) {
       editor.setContent(markdownToDoc(initialMarkdown, { nodes: editor.nodes, frontmatter }))
diff --git a/packages/react/src/extensions/html-block-view.tsx b/packages/react/src/extensions/html-block-view.tsx
new file mode 100644
index 00000000..aab70457
--- /dev/null
+++ b/packages/react/src/extensions/html-block-view.tsx
@@ -0,0 +1,26 @@
+import type { Extension } from '@prosekit/core'
+import {
+  defineReactNodeView,
+  type ReactNodeViewComponent,
+  type ReactNodeViewProps,
+} from '@prosekit/react'
+
+import { HTMLBlockView } from '../components/html-block-view.tsx'
+
+/**
+ * Renders `htmlBlock` nodes with the stacked source + sanitized preview node
+ * view. `renderPreview` (the editor's `renderHTMLPreview` prop) is read once at
+ * editor creation; when false, every block stays source-only. The caret-inside
+ * decoration comes from `defineCodeBlockPreviewPlugin`, already applied by
+ * `defineCodeBlockView`.
+ */
+export function defineHTMLBlockView(options: { renderPreview: boolean }): Extension {
+  const component = (props: ReactNodeViewProps) => (
+    <HTMLBlockView {...props} renderPreview={options.renderPreview} />
+  )
+  return defineReactNodeView({
+    name: 'htmlBlock',
+    contentAs: 'code',
+    component: component satisfies ReactNodeViewComponent,
+  })
+}

From 971788619fac1676f0164368793a151aca3d6d1c Mon Sep 17 00:00:00 2001
From: ocavue <ocavue@gmail.com>
Date: Wed, 8 Jul 2026 04:15:19 +1000
Subject: [PATCH 7/9] feat(react): render `htmlBlock` in `MarkdownView`

---
 .../src/components/markdown-view.test.tsx     | 20 +++++++++++
 .../react/src/components/markdown-view.tsx    | 33 +++++++++++++++++--
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/packages/react/src/components/markdown-view.test.tsx b/packages/react/src/components/markdown-view.test.tsx
index f525a367..0fe6b5a9 100644
--- a/packages/react/src/components/markdown-view.test.tsx
+++ b/packages/react/src/components/markdown-view.test.tsx
@@ -234,6 +234,26 @@ describe('MarkdownView math', () => {
       .element(view.getByTestId('code-block-math-preview').locate('.katex'))
       .toBeInTheDocument()
   })
+
+  it('renders an element HTML block as a sanitized preview', async () => {
+    await renderView('<div class="box">hello</div>')
+    const preview = view.getByTestId('html-block-preview')
+    await expect.element(preview.locate('.box')).toBeInTheDocument()
+    await expect.element(preview).toHaveTextContent('hello')
+  })
+
+  it('strips a script tag from an HTML block preview', async () => {
+    await renderView('<div>ok<script>alert(1)</script></div>')
+    const preview = view.getByTestId('html-block-preview')
+    await expect.element(preview.locate('div')).toBeInTheDocument()
+    expect(preview.element().querySelector('script')).toBeNull()
+  })
+
+  it('renders a comment block as source, never a preview', async () => {
+    await renderView('<!-- a note -->')
+    await expect.element(view.locate('pre[data-html-block]')).toHaveTextContent('<!-- a note -->')
+    await expect.element(view.getByTestId('html-block-preview')).not.toBeInTheDocument()
+  })
 })
 
 describe('MarkdownView parity with the editor', () => {
diff --git a/packages/react/src/components/markdown-view.tsx b/packages/react/src/components/markdown-view.tsx
index 191a0fc9..e1111b3a 100644
--- a/packages/react/src/components/markdown-view.tsx
+++ b/packages/react/src/components/markdown-view.tsx
@@ -1,6 +1,7 @@
 import {
   defaultResolveImageUrl,
   getCodeTokens,
+  getHTMLBlockKind,
   getMarkBuilders,
   inlineTextToMarkChunks,
   listenForTweetHeight,
@@ -44,6 +45,7 @@ import { useKaTeX } from '../hooks/use-katex.ts'
 import { attributesToProps } from './attributes-to-props.ts'
 import styles from './code-block-view.module.css'
 import { normalizeDOMOutputSpec, type TypedDOMOutputSpec } from './dom-output-spec.tsx'
+import { htmlBlockHasVisiblePreview, HTMLBlockRender } from './html-block-render.tsx'
 import { MathRender } from './math-render.tsx'
 
 /** Payload for {@link TaskClickHandler}. */
@@ -267,7 +269,8 @@ function renderTokens(code: string, tokens: readonly CodeToken[]): ReactNode {
   return out
 }
 
-function CodeBlock({ code, language }: { code: string; language: string }): ReactElement {
+/** Highlight `code` in `language`, loading the grammar on demand. */
+function useHighlightTokens(code: string, language: string): readonly CodeToken[] {
   // Synchronous tokens when the grammar is already loaded (the common path);
   // `null` means a grammar must load, which the effect awaits.
   const syncTokens = useMemo<readonly CodeToken[] | null>(() => {
@@ -288,7 +291,11 @@ function CodeBlock({ code, language }: { code: string; language: string }): Reac
       active = false
     }
   }, [code, language, syncTokens])
-  const tokens = syncTokens ?? asyncTokens ?? []
+  return syncTokens ?? asyncTokens ?? []
+}
+
+function CodeBlock({ code, language }: { code: string; language: string }): ReactElement {
+  const tokens = useHighlightTokens(code, language)
   return (
     <pre data-language={language || undefined}>
       <code>{tokens.length > 0 ? renderTokens(code, tokens) : code}</code>
@@ -296,6 +303,24 @@ function CodeBlock({ code, language }: { code: string; language: string }): Reac
   )
 }
 
+/**
+ * A raw HTML block. An element block that renders something shows its sanitized
+ * preview (the same component the editor uses, so both surfaces agree); a
+ * comment, processing instruction, or metadata block, and an element that
+ * sanitizes to nothing, show highlighted source instead.
+ */
+function HTMLBlock({ source }: { source: string }): ReactElement {
+  const tokens = useHighlightTokens(source, 'html')
+  if (getHTMLBlockKind(source) === 'element' && htmlBlockHasVisiblePreview(source)) {
+    return <HTMLBlockRender source={source} data-testid="html-block-preview" />
+  }
+  return (
+    <pre data-html-block>
+      <code>{tokens.length > 0 ? renderTokens(source, tokens) : source}</code>
+    </pre>
+  )
+}
+
 /**
  * Mirrors the editor's `MathMarkView` DOM: a KaTeX preview next to the source
  * text, flipped by the same mode CSS (the read-only view has no caret, so the
@@ -468,6 +493,10 @@ function renderBlock(node: ProseMirrorNode, context: RenderContext): ReactNode {
     return <CodeBlock key={key} code={node.textContent} language={language} />
   }
 
+  if (typeName === 'htmlBlock') {
+    return <HTMLBlock key={key} source={node.textContent} />
+  }
+
   const toDOM = node.type.spec.toDOM
   if (node.isTextblock) {
     const inline = renderInline(node, context)

From dfe3921d656ca7537edc8737fc20e2fcff536f82 Mon Sep 17 00:00:00 2001
From: ocavue <ocavue@gmail.com>
Date: Wed, 8 Jul 2026 04:17:17 +1000
Subject: [PATCH 8/9] docs: document HTML block support and add website sample

---
 packages/react/README.md | 2 ++
 website/src/app.tsx      | 9 +++++++++
 2 files changed, 11 insertions(+)

diff --git a/packages/react/README.md b/packages/react/README.md
index a06beba0..3e96a630 100644
--- a/packages/react/README.md
+++ b/packages/react/README.md
@@ -62,6 +62,8 @@ Import both stylesheets: `@meowdown/core/style.css` (the editor theme and variab
 
 Math (`$E=mc^2$` inline, `$$` blocks, and ` ```math ` fences) is compiled by KaTeX to native MathML.
 
+Raw HTML blocks render a live preview sanitized with DOMPurify (`<script>`, event handlers, `javascript:` URLs, remote embeds, and form controls are removed); the caret reveals the source below the preview. Comments and other non-visual blocks stay source-only. Pass `renderHTMLPreview={false}` to show every HTML block as source instead.
+
 ## License
 
 MIT
diff --git a/website/src/app.tsx b/website/src/app.tsx
index 09faaf37..368bbfbb 100644
--- a/website/src/app.tsx
+++ b/website/src/app.tsx
@@ -136,6 +136,15 @@ function greet(name: string): string {
 | ----- | ------ | -- | --------- |
 | even  | **in** | *tables* too! | :D |
 
+Drop in raw HTML and it renders as a live preview; click it to edit the source. A collapsible section works out of the box:
+
+<details>
+<summary>What can I tuck away in here?</summary>
+Anything that needs raw HTML, from <kbd>keyboard keys</kbd> to sized <img src="https://static.photos/yellow/16x16/8" width="16">.
+</details>
+
+<!-- Comments stay visible as source, so notes to yourself never disappear. -->
+
 > Switch modes above to choose how much Markdown syntax stays in view.
 `
 

From 7830036328a19223b736404af63b9ba58bb9aafa Mon Sep 17 00:00:00 2001
From: ocavue <ocavue@gmail.com>
Date: Wed, 8 Jul 2026 04:35:16 +1000
Subject: [PATCH 9/9] test(react): make live-preview html block test
 browser-agnostic

---
 packages/react/src/components/html-block-view.test.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/react/src/components/html-block-view.test.tsx b/packages/react/src/components/html-block-view.test.tsx
index bd96a3a9..700a267c 100644
--- a/packages/react/src/components/html-block-view.test.tsx
+++ b/packages/react/src/components/html-block-view.test.tsx
@@ -41,11 +41,11 @@ describe('html block preview', () => {
     await preview.click()
     await expect.element(source).toBeVisible()
 
-    // Caret lands at the block start; type inside the tag text.
-    await userEvent.keyboard('{End}')
-    await userEvent.keyboard('!')
+    // Clicking the preview drops the caret at the block start; typing there
+    // extends the source, and the preview re-renders live.
+    await userEvent.keyboard('x')
 
-    await expect.element(preview).toHaveTextContent('hello!')
+    await expect.element(preview).toHaveTextContent('xhello')
   })
 
   it('lets a details block toggle open on click without entering the source', async () => {